# `FeoxDB`
[🔗](https://github.com/ziinc/feoxdb-ex/blob/v0.2.0/lib/feox_db.ex#L1)

Elixir bindings for [FeOxDB](https://feoxdb.com), an embedded key-value
store written in Rust.

A `FeoxDB` store can run purely in memory, or persist to disk in the
background. See the project PRD (`docs/PRD.md`) for the full design
rationale, including which operations run as plain, dirty, or (eventually)
chunked NIFs.

## Example

    {:ok, store} = FeoxDB.open()
    :ok = FeoxDB.insert(store, "key", "value")
    {:ok, "value"} = FeoxDB.get(store, "key")
    :ok = FeoxDB.close(store)

A store's native resources are released when the resource reference is
garbage collected, but for disk-backed stores this can leave background
writer / TTL sweeper threads (and open file handles) alive for longer than
expected. Call `close/1` once you are done with a store to release those
resources deterministically instead of waiting on the GC.

# `error_reason`

```elixir
@type error_reason() ::
  :not_found
  | :out_of_memory
  | :out_of_space
  | :older_timestamp
  | :invalid_json
  | :invalid_key_size
  | :invalid_value_size
  | :key_too_large
  | :value_too_large
  | :database_full
  | :invalid_range
  | :ttl_not_enabled
  | :invalid_argument
  | :corrupted_data
  | :duplicate_key
  | :size_mismatch
  | :stale_extent
  | :io_error
  | :timeout
  | :not_implemented
  | :unsupported
  | :unknown_error
  | :limit_too_large
  | :closed
```

# `key`

```elixir
@type key() :: binary()
```

# `store`

```elixir
@type store() :: reference()
```

# `value`

```elixir
@type value() :: binary()
```

# `close`

```elixir
@spec close(store()) :: :ok
```

Closes a store, releasing its native resources (background writer / TTL
sweeper threads, and any open file handles for disk-backed stores)
deterministically instead of waiting for the resource reference to be
garbage collected.

Idempotent: calling `close/1` again on an already-closed store is a
no-op and returns `:ok`. Any other operation on a closed store returns
`{:error, :closed}` rather than raising or crashing.

# `compare_and_swap`

```elixir
@spec compare_and_swap(store(), key(), value(), value()) ::
  {:ok, boolean()} | {:error, error_reason()}
```

Atomically replaces `key`'s value with `new_value` if it currently equals
`expected`.

Returns `{:error, :key_too_large}` if `key` is larger than
102400 bytes, or `{:error, :value_too_large}` if `expected` or
`new_value` is larger than 4194304 bytes, without calling into
native code.

# `delete`

```elixir
@spec delete(store(), key()) :: :ok | {:error, error_reason()}
```

Deletes `key`.

Returns `{:error, :key_too_large}` if `key` is larger than 102400
bytes, without calling into native code.

# `flush`

```elixir
@spec flush(store()) :: :ok | {:error, error_reason()}
```

Flushes all buffered writes to disk.

Runs as a dirty I/O NIF (PRD section 5) because it waits for `fsync`.
No-op for memory-only stores.

# `get`

```elixir
@spec get(store(), key()) :: {:ok, value()} | {:error, error_reason()}
```

Retrieves the value for `key`.

Returns `{:error, :key_too_large}` if `key` is larger than 102400
bytes, without calling into native code.

# `get!`

```elixir
@spec get!(store(), key()) :: value()
```

Same as `get/2` but raises `FeoxDB.Error` on failure.

# `increment`

```elixir
@spec increment(store(), key(), integer()) ::
  {:ok, integer()} | {:error, error_reason()}
```

Atomically adds `delta` to the integer stored at `key` and returns the new
value.

The value is stored internally as an 8-byte little-endian `i64`; this
function takes and returns a plain Elixir integer; the little-endian
conversion happens on the Rust side; there is no `<<n::signed-little-64>>`
to get wrong (PRD section 7).

Returns `{:error, :key_too_large}` if `key` is larger than 102400
bytes, without calling into native code.

# `insert`

```elixir
@spec insert(store(), key(), value(), keyword()) :: :ok | {:error, error_reason()}
```

Inserts or updates `key` with `value`.

Pass `ttl: seconds` to set an expiry (requires `enable_ttl: true` at
`open/1` time).

Returns `{:error, :key_too_large}` if `key` is larger than
102400 bytes, or `{:error, :value_too_large}` if `value` is
larger than 4194304 bytes, without calling into native code.

# `insert!`

```elixir
@spec insert!(store(), key(), value(), keyword()) :: :ok
```

Same as `insert/4` but raises `FeoxDB.Error` on failure.

# `json_patch`

```elixir
@spec json_patch(store(), key(), binary()) :: :ok | {:error, error_reason()}
```

Applies an RFC 6902 JSON patch to the JSON document stored at `key`.

Returns `{:error, :key_too_large}` if `key` is larger than
102400 bytes, or `{:error, :value_too_large}` if `patch` is
larger than 4194304 bytes, without calling into native code.

# `max_key_size`

```elixir
@spec max_key_size() :: pos_integer()
```

Returns the largest key, in bytes, the store accepts.

# `max_value_size`

```elixir
@spec max_value_size() :: pos_integer()
```

Returns the largest value, in bytes, a single record accepts. Use
`FeoxDB.Term` to store larger values in chunks.

# `member?`

```elixir
@spec member?(store(), key()) :: boolean() | {:error, error_reason()}
```

Returns whether `key` exists in the store.

A `key` larger than 102400 bytes can never have been inserted
(see `insert/4`), so this returns `false` for it directly, without calling
into native code.

# `memory_usage`

```elixir
@spec memory_usage(store()) :: non_neg_integer() | {:error, error_reason()}
```

Returns the store's memory usage, in bytes.

# `open`

```elixir
@spec open(keyword()) :: {:ok, store()} | {:error, error_reason()}
```

Opens a `FeoxDB` store.

With no options, the store is memory-only. Pass `path:` to persist to
disk.

## Options

  * `:path` - device path for persistent storage. When omitted, the store
    is memory-only.
  * `:file_size` - initial file size in bytes for a new persistent store.
  * `:max_memory` - maximum memory usage in bytes. Defaults to the
    upstream FeOxDB default (1GB) when a persistent path is given, or
    unlimited for memory-only stores unless set explicitly.
  * `:hash_bits` - number of hash table bits (bucket count is `2^bits`).
  * `:enable_ttl` - enables TTL support (`ttl/2`, `update_ttl/3`,
    `persist/2`, and TTL-bearing inserts). Defaults to `false`.

# `open!`

```elixir
@spec open!(keyword()) :: store()
```

Same as `open/1` but raises `FeoxDB.Error` on failure.

# `persist`

```elixir
@spec persist(store(), key()) :: :ok | {:error, error_reason()}
```

Removes `key`'s TTL, making it permanent.

Returns `{:error, :key_too_large}` if `key` is larger than 102400
bytes, without calling into native code.

# `range`

```elixir
@spec range(store(), key(), key(), pos_integer()) ::
  {:ok, [{key(), value()}]} | {:error, error_reason()}
```

Returns up to `limit` key-value pairs with keys in `[start_key, end_key]`
(both bounds inclusive), ordered by key.

`limit` is required: an unbounded range query could run for an unknown
time on the scheduler and build an unbounded term (PRD section 7). `limit`
must also not exceed 10000; larger values return
`{:error, :limit_too_large}` without reaching the native code, since the
native side allocates a `Vec` sized to `limit`.

Runs as a dirty I/O NIF, since the cost of a scan depends on `limit`.

Returns `{:error, :key_too_large}` if `start_key` or `end_key` is larger
than 102400 bytes, without calling into native code.

# `size`

```elixir
@spec size(store()) :: non_neg_integer() | {:error, error_reason()}
```

Returns the number of records in the store.

# `stats`

```elixir
@spec stats(store()) :: map() | {:error, error_reason()}
```

Returns a snapshot of the store's internal statistics as a map.

# `ttl`

```elixir
@spec ttl(store(), key()) :: {:ok, non_neg_integer() | nil} | {:error, error_reason()}
```

Returns the remaining TTL in seconds for `key`, or `nil` if it has none.

Returns `{:error, :key_too_large}` if `key` is larger than 102400
bytes, without calling into native code.

# `update_ttl`

```elixir
@spec update_ttl(store(), key(), pos_integer()) :: :ok | {:error, error_reason()}
```

Sets `key`'s TTL to `seconds` from now.

Returns `{:error, :key_too_large}` if `key` is larger than 102400
bytes, without calling into native code.

---

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