Skip to main content

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 editHandlerPage
prose, notes, code, together and in real timeCRDTFugueTextHandlerCollaborative text
text with bold, links, headings, imagesCRDTFugueRichTextHandlerRich text
an ordered list: todos, items, blocksCRDTFugueListHandler, CRDTFugueMovableListHandlerLists
keys and values, a set of tags, one flagCRDTORMapHandler, CRDTORSetHandler, CRDTMapHandler, CRDTRegisterHandlerMaps, sets and values
a tree: chapters → paragraphs, slides → shapesthe container handlers (CRDTMapRefHandler, …)Nested data
a domain object changed by eventsCRDTAggregateHandlerAggregates

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 text and done of the same item at the same time: one update wins, 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 text while another toggles done on the same item, and both survive.
  • text merges character by character. done is 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​

QuestionLean 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