Documentation / @super-line/core / CrdtCollectionStore
Interface: CrdtCollectionStore
Defined in: packages/core/src/crdt-collections.ts:67
The server half of a CRDT collection backend. Does NOT enforce access or validate schemas itself — the server does both (policy callbacks + the CrdtCollectionStore.apply validate hook). One backend serves all of a server's CRDT collections.
Properties
clustering
readonlyclustering:"relay"|"self"
Defined in: packages/core/src/crdt-collections.ts:69
Cross-node sync mode, inherited from the store family: relay (core relays deltas over the adapter) or self.
Methods
apply()
apply(
change,opts,validate?):Awaitable<void>
Defined in: packages/core/src/crdt-collections.ts:96
Apply an inbound delta (client write or relayed remote change), gated by validate-before-commit: the backend computes the post-merge plaintext on a scratch copy and calls validate(snapshot); if it throws, nothing is committed and the throw propagates (the server resyncs the writer). On success it commits, fires CrdtCollectionStore.onChange, and returns. NOT_FOUND if the doc is absent.
validate is OPTIONAL, and its absence must skip the fold — not merely ignore its result. Two callers pass nothing: a relayed delta (already validated at its ingress node — the skip is what makes relay cheap) and any collection declaring crdt.validate: false. Both used to be spelled as a validator that did nothing, which left every backend computing a full encodeState() + scratch StoreValue + getSnapshot() in order to hand it to an empty function. Implementations MUST branch on validate being undefined and commit directly; the fold is the expensive half, so ignoring the result is not the same optimisation.
INVARIANT — a relay backend MUST apply synchronously. When a delta arrives from another node the server sets a re-publish guard, applies, and clears the guard in finally; the guard is what stops this node from re-publishing a delta it merely relayed in. It is sound only while apply emits onChange before returning — an async apply clears the guard first and the delta ping-pongs across the cluster forever. Nor can origin substitute: it identifies the writer and survives the relay, so the receiving node cannot tell a relayed delta from a local write by that same writer. A self backend is exempt: it never relays. (collections-crdt-libsql keeps its hot path sync and persists off onChange for exactly this reason — the rule lives here now rather than in that one backend's comment.)
Parameters
change
opts
DocOptions | undefined
validate?
(snapshot) => void
Returns
Awaitable<void>
close()?
optionalclose():Awaitable<void>
Defined in: packages/core/src/crdt-collections.ts:108
Release any resources held by the backend.
Returns
Awaitable<void>
create()
create(
n,id,data,opts):Awaitable<void>
Defined in: packages/core/src/crdt-collections.ts:73
Server-authoritative create with pre-validated initial data (Q10). Throws CONFLICT if the id exists.
Parameters
n
string
id
string
data
unknown
opts
DocOptions | undefined
Returns
Awaitable<void>
delete()
delete(
n,id):Awaitable<void>
Defined in: packages/core/src/crdt-collections.ts:98
Remove a document (idempotent).
Parameters
n
string
id
string
Returns
Awaitable<void>
list()
list(
n,opts?):Awaitable<DocSummary[]>
Defined in: packages/core/src/crdt-collections.ts:100
Id-enumeration + summaries for a collection (Q4) — no content query.
Parameters
n
string
opts?
Returns
Awaitable<DocSummary[]>
onChange()
onChange(
cb): () =>void
Defined in: packages/core/src/crdt-collections.ts:104
Subscribe to every applied delta across all CRDT collections — core's single fan-out source.
Parameters
cb
(change) => void
Returns
() => void
onDelete()?
optionalonDelete(cb): () =>void
Defined in: packages/core/src/crdt-collections.ts:106
Deletion mirror for self backends that own cross-node propagation (see CollectionStore.onChange).
Parameters
cb
(n, id) => void
Returns
() => void
open()
open(
n,id,opts?):CrdtServerReplica
Defined in: packages/core/src/crdt-collections.ts:102
Open a reactive in-process co-writer over an existing doc's canonical state.
Parameters
n
string
id
string
opts?
doc?
origin?
string
Returns
read()
read(
n,id):Awaitable<string|undefined>
Defined in: packages/core/src/crdt-collections.ts:71
Full encoded Yjs state (base64) for catch-up on open, or undefined if the doc doesn't exist.
Parameters
n
string
id
string
Returns
Awaitable<string | undefined>