slate/set

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 objects in the table (keeps 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.

This operation is idempotent — deleting a key that does not exist succeeds with Ok(Nil).

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 fun: fn(acc, k, v) -> acc,
) -> Result(acc, slate.DetsError)

Fold over all entries. Order is unspecified.

Returns Error(DecodeErrors(_)) if any entry doesn’t 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 fun: fn(acc, Result(#(k, v), List(decode.DecodeError))) -> acc,
) -> Result(acc, slate.DetsError)

Fold over all entries, passing decode results to the callback.

Unlike fold, decode failures do not abort the traversal. Each entry is presented to the callback as Ok(#(key, value)) on success or Error(decode_errors) on failure, letting the caller decide how to handle bad records.

DETS-level errors (e.g., the table does not exist) still fail the entire operation via the outer Result. If the callback raises, the exception is re-raised.

Examples

Skip entries that fail to decode:

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

Partition into successes and failures:

set.fold_results(table, #([], []), fn(acc, entry) {
  case entry {
    Ok(#(k, v)) -> #([#(k, v), ..acc.0], acc.1)
    Error(errs) -> #(acc.0, [errs, ..acc.1])
  }
})

info

</>

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

Get information about an open table.

insert

</>

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

Insert a key-value pair. Overwrites if key exists.

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 doesn’t match the expected type.

Note: For bag and duplicate bag tables, lookup returns Ok([]) for missing keys instead of Error(NotFound), since those table types naturally return a list of values.

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.

Decoders are used to validate data read from disk, ensuring type safety even when opening files created by other code or previous runs.

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 (e.g., after a crash):

AutoRepair — silently repair the file if needed (default for open)
ForceRepair — repair even if the file appears clean
NoRepair — return an error instead of repairing

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).

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(val) = set.lookup(table, key: "key")
// set.insert(table, "key", "val") would return Error(AccessDenied)

size

</>

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

Return the number of objects stored.

sync

</>

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

Flush pending writes to disk without closing the table.

DETS auto-syncs periodically, so this is only needed when you require a durability guarantee at a specific point (e.g., after a critical write).

to_list

</>

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

Return all key-value pairs as a list.

Warning: loads entire table into memory. Returns Error(DecodeErrors(_)) if any entry doesn’t 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 doesn’t 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_table

</>

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

Use a table within a callback, ensuring it is closed afterward.

This is the recommended way to use DETS tables for short-lived operations. Opens with AutoRepair and ReadWrite access; use open_with_access and manual close if you need different settings.

If both the callback and close fail, the callback error is returned. If the callback raises an exception, close is attempted before re-raising.

import gleam/dynamic/decode
use table <- set.with_table("data/cache.dets",
  key_decoder: decode.string, value_decoder: decode.string)
set.insert(table, "key", "value")