feat(json-crdt-patch): 🎸 implement combine() for joining two adjacent patches

Author: streamich

src/json-crdt-patch/Patch.ts

@@ -62,7 +62,7 @@ export class Patch implements Printable {
   /**
    * A list of operations in the patch.
    */
-  public readonly ops: JsonCrdtPatchOperation[] = [];
+  public ops: JsonCrdtPatchOperation[] = [];
 
   /**
    * Arbitrary metadata associated with the patch, which is not used by the

src/json-crdt-patch/__tests__/compaction.spec.ts

@@ -0,0 +1,89 @@
+import {LogicalClock} from '../clock';
+import {combine} from '../compaction';
+import {SESSION} from '../constants';
+import {NopOp} from '../operations';
+import {Patch} from '../Patch';
+import {PatchBuilder} from '../PatchBuilder';
+
+describe('.combine()', () => {
+  test('can combine two adjacent patches', () => {
+    const builder = new PatchBuilder(new LogicalClock(123456789, 1));
+    const objId = builder.json({
+      str: 'hello',
+      num: 123,
+      tags: ['a', 'b', 'c'],
+    });
+    builder.root(objId);
+    const patch = builder.flush();
+    const str1 = patch + '';
+    for (let i = 1; i < patch.ops.length - 2; i++) {
+      const ops1 = patch.ops.slice(0, i);
+      const ops2 = patch.ops.slice(i);
+      const patch1 = new Patch();
+      patch1.ops = patch1.ops.concat(ops1);
+      const patch2 = new Patch();
+      patch2.ops = patch2.ops.concat(ops2);
+      combine(patch1, patch2);
+      const str2 = patch1 + '';
+      expect(str2).toBe(str1);
+    }
+  });
+
+  test('can combine two patches with gap', () => {
+    const builder1 = new PatchBuilder(new LogicalClock(123456789, 1));
+    const builder2 = new PatchBuilder(new LogicalClock(123456789, 100));
+    builder1.str();
+    builder2.const(123);
+    const patch1 = builder1.flush();
+    const patch2 = builder2.flush();
+    combine(patch1, patch2);
+    expect(patch1.ops.length).toBe(3);
+    expect(patch1.ops[1]).toBeInstanceOf(NopOp);
+    const nop = patch1.ops[1] as NopOp;
+    expect(nop.id.sid).toBe(123456789);
+    expect(nop.id.time).toBe(2);
+    expect(nop.len).toBe(98);
+  });
+
+  test('throws on mismatching sessions', () => {
+    const builder1 = new PatchBuilder(new LogicalClock(1111111, 1));
+    const builder2 = new PatchBuilder(new LogicalClock(2222222, 100));
+    builder1.str();
+    builder2.const(123);
+    const patch1 = builder1.flush();
+    const patch2 = builder2.flush();
+    expect(() => combine(patch1, patch2)).toThrow(new Error('SID_MISMATCH'));
+  });
+
+  test('first patch can be empty', () => {
+    const builder2 = new PatchBuilder(new LogicalClock(2222222, 100));
+    builder2.const(123);
+    const patch1 = new Patch();
+    const patch2 = builder2.flush();
+    combine(patch1, patch2);
+    expect(patch1 + '').toBe(patch2 + '');
+  });
+
+  test('second patch can be empty', () => {
+    const builder2 = new PatchBuilder(new LogicalClock(2222222, 100));
+    builder2.const(123);
+    const patch1 = new Patch();
+    const patch2 = builder2.flush();
+    const str1 = patch2 + '';
+    combine(patch2, patch1);
+    const str2 = patch2 + '';
+    expect(str2).toBe(str1);
+    expect(patch1.getId()).toBe(undefined);
+  });
+
+  test('throws if first patch has higher logical time', () => {
+    const builder1 = new PatchBuilder(new LogicalClock(123456789, 1));
+    const builder2 = new PatchBuilder(new LogicalClock(123456789, 100));
+    builder1.str();
+    builder2.const(123);
+    const patch1 = builder1.flush();
+    const patch2 = builder2.flush();
+    expect(() => combine(patch2, patch1)).toThrow(new Error('TIMESTAMP_CONFLICT'));
+    combine(patch1, patch2)
+  });
+});

src/json-crdt-patch/compaction.ts

@@ -0,0 +1,41 @@
+/**
+ * @description Operations for combining patches together, combining operations
+ *     together, and cleaning up operations.
+ */
+
+import {Timestamp} from "./clock";
+import {NopOp} from "./operations";
+import type {Patch} from "./Patch";
+
+/**
+ * Combines two patches together. The first patch is modified in place.
+ * Operations from the second patch are appended to the first patch as is
+ * (without cloning).
+ * 
+ * The patches must have the same `sid`. The first patch must have lower logical
+ * time than the second patch, and the logical times must not overlap.
+ *
+ * @param a First patch to combine.
+ * @param b Second patch to combine.
+ */
+export const combine = (a: Patch, b: Patch): void => {
+  const idA = a.getId();
+  const idB = b.getId();
+  if (!idA) {
+    if (!idB) return;
+    a.ops = a.ops.concat(b.ops);
+    return;
+  }
+  if (!idB) return;
+  if (!idA || !idB) throw new Error('EMPTY_PATCH');
+  const sidA = idA.sid;
+  if (sidA !== idB.sid) throw new Error('SID_MISMATCH');
+  const timeA = idA.time;
+  const nextTick = timeA + a.span();
+  const timeB = idB.time;
+  const timeDiff = timeB - nextTick;
+  if (timeDiff < 0) throw new Error('TIMESTAMP_CONFLICT');
+  const needsNoop = timeDiff > 0;
+  if (needsNoop) a.ops.push(new NopOp(new Timestamp(sidA, nextTick), timeDiff));
+  a.ops = a.ops.concat(b.ops);
+};