# `AshCache`
[🔗](https://github.com/Undeadlol1/ash_cache/blob/v0.1.0/lib/ash_cache.ex#L1)

Declarative read-through caching for Ash read and generic actions. See
`AshCache.Resource` for the DSL and `README.md` in this directory for the design.

These helpers are the runtime escape hatch for operational situations
(a support task, a migration) that need to reach past the declarative
layer.

## Telemetry

Seven `:telemetry` events let you assert cache behaviour in tests and
measure hit rates in production. All have empty measurements. Calls that
are bypassed, or not cached, emit nothing. Actor and tenant are never in
the metadata.

  * `[:ash_cache, :read, :hit]` - a cached read was answered without the
    data layer: from the store, or with the records of an identical read
    running at the same time (see `AshCache.Coalesce`). Metadata:
    `:resource`, `:action`, `:store`.
  * `[:ash_cache, :read, :miss]` - a cached read was not in the store and
    went to the data layer. Metadata: `:resource`, `:action`, `:store`,
    and `:error`, which is `nil` normally or the reason when the store
    failed to answer (the read still goes through).
  * `[:ash_cache, :action, :hit]` and `[:ash_cache, :action, :miss]` -
    the same for a cached generic action, with the same metadata. A miss
    means the action's `run` was called.
  * `[:ash_cache, :calculation, :hit]` and `[:ash_cache, :calculation, :miss]` -
    the same for one record of a cached calculation (see
    `AshCache.Calculations.CalculateThrough`), with `:calculation` in place
    of `:action`. A miss means the calculation ran for that record.
  * `[:ash_cache, :invalidate]` - a resource's cache was invalidated, by
    a successful create, update or destroy or by `invalidate/1`.
    Metadata: `:resource`, `:store`.

# `clear_store`

```elixir
@spec clear_store(atom()) :: :ok | {:error, term()}
```

Clears a whole store, including other resources' entries.

# `invalidate`

```elixir
@spec invalidate(Ash.Resource.t()) :: :ok | {:error, term()}
```

Invalidates every cached read and generic action of a resource, exactly
like a successful write does.

---

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