slate/set

DETS set tables: one value per key.

Set tables store key-value pairs where each key maps to exactly one value. Inserting with an existing key overwrites the previous value.

Example

import gleam/dynamic/decode
import slate/set

let assert Ok(table) = set.open("users.dets",
  key_decoder: decode.string, value_decoder: decode.int)
let assert Ok(Nil) = set.insert(table, "alice", 42)
let assert Ok(42) = set.lookup(table, "alice")
let assert Ok(Nil) = set.close(table)

Types

Set

opaque </>

An open DETS set table with typed keys and values.

pub opaque type Set(k, v)

UpdateCounterError

</>

Errors returned by update_counter.

pub type UpdateCounterError {
  CounterValueNotInteger
  TableError(slate.DetsError)
}

Constructors

```
CounterValueNotInteger
```
update_counter requires the stored value to be an integer.
```
TableError(slate.DetsError)
```
A shared DETS table error from the underlying operation.

Values

close

</>

pub fn close(table: Set(k, v)) -> Result(Nil, slate.DetsError)

Close the table, flushing all pending writes to disk.

The table handle must not be used after closing.

delete_all

</>

pub fn delete_all(
  from table: Set(k, v),
) -> Result(Nil, slate.DetsError)

Delete all entries and keep the table open.

delete_key

</>

pub fn delete_key(
  from table: Set(k, v),
  key key: k,
) -> Result(Nil, slate.DetsError)

Delete the entry with the given key.

Returns Ok(Nil) even if the key does not exist.

delete_object

</>

pub fn delete_object(
  from table: Set(k, v),
  key key: k,
  value value: v,
) -> Result(Nil, slate.DetsError)

Delete a specific key-value pair from the table.

Unlike delete_key, this only removes the entry if both the key and value match. For set tables, this acts as a conditional delete: the entry is removed only when the stored value equals the given value.

fold

</>

pub fn fold(
  over table: Set(k, v),
  from initial: acc,
  with callback: fn(acc, k, v) -> acc,
) -> Result(acc, slate.DetsError)

Fold over all entries. Order is unspecified.

Returns Error(DecodeErrors(_)) if any entry does not match the expected types. The fold stops at the first decode error. If the callback raises, the exception is re-raised.

fold_results

</>

pub fn fold_results(
  over table: Set(k, v),
  from initial: acc,
  with callback: fn(
    acc,
    Result(#(k, v), List(decode.DecodeError)),
  ) -> acc,
) -> Result(acc, slate.DetsError)

Call your callback once for each entry, in an unspecified order.

Pass the decoded entry as Ok(#(key, value)), or its decode errors as Error(decode_errors). The callback returns the next accumulator value. Unlike fold, this function continues after a decode error.

The function returns Ok(accumulator) when it finishes. A table error, such as TableDoesNotExist, makes the function return Error(error). If the callback raises an exception, that exception propagates to the caller.

Examples

Skip entries that fail to decode:

set.fold_results(table, [], fn(acc, entry) {
  case entry {
    Ok(#(key, value)) -> [#(key, value), ..acc]
    Error(_) -> acc
  }
})

Collect decoded entries and decode errors separately:

set.fold_results(table, #([], []), fn(acc, entry) {
  case entry {
    Ok(#(key, value)) -> #([#(key, value), ..acc.0], acc.1)
    Error(errors) -> #(acc.0, [errors, ..acc.1])
  }
})

info

</>

pub fn info(
  table: Set(k, v),
) -> Result(slate.TableInfo, slate.DetsError)

Get the file size in bytes, entry count, and absolute path of an open table.

Returns Error(TableDoesNotExist) if the table is no longer open.

insert

</>

pub fn insert(
  into table: Set(k, v),
  key key: k,
  value value: v,
) -> Result(Nil, slate.DetsError)

Insert a key-value pair. If the key exists, replace its value.

insert_list

</>

pub fn insert_list(
  into table: Set(k, v),
  entries entries: List(#(k, v)),
) -> Result(Nil, slate.DetsError)

Insert multiple key-value pairs.

insert_new

</>

pub fn insert_new(
  into table: Set(k, v),
  key key: k,
  value value: v,
) -> Result(Nil, slate.DetsError)

Insert only if the key does not already exist.

Returns Error(KeyAlreadyPresent) if the key exists.

lookup

</>

pub fn lookup(
  from table: Set(k, v),
  key key: k,
) -> Result(v, slate.DetsError)

Look up the value for a key.

Returns Error(NotFound) if the key does not exist. Returns Error(DecodeErrors(_)) if the stored value does not match the expected type.

For bag and duplicate bag tables, lookup returns Ok([]) for missing keys instead of Error(NotFound).

member

</>

pub fn member(
  of table: Set(k, v),
  key key: k,
) -> Result(Bool, slate.DetsError)

Check if a key exists without returning the value.

open

</>

pub fn open(
  path: String,
  key_decoder key_decoder: decode.Decoder(k),
  value_decoder value_decoder: decode.Decoder(v),
) -> Result(Set(k, v), slate.DetsError)

Open or create a DETS set table at the given file path.

The parent directory must exist. This function uses AutoRepair and ReadWrite.

Reads use your decoders to check stored data. Opening a table does not check all its entries.

import gleam/dynamic/decode
let assert Ok(table) = set.open("data/cache.dets",
  key_decoder: decode.string, value_decoder: decode.int)

open_with

</>

pub fn open_with(
  path path: String,
  repair repair: slate.RepairPolicy,
  key_decoder key_decoder: decode.Decoder(k),
  value_decoder value_decoder: decode.Decoder(v),
) -> Result(Set(k, v), slate.DetsError)

Open or create a DETS set table with a specific repair policy.

The repair policy controls what happens when the table file was not closed cleanly, for example after an abnormal node shutdown:

AutoRepair: Attempt repair if needed. This is the default for open.
ForceRepair: Repair even if the file was closed properly.
NoRepair: Return NeedsRepair if the file requires repair.

Make a backup before you repair a file with data you need to keep. Repair does not guarantee recovery of all data.

import gleam/dynamic/decode
import slate.{ForceRepair}
let assert Ok(table) = set.open_with(path: "data/cache.dets",
  repair: ForceRepair,
  key_decoder: decode.string, value_decoder: decode.int)

open_with_access

</>

pub fn open_with_access(
  path path: String,
  repair repair: slate.RepairPolicy,
  access access: slate.AccessMode,
  key_decoder key_decoder: decode.Decoder(k),
  value_decoder value_decoder: decode.Decoder(v),
) -> Result(Set(k, v), slate.DetsError)

Open a DETS set table with repair and access mode options.

Use ReadOnly to open a table for reading only. Write operations on a read-only table will return Error(AccessDenied(context)).

import gleam/dynamic/decode
import slate.{AutoRepair, ReadOnly}
let assert Ok(table) = set.open_with_access(path: "data/cache.dets",
  repair: AutoRepair, access: ReadOnly,
  key_decoder: decode.string, value_decoder: decode.string)
let assert Ok(value) = set.lookup(table, key: "key")
// set.insert(table, "key", "val") would return Error(AccessDenied(context))

size

</>

pub fn size(of table: Set(k, v)) -> Result(Int, slate.DetsError)

Return the number of stored entries. Each entry is one key-value pair.

sync

</>

pub fn sync(table: Set(k, v)) -> Result(Nil, slate.DetsError)

Flush pending writes to disk without closing the table.

By default, DETS saves the table after three minutes without table access. Call sync and handle its result when you need to write pending updates to disk before continuing.

to_list

</>

pub fn to_list(
  from table: Set(k, v),
) -> Result(List(#(k, v)), slate.DetsError)

Return all entries as a list in an unspecified order.

This loads the entire table into memory. Returns Error(DecodeErrors(_)) if any entry does not match the expected types.

update_counter

</>

pub fn update_counter(
  in table: Set(k, Int),
  key key: k,
  increment amount: Int,
) -> Result(Int, UpdateCounterError)

Atomically increment a counter value by the given amount.

The value associated with the key must be an integer. Returns the new value after incrementing. The increment can be negative.

Returns Error(TableError(slate.NotFound)) if the key does not exist, Error(CounterValueNotInteger) if the stored value is not an integer, or Error(TableError(error)) for other DETS table failures.

import gleam/dynamic/decode
let assert Ok(table) = set.open("counters.dets",
  key_decoder: decode.string, value_decoder: decode.int)
let assert Ok(Nil) = set.insert(table, "hits", 0)
let assert Ok(1) = set.update_counter(table, "hits", 1)
let assert Ok(3) = set.update_counter(table, "hits", 2)

with_exclusive_table

</>

pub fn with_exclusive_table(
  path path: String,
  repair repair: slate.RepairPolicy,
  access access: slate.AccessMode,
  wait wait: exclusive.Wait,
  key_decoder key_decoder: decode.Decoder(k),
  value_decoder value_decoder: decode.Decoder(v),
  callback callback: fn(Set(k, v)) -> Result(a, slate.DetsError),
) -> Result(a, exclusive.SessionError)

Use a table under exclusive ownership across OS processes.

All clients of this file, including readers, must use exclusive sessions. Ownership is acquired before open or repair, and released after clean close. wait limits acquisition only; it does not cancel an acquired callback.

Keep the handle and all table work within this callback. Do not reopen or manually close this table. A nested same-file session contends for ownership. Callback errors do not undo earlier writes. Exceptions are re-raised after cleanup; cleanup failures on this path are logged. If cleanup cannot confirm closure, ownership may remain until the VM exits.

Requires the native lock component and a qualified local filesystem. Symlinks are resolved; hard-linked data files and unsafe sidecars are rejected. Do not replace data paths or sidecars while clients can start sessions.

with_table

</>

pub fn with_table(
  path path: String,
  repair repair: slate.RepairPolicy,
  access access: slate.AccessMode,
  key_decoder key_decoder: decode.Decoder(k),
  value_decoder value_decoder: decode.Decoder(v),
  callback callback: fn(Set(k, v)) -> Result(a, slate.DetsError),
) -> Result(a, slate.DetsError)

Use a table within a callback with repair and access mode options.

Select the repair policy and access mode as for open_with_access. The callback must return a Result. ReadOnly requires an existing file, and writes return Error(AccessDenied(context)). NoRepair returns Error(NeedsRepair(context)) if the file was not closed cleanly.

If opening fails, returns the open error without calling the callback. Otherwise, runs the callback and attempts to close the table. If close fails after a successful callback, returns the close error. If both fail, returns the callback error. If the callback raises, attempts close before re-raising the original exception.

Keep the table handle within the callback; do not use it after cleanup. This cannot guarantee cleanup if the process is killed.

import gleam/dynamic/decode
import slate.{NoRepair, ReadOnly}
import slate/set

use table <- set.with_table(path: "data/cache.dets",
  repair: NoRepair, access: ReadOnly,
  key_decoder: decode.string, value_decoder: decode.string)
set.lookup(table, key: "key")