strata_document

Immutable typed collaborative documents.

Each document is an add-wins OR-Map whose active values are LWWRegister(String) CRDTs. The string is encoded JSON. A document owns its local replica ID and Lamport clock; every local set creates a fresh register owned by that replica, so a remote winner is never mutated as if it were local.

Types

DocId

A typed document identifier. tag is phantom and matches the document schema tag. The tag is not serialized. This wrapper does not check runtime existence, stored schema, deletion parentage, or authorization.

pub type DocId(a)

Document

A typed CRDT document. tag is phantom and identifies its schema.

pub type Document(a)

DocumentError

A failure while decoding or merging serialized document state.

pub type DocumentError {
  InvalidDocument(reason: json.DecodeError)
  MergeTypeMismatch(expected: String, found: String)
  WrongValueType(key: String, found: String)
  ReservedKey(key: String)
}

InvalidDocument(reason: json.DecodeError)

The serialized OR-Map was malformed or incompatible.

MergeTypeMismatch(expected: String, found: String)

The incoming map used a different nested CRDT specification.

WrongValueType(key: String, found: String)

An active map value was not an LWW register.

ReservedKey(key: String)

An operation attempted to use the document's reserved clock key.

Constants

clock_key

Reserved OR-Map key that persists the document's Lamport clock.

It is excluded from keys, field reads, and whole-record schema entries. Applications must not use this key for document data.

pub const clock_key: String

Functions

clock

Return the current Lamport clock.

pub fn clock(Document(a)) -> Int

delete

Delete a typed field and return the updated document.

Deletes advance the Lamport clock like every other local write. Returns Error(ReservedKey(key)) for the internal clock key.

pub fn delete(
  Document(a),
  schema.Field(a, b)
) -> Result(Document(a), DocumentError)

doc_id

Wrap a string as a typed document identifier without runtime validation.

pub fn doc_id(String) -> DocId(a)

doc_id_to_string

Return the document identifier string.

pub fn doc_id_to_string(DocId(a)) -> String

encode

Encode the underlying modern OR-Map state as a string.

pub fn encode(Document(a)) -> String

get

Read a typed field.

Absence is Ok(None). Malformed JSON and wrong JSON types are returned as FieldError values rather than being ignored. The reserved clock key returns schema.ReservedKey.

pub fn get(
  Document(a),
  schema.Field(a, b)
) -> Result(option.Option(b), schema.FieldError)

get_required

Read a required typed field.

pub fn get_required(
  Document(a),
  schema.Field(a, b)
) -> Result(b, schema.FieldError)

keys

Return active keys in deterministic lexicographic order.

pub fn keys(Document(a)) -> List(String)

merge

Merge two in-memory documents.

The receiver keeps its local replica identity. Its clock advances to the maximum of both local clocks and all active winning register timestamps.

pub fn merge(
  Document(a),
  Document(a)
) -> Result(Document(a), DocumentError)

merge_encoded

Merge an OR-Map encoded as a JSON string.

Lattice OR-Map v1 and v2 envelopes are accepted by the underlying modern decoder. Decode and merge failures are explicit.

pub fn merge_encoded(
  Document(a),
  String
) -> Result(Document(a), DocumentError)

merge_json

Merge an OR-Map encoded as json.Json.

pub fn merge_json(
  Document(a),
  json.Json
) -> Result(Document(a), DocumentError)

new

Create an empty typed document owned by replica_id.

pub fn new(replica_id: String) -> Document(a)

read

Decode the active keys as one record using schema.

pub fn read(
  Document(a),
  schema.Schema(a, b)
) -> Result(b, schema.FieldError)

replica_id

Return the document's local replica ID.

pub fn replica_id(Document(a)) -> String

set

Set a typed field and return the updated document.

The Lamport clock advances and a fresh locally-owned LWW register is created. This intentionally does not call lww_register.set on a register that may have been won by a remote replica. The timestamp is strictly above both the document clock and any retained register for the key.

Returns Error(ReservedKey(key)) for the internal clock key.

pub fn set(
  Document(a),
  schema.Field(a, b),
  b
) -> Result(Document(a), DocumentError)

stamp

Write the schema version marker if the schema is versioned.

Unversioned schemas leave the document unchanged.

pub fn stamp(
  Document(a),
  schema.Schema(a, b)
) -> Document(a)

to_json

Encode the underlying modern OR-Map state.

pub fn to_json(Document(a)) -> json.Json

write

Apply a whole-record schema as independent per-key writes.

Optional properties whose value is None remove their key. Returns Error(ReservedKey(key)) without applying any operations when the schema encodes the internal clock key.

pub fn write(
  Document(a),
  schema.Schema(a, b),
  b
) -> Result(Document(a), DocumentError)