<!--
This file was generated by Spark. Do not edit it by hand.
-->
# AshCache.Resource

Caches the read and generic actions you declare, each with its own lifetime.

    defmodule MyApp.Shop.Product do
      use Ash.Resource,
        domain: MyApp.Shop,
        extensions: [AshCache.Resource]

      cache do
        read :get_by_sku, ttl: :timer.hours(1)
        action :exchange_rate, ttl: :timer.minutes(10)
        calculation :shipping_quote, ttl: :timer.hours(1)
      end
    end

Each `read` is cached, keyed by the action, the whole query, the actor and
the tenant (see `AshCache.Key`). A `read` lives as long as its own `ttl`,
else the block's `ttl` (5 minutes by default); empty results are not
cached unless you ask. Entries go in the shared `:ash_cache` store unless you
set `store`. Every create, update or destroy clears the resource's cached
reads after the transaction commits (see `AshCache.Changes.InvalidateCache`).
So does a write to any resource listed in `clear_when_changed`.

Each `action` caches a generic action, keyed by the action, its arguments,
the actor and the tenant, with the same `ttl` rules. On a hit its `run` is
not called (see `AshCache.Actions.RunThrough`). Writes clear these entries
too.

Each `calculation` caches a module calculation's result per record, keyed
by its arguments, the actor, the tenant and every value it can read from
the record (see `AshCache.Calculations.CalculateThrough`). It lives as
long as its own `ttl`, else the block's. Writes do not clear these
entries: a changed record gives a new key. Expression calculations are
rejected; they already run in the database and cached reads hold them.

Actions and calculations without an entry are never cached.


## cache
Which reads, generic actions and calculations to cache, where, and for how long.

### Nested DSLs
 * [read](#cache-read)
 * [action](#cache-action)
 * [calculation](#cache-calculation)
 * [refresh](#cache-refresh)


### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`store`](#cache-store){: #cache-store } | `atom` | `:ash_cache` | Name of the cache store. Distinct stores isolate eviction and clearing. With `AshCache.Store.Adapters.Nebulex`, the Nebulex cache module. |
| [`ttl`](#cache-ttl){: #cache-ttl } | `pos_integer \| :infinity` | `300000` | Milliseconds a cached entry lives before it expires, for every `read`, `action` and `calculation` that does not set its own `ttl`. `:infinity` never expires; it is never the default. |
| [`clear_when_changed`](#cache-clear_when_changed){: #cache-clear_when_changed } | `list(atom)` | `[]` | Other resources whose create, update or destroy also clears this resource's cached reads and generic actions, e.g. `clear_when_changed [MyApp.Blog.Comment]`. Each one must use the `AshCache.Resource` extension, even if it caches nothing itself. |


### cache.read
```elixir
read name
```


Cache this read action, with its own lifetime and settings.


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#cache-read-name){: #cache-read-name .spark-required} | `atom` |  | The read action to cache. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`ttl`](#cache-read-ttl){: #cache-read-ttl } | `pos_integer \| :infinity` |  | Milliseconds a cached entry of this read lives before it expires, or `:infinity` to never expire. Defaults to the `cache` block's `ttl`. |
| [`cache_empty?`](#cache-read-cache_empty?){: #cache-read-cache_empty? } | `boolean` | `false` | Whether empty results ([] or nil) are cached. Off by default. |
| [`store_options`](#cache-read-store_options){: #cache-read-store_options } | `keyword` | `[]` | Options passed verbatim to the store adapter's put/4. Couples the resource to that adapter. |


### Introspection

Target: `AshCache.CachedRead`

### cache.action
```elixir
action name
```


Cache this generic action, with its own lifetime and settings.


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#cache-action-name){: #cache-action-name .spark-required} | `atom` |  | The generic action to cache. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`ttl`](#cache-action-ttl){: #cache-action-ttl } | `pos_integer \| :infinity` |  | Milliseconds a cached entry of this read lives before it expires, or `:infinity` to never expire. Defaults to the `cache` block's `ttl`. |
| [`cache_empty?`](#cache-action-cache_empty?){: #cache-action-cache_empty? } | `boolean` | `false` | Whether empty results ([] or nil) are cached. Off by default. |
| [`store_options`](#cache-action-store_options){: #cache-action-store_options } | `keyword` | `[]` | Options passed verbatim to the store adapter's put/4. Couples the resource to that adapter. |


### Introspection

Target: `AshCache.CachedAction`

### cache.calculation
```elixir
calculation name
```


Cache this module calculation's result per record, with its own lifetime.


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#cache-calculation-name){: #cache-calculation-name .spark-required} | `atom` |  | The calculation to cache. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`ttl`](#cache-calculation-ttl){: #cache-calculation-ttl } | `pos_integer \| :infinity` |  | Milliseconds a cached entry of this read lives before it expires, or `:infinity` to never expire. Defaults to the `cache` block's `ttl`. |
| [`store_options`](#cache-calculation-store_options){: #cache-calculation-store_options } | `keyword` | `[]` | Options passed verbatim to the store adapter's put/4. Couples the resource to that adapter. |


### Introspection

Target: `AshCache.CachedCalculation`

### cache.refresh
```elixir
refresh read
```


Re-run a read after every successful create/update so the fresh value is
cached immediately (write-through), e.g. `refresh :get_by_key, arguments: [key: :key]`.


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`read`](#cache-refresh-read){: #cache-refresh-read .spark-required} | `atom` |  | The cached read action to refresh. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`arguments`](#cache-refresh-arguments){: #cache-refresh-arguments } | `keyword` | `[]` | Read arguments as `argument_name: record_attribute` pairs. |
| [`actor`](#cache-refresh-actor){: #cache-refresh-actor } | `nil \| mfa` |  | MFA returning the actor to refresh as. Refreshed entries are cached under this actor's key, so it must match how the read is normally called. |


### Introspection

Target: `AshCache.Refresh`


<style type="text/css">.spark-required::after { content: "*"; color: red !important; }</style>