# `PhoenixKit.Cache`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.165/lib/phoenix_kit/cache/cache.ex#L1)

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)

# `cache_key`

```elixir
@type cache_key() :: any()
```

# `cache_name`

```elixir
@type cache_name() :: atom()
```

# `cache_value`

```elixir
@type cache_value() :: any()
```

# `default_value`

```elixir
@type default_value() :: any()
```

# `options`

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

# `warmer_fun`

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

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `clear`

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

Clears all entries from the cache.

## Examples

    PhoenixKit.Cache.clear(:settings)

# `clear_by_prefix`

```elixir
@spec clear_by_prefix(cache_name(), String.t()) ::
  {:ok, non_neg_integer()} | {:error, any()}
```

Clears all cache entries whose keys start with the given prefix.

Returns the count of entries cleared.

## Examples

    PhoenixKit.Cache.clear_by_prefix(:publishing_posts, "v1:publishing_post:my-blog:")
    # => {:ok, 15}

# `get`

```elixir
@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_uuid, [])

# `get_multiple`

```elixir
@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`

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

Invalidates a key in the cache.

## Examples

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

# `invalidate_multiple`

```elixir
@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`

```elixir
@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_uuid, ["admin", "user"])

# `put_multiple`

```elixir
@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`

```elixir
@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`

```elixir
@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`

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

Warms the cache using the configured warmer function.

## Examples

    PhoenixKit.Cache.warm(:settings)

---

*Consult [api-reference.md](api-reference.md) for complete listing*