@storacha/md-merge 0.5.0 → 0.7.0

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";
@@ -31,3 +31,7 @@ export declare function applyToMarkdown<E extends RGAEvent>(tree: RGATreeRoot<E>
  * Bootstrap: create an RGA tree from a markdown string.
  */
 export declare function fromMarkdown<E extends RGAEvent>(markdown: string, event: E, compareEvents: EventComparator<E>): RGATreeRoot<E>;
+/**
+ * Convert an RGA tree back to a markdown string.
+ */
+export declare function toMarkdown<E extends RGAEvent>(tree: RGATreeRoot<E>): string;

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";
 /**
@@ -39,3 +39,9 @@ export function fromMarkdown(markdown, event, compareEvents) {
     const root = parse(markdown);
     return toRGATree(root, event, compareEvents);
 }
+/**
+ * Convert an RGA tree back to a markdown string.
+ */
+export function toMarkdown(tree) {
+    return stringify(toMdast(tree));
+}

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

@@ -208,3 +208,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.5.0",
+  "version": "0.7.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -24,6 +24,7 @@ export {
   applyMdastToRGATree,
   generateRGAChangeSet,
   applyRGAChangeSet,
+  mergeRGATrees,
 } from "./rga-tree.js";
 export {
   encodeTree,
@@ -96,3 +97,10 @@ export function fromMarkdown<E extends RGAEvent>(
   const root = parse(markdown);
   return toRGATree(root, event, compareEvents);
 }
+
+/**
+ * Convert an RGA tree back to a markdown string.
+ */
+export function toMarkdown<E extends RGAEvent>(tree: RGATreeRoot<E>): string {
+  return stringify(toMdast(tree));
+}

package/src/rga-tree.ts

@@ -299,3 +299,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 } from "../src/rga-tree.js";
 import {
   RGA,
   type RGAEvent,
@@ -208,3 +208,116 @@ 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);
+  });
+});