DatumHuePlatform v0.0.24datumhue.com
Contents

namespaceShared Key-Value State5 functions, 1 property

datumhue.documents

Shared key-value documents with change subscriptions; a document's scope decides where it lives and who shares it. Access is shared through grants minted by doc:grant, which can be narrowed further and whose encoded form travels over any channel. For private durable bytes no other app can observe, see storage.

Returns handles
Document, DocumentGrant

Fields 1

FieldTypeAccessDescription
identitystringread-onlyThis user's durable document identity key — what others pass as to in grants and what appears as meta.author on this user's writes. Stable across restarts.

Functions 5

datumhue.documents.create

functionsuspends
datumhue.documents.create(opts?: documents.CreateOptions) -> Document

Create a new document. The returned handle is writable; share access with doc:grant. Requires the network capability when scope = "network".

Example
local doc = datumhue.documents.create({ scope = "local" })
print(doc.scope, doc.can_write) --> local true

opts documents.CreateOptions options 1 key, 1 inherited

KeyTypeDefaultDescription
From documents.ScopedOptions
scope"local" | "network""local"Where the document lives, and who shares it.

In the guide: Messages, events and shared state

datumhue.documents.open_named

functionsuspends
datumhue.documents.open_named(opts: documents.OpenNamedOptions) -> Document

Open (creating if needed) a document keyed by name within this app's @scope. Apps of one @scope share it when their packages came from the same place: one registry or a folder. An app under another @scope, or a copy of this one that came another way, opens a different document under the same name; with shared, every app that also sets it opens one. The returned handle is always writable. Requires the network capability when scope = "network".

Example
-- Every app of this @scope on this workstation that opens "scores"
-- shares it.
local scores = datumhue.documents.open_named({ name = "scores" })
scores:set("ada", 3):ready()
print(scores:get("ada"):ready().value) --> 3

opts documents.OpenNamedOptions options 6 keys, 1 inherited

KeyTypeDefaultDescription
name requiredstringno defaultStable document name, unique within your @scope.
sharedbooleanfalseOpen the document of this name that every app setting shared opens, whatever its @scope and wherever its package came from, instead of one kept within this app's @scope. Any app can open a shared name: to hand a document to one other app, give it a DocumentGrant.
prefixstringthe whole documentSync, read, and observe only this key subtree.
sinceintegerentries of any ageSync only entries written at or after this UNIX-microseconds timestamp.
authorsstring[]every writer's entriesSync only these writers' entries (identity keys, as meta.author / documents.identity).
From documents.ScopedOptions
scope"local" | "network""local"Where the document lives, and who shares it.

In the guide: Messages, events and shared state

datumhue.documents.open

functionsuspends
datumhue.documents.open(grant: DocumentGrant | string, opts?: documents.OpenOptions) -> Document

Open the document a grant authorizes. The scope is decided by the grant; requires the network capability when the grant is network-scoped. opts narrows the synced window — reads and subscriptions outside it see nothing.

Example
local doc = datumhue.documents.create()
doc:set("title", "Notes"):ready()
local encoded = doc:grant({ mode = "read" }):encode()
-- Whoever receives the string opens a read-only handle.
local copy = datumhue.documents.open(encoded)
print(copy.can_write, copy:get("title"):ready().value) --> false Notes

opts documents.OpenOptions options 3 keys

KeyTypeDefaultDescription
prefixstringthe whole documentSync, read, and observe only this key subtree.
sinceintegerentries of any ageSync only entries written at or after this UNIX-microseconds timestamp.
authorsstring[]every writer's entriesSync only these writers' entries (identity keys, as meta.author / documents.identity).

In the guide: Messages, events and shared state

datumhue.documents.communal

functionsuspends
datumhue.documents.communal(opts?: documents.CommunalOptions) -> Document

Open the communal document derived from an identity. Every user holds intrinsic write authority over their own section; reading another user's section requires a grant from them. Requires the identity and network capabilities.

Example
local mine = datumhue.documents.communal()
mine:set("status", "online"):ready()

opts documents.CommunalOptions options 4 keys

KeyTypeDefaultDescription
identitystringyour own, as documents.identity names itWhose communal namespace to open.
prefixstringthe whole documentSync, read, and observe only this key subtree.
sinceintegerentries of any ageSync only entries written at or after this UNIX-microseconds timestamp.
authorsstring[]every writer's entriesSync only these writers' entries (identity keys, as meta.author / documents.identity).

In the guide: Messages, events and shared state

datumhue.documents.decode_grant

function
datumhue.documents.decode_grant(encoded: string) -> DocumentGrant

Parse and verify an encoded grant. Raises when the string is not a grant or its authorization does not verify.

Example
local doc = datumhue.documents.create()
local encoded = doc:grant({ mode = "write" }):encode()
local grant = datumhue.documents.decode_grant(encoded)
print(grant.mode, grant.scope, grant.bearer) --> write local true

Types 9

documents.CollectionMeta

record

record 3 keys

KeyTypeDescription
idstringThe entry's id within the collection — what ack takes and on_ack carries.
timestampintegerWrite time, UNIX microseconds.
author?stringThe verified writer identity. Absent on local scope, which has no author concept.

Nested in: documents.CollectionOptions

documents.Entry

record

record 2 keys

KeyTypeDescription
valueanyThe stored value.
metadocuments.MetaWrite metadata.

Used by: DocQuery.entries

documents.GrantMode

enum
ValueDescription
"read"
"write"

Used by: DocumentGrant.mode

Nested in: documents.GrantOptions

documents.GrantOptions

options

options 4 keys

KeyTypeDefaultDescription
tostringa bearer grant: anyone holding the encoded string holds its authorityReceiver identity key the grant is bound to.
mode"read" | "write""read"Never wider than the granting handle's own mode.
prefixstringthe granting handle's own subtreeNarrow the grant to this key subtree.
valid_daysinteger30 days; a local grant never expiresDays the grant lasts, counted from an hour before now. It never outlasts the granting handle's own access.

Used by: Document:grant, DocumentGrant:delegate

documents.Meta

record

record 2 keys

KeyTypeDescription
timestampintegerWrite time, UNIX microseconds.
author?stringThe writer's identity key. Absent on local-scope writes, which have no author concept.

Used by: Document:subscribe, DocEntry.meta

Nested in: documents.Entry

documents.SchemaField

options

options 6 keys

KeyTypeDefaultDescription
type required"string" | "integer" | "number" | "boolean" | "enum"no defaultThe field's declared type.
max_lenintegerno length boundMaximum byte length; string fields only.
minnumberno lower boundInclusive lower bound; integer and number fields only.
maxnumberno upper boundInclusive upper bound; integer and number fields only.
valuesstring[]an enum field raises without itThe admitted strings; enum fields only, at least one.
optionalbooleanfalseAn absent field passes; a present one still validates.

Nested in: documents.CollectionOptions

documents.SchemaFieldType

enum
ValueDescription
"string"UTF-8 text; bound its byte length with max_len.
"integer"
"number"Any finite numeric value; NaN and infinities always fail.
"boolean"
"enum"A string drawn from values.

Nested in: documents.SchemaField

documents.Scope

enum
ValueDescription
"local"Shared by the apps on this workstation, until it quits.
"network"Replicated with other workstations connected to the same deployment.

Used by: Document.scope, DocumentGrant.scope

Nested in: documents.ScopedOptions

documents.ScopedOptions

options

options 1 key

KeyTypeDefaultDescription
scope"local" | "network""local"Where the document lives, and who shares it.

Extended by: documents.CreateOptions, documents.OpenNamedOptions

datumhue.com

(c) 2026 Shuusei AB. Quote excerpts of this manual, with attribution to DatumHue, in your own documentation, tutorials, course materials, reviews, and other writing or video. Republishing it in whole or in substantial part needs written permission: support@datumhue.com.

Victor Mono is licensed under the SIL Open Font License 1.1
Copyright (c) 2024, Rune Bjørnerås (https://github.com/rubjo)

This Font Software is licensed under the SIL Open Font License, Version 1.1.
This license is copied below, and is also available with a FAQ at:
http://scripts.sil.org/OFL


-----------------------------------------------------------
SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
-----------------------------------------------------------

PREAMBLE
The goals of the Open Font License (OFL) are to stimulate worldwide
development of collaborative font projects, to support the font creation
efforts of academic and linguistic communities, and to provide a free and
open framework in which fonts may be shared and improved in partnership
with others.

The OFL allows the licensed fonts to be used, studied, modified and
redistributed freely as long as they are not sold by themselves. The
fonts, including any derivative works, can be bundled, embedded,
redistributed and/or sold with any software provided that any reserved
names are not used by derivative works. The fonts and derivatives,
however, cannot be released under any other type of license. The
requirement for fonts to remain under this license does not apply
to any document created using the fonts or their derivatives.

DEFINITIONS
"Font Software" refers to the set of files released by the Copyright
Holder(s) under this license and clearly marked as such. This may
include source files, build scripts and documentation.

"Reserved Font Name" refers to any names specified as such after the
copyright statement(s).

"Original Version" refers to the collection of Font Software components as
distributed by the Copyright Holder(s).

"Modified Version" refers to any derivative made by adding to, deleting,
or substituting -- in part or in whole -- any of the components of the
Original Version, by changing formats or by porting the Font Software to a
new environment.

"Author" refers to any designer, engineer, programmer, technical
writer or other person who contributed to the Font Software.

PERMISSION & CONDITIONS
Permission is hereby granted, free of charge, to any person obtaining
a copy of the Font Software, to use, study, copy, merge, embed, modify,
redistribute, and sell modified and unmodified copies of the Font
Software, subject to the following conditions:

1) Neither the Font Software nor any of its individual components,
in Original or Modified Versions, may be sold by itself.

2) Original or Modified Versions of the Font Software may be bundled,
redistributed and/or sold with any software, provided that each copy
contains the above copyright notice and this license. These can be
included either as stand-alone text files, human-readable headers or
in the appropriate machine-readable metadata fields within text or
binary files as long as those fields can be easily viewed by the user.

3) No Modified Version of the Font Software may use the Reserved Font
Name(s) unless explicit written permission is granted by the corresponding
Copyright Holder. This restriction only applies to the primary font name as
presented to the users.

4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
Software shall not be used to promote, endorse or advertise any
Modified Version, except to acknowledge the contribution(s) of the
Copyright Holder(s) and the Author(s) or with their explicit written
permission.

5) The Font Software, modified or unmodified, in part or in whole,
must be distributed entirely under this license, and must not be
distributed under any other license. The requirement for fonts to
remain under this license does not apply to any document created
using the Font Software.

TERMINATION
This license becomes null and void if any of the above conditions are
not met.

DISCLAIMER
THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
OTHER DEALINGS IN THE FONT SOFTWARE.

Try

    ↑↓ selectEnter openTab filter

    Settings

    Theme
    Text
    Print

    Keyboard shortcuts

    / or Ctrl KSearch
    ↑ ↓ EnterPick a result
    TabNext result filter
    j kNext or previous entry
    [ ]Previous or next page
    yCopy a link to the current entry
    ?These shortcuts
    EscClose

    On this page