feat(json-crdt): 🎸 improve the PatchLog class

Author: streamich

src/json-crdt/file/File.ts

@@ -1,5 +1,5 @@
 import {Model} from '../model';
-import {PatchLog} from './PatchLog';
+import {PatchLog} from '../history/PatchLog';
 import {printTree} from '../../util/print/printTree';
 import {decodeModel, decodeNdjsonComponents, decodePatch, decodeSeqCborComponents} from './util';
 import {Patch} from '../../json-crdt-patch';
@@ -75,7 +75,7 @@ export class File implements Printable {
   }
 
   public static fromModel(model: Model<any>, options: FileOptions = {}): File {
-    return new File(model, PatchLog.fromModel(model), options);
+    return new File(model, PatchLog.fromNewModel(model), options);
   }
 
   constructor(

src/json-crdt/history/PatchLog.ts

@@ -1,3 +1,4 @@
+import {FanOutUnsubscribe} from 'thingies/es2020/fanout';
 import {ITimestampStruct, Patch, compare} from '../../json-crdt-patch';
 import {printTree} from '../../util/print/printTree';
 import {AvlMap} from '../../util/trees/avl/AvlMap';
@@ -6,32 +7,84 @@ import {first, next} from '../../util/trees/util';
 import type {Printable} from '../../util/print/types';
 
 export class PatchLog implements Printable {
+  /**
+   * Creates a `PatchLog` instance from a newly JSON CRDT model. Checks if
+   * the model API buffer has any initial operations applied, if yes, it
+   * uses them to create the initial state of the log.
+   *
+   * @param model A new JSON CRDT model, just created with
+   *              `Model.withLogicalClock()` or `Model.withServerClock()`.
+   * @returns A new `PatchLog` instance.
+   */
   public static fromNewModel(model: Model<any>): PatchLog {
-    const start = new Model(model.clock.clone());
-    const log = new PatchLog(start);
+    const clock = model.clock.clone();
+    const log = new PatchLog(() => new Model(clock));
     const api = model.api;
-    if (api.builder.patch.ops.length) log.push(api.flush());
+    if (api.builder.patch.ops.length) log.end.applyPatch(api.flush());
     return log;
   }
 
+  /**
+   * Model factory function that creates a new JSON CRDT model instance, which
+   * is used as the starting point of the log. It is called every time a new
+   * model is needed to replay the log.
+   */
+  public readonly start: () => Model;
+
+  /**
+   * The end of the log, the current state of the document. It is the model
+   * instance that is used to apply new patches to the log.
+   */
+  public readonly end: Model;
+
+  /**
+   * The patches in the log, stored in an AVL tree for efficient replaying. The
+   * collection of patches which are applied to the `start()` model to reach
+   * the `end` model.
+   */
   public readonly patches = new AvlMap<ITimestampStruct, Patch>(compare);
+  private _patchesUnsub: FanOutUnsubscribe;
 
-  constructor(public readonly start: Model) {}
+  constructor(start: () => Model) {
+    this.start = start;
+    this.end = start();
+    this._patchesUnsub = this.end.api.onPatch.listen((patch) => {
+      const id = patch.getId();
+      if (!id) return;
+      this.patches.set(id, patch);
+    });
+  }
 
-  public push(patch: Patch): void {
-    const id = patch.getId();
-    if (!id) return;
-    this.patches.set(id, patch);
+  /**
+   * Call this method to destroy the `PatchLog` instance. It unsubscribes from
+   * the model's `onPatch` event listener.
+   */
+  public destroy() {
+    this._patchesUnsub();
   }
 
+  /**
+   * Creates a new model instance using the `start()` factory function and
+   * replays all patches in the log to reach the current state of the document.
+   *
+   * @returns A new model instance with all patches replayed.
+   */
   public replayToEnd(): Model {
-    const clone = this.start.clone();
+    const clone = this.start().clone();
     for (let node = first(this.patches.root); node; node = next(node)) clone.applyPatch(node.v);
     return clone;
   }
 
+  /**
+   * Replays the patch log until a specified timestamp, including the patch
+   * at the given timestamp. The model returned is a new instance of `start()`
+   * with patches replayed up to the given timestamp.
+   *
+   * @param ts Timestamp ID of the patch to replay to.
+   * @returns A new model instance with patches replayed up to the given timestamp.
+   */
   public replayTo(ts: ITimestampStruct): Model {
-    const clone = this.start.clone();
+    const clone = this.start().clone();
     for (let node = first(this.patches.root); node && compare(ts, node.k) >= 0; node = next(node))
       clone.applyPatch(node.v);
     return clone;
@@ -45,14 +98,16 @@ export class PatchLog implements Printable {
     return (
       `log` +
       printTree(tab, [
-        (tab) => this.start.toString(tab),
+        (tab) => `start` + printTree(tab, [tab => this.start().toString(tab)]),
         () => '',
         (tab) =>
-          'history' +
+        'history' +
           printTree(
             tab,
             log.map((patch, i) => (tab) => `${i}: ${patch.toString(tab)}`),
           ),
+        () => '',
+        (tab) => `end` + printTree(tab, [tab => this.end.toString(tab)]),
       ])
     );
   }

src/json-crdt/file/__tests__/PatchLog.spec.ts renamed to src/json-crdt/history/__tests__/PatchLog.spec.ts

@@ -1,28 +1,28 @@
 import {Model} from '../../model';
-import {File} from '../File';
+import {PatchLog} from '../PatchLog';
 
 const setup = (view: unknown) => {
   const model = Model.withServerClock();
   model.api.root(view);
-  const file = File.fromModel(model);
-  return {model, file};
+  const log = PatchLog.fromNewModel(model);
+  return {log};
 };
 
 test('can replay to specific patch', () => {
-  const {file} = setup({foo: 'bar'});
-  const model = file.model.clone();
+  const {log} = setup({foo: 'bar'});
+  const model = log.end.clone();
   model.api.obj([]).set({x: 1});
   const patch1 = model.api.flush();
   model.api.obj([]).set({y: 2});
   const patch2 = model.api.flush();
-  file.apply(patch1);
-  file.apply(patch2);
-  const model2 = file.log.replayToEnd();
-  const model3 = file.log.replayTo(patch1.getId()!);
-  const model4 = file.log.replayTo(patch2.getId()!);
+  log.end.applyPatch(patch1);
+  log.end.applyPatch(patch2);
+  const model2 = log.replayToEnd();
+  const model3 = log.replayTo(patch1.getId()!);
+  const model4 = log.replayTo(patch2.getId()!);
   expect(model.view()).toEqual({foo: 'bar', x: 1, y: 2});
-  expect(file.model.view()).toEqual({foo: 'bar', x: 1, y: 2});
-  expect(file.log.start.view()).toEqual(undefined);
+  expect(log.end.view()).toEqual({foo: 'bar', x: 1, y: 2});
+  expect(log.start().view()).toEqual(undefined);
   expect(model2.view()).toEqual({foo: 'bar', x: 1, y: 2});
   expect(model3.view()).toEqual({foo: 'bar', x: 1});
   expect(model4.view()).toEqual({foo: 'bar', x: 1, y: 2});