Skip to main content

crdt_lf 3.x → 4.0

A 4.0 peer refuses to read v3 bytes — not from a document's history, not from a snapshot, not from the bytes a Hive/SQLite/Drift adapter saved. 4.0 changes what several of those bytes mean, so reading them under the old assumptions would leave two peers with different content while their version vectors still agreed.

Most of the table below is harmless if you never persisted a document and never wrote a custom handler. With no stored bytes there is nothing a 4.0 peer can refuse to open, and the operation-layer rows (ORHandlerTag, OperationDecoders, OperationType, incrementCachedState) only reach code that implements Handler itself. Peers still have to upgrade together: a 3.x and a 4.0 client talking live break the same way.

The one row that reaches ordinary code either way is rune indexing. It changes nothing while the text stays inside the BMP — for ASCII and most Latin text a rune and a UTF-16 code unit are the same thing. It bites when the text holds emoji or other non-BMP characters, or when you hand a handler an offset taken from a Flutter TextField, which counts code units.

Every package that depends on crdt_lf has to move to a version that requires crdt_lf: ^4.0.0 as well, or a client still resolving 3.x never reaches the guard.

Renamed or removed symbols:

3.x4.0Note
ORHandlerTagOperationIdThe tie-break is the id of the change carrying the operation. A handler no longer writes its own, and it costs no bytes.
OperationType.typeNameFromKindremovedNo caller anywhere in the monorepo; OperationType.type already carries the name.
OperationType.fromPayloadremovedThe payload string is a debug format and never carried a kind.
a fromBytes(bytes) a handler implemented by handOperationDecoders operationDecodersWas raw bytes decoded by whatever a handler wrote. Now a Map<int, Operation Function(Uint8List body)> keyed by the operation's kind byte: the framework looks the kind up itself and raises UnknownOperationKindException on a miss, instead of a handler returning null or hand-rolling the same check.
FugueTree, FugueNode, FugueNodeTriple, FugueValueNodeno longer exportedImplementation detail of the two Fugue sequence handlers. FugueElementID is still public.
update on CRDTFugueTextHandler / CRDTFugueListHandler (delete + insert)update keeps the element's identityFor the old behavior, ask for it: doc.runInTransaction(() { text..delete(index, count)..insert(index, replacement); });
incrementCachedState({required operation, required state})adds an optional DeltaSink<Object?>? sinkIt is null unless someone watches the handler's deltas. An override that wants to publish them writes what the operation did to it; see Handler deltas.
class MyHandler extends Handler<T>base/final/sealed class MyHandler extends Handler<T>Handler is a base class now. Extending it is unchanged; implementing it is no longer allowed. See Custom handlers.
Dart >=2.17.0Dart >=3.0.0Class modifiers need it. crdt_socket_sync and crdt_lf_hive move with it.
Text handler positions in UTF-16 code unitspositions in runesAffects insert, delete, update, length, stablePositionAt, indexOfStablePosition and myersDiff. See Text positions.