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
);
documentIdnames the resource: storage and sync route by it, and peers that share a document use the same one. Left out, it is random.peerIdis 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 to | Page |
|---|---|
| open, find and delete handlers | Handlers |
| group edits into one change, and exchange changes with a peer | Changes and sync |
| keep the history small | Snapshots and history |
| look at the past | History |
| react to changes | Reactivity, Handler deltas |
| take back your own edits | Undo and redo |
| check what a peer can read | Versions and compatibility |
| handle what it throws | Errors |
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.