# `Nebulex.Adapter.KV`
[🔗](https://github.com/elixir-nebulex/nebulex/blob/v3.0.3/lib/nebulex/adapter/kv.ex#L1)

Specifies the adapter Key/Value API.

This behaviour specifies all read/write key-based functions,
applied to a specific cache key.

# `adapter_meta`

```elixir
@type adapter_meta() :: Nebulex.Adapter.adapter_meta()
```

Proxy type to the adapter meta

# `entries`

```elixir
@type entries() :: Nebulex.Cache.entries()
```

Proxy type to the cache entries

# `keep_ttl`

```elixir
@type keep_ttl() :: boolean()
```

Keep TTL flag

# `key`

```elixir
@type key() :: Nebulex.Cache.key()
```

Proxy type to the cache key

# `on_write`

```elixir
@type on_write() :: :put | :put_new | :replace
```

Write command type

# `opts`

```elixir
@type opts() :: Nebulex.Cache.opts()
```

Proxy type to the cache options

# `ttl`

```elixir
@type ttl() :: timeout()
```

TTL for a cache entry

# `value`

```elixir
@type value() :: Nebulex.Cache.value()
```

Proxy type to the cache value

# `delete`

```elixir
@callback delete(adapter_meta(), key(), opts()) :: :ok | Nebulex.Cache.error_tuple()
```

Deletes a single entry from cache.

If there's an error with executing the command, `{:error, reason}`
is returned, where `reason` is the cause of the error.

See `c:Nebulex.Cache.delete/2`.

# `expire`

```elixir
@callback expire(adapter_meta(), key(), ttl(), opts()) ::
  Nebulex.Cache.ok_error_tuple(boolean())
```

Returns `{:ok, true}` if the given `key` exists and the new `ttl` is
successfully updated; otherwise, `{:ok, false}` is returned.

If there's an error with executing the command, `{:error, reason}`
is returned; where `reason` is the cause of the error.

See `c:Nebulex.Cache.expire/3`.

# `fetch`

```elixir
@callback fetch(adapter_meta(), key(), opts()) ::
  Nebulex.Cache.ok_error_tuple(value(), Nebulex.Cache.fetch_error_reason())
```

Fetches the value for a specific `key` in the cache.

If the cache contains the given `key`, then its value is returned
in the shape of `{:ok, value}`.

If there's an error with executing the command, `{:error, reason}`
is returned. `reason` is the cause of the error and can be
`Nebulex.KeyError` if the cache does not contain `key`,
`Nebulex.Error` otherwise.

See `c:Nebulex.Cache.fetch/2`.

# `has_key?`

```elixir
@callback has_key?(adapter_meta(), key(), opts()) ::
  Nebulex.Cache.ok_error_tuple(boolean())
```

Determines if the cache contains an entry for the specified `key`.

More formally, it returns `{:ok, true}` if the cache contains the given `key`.
If the cache doesn't contain `key`, `{:ok, false}` is returned.

If there's an error with executing the command, `{:error, reason}`
is returned, where `reason` is the cause of the error.

See `c:Nebulex.Cache.has_key?/2`.

# `put`

```elixir
@callback put(adapter_meta(), key(), value(), on_write(), ttl(), keep_ttl(), opts()) ::
  Nebulex.Cache.ok_error_tuple(boolean())
```

Puts the given `value` under `key` into the `cache`.

Returns `{:ok, true}` if the `value` with key `key` is successfully inserted.
Otherwise, `{:ok, false}` is returned.

If there's an error with executing the command, `{:error, reason}`
is returned, where `reason` is the cause of the error.

The `ttl` argument defines the time-to-live for the stored entry. If it is not
set, it means the entry doesn't have a time-to-live, so it shouldn't expire.

The `keep_ttl` argument tells whether to retain the time to live associated
with the key. Otherwise, the TTL is always overwritten.

## `on_write` argument

The `on_write` argument supports the following values:

  * `:put` - If the `key` already exists, it is overwritten. Any previous
    time-to-live associated with the key is discarded on a successful `write`
    operation.

  * `:put_new` - It only stores the entry if the `key` does not exist.
    Otherwise, `{:ok, false}` is returned.

  * `:replace` - Alters the value stored under the given `key`, but only
    if the key already exists in the cache. Otherwise, `{ok, false}` is
    returned.

See `c:Nebulex.Cache.put/3`, `c:Nebulex.Cache.put_new/3`,
`c:Nebulex.Cache.replace/3`.

# `put_all`

```elixir
@callback put_all(adapter_meta(), entries(), on_write(), ttl(), opts()) ::
  Nebulex.Cache.ok_error_tuple(boolean())
```

Puts the given `entries` (key/value pairs) into the `cache` atomically
or fail otherwise.

If there's an error with executing the command, `{:error, reason}`
is returned, where `reason` is the cause of the error.

The `ttl` argument works the same as `c:put/7` but applies to all keys.

## `on_write` argument

The `on_write` argument supports the following values:

  * `:put` - If the `key` already exists, it is overwritten. Any previous
    time-to-live associated with the key is discarded on a successful `write`
    operation.

  * `:put_new` - Insert all entries only if none exist in the cache, and it
    returns `{:ok, true}` . Otherwise, `{:ok, false}` is returned.

See `c:Nebulex.Cache.put_all/2` and `c:Nebulex.Cache.put_new_all/2`.

# `take`

```elixir
@callback take(adapter_meta(), key(), opts()) ::
  Nebulex.Cache.ok_error_tuple(value(), Nebulex.Cache.fetch_error_reason())
```

Removes and returns the value associated with `key` in the cache.

If `key` is present in the cache, its value is removed and returned as
`{:ok, value}`.

If there's an error with executing the command, `{:error, reason}`
is returned. `reason` is the cause of the error and can be
`Nebulex.KeyError` if the cache does not contain `key` or
`Nebulex.Error` otherwise.

See `c:Nebulex.Cache.take/2`.

# `touch`

```elixir
@callback touch(adapter_meta(), key(), opts()) :: Nebulex.Cache.ok_error_tuple(boolean())
```

Returns `{:ok, true}` if the given `key` exists and the last access time is
successfully updated; otherwise, `{:ok, false}` is returned.

If there's an error with executing the command, `{:error, reason}`
is returned, where `reason` is the cause of the error.

See `c:Nebulex.Cache.touch/2`.

# `ttl`

```elixir
@callback ttl(adapter_meta(), key(), opts()) ::
  Nebulex.Cache.ok_error_tuple(value(), Nebulex.Cache.fetch_error_reason())
```

Returns the remaining time-to-live for the given `key`.

If `key` is present in the cache, then its remaining TTL is returned
in the shape of `{:ok, ttl}`.

If there's an error with executing the command, `{:error, reason}`
is returned. `reason` is the cause of the error and can be
`Nebulex.KeyError` if the cache does not contain `key`,
`Nebulex.Error` otherwise.

See `c:Nebulex.Cache.ttl/2`.

# `update_counter`

```elixir
@callback update_counter(adapter_meta(), key(), amount, default, ttl(), opts()) ::
  Nebulex.Cache.ok_error_tuple(integer())
when amount: integer(), default: integer()
```

Updates the counter mapped to the given `key`.

If `amount` > 0, the counter is incremented by the given `amount`.
If `amount` < 0, the counter is decremented by the given `amount`.
If `amount` == 0, the counter is not updated.

If there's an error with executing the command, `{:error, reason}`
is returned, where `reason` is the cause of the error.

The `ttl` is set when the key doesn't exist. Otherwise, only the counter is
updated keeping the TTL when the counter was updated for the first time.

See `c:Nebulex.Cache.incr/3`.
See `c:Nebulex.Cache.decr/3`.

---

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