Skip to main content

Delta widgets

Start with CrdtHandlerBuilder: it hands you the handler, you read handler.value, done. That read is cache-backed (an edit moves the cached state forward instead of replaying the history), so for most values it is already the right answer, and there is nothing to keep in sync.

The widgets on this page are for when re-reading is the expensive part, or when the value alone does not tell you enough. They follow the handler's deltas: what each change did, in your coordinates.

You wantWidgetWhat the builder gets
the value on screen: the defaultCrdtHandlerBuilderthe handler; read handler.value
the same, without re-reading the value each timeCrdtHandlerDeltaBuilderthe value, already moved
to know where it changed, or not to rebuild at allCrdtHandlerDeltaListenerthe delta of each change

The two type arguments are the value of the handler and its delta type, for example List<String> and SequenceDelta<String> for a list of strings. The delta types are listed in Handler deltas.

Putting the value on screen​

When the value is what you render, CrdtHandlerDeltaBuilder holds it for you. It seeds itself while attaching, so the first frame already shows the document. Then it moves the value by the delta of each change:

CrdtHandlerDeltaBuilder<List<String>, SequenceDelta<String>>(
id: 'todos',
builder: (context, todos) => ListView(
children: [for (final todo in todos) Text(todo)],
),
);

It rebuilds once per change, exactly like CrdtHandlerBuilder. The difference is only what the rebuild costs: the value arrives already moved by the delta, instead of being read again from the document. On a long text or a large list that is the whole point; on a handful of keys it buys nothing.

Reacting to each change​

CrdtHandlerDeltaListener reports what moved, one call per change, so you can move a projection you already hold forward: drive an AnimatedList, replay an edit into a controller, append to a log.

CrdtHandlerDeltaListener<List<String>, SequenceDelta<String>>(
id: 'todos',
// Seed here: fires once on subscribe, and again whenever the value has to
// be taken fresh (a snapshot import, a dropped cache).
onReset: (context, sync, cause) => _items = sync.value,
// One call per change, with the retain/insert/delete of that change.
onDelta: (context, event) => _items = event.delta.apply(_items),
child: const TodoList(),
);

The widget handles the awkward part of the contract for you. A reset means "read it again", and the events that the fresh read already holds must not be applied on top of it. The widget performs the read and drops those events, so onDelta never reports a change twice. The value sync.value hands over is yours to keep: no copy needed.

Like the other listener, it renders child unchanged and never rebuilds the subtree.

If you also write​

A listener that moves its own copy by hand and writes to the handler gets its own write back as a delta. Tag the write with an origin and pass the same object to the listener's origin, and it skips it. See Your own edit comes back. CrdtHandlerDeltaBuilder has no origin, on purpose: it owns the value on screen, so skipping your write would hide it.