Skip to main content

The document

A CRDTDocument is one shared piece of data: a note, a board, a project. Every peer holds its own copy. Everything else in this site works around a document: the handlers live in it, the connectors store it and send it.

What it holds​

  • Handlers. Each handler is one value with its own merge rules, under an id: CRDTFugueTextHandler(doc, 'note'). See Handlers.
  • Changes. Every edit becomes an operation. A transaction turns the operations into changes: the unit that peers exchange. See Changes and sync.
  • The change graph. Each change points at the changes it depends on. That graph says which changes are concurrent, and what each peer has already seen.
  • The snapshot. The state of every handler at one version, so the history before it can be dropped. See Snapshots and history.
  • The clock. A hybrid logical clock plus the peer id gives every change a unique, ordered id.

Create one​

final doc = CRDTDocument(
documentId: 'note-42', // the resource: storage and sync route by it
peerId: devicePeerId, // the author of the changes written here
);
  • documentId names the resource: storage and sync route by it, and peers that share a document use the same one. Left out, it is random.
  • peerId is the author of every change this copy writes. Keep one per device (see Peer identity). Left out, a new one is generated.

In an app you rarely call the constructor yourself: CRDTReplica.open and the persistence adapters build the document, restore it and keep the same peerId.

dispose() closes the document, the streams of its handlers and its undo managers. The events still waiting are delivered first.

Find your way​

You want toPage
open, find and delete handlersHandlers
group edits into one change, and exchange changes with a peerChanges and sync
keep the history smallSnapshots and history
look at the pastHistory
react to changesReactivity, Handler deltas
take back your own editsUndo and redo
check what a peer can readVersions and compatibility
handle what it throwsErrors

These pages say when to use a member. Every member, with its arguments and defaults, is in the API reference of CRDTDocument. How it works inside is in the deep dive.