Skip to main content

History

A document keeps every change it applied, so it can show itself as it was after any of them: "who wrote this paragraph, and when?". A history session is a read-only copy of the document with a cursor you move through its changes.

It is different from undo. Undo writes a new edit that other peers receive. A history session writes nothing: it only shows the past.

Time travel in crdt_lf​

toTimeTravel() freezes the document as it is now, and puts the cursor at the end:

final document = CRDTDocument();
final note = CRDTFugueTextHandler(document, 'note');
note
..insert(0, 'Hello')
..insert(5, ' world');

final session = document.toTimeTravel();
final past = session.getHandler((doc) => CRDTFugueTextHandler(doc, 'note'));

print(session.length); // 2: one step per change
print(past.value); // Hello world

session.previous();
print(past.value); // Hello

session.jump(0);
print(past.value); // '': the state before the first change

session.dispose();
  • cursor is the number of changes the view shows, from 0 to length. next(), previous() and jump(cursor) move it. canNext and canPrevious tell you if a move is possible, so you can enable your buttons.
  • cursorStream emits the new cursor after each move.
  • session.document is the read-only document. getHandler opens a handler on it. session.document.handlerById(id) also works: it opens the handlers the changes name, at any cursor.
  • The steps follow the order of the changes' clocks (then of their authors): the same order on every peer.
  • Each handler you opened reads the state at the cursor. Its watch() stream gets a reset at every move, so a watcher reads the value again.
  • dispose() releases the session and ends the delta streams it gave out.

Read-only, and frozen​

The view refuses every write: insert, runInTransaction, deleteHandler throw a ReadOnlyDocumentException.

The session is a copy of the history when you created it. Edits made later, local or remote, do not reach it. Create a new session to see them.

How far back it goes​

A session starts from the last snapshot of the document. After a prune (takeSnapshot, garbageCollect), the changes the snapshot covers are gone, so cursor 0 is the snapshot, not an empty document. To keep the whole history, take snapshots with pruneHistory: false (see Snapshots).

With persistence, documentAt reads a stored document as it was at a version, and keepSnapshots keeps older snapshots so that it can reach further back (see The document as it was).

In Flutter​

CrdtHistoryScope from crdt_lf_flutter takes a session of the document in scope, and shows the frozen view to the widgets below it. The widgets that follow one handler, such as CrdtHandlerBuilder, read the view instead of the live document. So the widget that draws the note today can also draw it in the past, with no change.


Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('History')),
// Takes the history as it is now, and shows it to the widgets below.
body: CrdtHistoryScope(
// Built once: it reads the view, and rebuilds on every move.
child: const NotePreview(),
builder:
(context, session, preview) => Column(
children: [
Expanded(child: preview!),
HistoryControls(session: session),
],
),
),
);
}

/// The text of the note. Inside a history scope it reads the past.
class NotePreview extends StatelessWidget {
/// Creates the preview of the note.
const NotePreview({super.key});


Widget build(BuildContext context) {
// The same widget shows the live note outside a history scope.
return CrdtHandlerBuilder<CRDTFugueTextHandler>(
id: 'note',
builder:
(context, note) => SingleChildScrollView(
padding: const EdgeInsets.all(16),
child: Align(alignment: Alignment.topLeft, child: Text(note.value)),
),
);
}
}
  • builder runs on every move of the cursor, with the session.
  • The scope takes the session once per document, and disposes it with itself. Open the screen again to see the edits made after it opened.
  • The widgets that read or write the live document throw inside the scope: the document-level builders (CrdtBuilder), the text fields, the editor binder and the cursor overlays. They would draw the present inside a view that looks frozen, and a text field there would look editable.

Who wrote it, and when​

Every change carries its author and its clock, so a history screen can say who made the change the cursor stands on:

/// Who made the change the cursor of [session] stands on, and when.
String describeChange(HistorySession session) {
// The view holds the changes up to the cursor.
final changes = session.document.exportChanges();
if (changes.isEmpty) {
return 'Before the first change';
}
final last = changes.last;
final author =
last.author == session.document.peerId
? 'You'
: last.author.id.substring(0, 8);
final time = last.id.hlc.asDateTime.toLocal();
final minute = time.minute.toString().padLeft(2, '0');
return '$author · ${time.hour}:$minute';
}

The view exports the changes up to the cursor, so the last one is the change the cursor stands on. At cursor 0 there is none.