pevensie/cache

Pevensie Cache is a smiple module for caching data in your application. It is designed to be easily used with all parts of Pevensie, and follows the driver-based architecture.

Important: data stored in Pevensie Cache may be lost (e.g. on restart), and is not guaranteed to be durable. Do not use Pevensie Cache for data that you need to keep indefinitely.

Getting Started

All you need to provide to the new function is your chosen driver.

import pevensie/cache.{type PevensieCache}
import pevensie/drivers/postgres.{type PostgresConfig}

pub fn main() {
  let config = PostgresConfig(
    ..postgres.default_config(),
    database: "my_database",
  )
  let driver = postgres.new_cache_driver(config)
  let pevensie_cache = cache.new(driver)
}

You’ll need to run the connect function on your Pevensie Cache instance before using it. This allows your driver to perform any setup required, such as creating a database connection pool.

Once connected, you can use the set, get, and delete functions to store, retrieve, and delete data from the cache.

import pevensie/cache.{type PevensieCache}

pub fn main() {
  // ...
let assert Ok(pevensie_cache) = cache.connect(pevensie_cache)
  cache.set(pevensie_cache, "key", "value", None)
  cache.get(pevensie_cache, "key")
  cache.delete(pevensie_cache, "key")
  // ...
}

Drivers

Pevensie Cache is designed to be driver-agnostic, so you can use any driver you like. The drivers provided with Pevensie are:

The hope is that other first- and third-party drivers will be available in the future.

Note: database-based drivers will require migrations to be run before using them. See the documentation for your chosen driver for more information.

Types

pub type CacheDriver(driver, driver_error) {
  CacheDriver(
    driver: driver,
    connect: ConnectFunction(driver, driver_error),
    disconnect: DisconnectFunction(driver, driver_error),
    set: CacheSetFunction(driver, driver_error),
    get: CacheGetFunction(driver, driver_error),
    delete: CacheDeleteFunction(driver, driver_error),
  )
}

Constructors

  • CacheDriver(
      driver: driver,
      connect: ConnectFunction(driver, driver_error),
      disconnect: DisconnectFunction(driver, driver_error),
      set: CacheSetFunction(driver, driver_error),
      get: CacheGetFunction(driver, driver_error),
      delete: CacheDeleteFunction(driver, driver_error),
    )
pub type DeleteError(cache_driver_error) {
  DeleteDriverError(cache_driver_error)
}

Constructors

  • DeleteDriverError(cache_driver_error)
pub type GetError(cache_driver_error) {
  GetDriverError(cache_driver_error)
  GotTooFewRecords
  GotTooManyRecords
}

Constructors

  • GetDriverError(cache_driver_error)
  • GotTooFewRecords
  • GotTooManyRecords

The entrypoint to the Pevensie Cache API. This type is used when using the majority of the functions in pevensie/cache.

You must connect your Pevensie Cache instance before using it. This allows your driver to perform any setup required, such as creating a database connection pool.

Create a new PevensieCache instance using the new function.

import pevensie/cache.{type PevensieCache}

pub fn main() {
  let pevensie_cache = cache.new(
    postgres.new_cache_driver(postgres.default_config()),
  )
  // ...
}
pub type PevensieCache(driver, driver_error, connected) {
  PevensieCache(driver: CacheDriver(driver, driver_error))
}

Constructors

  • PevensieCache(driver: CacheDriver(driver, driver_error))
pub type SetError(cache_driver_error) {
  SetDriverError(cache_driver_error)
}

Constructors

  • SetDriverError(cache_driver_error)

Functions

pub fn connect(
  pevensie_cache: PevensieCache(a, b, Disconnected),
) -> Result(PevensieCache(a, b, Connected), ConnectError(b))

Runs setup for your chosen cache driver and returns a connected PevensieCache instance.

This function must be called before using any other functions in the Pevensie Cache API. Attempting to use the API before calling connect will result in a compile error.

import pevensie/cache.{type PevensieCache}

pub fn main() {
  // ...
  let assert Ok(pevensie_cache) = cache.connect(pevensie_cache)
  // ...
}
pub fn delete(
  pevensie_cache: PevensieCache(a, b, Connected),
  resource_type resource_type: String,
  key key: String,
) -> Result(Nil, DeleteError(b))

Delete a value from the cache.

pub fn disconnect(
  pevensie_cache: PevensieCache(a, b, Connected),
) -> Result(PevensieCache(a, b, Disconnected), DisconnectError(b))

Runs teardown for your chosen cache driver and returns a disconnected PevensieCache instance.

After calling this function, you can no longer use the cache driver unless you call connect again.

pub fn get(
  pevensie_cache: PevensieCache(a, b, Connected),
  resource_type resource_type: String,
  key key: String,
) -> Result(String, GetError(b))

Retrieve a value from the cache.

pub fn new(
  driver driver: CacheDriver(a, b),
) -> PevensieCache(a, b, Disconnected)

Creates a new PevensieCache instance.

The driver argument is the driver to use for caching. Use either a driver provided by Pevensie, or any third-party driver you like.

import pevensie/cache.{type PevensieCache}

pub fn main() {
  let pevensie_cache = cache.new(
    postgres.new_cache_driver(postgres.default_config()),
  )
  // ...
}
pub fn set(
  pevensie_cache: PevensieCache(a, b, Connected),
  resource_type resource_type: String,
  key key: String,
  value value: String,
  ttl_seconds ttl_seconds: Option(Int),
) -> Result(Nil, SetError(b))

Store a value in the cache. Both the key and value must be strings.

The resource_type argument is used to help organize your cache. It should be a string that uniquely identifies the type of data you’re caching. For example, if you’re caching user data, you might use "user" as the resource type.

The ttl_seconds argument is the number of seconds the value should be stored in the cache. If None, the value will never expire.

import pevensie/cache.{type PevensieCache}

pub fn main() {
  // ...
  let assert Ok(pevensie_cache) = cache.connect(pevensie_cache)
  let assert Ok(_) = cache.set(
    pevensie_cache,
    "ship",
    "dawntreader",
    "{\"name\": \"Dawn Treader\", \"captain\": \"Prince Caspian\"}",
    None,
  )
  // ...
}
Search Document