A shared outline: nested data, saved and synced
A tree of handlers has two rules that a flat document does not have: every peer must know the kinds the tree is made of, and its root needs an id that every peer agrees on. This recipe keeps both, with storage and sync around the tree. The same tree in a Flutter screen is the todo list recipe.
A shared outline: nested data, saved and syncedSource ↗
A Dart program that keeps a tree (chapters, each with a title and a text) in a SQLite file and syncs it through a relay. Another device rebuilds the same tree, and a restart reads it back.
- outline.dart
- open_outline.dart
- main.dart
- Install
import 'package:crdt_lf/crdt_lf.dart';
/// Declares the kinds the outline is made of.
///
/// A peer rebuilds a chapter another peer wrote only when it knows its kinds.
void registerKinds(CRDTDocument document) {
document
..register(CRDTListRefHandler.spec)
..register(CRDTMapRefHandler.spec)
..register(CRDTFugueTextHandler.spec);
}
/// The chapters of [document]: the root of the tree, under a fixed id.
CRDTListRefHandler chaptersOf(CRDTDocument document) {
return document.handler(CRDTListRefHandler.spec, 'chapters');
}
/// Adds a chapter named [title] at the end of [chapters].
CRDTMapRefHandler addChapter(CRDTListRefHandler chapters, String title) {
// One transaction: the other peers get the chapter with both its texts.
return chapters.doc.runInTransaction(() {
final chapter = chapters.insertChild(
chapters.childRefs().length,
CRDTMapRefHandler.spec,
);
chapter.child('title', CRDTFugueTextHandler.spec).insert(0, title);
chapter.child('body', CRDTFugueTextHandler.spec);
return chapter;
});
}
/// The texts of one chapter, each merged character by character.
extension ChapterTexts on CRDTMapRefHandler {
/// The title of the chapter.
CRDTFugueTextHandler get title => child('title', CRDTFugueTextHandler.spec);
/// The text of the chapter.
CRDTFugueTextHandler get body => child('body', CRDTFugueTextHandler.spec);
}
import 'package:crdt_lf_sqlite/crdt_lf_sqlite.dart';
import 'package:crdt_socket_sync/replica.dart';
import 'package:crdt_socket_sync/web_socket_relay_client.dart';
import 'outline.dart';
/// Opens the outline stored in the file [path], and syncs it through the
/// relay at [url].
///
/// Completes once the local copy is ready, even when the relay is down.
Future<CRDTReplica> openOutline(String url, {required String path}) {
return CRDTReplica.open(
// The relay room: every peer of the outline opens the same id.
documentId: 'outline',
// One file per device: it also keeps the peer id of this device.
storage: () => CRDTSqlite.open(path),
sync:
(document) => WebSocketRelayClient(
url: url,
document: document,
author: document.peerId,
),
// Before the restore: the kinds the stored tree is rebuilt from.
onDocument: registerKinds,
);
}
import 'dart:io';
import 'open_outline.dart';
import 'outline.dart';
/// Run it twice, with two files, next to a relay such as the one of the
/// relay recipe: `dart run main.dart alice.db Intro`.
Future<void> main(List<String> args) async {
final path = args.isEmpty ? 'outline.db' : args.first;
final replica = await openOutline('ws://localhost:8080', path: path);
final chapters = chaptersOf(replica.document);
// The whole tree, every reference resolved, after each change.
replica.document.updates.listen((_) => stdout.writeln(chapters.resolved));
if (args.length > 1) {
addChapter(chapters, args[1]);
}
await ProcessSignal.sigint.watch().first;
await replica.close();
}
dart pub add crdt_lf crdt_lf_sqlite crdt_socket_sync
Key points
- Declare the kinds of the tree (
register) inonDocument. Without them, a chapter that comes from the storage or from another peer reads asnull. - Open the root under a fixed id, with
document.handler. Two peers that both start empty and callchild(key, …)each create their own child: one wins, and what the other wrote under its child leaves the tree. insertChildalways adds a new child, so two peers can add chapters at the same time.- Create a chapter and its texts in one transaction: the other peers get the chapter whole.
resolvedreads the whole tree, every reference followed.- Each device needs its own file: it keeps the peer id of the device.