Add incremental Automerge field changes

src/crdt-automerge.ts

@@ -1,6 +1,13 @@
 import * as Automerge from "@automerge/automerge";
 
-export type CaminoCrdtEncoding = "base64";
+export const AUTOMERGE_SNAPSHOT_ENCODING = "automerge-snapshot-v1";
+export const AUTOMERGE_CHANGES_ENCODING = "automerge-changes-v1";
+
+// `base64` was the original encoding label. Its payload was an Automerge save.
+export type CaminoCrdtEncoding =
+  | "base64"
+  | typeof AUTOMERGE_SNAPSHOT_ENCODING
+  | typeof AUTOMERGE_CHANGES_ENCODING;
 
 export type CaminoCrdtEnvelope = {
   $caminoCrdtType: string;
@@ -29,7 +36,7 @@ const bytesToBase64 = (value: Uint8Array) => {
 
 const base64ToBytes = (value: string) => {
   if (typeof Buffer !== "undefined") {
-    return Buffer.from(value, "base64");
+    return new Uint8Array(Buffer.from(value, "base64"));
   }
   const binary = atob(value);
   const bytes = new Uint8Array(binary.length);
@@ -39,6 +46,11 @@ const base64ToBytes = (value: string) => {
   return bytes;
 };
 
+const isCrdtEncoding = (value: unknown): value is CaminoCrdtEncoding =>
+  value === "base64" ||
+  value === AUTOMERGE_SNAPSHOT_ENCODING ||
+  value === AUTOMERGE_CHANGES_ENCODING;
+
 export const isCaminoCrdtEnvelope = (
   value: unknown,
 ): value is CaminoCrdtEnvelope =>
@@ -49,10 +61,10 @@ export const isCaminoCrdtEnvelope = (
     "string" &&
   typeof (value as { $caminoCrdtPayload?: unknown }).$caminoCrdtPayload ===
     "string" &&
-  ((value as { $caminoCrdtEncoding?: unknown }).$caminoCrdtEncoding ===
-    undefined ||
-    (value as { $caminoCrdtEncoding?: unknown }).$caminoCrdtEncoding ===
-      "base64");
+  isCrdtEncoding(
+    (value as { $caminoCrdtEncoding?: unknown }).$caminoCrdtEncoding ??
+      "base64",
+  );
 
 const assertEnvelopeType = (value: CaminoCrdtEnvelope, type: string) => {
   if (value.$caminoCrdtType !== type) {
@@ -62,13 +74,21 @@ const assertEnvelopeType = (value: CaminoCrdtEnvelope, type: string) => {
   }
 };
 
+const requireSnapshotEnvelope = (value: CaminoCrdtEnvelope, type: string) => {
+  assertEnvelopeType(value, type);
+  if (value.$caminoCrdtEncoding === AUTOMERGE_CHANGES_ENCODING) {
+    throw new Error("An Automerge change batch cannot be loaded without a base document");
+  }
+  return value;
+};
+
 export const loadAutomergeFieldDoc = (
   value: CaminoCrdtEnvelope,
   type: string,
 ): Automerge.Doc<AutomergeFieldDoc> => {
-  assertEnvelopeType(value, type);
+  const snapshot = requireSnapshotEnvelope(value, type);
   return Automerge.load<AutomergeFieldDoc>(
-    base64ToBytes(value.$caminoCrdtPayload),
+    base64ToBytes(snapshot.$caminoCrdtPayload),
   );
 };
 
@@ -77,7 +97,7 @@ export const saveAutomergeFieldDoc = (
   type: string,
 ): CaminoCrdtEnvelope => ({
   $caminoCrdtType: type,
-  $caminoCrdtEncoding: "base64",
+  $caminoCrdtEncoding: AUTOMERGE_SNAPSHOT_ENCODING,
   $caminoCrdtPayload: bytesToBase64(Automerge.save(doc)),
 });
 
@@ -101,6 +121,61 @@ export const isAutomergeFieldDoc = (
   }
 };
 
+const encodeChanges = (changes: Automerge.Change[]): Uint8Array => {
+  const totalLength = changes.reduce((total, change) => total + 4 + change.length, 4);
+  const payload = new Uint8Array(totalLength);
+  const view = new DataView(payload.buffer);
+  view.setUint32(0, changes.length);
+  let offset = 4;
+  for (const change of changes) {
+    view.setUint32(offset, change.length);
+    offset += 4;
+    payload.set(change, offset);
+    offset += change.length;
+  }
+  return payload;
+};
+
+const decodeChanges = (payload: Uint8Array): Automerge.Change[] => {
+  if (payload.length < 4) {
+    throw new Error("Invalid Automerge change batch: missing change count");
+  }
+  const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength);
+  const count = view.getUint32(0);
+  const changes: Automerge.Change[] = [];
+  let offset = 4;
+  for (let index = 0; index < count; index += 1) {
+    if (offset + 4 > payload.length) {
+      throw new Error("Invalid Automerge change batch: missing change length");
+    }
+    const length = view.getUint32(offset);
+    offset += 4;
+    if (offset + length > payload.length) {
+      throw new Error("Invalid Automerge change batch: truncated change");
+    }
+    changes.push(payload.slice(offset, offset + length));
+    offset += length;
+  }
+  if (offset !== payload.length) {
+    throw new Error("Invalid Automerge change batch: trailing bytes");
+  }
+  return changes;
+};
+
+export const createAutomergeFieldChanges = (
+  base: Automerge.Doc<AutomergeFieldDoc>,
+  next: Automerge.Doc<AutomergeFieldDoc>,
+  type: string,
+): CaminoCrdtEnvelope => ({
+  $caminoCrdtType: type,
+  $caminoCrdtEncoding: AUTOMERGE_CHANGES_ENCODING,
+  $caminoCrdtPayload: bytesToBase64(
+    encodeChanges(Automerge.getChanges(base, next)),
+  ),
+});
+
+// Full snapshots remain an explicit escape hatch for initialization, import,
+// and recovery when a client cannot establish a shared Automerge history.
 export const encodeAutomergeFieldWrite = (
   value: unknown,
   type: string,
@@ -142,17 +217,35 @@ export const mergeAutomergeFieldValues = ({
   incoming,
   type,
 }: MergeAutomergeFieldValueParams): MergeAutomergeFieldValueResult => {
-  const incomingDoc = loadAutomergeFieldDoc(
-    normalizeAutomergeFieldValue(incoming, type),
-    type,
-  );
-  const mergedDoc =
-    existing === undefined || existing === null
-      ? incomingDoc
-      : Automerge.merge(
-          loadAutomergeFieldDoc(normalizeAutomergeFieldValue(existing, type), type),
-          incomingDoc,
-        );
+  const incomingEnvelope = isCaminoCrdtEnvelope(incoming)
+    ? incoming
+    : encodeAutomergeFieldWrite(incoming, type);
+  assertEnvelopeType(incomingEnvelope, type);
+
+  let mergedDoc: Automerge.Doc<AutomergeFieldDoc>;
+  if (incomingEnvelope.$caminoCrdtEncoding === AUTOMERGE_CHANGES_ENCODING) {
+    if (existing === undefined || existing === null) {
+      throw new Error("Cannot apply an Automerge change batch to a missing field");
+    }
+    const existingDoc = loadAutomergeFieldDoc(
+      encodeAutomergeFieldWrite(existing, type),
+      type,
+    );
+    [mergedDoc] = Automerge.applyChanges(
+      existingDoc,
+      decodeChanges(base64ToBytes(incomingEnvelope.$caminoCrdtPayload)),
+    );
+  } else {
+    const incomingDoc = loadAutomergeFieldDoc(incomingEnvelope, type);
+    mergedDoc =
+      existing === undefined || existing === null
+        ? incomingDoc
+        : Automerge.merge(
+            loadAutomergeFieldDoc(encodeAutomergeFieldWrite(existing, type), type),
+            incomingDoc,
+          );
+  }
+
   const stored = saveAutomergeFieldDoc(mergedDoc, type);
   return {
     stored,