Skip to main content

Reactivity

Three signals tell a consumer that something moved, each at a different grain. None of them replays history to answer, so polling any of them is cheap.

SignalGrainUse it to
revisionForHandler(id)one handlerdecide whether a handler changed
updatesthe documentknow when to check
eventsthe document, typedknow what happened (changes, snapshots, prunes)
handler.watch()inside one handlerknow what changed in the value: see Handler deltas

revision​

document.revisionForHandler(handlerId) is a per-handler, monotonically increasing int. It moves every time the observable state of that handler may have changed: a local or imported change targets it, a snapshot carrying its state is imported or merged, or it (or a handler it references) is deleted.

It never decreases, pruning included, so two equal readings guarantee the handler's state did not change in between. This is the signal a reactive binding should watch.

Deleting a handler that a container references bumps the container's revision (its resolved view now reads differently) without touching its cached raw value: the container still holds the same HandlerRefs, only one of them no longer resolves to anything.

updates​

document.updates is a Stream<void>: one coarse "something changed, read again" signal, with no detail on what changed or where. It fires after every change this document applies (local or imported; inside a transaction only once, at the commit), and after every snapshot import or merge.

This is the pair crdt_lf_flutter builds its reactivity on: updates says when to check, revisionForHandler says what actually moved. A widget compares two revisions instead of re-reading and diffing the value on every tick:

int _lastRevision = -1;

document.updates.listen((_) {
final revision = document.revisionForHandler(handler.id);
if (revision == _lastRevision) {
return; // woken up, but this handler did not change
}
_lastRevision = revision;
rebuild();
});

events​

document.events is a Stream<CRDTDocumentEvent>: a typed stream for a consumer that needs what updates throws away. DocumentChangesApplied, DocumentSnapshotUpdated, DocumentHistoryPruned and the other CRDTDocumentEvent subclasses say what happened, not just that something did.

This is how persistence keeps a document on disk: it listens once on events, and writes down exactly what each variant says happened, without reading any handler.

document.events.listen((event) {
switch (event) {
case DocumentChangesApplied():
storage.appendChanges(event.changes); // batched, then flushed
case DocumentSnapshotUpdated():
storage.writeSnapshot(event.snapshot);
case DocumentHistoryPruned():
storage.recordPrune(event.removed, event.rewritten);
}
});