Skip to main content

Handler deltas

A Change and a delta describe the same edit from two different places.

A change is what the network carries: one peer's edit, written in that peer's terms. A Fugue text insert says "put these elements after element e7". Every peer receives that same change, and none of them can tell from it where the edit lands in the text they are looking at: e7 is an identity, not a position.

A delta answers the other question: how your own copy moved when that change was folded in, written in your coordinates. "Keep the 5 characters you have, then put world after them." It is derived locally, by this document, from the state this document holds. It never travels.

So a change tells you what someone did; a delta tells you what happened to what you are holding. That is why a delta can place a caret and a change cannot. It is also why two peers that agree on the state can still see two different sequences of deltas: they folded the same changes in a different order.

Consuming deltas​

watch() publishes one delta event per change, so a consumer keeps its own projection and never reads handler.value again.

final text = CRDTFugueTextHandler(doc, 'text');

var mine = '';
var seen = -1;

text.watch().listen((update) {
switch (update) {
case HandlerReset():
// The base moved: read it, and learn which events it already holds.
// The value it hands back is yours to keep.
final point = text.readSynced();
mine = point.value;
seen = point.seq;
case HandlerDelta():
if (update.seq <= seen) {
return; // already inside the value the last read handed over
}
// The handler is the only place that knows both its value type and its
// delta type, so it is the one that says how a delta moves a value.
mine = text.applyDelta(mine, update.delta);
seen = update.seq;
}
});

Three calls: watch() to subscribe, readSynced() to answer a reset with a value and the point of the stream it reflects, and applyDelta to move that value by each delta that follows. The one rule that keeps the two in step: drop every event whose seq the last read already covers.

Four vocabularies cover every built-in handler, by shape rather than by handler: SequenceDelta<T> (retain / insert / delete, plus a move for the movable list), MapDelta<K, V>, SetDelta<T> and RegisterDelta<T>. The rich text handler has its own, RichTextDelta.

A reset is not an error. It is the honest answer when the base the deltas described has been replaced: a snapshot arrived, or the handler dropped its cached state. ResetCause says which. Every subscription opens with ResetCause.initial, so the reset path runs on the first frame instead of months later.

An operation with no visible effect (update of a missing key, delete past the end) still publishes its own event, with an empty delta: one event covers one change, and the change did happen.

In Flutter, the delta widgets do all of this for you.

Where a delta comes from​

A local edit and a remote change reach the same event by two different roads.

Two things follow from that shape.

A local delta is computed early and published late. It is built while the operation is applied, before the Change that will carry it exists, and it is published on commit, after compaction may have fused several operations into one. One event always covers exactly one change, so the deltas of fused operations are composed into one.

Watching changes when the work happens, not what work happens. Unwatched, a remote change waits in the queue and is folded at the next read. Watched, it is folded on arrival, because a stream cannot wait for a read that may never come. The work is the same; only the moment differs. While nobody watches, the whole feature is one null check on the apply path.

Deltas, or the value?​

Start with handler.value. It is cache-backed (see State cache): an edit moves the cache forward instead of replaying, and for most reads it is already the right answer.

Reach for deltas when the projection you keep costs more to rebuild than the edit costs to apply:

What you needReach for
an occasional read, or you re-render everything anywayhandler.value
to move something expensive to rebuild: a long text, a large listdeltas
to know where it changed: a caret, an AnimatedList, a scroll anchordeltas
to know who changed it, or which peer it came fromdeltas (HandlerDelta.author, .local)
to skip the echo of your own writedeltas (origin, below)

If you write too: your own edit comes back​

A write publishes while it is still being applied, so the event reaches your listener before the write has even returned. If you had already moved your own copy by hand, you now move it twice:

items = [...items, 'bread']; // 1. move my own copy
list.insert(0, 'bread'); // 2. write to the CRDT
// ← the event arrives inside this line:
// onDelta applies it again: ['bread', 'bread']

With two consumers on one document, the same event must be dropped by one and applied by the other, so no property of the event alone can decide it. What decides is who caused it, which is what origin carries.

Your situationWhat to use
you apply every delta and never touch your copy by handnothing
you move your copy by hand (a controller, an AnimatedList, an optimistic update)origin
you want to show who edited, or tell the network apart from this peerlocal / author

Try the first row first: write to the handler, move nothing by hand, and let the event do the work. Then there is no echo, and nothing to tag.

local is not an echo flag

HandlerDelta.local is true for every change this peer authored. Two consumers on one document both read true for each other's writes, and a change written in an earlier session reads true when persistence loads it back. Skipping on local drops content. Use origin.

Tagging a write​

final tag = Object();

doc.runInTransaction(() => list.insert(0, 'bread'), origin: tag);

// in the listener:
if (identical(update.origin, tag)) {
return; // mine, already applied
}

origin takes any object, and is compared by identity. It never travels (a delta is a local observation), so it costs nothing on the wire. importChanges, binaryImportChanges, applyChange, createChange and import take it too, which is how a sync manager marks what arrived from the network.

A HandlerReset carries no origin. It asks for a read, and that read is owed to whoever caused it.

In Flutter, crdt_lf_flutter does all of that for you. CrdtHandlerDeltaBuilder holds the value and rebuilds with it already moved (the first row of the table, so it needs no tag). CrdtHandlerDeltaListener hands you each change as a side effect, and takes an origin for the second row. CrdtTextFieldBuilder drives a TextEditingController from the same stream.