# `Lotus.Cache.Adapter`
[🔗](https://github.com/typhoonworks/lotus/blob/v0.16.6/lib/lotus/cache/adapter.ex#L1)

Behaviour specification for cache adapters in the Lotus framework.

All cache adapters must implement this behavior.

Cache adapters are only meant to be used internally by Lotus and should not be
called directly by application code, as their implementation may change without notice.

## Built-in Adapters

- `Lotus.Cache.ETS` - Default ETS-based local in-memory cache
- `Lotus.Cache.Cachex` - Cachex-based cache supporting local and distributed modes

## Usage

Simply `use` the behavior in your adapter implementation:

    defmodule MyApp.CustomCacheAdapter do
      use Lotus.Cache.Adapter

      # Implement required callbacks...
    end

## Configuration

Configure your chosen adapter in your application config:

    config :lotus,
      cache: %{
        adapter: MyApp.CustomCacheAdapter,
        # adapter-specific options...
      }

# `opts`

```elixir
@type opts() :: Keyword.t()
```

Options passed to cache operations

# `ttl_ms`

```elixir
@type ttl_ms() :: non_neg_integer()
```

How long the cache entry should live, in milliseconds

# `delete`

```elixir
@callback delete(key()) :: :ok | {:error, term()}
```

Removes a value from the cache by key.

# `get`

```elixir
@callback get(key()) :: {:ok, value()} | :miss | {:error, term()}
```

Retrieves a value from the cache by key.

# `get_or_store`

```elixir
@callback get_or_store(key(), ttl_ms(), (-> value()), opts()) ::
  {:ok, value(), :hit | :miss} | {:error, term()}
```

Retrieves a value from cache or stores it if missing.

# `invalidate_tags`

```elixir
@callback invalidate_tags([binary()]) :: :ok | {:error, term()}
```

Invalidates all cache entries associated with the given tags.

Tags allow for bulk invalidation of related cache entries. When a tag is
invalidated, all cache entries that were stored with that tag are removed.

## Parameters

- `tags` - List of tag names to invalidate

# `put`

```elixir
@callback put(key(), value(), ttl_ms(), opts()) :: :ok | {:error, term()}
```

Stores a value in the cache with the given key and TTL.

# `spec_config`

```elixir
@callback spec_config() :: [Supervisor.child_spec()] | [Supervisor.module_spec()]
```

Returns the adapter specification configuration.

This should return a keyword list of configuration options specific to the adapter.

Called by `Lotus.Supervisor` to start the cache adapter under the supervisor.

# `touch`

```elixir
@callback touch(key(), ttl_ms()) :: :ok | {:error, term()}
```

Updates the TTL of an existing cache entry without modifying its value.

# `decode`

Decodes a binary back into its original term.

# `encode`

Encodes a value into a binary for storage.

The `compress` flag indicates whether to use compression.

---

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