Search documentation of phoenix_kit

# PhoenixKit.Cache (phoenix_kit v1.6.19)

View Source

Generic caching system for PhoenixKit with ETS-backed storage.

This module provides a flexible caching foundation that can be used for:

- Settings caching
- User roles and permissions
- Module configurations
- Any frequently accessed data

## Features

- ETS-backed storage for high-performance lookups
- Automatic cache warming
- TTL support for expiring data
- Statistics tracking
- Robust fallback mechanisms
- Multiple cache instances via registry

## Usage

    # Start a cache instance
    {:ok, pid} = PhoenixKit.Cache.start_link(name: :my_cache, warmer: &MyApp.load_data/0)

    # Basic operations
    PhoenixKit.Cache.put(:my_cache, "key", "value")
    PhoenixKit.Cache.get(:my_cache, "key", "default")
    PhoenixKit.Cache.invalidate(:my_cache, "key")

    # Batch operations
    PhoenixKit.Cache.get_multiple(:my_cache, ["key1", "key2"], %{"key1" => "default1"})
    PhoenixKit.Cache.invalidate_multiple(:my_cache, ["key1", "key2"])

## Configuration

Cache instances can be configured with:

- `:name` - Unique name for the cache instance
- `:warmer` - Function to warm the cache on startup
- `:ttl` - Time-to-live for cache entries (optional)
- `:max_size` - Maximum number of entries (optional)

# Summary

## Types

cache_key()
cache_name()
cache_value()
default_value()
options()
warmer_fun()

## Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

clear(cache_name)

Clears all entries from the cache.

get(cache_name, key, default \\ nil)

Gets a value from the cache.

get_multiple(cache_name, keys, defaults \\ %{})

Gets multiple values from the cache.

invalidate(cache_name, key)

Invalidates a key in the cache.

invalidate_multiple(cache_name, keys)

Invalidates multiple keys in the cache.

put(cache_name, key, value)

Puts a value in the cache.

put_multiple(cache_name, key_values)

Puts multiple values in the cache.

start_link(opts)

Starts a new cache instance.

stats(cache_name)

Gets cache statistics.

warm(cache_name)

Warms the cache using the configured warmer function.

# Types

# cache_key()

    @type cache_key() :: any()

# cache_name()

    @type cache_name() :: atom()

# cache_value()

    @type cache_value() :: any()

# default_value()

    @type default_value() :: any()

# options()

    @type options() :: [
      name: cache_name(),
      warmer: warmer_fun(),
      ttl: pos_integer() | nil,
      max_size: pos_integer() | nil
    ]

# warmer_fun()

    @type warmer_fun() :: (-> map() | nil)

# Functions

# child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# clear(cache_name)

    @spec clear(cache_name()) :: :ok

Clears all entries from the cache.

## Examples

    PhoenixKit.Cache.clear(:settings)

# get(cache_name, key, default \\ nil)

    @spec get(cache_name(), cache_key(), default_value()) :: cache_value()

Gets a value from the cache.

Returns the default value if the key is not found or the cache is unavailable.

## Examples

    PhoenixKit.Cache.get(:settings, "date_format", "Y-m-d")
    PhoenixKit.Cache.get(:user_roles, user_id, [])

# get_multiple(cache_name, keys, defaults \\ %{})

    @spec get_multiple(cache_name(), [cache_key()], map()) :: map()

Gets multiple values from the cache.

Returns a map with the requested keys and their values, using defaults for missing keys.

## Examples

    defaults = %{"date_format" => "Y-m-d", "time_format" => "H:i"}
    PhoenixKit.Cache.get_multiple(:settings, ["date_format", "time_format"], defaults)

# invalidate(cache_name, key)

    @spec invalidate(cache_name(), cache_key()) :: :ok

Invalidates a key in the cache.

## Examples

    PhoenixKit.Cache.invalidate(:settings, "date_format")

# invalidate_multiple(cache_name, keys)

    @spec invalidate_multiple(cache_name(), [cache_key()]) :: :ok

Invalidates multiple keys in the cache.

## Examples

    PhoenixKit.Cache.invalidate_multiple(:settings, ["date_format", "time_format"])

# put(cache_name, key, value)

    @spec put(cache_name(), cache_key(), cache_value()) :: :ok

Puts a value in the cache.

## Examples

    PhoenixKit.Cache.put(:settings, "date_format", "m/d/Y")
    PhoenixKit.Cache.put(:user_roles, user_id, ["admin", "user"])

# put_multiple(cache_name, key_values)

    @spec put_multiple(cache_name(), map()) :: :ok

Puts multiple values in the cache.

## Examples

    PhoenixKit.Cache.put_multiple(:settings, %{"date_format" => "m/d/Y", "time_format" => "h:i A"})

# start_link(opts)

    @spec start_link(options()) :: GenServer.on_start()

Starts a new cache instance.

## Options

- `:name` - Required. Unique name for the cache instance
- `:warmer` - Optional. Function to warm the cache on startup
- `:ttl` - Optional. Time-to-live for cache entries in milliseconds
- `:max_size` - Optional. Maximum number of entries before eviction

## Examples

    {:ok, pid} = PhoenixKit.Cache.start_link(name: :settings)
    {:ok, pid} = PhoenixKit.Cache.start_link(name: :user_roles, warmer: &MyApp.load_user_roles/0)

# stats(cache_name)

    @spec stats(cache_name()) :: map()

Gets cache statistics.

## Examples

    PhoenixKit.Cache.stats(:settings)
    # => %{hits: 150, misses: 5, puts: 20, invalidations: 3, hit_rate: 0.97}

# warm(cache_name)

    @spec warm(cache_name()) :: :ok

Warms the cache using the configured warmer function.

## Examples

    PhoenixKit.Cache.warm(:settings)