@storacha/md-merge 0.6.0 → 0.8.0

package/dist/diff.js

@@ -109,14 +109,19 @@ function diffGap(oldNodes, newNodes, oldStartIdx, newStartIdx, pathPrefix) {
         });
         oi++;
     }
-    // Remaining new = inserts
-    while (ni < newNodes.length) {
+    // Remaining new = inserts (batched into a single change)
+    if (ni < newNodes.length) {
+        const insertNodes = [];
+        const insertIdx = newStartIdx + ni;
+        while (ni < newNodes.length) {
+            insertNodes.push(newNodes[ni]);
+            ni++;
+        }
         changes.push({
             type: "insert",
-            path: [...pathPrefix, newStartIdx + ni],
-            nodes: [newNodes[ni]],
+            path: [...pathPrefix, insertIdx],
+            nodes: insertNodes,
         });
-        ni++;
     }
     return changes;
 }

package/dist/index.d.ts

@@ -8,7 +8,7 @@ import type { RGAChangeSet, RGATreeRoot } from "./types.js";
 import type { RGAEvent, EventComparator } from "./crdt/rga.js";
 export { parse, stringify, stringifyNode, fingerprint } from "./parse.js";
 export { diff, applyChangeSet } from "./diff.js";
-export { toRGATree, toMdast, applyMdastToRGATree, generateRGAChangeSet, applyRGAChangeSet, } from "./rga-tree.js";
+export { toRGATree, toMdast, applyMdastToRGATree, generateRGAChangeSet, applyRGAChangeSet, mergeRGATrees, } from "./rga-tree.js";
 export { encodeTree, decodeTree, encodeChangeSet, decodeChangeSet, encodeRGA, decodeRGA, } from "./codec.js";
 export type { ChangeSet, Change, RGAChangeSet, RGAChange, RGATreeRoot, RGATreeNode, RGAParentNode, RGALeafNode, } from "./types.js";
 export { RGA, type RGAEvent, type RGANodeId, type EventComparator, } from "./types.js";

package/dist/index.js

@@ -9,7 +9,7 @@ import { toRGATree, toMdast, generateRGAChangeSet, applyRGAChangeSet, } from "./
 // Re-exports
 export { parse, stringify, stringifyNode, fingerprint } from "./parse.js";
 export { diff, applyChangeSet } from "./diff.js";
-export { toRGATree, toMdast, applyMdastToRGATree, generateRGAChangeSet, applyRGAChangeSet, } from "./rga-tree.js";
+export { toRGATree, toMdast, applyMdastToRGATree, generateRGAChangeSet, applyRGAChangeSet, mergeRGATrees, } from "./rga-tree.js";
 export { encodeTree, decodeTree, encodeChangeSet, decodeChangeSet, encodeRGA, decodeRGA, } from "./codec.js";
 export { RGA, } from "./types.js";
 /**

package/dist/rga-tree.d.ts

@@ -30,3 +30,14 @@ export declare function generateRGAChangeSet<E extends RGAEvent>(existing: RGATr
  * Navigates by node IDs at every level — no index dependency.
  */
 export declare function applyRGAChangeSet<E extends RGAEvent>(root: RGATreeRoot<E>, changeset: RGAChangeSet<E>, compareEvents: EventComparator<E>): RGATreeRoot<E>;
+/**
+ * Merge two RGA trees, returning a new tree with nodes from both.
+ *
+ * Clones the target first (non-destructive), merges all source nodes in,
+ * and sets the comparator throughout so linearization uses the correct
+ * (merged) event ordering.
+ *
+ * At each level: union of RGA nodes, tombstones win. For nodes present in
+ * both trees with children, recursively merges children RGAs.
+ */
+export declare function mergeRGATrees<E extends RGAEvent>(target: RGATreeRoot<E>, source: RGATreeRoot<E>, compareEvents: EventComparator<E>): RGATreeRoot<E>;

package/dist/rga-tree.js

@@ -189,18 +189,20 @@ export function applyRGAChangeSet(root, changeset, compareEvents) {
                 break;
             }
             case "insert": {
+                let afterId = change.afterId;
                 for (const node of change.nodes ?? []) {
                     const rgaNode = convertNode(node, changeset.event, compareEvents);
-                    currentRGA.insert(change.afterId, rgaNode, changeset.event);
+                    afterId = currentRGA.insert(afterId, rgaNode, changeset.event);
                 }
                 break;
             }
             case "modify": {
                 if (change.targetId)
                     currentRGA.delete(change.targetId);
+                let afterId = change.afterId;
                 for (const node of change.nodes ?? []) {
                     const rgaNode = convertNode(node, changeset.event, compareEvents);
-                    currentRGA.insert(change.afterId, rgaNode, changeset.event);
+                    afterId = currentRGA.insert(afterId, rgaNode, changeset.event);
                 }
                 break;
             }
@@ -208,3 +210,67 @@ export function applyRGAChangeSet(root, changeset, compareEvents) {
     }
     return { type: "root", children: updatedChildren };
 }
+// ---- Tree Merge ----
+/**
+ * Clone an RGATreeNode, deep-cloning any children RGA.
+ */
+function cloneTreeNode(node) {
+    if (isRGAParent(node)) {
+        return { ...node, children: cloneRGA(node.children) };
+    }
+    return node;
+}
+/**
+ * Merge source RGA nodes into target RGA (mutates target).
+ * For nodes present in both that have children, recursively merges children.
+ * Tombstones win.
+ */
+function mergeChildrenRGA(target, source) {
+    for (const [key, sourceNode] of source.nodes) {
+        const targetNode = target.nodes.get(key);
+        if (!targetNode) {
+            target.nodes.set(key, {
+                ...sourceNode,
+                value: cloneTreeNode(sourceNode.value),
+            });
+        }
+        else {
+            if (sourceNode.tombstone) {
+                targetNode.tombstone = true;
+            }
+            if (isRGAParent(targetNode.value) && isRGAParent(sourceNode.value)) {
+                mergeChildrenRGA(targetNode.value.children, sourceNode.value.children);
+            }
+        }
+    }
+}
+/**
+ * Update the compareEvents function on an RGA and all nested child RGAs.
+ */
+function updateComparators(rga, compareEvents) {
+    rga.compareEvents = compareEvents;
+    for (const node of rga.nodes.values()) {
+        if (isRGAParent(node.value)) {
+            updateComparators(node.value.children, compareEvents);
+        }
+    }
+}
+/**
+ * Merge two RGA trees, returning a new tree with nodes from both.
+ *
+ * Clones the target first (non-destructive), merges all source nodes in,
+ * and sets the comparator throughout so linearization uses the correct
+ * (merged) event ordering.
+ *
+ * At each level: union of RGA nodes, tombstones win. For nodes present in
+ * both trees with children, recursively merges children RGAs.
+ */
+export function mergeRGATrees(target, source, compareEvents) {
+    const result = {
+        type: "root",
+        children: cloneRGA(target.children),
+    };
+    mergeChildrenRGA(result.children, source.children);
+    updateComparators(result.children, compareEvents);
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storacha/md-merge",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/diff.ts

@@ -131,14 +131,19 @@ function diffGap(
     });
     oi++;
   }
-  // Remaining new = inserts
-  while (ni < newNodes.length) {
+  // Remaining new = inserts (batched into a single change)
+  if (ni < newNodes.length) {
+    const insertNodes: RootContent[] = [];
+    const insertIdx = newStartIdx + ni;
+    while (ni < newNodes.length) {
+      insertNodes.push(newNodes[ni] as RootContent);
+      ni++;
+    }
     changes.push({
       type: "insert",
-      path: [...pathPrefix, newStartIdx + ni],
-      nodes: [newNodes[ni] as RootContent],
+      path: [...pathPrefix, insertIdx],
+      nodes: insertNodes,
     });
-    ni++;
   }
   return changes;
 }

package/src/index.ts

@@ -24,6 +24,7 @@ export {
   applyMdastToRGATree,
   generateRGAChangeSet,
   applyRGAChangeSet,
+  mergeRGATrees,
 } from "./rga-tree.js";
 export {
   encodeTree,
@@ -100,8 +101,6 @@ export function fromMarkdown<E extends RGAEvent>(
 /**
  * Convert an RGA tree back to a markdown string.
  */
-export function toMarkdown<E extends RGAEvent>(
-  tree: RGATreeRoot<E>,
-): string {
+export function toMarkdown<E extends RGAEvent>(tree: RGATreeRoot<E>): string {
   return stringify(toMdast(tree));
 }

package/src/rga-tree.ts

@@ -272,25 +272,27 @@ export function applyRGAChangeSet<E extends RGAEvent>(
         break;
       }
       case "insert": {
+        let afterId = change.afterId;
         for (const node of change.nodes ?? []) {
           const rgaNode = convertNode(
             node as Node,
             changeset.event,
             compareEvents,
           );
-          currentRGA.insert(change.afterId, rgaNode, changeset.event);
+          afterId = currentRGA.insert(afterId, rgaNode, changeset.event);
         }
         break;
       }
       case "modify": {
         if (change.targetId) currentRGA.delete(change.targetId);
+        let afterId = change.afterId;
         for (const node of change.nodes ?? []) {
           const rgaNode = convertNode(
             node as Node,
             changeset.event,
             compareEvents,
           );
-          currentRGA.insert(change.afterId, rgaNode, changeset.event);
+          afterId = currentRGA.insert(afterId, rgaNode, changeset.event);
         }
         break;
       }
@@ -299,3 +301,83 @@ export function applyRGAChangeSet<E extends RGAEvent>(
 
   return { type: "root", children: updatedChildren };
 }
+
+// ---- Tree Merge ----
+
+/**
+ * Clone an RGATreeNode, deep-cloning any children RGA.
+ */
+function cloneTreeNode<E extends RGAEvent>(
+  node: RGATreeNode<E>,
+): RGATreeNode<E> {
+  if (isRGAParent(node)) {
+    return { ...node, children: cloneRGA(node.children) } as RGATreeNode<E>;
+  }
+  return node;
+}
+
+/**
+ * Merge source RGA nodes into target RGA (mutates target).
+ * For nodes present in both that have children, recursively merges children.
+ * Tombstones win.
+ */
+function mergeChildrenRGA<E extends RGAEvent>(
+  target: RGA<RGATreeNode<E>, E>,
+  source: RGA<RGATreeNode<E>, E>,
+): void {
+  for (const [key, sourceNode] of source.nodes) {
+    const targetNode = target.nodes.get(key);
+    if (!targetNode) {
+      target.nodes.set(key, {
+        ...sourceNode,
+        value: cloneTreeNode(sourceNode.value),
+      });
+    } else {
+      if (sourceNode.tombstone) {
+        targetNode.tombstone = true;
+      }
+      if (isRGAParent(targetNode.value) && isRGAParent(sourceNode.value)) {
+        mergeChildrenRGA(targetNode.value.children, sourceNode.value.children);
+      }
+    }
+  }
+}
+
+/**
+ * Update the compareEvents function on an RGA and all nested child RGAs.
+ */
+function updateComparators<E extends RGAEvent>(
+  rga: RGA<RGATreeNode<E>, E>,
+  compareEvents: EventComparator<E>,
+): void {
+  rga.compareEvents = compareEvents;
+  for (const node of rga.nodes.values()) {
+    if (isRGAParent(node.value)) {
+      updateComparators(node.value.children, compareEvents);
+    }
+  }
+}
+
+/**
+ * Merge two RGA trees, returning a new tree with nodes from both.
+ *
+ * Clones the target first (non-destructive), merges all source nodes in,
+ * and sets the comparator throughout so linearization uses the correct
+ * (merged) event ordering.
+ *
+ * At each level: union of RGA nodes, tombstones win. For nodes present in
+ * both trees with children, recursively merges children RGAs.
+ */
+export function mergeRGATrees<E extends RGAEvent>(
+  target: RGATreeRoot<E>,
+  source: RGATreeRoot<E>,
+  compareEvents: EventComparator<E>,
+): RGATreeRoot<E> {
+  const result: RGATreeRoot<E> = {
+    type: "root",
+    children: cloneRGA(target.children),
+  };
+  mergeChildrenRGA(result.children, source.children);
+  updateComparators(result.children, compareEvents);
+  return result;
+}

package/test/rga-tree.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect } from "vitest";
 import { parse, stringify } from "../src/parse.js";
-import { toRGATree, toMdast, applyMdastToRGATree } from "../src/rga-tree.js";
+import { toRGATree, toMdast, applyMdastToRGATree, mergeRGATrees, applyRGAChangeSet } from "../src/rga-tree.js";
 import {
   RGA,
   type RGAEvent,
@@ -208,3 +208,242 @@ describe("applyMdast", () => {
     expect(stringify(result).trim()).toBe(stringify(newRoot).trim());
   });
 });
+
+describe("mergeRGATrees", () => {
+
+  const r2 = new TestEvent("r2");
+  const r3 = new TestEvent("r3");
+
+  it("merges two trees from the same base with different additions", () => {
+    const baseMd = "# Hello\n\nOriginal.\n";
+    const baseRoot = parse(baseMd);
+    const base = toRGATree(baseRoot, r1, cmp);
+
+    // Branch 1: add paragraph from r2
+    const tree1 = applyMdastToRGATree(
+      base,
+      parse("# Hello\n\nOriginal.\n\nFrom branch 1.\n"),
+      r2,
+      cmp,
+    );
+
+    // Branch 2: add paragraph from r3
+    const tree2 = applyMdastToRGATree(
+      base,
+      parse("# Hello\n\nOriginal.\n\nFrom branch 2.\n"),
+      r3,
+      cmp,
+    );
+
+    const merged = mergeRGATrees(tree1, tree2, cmp);
+    const result = stringify(toMdast(merged));
+
+    expect(result).toContain("Original.");
+    expect(result).toContain("From branch 1.");
+    expect(result).toContain("From branch 2.");
+  });
+
+  it("merges two independently created trees (concurrent initials)", () => {
+    // Two trees created independently — no shared base
+    const tree1 = toRGATree(parse("# Doc\n\nFrom replica 1.\n"), r2, cmp);
+    const tree2 = toRGATree(parse("# Doc\n\nFrom replica 2.\n"), r3, cmp);
+
+    const merged = mergeRGATrees(tree1, tree2, cmp);
+    const result = stringify(toMdast(merged));
+
+    // Both trees' content should be present (interleaved by event order)
+    expect(result).toContain("From replica 1.");
+    expect(result).toContain("From replica 2.");
+  });
+
+  it("tombstones win during merge", () => {
+    const baseMd = "# Hello\n\nParagraph one.\n\nParagraph two.\n";
+    const baseRoot = parse(baseMd);
+    const base = toRGATree(baseRoot, r1, cmp);
+
+    // Branch 1: delete paragraph two
+    const tree1 = applyMdastToRGATree(
+      base,
+      parse("# Hello\n\nParagraph one.\n"),
+      r2,
+      cmp,
+    );
+
+    // Branch 2: no changes (still has paragraph two)
+    const tree2 = applyMdastToRGATree(base, baseRoot, r1, cmp);
+
+    const merged = mergeRGATrees(tree1, tree2, cmp);
+    const result = stringify(toMdast(merged));
+
+    expect(result).toContain("Paragraph one.");
+    expect(result).not.toContain("Paragraph two.");
+  });
+
+  it("recursively merges nested children (list items)", () => {
+    const baseMd = "- item 1\n- item 2\n";
+    const base = toRGATree(parse(baseMd), r1, cmp);
+
+    // Branch 1: add item 3
+    const tree1 = applyMdastToRGATree(
+      base,
+      parse("- item 1\n- item 2\n- item 3\n"),
+      r2,
+      cmp,
+    );
+
+    // Branch 2: add item 4
+    const tree2 = applyMdastToRGATree(
+      base,
+      parse("- item 1\n- item 2\n- item 4\n"),
+      r3,
+      cmp,
+    );
+
+    const merged = mergeRGATrees(tree1, tree2, cmp);
+    const result = stringify(toMdast(merged));
+
+    expect(result).toContain("item 1");
+    expect(result).toContain("item 2");
+    expect(result).toContain("item 3");
+    expect(result).toContain("item 4");
+  });
+
+  it("does not mutate the input trees", () => {
+    const tree1 = toRGATree(parse("# A\n"), r2, cmp);
+    const tree2 = toRGATree(parse("# B\n"), r3, cmp);
+
+    const origSize1 = tree1.children.nodes.size;
+    const origSize2 = tree2.children.nodes.size;
+
+    mergeRGATrees(tree1, tree2, cmp);
+
+    expect(tree1.children.nodes.size).toBe(origSize1);
+    expect(tree2.children.nodes.size).toBe(origSize2);
+  });
+});
+
+describe("multi-append", () => {
+  it("handles appending multiple nodes at once", () => {
+    const oldMd = "# Hello\n\nOriginal.\n";
+    const newMd = "# Hello\n\nOriginal.\n\nSecond.\n\nThird.\n";
+    const oldRoot = parse(oldMd);
+    const newRoot = parse(newMd);
+    const tree = toRGATree(oldRoot, r1, cmp);
+
+    const r2 = new TestEvent("r2");
+    const updated = applyMdastToRGATree(tree, newRoot, r2, cmp);
+    const result = stringify(toMdast(updated));
+
+    expect(result).toContain("Original.");
+    expect(result).toContain("Second.");
+    expect(result).toContain("Third.");
+    // Verify order is preserved
+    const origIdx = result.indexOf("Original.");
+    const secIdx = result.indexOf("Second.");
+    const thirdIdx = result.indexOf("Third.");
+    expect(origIdx).toBeLessThan(secIdx);
+    expect(secIdx).toBeLessThan(thirdIdx);
+  });
+
+  it("handles appending to an empty children array", () => {
+    const oldMd = "";
+    const newMd = "# Hello\n\nWorld.\n";
+    const oldRoot = parse(oldMd);
+    const newRoot = parse(newMd);
+    const tree = toRGATree(oldRoot, r1, cmp);
+
+    const r2 = new TestEvent("r2");
+    const updated = applyMdastToRGATree(tree, newRoot, r2, cmp);
+    const result = stringify(toMdast(updated));
+
+    expect(result).toContain("Hello");
+    expect(result).toContain("World.");
+  });
+});
+
+describe("applyRGAChangeSet multi-node", () => {
+  const r2 = new TestEvent("r2");
+
+  it("insert with multiple nodes preserves order", () => {
+    const tree = toRGATree(parse("# Hello\n"), r1, cmp);
+    const afterId = tree.children.toNodes()[0].id; // after the heading
+
+    const changeset = {
+      event: r2,
+      changes: [{
+        type: "insert" as const,
+        parentPath: [],
+        afterId,
+        nodes: [
+          { type: "paragraph", children: [{ type: "text", value: "First" }] },
+          { type: "paragraph", children: [{ type: "text", value: "Second" }] },
+          { type: "paragraph", children: [{ type: "text", value: "Third" }] },
+        ] as any,
+      }],
+    };
+
+    const result = applyRGAChangeSet(tree, changeset, cmp);
+    const md = stringify(toMdast(result));
+
+    expect(md).toContain("First");
+    expect(md).toContain("Second");
+    expect(md).toContain("Third");
+    expect(md.indexOf("First")).toBeLessThan(md.indexOf("Second"));
+    expect(md.indexOf("Second")).toBeLessThan(md.indexOf("Third"));
+  });
+
+  it("modify with multiple replacement nodes preserves order", () => {
+    const tree = toRGATree(parse("# Hello\n\nOriginal.\n"), r1, cmp);
+    const nodes = tree.children.toNodes();
+    const targetId = nodes[1].id; // the paragraph
+    const afterId = nodes[0].id; // after the heading
+
+    const changeset = {
+      event: r2,
+      changes: [{
+        type: "modify" as const,
+        parentPath: [],
+        targetId,
+        afterId,
+        nodes: [
+          { type: "paragraph", children: [{ type: "text", value: "Replacement A" }] },
+          { type: "paragraph", children: [{ type: "text", value: "Replacement B" }] },
+        ] as any,
+      }],
+    };
+
+    const result = applyRGAChangeSet(tree, changeset, cmp);
+    const md = stringify(toMdast(result));
+
+    expect(md).not.toContain("Original.");
+    expect(md).toContain("Replacement A");
+    expect(md).toContain("Replacement B");
+    expect(md.indexOf("Replacement A")).toBeLessThan(md.indexOf("Replacement B"));
+  });
+
+  it("insert at start (no afterId) with multiple nodes preserves relative order", () => {
+    // Insert two nodes at root with no afterId. RGA ordering means they
+    // appear after existing r1 nodes (r2 > r1), but their relative order
+    // (A before B) is preserved via chained afterIds.
+    const tree = toRGATree(parse("# Existing\n"), r1, cmp);
+
+    const changeset = {
+      event: r2,
+      changes: [{
+        type: "insert" as const,
+        parentPath: [],
+        afterId: undefined,
+        nodes: [
+          { type: "paragraph", children: [{ type: "text", value: "Added A" }] },
+          { type: "paragraph", children: [{ type: "text", value: "Added B" }] },
+        ] as any,
+      }],
+    };
+
+    const result = applyRGAChangeSet(tree, changeset, cmp);
+    const md = stringify(toMdast(result));
+
+    // Relative order of the inserted nodes is preserved
+    expect(md.indexOf("Added A")).toBeLessThan(md.indexOf("Added B"));
+  });
+});