Which handler do you need?
A document holds handlers. Each handler is one value with its own merge rules, so the first choice is: what do your users edit?
| Your users edit | Handler | Page |
|---|---|---|
| prose, notes, code, together and in real time | CRDTFugueTextHandler | Collaborative text |
| text with bold, links, headings, images | CRDTFugueRichTextHandler | Rich text |
| an ordered list: todos, items, blocks | CRDTFugueListHandler, CRDTFugueMovableListHandler | Lists |
| keys and values, a set of tags, one flag | CRDTORMapHandler, CRDTORSetHandler, CRDTMapHandler, CRDTRegisterHandler | Maps, sets and values |
| a tree: chapters → paragraphs, slides → shapes | the container handlers (CRDTMapRefHandler, …) | Nested data |
| a domain object changed by events | CRDTAggregateHandler | Aggregates |
Three pages apply to every handler: Undo and redo, History (the document after each past change), and Your own value types for storing your classes in a list or a map.
How far down to resolve conflicts
There is rarely a single "right" model. It depends on how far down you want conflicts to be resolved, and the trade-off is always the same:
- Coarser (flat values): fewer handlers, less memory, simpler code. A concurrent edit is resolved for the whole value, often with last-writer-wins.
- Finer (nested handlers): concurrent edits merge per field or per character. You pay with more handlers (memory, snapshot size, read cost) and more setup.
Rule of thumb: push granularity down only where concurrency happens. Make a node a nested container when peers edit different parts of it at the same time and both edits must survive. Keep it a flat value when it is atomic, or when last-writer-wins is fine.
Worked example: a todo list
Each todo has a text and a done flag. Two reasonable models:
A — a flat list of values
final todos = CRDTFugueListHandler<Map<String, dynamic>>(
doc,
'todos',
handlerType: 'todo-list',
);
todos.insert(0, {'text': 'Buy milk', 'done': false});
todos.update(0, {'text': 'Buy milk', 'done': true});
- The list merges without conflicts: order, concurrent inserts.
- Each item is atomic: an edit replaces the whole value. Two peers that
change
textanddoneof the same item at the same time: oneupdatewins, the other is lost. - Simple, compact, fast. Good when items are small and rarely edited together.
B — a list of references to one small document per item
import 'package:crdt_lf/crdt_lf.dart';
/// The kind of the `done` flag. A generic handler needs a tag: write it once.
final doneKind = CRDTRegisterHandler.spec<bool>('todo.done');
/// The todo list of [document]: a movable list with one map per todo.
CRDTMovableListRefHandler todosOf(CRDTDocument document) {
// The kinds this peer must rebuild when the todos of another peer arrive.
document
..register(CRDTMapRefHandler.spec)
..register(CRDTFugueTextHandler.spec)
..register(doneKind);
return document.handler(CRDTMovableListRefHandler.spec, 'todos');
}
/// Adds a todo that reads [text] at the end of [todos].
CRDTMapRefHandler addTodo(CRDTMovableListRefHandler todos, {String text = ''}) {
// One transaction: the other peers get the todo with both its fields.
return todos.doc.runInTransaction(() {
final todo = todos.insertChild(
todos.childRefs().length,
CRDTMapRefHandler.spec,
);
final title = todo.child('text', CRDTFugueTextHandler.spec);
if (text.isNotEmpty) {
title.insert(0, text);
}
todo.child('done', doneKind).set(false);
return todo;
});
}
/// The fields of one todo, each merged on its own.
extension TodoFields on CRDTMapRefHandler {
/// The text of the todo: merged character by character.
CRDTFugueTextHandler get text => child('text', CRDTFugueTextHandler.spec);
/// Whether the todo is done: the last write wins.
CRDTRegisterHandler<bool> get done => child('done', doneKind);
}
- Conflicts are resolved per field: one peer edits
textwhile another togglesdoneon the same item, and both survive. textmerges character by character.doneis a small last-writer-wins register.- A movable list keeps each item's identity when peers reorder at the same time: no duplicates. It costs more handlers and more setup.
A third model, C, writes each change as a domain event and folds the events into one object: see Aggregates.
Both as complete apps: model B and model C.
A quick decision guide
| Question | Lean towards |
|---|---|
| Peers edit different fields of the same item at the same time? | Nested, per field — model B |
| Peers edit the same text in real time? | A text handler as a child (model B) |
| The item is atomic, or edited together only rarely? | Flat value + last-writer-wins — model A |
| Drag-to-reorder, with no duplicates on concurrent moves? | CRDTMovableListRefHandler / CRDTFugueMovableListHandler |
| Order matters, and peers insert at the same spot? | A Fugue list (less interleaving) |
| An object changed by domain events, as one unit? | CRDTAggregateHandler — model C |
| A kind of data none of these covers? | Write your own handler |