glindex

Core types and value converters for glindex.

This module exposes the fundamental building blocks used across the entire library. Use store and index to declare type-safe store and index definitions that bundle their name together with serialization and deserialization codecs. Use Query to target records by key, and the value helpers (int, string, float, object, …) to build the Values that IndexedDB operates on.

The recommended entry points for actual database work are:

glindex/database - open and manage databases.
glindex/upgrade - schema migrations inside a version-change transaction.
glindex/transaction - build and start transactions over one or more object stores.
glindex/store - read and write operations on object stores within a transaction.
glindex/index - read operations on indexes within a transaction.
glindex/cursor - cursor-based iteration over store or index records.

Types

Action

</>

Indicates whether a write operation is an insert or an upsert.

Passed to the to_value function of a Store so the serializer can produce a different object shape for each case - typically to omit the primary key field on Add when IndexedDB generates the key automatically, and to include it on Put so the existing record is correctly replaced.

pub type Action {
  Add
  Put
}

Constructors

```
Add
```
```
Put
```

Database

</>

Hold an IndexedDB database connection.

Obtained from glindex/database.open.

pub type Database

Index

opaque </>

A definition of an IndexedDB index, bundling its name with the codecs needed to serialize and decode the index key.

The phantom type store_type links the index to its parent store - the compiler will reject any attempt to use an index with a store of a different type.

Create one with index and pass it to transaction.index to obtain a handle for use inside a transaction:

pub fn track_artist_index() -> Index(TrackStore, _, _, _) {
  glindex.index(
    name: "tracks_artist",
    to_index_key: fn(artist: String) { glindex.string(artist) },
    index_key_decoder: decode.string,
  )
}

pub opaque type Index(store_type, t, k, i)

Query

</>

Specifies which records a store or index operation targets.

All - every record in the store or index.
Only(value) - the single record whose key equals value.
LowerBound(value, exclusive) - records with key ≥ value (or > when exclusive is True).
UpperBound(value, exclusive) - records with key ≤ value (or < when exclusive is True).
Bound(lower, upper, excl_lower, excl_upper) - records whose key falls within the given range.

pub type Query(v) {
  All
  Only(v)
  LowerBound(value: v, exclusive: Bool)
  UpperBound(value: v, exclusive: Bool)
  Bound(
    lower: v,
    upper: v,
    exclusive_lower: Bool,
    exclusive_upper: Bool,
  )
}

Constructors

```
All
```
```
Only(v)
```
```
LowerBound(value: v, exclusive: Bool)
```
```
UpperBound(value: v, exclusive: Bool)
```

Bound(
  lower: v,
  upper: v,
  exclusive_lower: Bool,
  exclusive_upper: Bool,
)

Store

opaque </>

A definition of an IndexedDB object store, bundling its name with the codecs needed to serialize records and keys to Value and decode them back.

Create one with store (inline key) or store_with_out_of_line_key (out-of-line key), then pass it to transaction.store to obtain a handle for use inside a transaction:

pub type TrackStore

pub fn track_store() -> Store(TrackStore, _, _, _) {
  glindex.store(
    name: "tracks",
    to_value: fn(track: Track, _action) { ... },
    decoder: track_decoder(),
    to_key: fn(id: Int) { glindex.int(id) },
    key_decoder: decode.int,
  )
}

pub opaque type Store(store_type, key_mode, t, k)

Value

</>

An opaque JavaScript value that IndexedDB can store or use as a key.

Convert Gleam values to Value using the helpers in this module: int, string, float, bool, bytea, array, object, and so on.

pub type Value

Values

array

</>

pub fn array(values: List(Value)) -> Value

Converts a list of Values to a JavaScript Array Value.

bool

</>

pub fn bool(a: Bool) -> Value

Converts a Bool to a Value.

bytea

</>

pub fn bytea(a: BitArray) -> Value

Converts a BitArray to a Value (stored as an ArrayBuffer).

calendar_date

</>

pub fn calendar_date(date: calendar.Date) -> Value

Converts a Date to an array Value of [year, month, day]. Use calendar_date_decoder to read it back.

calendar_date_decoder

</>

pub fn calendar_date_decoder() -> decode.Decoder(calendar.Date)

Decoder for a Date stored by calendar_date.

calendar_time_of_day

</>

pub fn calendar_time_of_day(time: calendar.TimeOfDay) -> Value

Converts a TimeOfDay to an array Value of [hours, minutes, seconds]. Use calendar_time_of_day_decoder to read it back.

calendar_time_of_day_decoder

</>

pub fn calendar_time_of_day_decoder() -> decode.Decoder(
  calendar.TimeOfDay,
)

Decoder for a TimeOfDay stored by calendar_time_of_day.

cmp

</>

pub fn cmp(a: Value, b: Value) -> order.Order

Compares two Values using IndexedDB’s built-in key comparison algorithm.

This mirrors the ordering IndexedDB uses internally for keys and ranges, which differs from JavaScript’s default < / > operators for certain types such as arrays.

float

</>

pub fn float(a: Float) -> Value

Converts a Float to a Value.

index

</>

pub fn index(
  name name: String,
  to_index_key to_index_key: fn(i) -> Value,
  index_key_decoder index_key_decoder: decode.Decoder(i),
) -> Index(store_type, t, k, i)

Create an index definition.

to_index_key converts a Gleam value into the Value used to query the index. index_key_decoder reads the raw index key back into a Gleam value when iterating via a cursor.

int

</>

pub fn int(a: Int) -> Value

Converts an Int to a Value.

map

</>

pub fn map(
  key_converter: fn(k) -> Value,
  value_converter: fn(v) -> Value,
  dict: dict.Dict(k, v),
) -> Value

Converts a Dict to a JavaScript Map Value.

Both keys and values are converted with the provided converter functions.

null

</>

pub fn null() -> Value

A Value representing JavaScript null.

object

</>

pub fn object(entries: List(#(String, Value))) -> Value

Converts a list of key-value pairs to a JavaScript object Value.

Example

glindex.object([
  #("title", glindex.string("Bohemian Rhapsody")),
  #("artist", glindex.string("Queen")),
  #("duration", glindex.int(354)),
])

set

</>

pub fn set(converter: fn(a) -> Value, values: List(a)) -> Value

Converts a list to a JavaScript Set Value.

store

</>

pub fn store(
  name name: String,
  to_value to_value: fn(t, Action) -> Value,
  decoder decoder: decode.Decoder(t),
  to_key to_key: fn(k) -> Value,
  key_decoder key_decoder: decode.Decoder(k),
) -> Store(store_type, @internal InlineKey, t, k)

Create a store definition with an inline key.

Use this when the primary key is a property of the stored object (i.e. the store was created with a KeyPath). The to_value function receives the record and an Action so you can omit the key field on Add when IndexedDB generates it automatically.

store_with_out_of_line_key

</>

pub fn store_with_out_of_line_key(
  name name: String,
  to_value to_value: fn(t, Action) -> Value,
  decoder decoder: decode.Decoder(t),
  to_key to_key: fn(k) -> Value,
  key_decoder key_decoder: decode.Decoder(k),
) -> Store(store_type, @internal OutOfLineKey, t, k)

Create a store definition with an out-of-line key.

Use this when the store was created with OutOfLineKey and the primary key is not embedded in the object. Write operations require supplying the key separately via store.add_with_out_of_line_key or store.put_with_out_of_line_key.

string

</>

pub fn string(a: String) -> Value

Converts a String to a Value.

timestamp

</>

pub fn timestamp(timestamp: timestamp.Timestamp) -> Value

Converts a Timestamp to a Value stored as microseconds since the Unix epoch. Use timestamp_decoder to read it back.

timestamp_decoder

</>

pub fn timestamp_decoder() -> decode.Decoder(timestamp.Timestamp)

Decoder for a Timestamp stored by timestamp.