Skip to main content

crdt_lf 4.x → 5.0

The bytes do not change. Changes and snapshot blobs keep the 4.x layout, so a stored document opens as it is and a 4.x peer and a 5.0 peer read the same data. What changes is the Dart API: a handler now always says which kind it is, out loud.

In 4.x a generic handler could leave its kind implicit and fall back on runtimeType.toString(). That reads CRDTRegisterHandler<bool> on the VM, and a short renamed symbol in a Flutter web --release build, where dart2js minifies type names. So two peers on two platforms wrote two different tags for the same kind, and a reference from one could not be rebuilt by the other — and dart test -p chrome does not minify, so nothing caught it.

The tag is therefore explicit:

// 4.x — the tag came from the class name
final done = CRDTRegisterHandler<bool>(doc, 'todo.1.done');

// 5.0 — you name the kind
final done = CRDTRegisterHandler<bool>(
doc,
'todo.1.done',
handlerType: 'todo.done',
);

Only the seven generic handlers ask for it: CRDTListHandler, CRDTMapHandler, CRDTRegisterHandler, CRDTORSetHandler, CRDTORMapHandler, CRDTFugueListHandler, CRDTFugueMovableListHandler. A non-generic one fixes its own tag, so CRDTTextHandler(doc, 'text') still compiles.

Pick the tag once and keep it: it travels in every operation envelope and in every reference, so every peer has to spell it the same way. It is not the handler's id — many ids share one tag. See Naming a generic handler.

Registration follows the same idea. A kind is now a HandlerSpec, which every handler class exposes as spec, and the three calls that name a kind take one: doc.register(spec), doc.handler(spec, id) and a container's child(key, spec) / insertChild(index, spec) — see Nested data.

Renamed or removed symbols:

4.x5.0Note
CRDTListHandler<T>(doc, id)CRDTListHandler<T>(doc, id, handlerType: 'todo-list')And the same for the six other generic handlers.
registerFactory(type, factory)register(HandlerSpec)The spec carries the tag, the builder and the formats together, so the tag is not passed beside a factory that also knows it.
registerDefaultFactories()removedThere is no privileged set of kinds any more. Open a handler of the kind, or register(CRDTMapRefHandler.spec).
registerHandler(handler)removedThe constructor registers the handler on the document it is given.
HandlerFactoryHandlerBuilder<T>Same shape, (doc, id) => handler, with the handler type on the signature.
a custom handler's MyHandler(super.doc, this.id);MyHandler(super.doc, this.id) : super(spec: MyHandler.spec);A handler cannot exist without naming its kind. See Custom handlers.

A 5.0 snapshot carries one extra reserved data entry (crdt_lf/capabilities), which records what the blobs are written in so a pruned document can still say what it holds. A 4.x peer ignores it.