A shared key-value document. On a network document, keys are /-separated paths: writing a key supersedes what the same author wrote under it, so a parent write replaces that author's subtree and leaves other authors' keys.
An append-only view over the prefix: each distinct entry, whether already in the document or written later, reaches on_add exactly once, until max entries have been delivered. Without a schema, values pass through unvalidated and treating them as untrusted stays the caller's job.
Example
local chat = doc:collection("chat/", {
schema = { text = { type = "string", max_len = 280 } },
on_add = function(entry)
print(entry.text) --> helloend,
})
chat:add({ text = "hello" })
Fired once per distinct entry, the entries already in the document included, up to max entries.
max
integer
1024
Bound on on_add fires. Entries past it still sync and are counted by count(); they just no longer reach on_add.
max_per_author
integer
no bound per author
Bound on on_add fires per verified author. Past it that author's further entries no longer reach on_add — they still sync, still count toward count(), and still consume the global max, which applies on top of this. Requires a network-scope document.
since
integer
entries of any age
Observe only entries written at or after this UNIX-microseconds timestamp. Older entries, already in the document or arriving later, never reach on_add or count().
authors
string[]
every writer's entries
Observe only these writers' entries (identity keys, as meta.author). Requires a network-scope document. Other writers' entries still sync, but never reach on_add or count().
Declarative per-entry validation, keyed by field name. An entry that fails — wrong type, out of bounds, a missing required field, or any undeclared field — is dropped whole: it never reaches on_add and never counts. The schema declaration itself is validated here and raises on unknown keys or malformed specs.
on_ack
fun(id: string)
–no default
Fired at most once per entry this handle added (or, on network scope, authored), when a reader acknowledges it via ack. The receipt carries the entry id only — no reader identity, and no proof: it is an anonymous, unauthenticated courtesy signal.
A grow-only counter over the prefix, shared by every holder of the same prefix. No increment counts twice, whether it was made before the counter opened or after.
Example
local likes = doc:counter("likes/")
likes:on_change(function(value)
print(value) --> 1end)
likes:increment()
Document:set
method
Document:set(key: string,value: nil | boolean | integer | number | string | table) -> Op
Write a key-value pair. Errors when doc.can_write is false. The write starts immediately; :ready() observes completion or failure.
Remove a key. Errors when doc.can_write is false. After delete, get returns nil and query_prefix omits the key; subscribers are notified with a nil value.
Query every key under the prefix, newest per key; the result's entries is {[key] = {value, meta}}.
Example
doc:set("players/ada", 3):ready()
doc:set("players/bo", 5):ready()
local players = doc:query_prefix("players/"):ready()
-- Entries are keyed by the whole key.print(players.entries["players/bo"].value) --> 5
Remove the key subtree: on a local document every key under prefix; on a network document the keys this handle's author wrote under it, erased, and the space they took freed, everywhere the document syncs, while keys other authors wrote there stay. Subscribers are notified with nil values. Errors when doc.can_write is false.
Mint a grant from this handle's authority. With to, the grant is bound to that identity; without it, anyone holding the encoded string holds its authority. A write grant always carries read alongside. A network grant starts from this handle's own access, not from the part of the document the handle syncs: it reads the document's history and the changes stamped until it ends, and once it ends, DatumHue stops syncing the document to its holder. A network write grant adds changes stamped from an hour before it was made until it ends; a newer change to the same key wins. A grant cannot be withdrawn. Raises on any attempted widening, and on a handle opened from the last grant a line can hold. Network grants made each from the one before form a line that holds eight from a network document documents.create made and seven from a named or communal one; a grant past them could not sync.
Example
-- Without `to`, whoever holds the encoded string may read.local grant = doc:grant({ mode = "read" })
print(grant.mode, grant.bearer) --> read truelocal encoded = grant:encode()
Close this handle. Other handles and subscriptions on the same document keep working. Once none is open on a network document, DatumHue stops syncing it on this workstation until it is opened again; what was written here before still reaches the workstations it was syncing with. An app's handles close when the app ends.