shelf

Types

Config

opaque </>

Configuration for opening a persistent table.

pub opaque type Config

ShelfError

</>

pub type ShelfError {
  NotFound
  KeyAlreadyPresent
  TableClosed
  NotOwner
  FileError(String)
  NameConflict
  InvalidPath(String)
  FileSizeLimitExceeded
  TypeMismatch(List(decode.DecodeError))
  ErlangError(String)
}

Constructors

```
NotFound
```
No value found for the given key
```
KeyAlreadyPresent
```
Key already exists (for insert_new)
```
TableClosed
```
Table has been closed or doesn’t exist
```
NotOwner
```
The calling process is not the table owner.

ETS tables are protected — only the process that called open() can perform writes and lifecycle operations. Other processes can read freely. Wrap the table in a supervised actor/server if you need cross-process writes.
```
FileError(String)
```
DETS file could not be found or created
```
NameConflict
```
A DETS file at this path is already open by another shelf table. This is a file-level conflict, not related to the table name.
```
InvalidPath(String)
```
The DETS file path is invalid (escapes base directory, contains null bytes, or is otherwise unsafe)
```
FileSizeLimitExceeded
```
DETS file exceeds the 2 GB limit
```
TypeMismatch(List(decode.DecodeError))
```
Data loaded from DETS did not match the expected types.

Returned when opening a table whose DETS file contains entries that fail to decode with the provided key/value decoders. The list of DecodeErrors describes which fields failed and why.
```
ErlangError(String)
```
Erlang-level error (catch-all)

WriteMode

</>

Controls when writes are persisted to disk.

pub type WriteMode {
  WriteBack
  WriteThrough
}

Constructors

```
WriteBack
```
Writes go to ETS only. Call save() to persist.

Best for high-throughput writes where you control the save schedule. Data written since the last save() is lost on crash.
```
WriteThrough
```
Every write goes to both ETS and DETS immediately.

Slower writes but no data loss between saves. Reads are still fast (always from ETS).

Values

config

</>

pub fn config(
  name name: String,
  path path: String,
  base_directory base_directory: String,
) -> Config

Create a config with defaults (WriteBack mode).

The name is a diagnostic label for the table — it is not used as an ETS table name and does not need to be unique. Multiple tables can share the same name as long as they use different DETS file paths.

The base_directory restricts DETS file paths to prevent directory traversal attacks. The path is resolved relative to base_directory.

let conf = shelf.config(name: "users", path: "users.dets",
  base_directory: "/app/data")

write_mode

</>

pub fn write_mode(
  config config: Config,
  mode mode: WriteMode,
) -> Config

Set the write mode on a config.

let conf =
  shelf.config(name: "users", path: "users.dets",
    base_directory: "/app/data")
  |> shelf.write_mode(shelf.WriteThrough)