lattice_registers

Last-writer-wins and multi-value CRDT registers for Gleam.

Use this package when replicas need to store a single logical value and resolve concurrent writes deterministically or explicitly expose conflicts.

Installation

gleam add lattice_registers

Quick example

import lattice_core/replica_id
import lattice_registers/lww_register

pub fn main() {
  let node_a = replica_id.new("node-a")

  let register =
    lww_register.new("draft", 1, node_a)
    |> lww_register.set("published", 2, node_a)

  lww_register.value(register)
  // -> "published"
}

Modules

Module	Purpose
`lattice_registers/lww_register`	Last-writer-wins register. Higher timestamps win; equal timestamps use replica ID tie-breaking.
`lattice_registers/mv_register`	Multi-value register. Concurrent writes are preserved as multiple values.

Notes

LWWRegister exposes new, set, set_with_delta, merge, value, timestamp, replica_id, to_json, and from_json.
MVRegister exposes new, set, set_with_delta, merge, value, to_json, and from_json.
Labeled calls to LWW-register new, set, and set_with_delta use value: instead of the former val: label. Positional calls are unchanged.
Use LWWRegister when a deterministic winner is acceptable.
Use MVRegister when application code should resolve concurrent writes.

Typed payloads and local authors

Both register types accept generic payloads. Use to_json_with and from_json_with with your payload encoder and decoder for integers, records, or tagged unions. The existing to_json and from_json entry points retain their String formats.

An LWWRegister stores the author of its winning write. Loading or merging a register on another replica does not change that author. Every set and set_with_delta call requires the local writer ID so a new write cannot inherit the remote winner’s identity.

Version 2 LWWRegister snapshots must contain a string replica_id. Version 1 snapshots without that field still decode with "" as a legacy placeholder, but the placeholder does not establish the historical writer’s identity. Pass the local replica ID to every subsequent write. Producers of incomplete version 2 snapshots must migrate them with an application-specific policy that recovers the actual winning writer; the decoder does not invent provenance.

Do not reuse the same timestamp and replica ID for different values. After a restart, generate a fresh replica ID or restore a durable logical clock that advances beyond every prior write from that ID.

License

MIT