reptree 1.0.0 → 1.0.2

package/README.md

@@ -1,116 +1,131 @@
-# RepTree - replicated trees with properties
+# RepTree
 
-A JavaScript tree data structure for storing and syncing app state. It can be used both to represent and persist the state in the frontend and backend.
+RepTree is a small TypeScript library for replicated trees with properties.
 
-RepTree uses [CRDTs](https://crdt.tech/) for seamless replication between users.
+Use it when your application state is naturally a tree and multiple peers may edit it: folders, documents with nested blocks, scene graphs, project structures, object graphs, or any UI model where nodes can move and carry properties.
 
-> RepTree was created for the [Sila](https://github.com/silaorg/sila) project, an open-source alternative to ChatGPT.
+RepTree is built on CRDTs, so peers can exchange operations in any order and converge on the same state without a central merge coordinator.
 
-## What it solves
-
-If you have a tree structure in your app where each node can be moved independently by multiple users, you need a solution that resolves conflicts when the same node is moved in different ways. Otherwise your tree can diverge or form loops. This includes folder structures (people creating and moving folders), 2D/3D scenes with objects being moved and parented, and Notion‑like documents where blocks with text and other properties are edited by users.
-
-You probably also want properties on each node and to have them sync correctly between peers without conflicts. RepTree syncs properties too.
-
-## Getting started
+## Install
 
 ```bash
 npm install reptree
 ```
 
-### Example 1
+## What RepTree Gives You
+
+- Tree nodes that can be created, moved, deleted, and observed.
+- JSON-serializable properties on every node.
+- Last-writer-wins property conflict resolution.
+- Move conflict resolution based on the move operation tree CRDT.
+- Operation-based sync for persistence or peer replication.
+- State vectors for efficient delta sync.
+- Optional typed/reactive node bindings.
+
+## Basic Usage
+
 ```ts
 import { RepTree } from "reptree";
 
-// Create a tree with a root
-const tree = new RepTree("company-org-1");
-const company = tree.createRoot();
+const tree = new RepTree("peer-a");
+const root = tree.createRoot();
+root.name = "Project";
 
-// Create nodes in the root of our new tree
-const devs = company.newNamedChild("developers");
-const qa = company.newNamedChild("qa");
+const docs = root.newNamedChild("Docs", {
+  type: "folder",
+  icon: "folder",
+});
 
-// Create a node in another node
-const alice = qa.newChild();
+const readme = docs.newNamedChild("README.md", {
+  type: "file",
+  size: 2048,
+  tags: ["docs", "intro"],
+});
 
-// Set properties (supports any JSON-serializable values)
-alice.setProperty("name", "Alice");
-alice.setProperty("age", 32);
-alice.setProperty("meta", { department: "QA", skills: ["cypress", "playwright"], flags: { lead: false } });
+const assets = root.newNamedChild("Assets", { type: "folder" });
+readme.moveTo(assets);
 
-// Move the node inside a different node
-alice.moveTo(devs);
+console.log(readme.parent?.name); // "Assets"
+console.log(readme.getProperty("size")); // 2048
+```
 
-// Bind a node to a type to set its properties like regular fields
-const bob = qa.newChild().bind<{ name: string; age: number }>();
-bob.name = "Bob";
-bob.age = 33;
+## Sync
 
-// Use a Zod type for runtime type checks
-import { z } from "zod";
-const Person = z.object({ name: z.string(), age: z.number().int().min(0) });
-const casey = devs.newNamedChild("Casey").bind(Person);
-casey.name = "Casey";
-casey.age = 34;
+RepTree syncs by exchanging operations. Store operations, send them over the network, and merge operations received from other peers.
+
+```ts
+import { RepTree } from "reptree";
+
+const alice = new RepTree("alice");
+const aliceRoot = alice.createRoot();
+aliceRoot.newNamedChild("Roadmap", { status: "draft" });
+
+const bob = new RepTree("bob");
+bob.merge(alice.getAllOps());
+
+bob.root!.newNamedChild("Notes", { status: "open" });
+alice.merge(bob.getAllOps());
 ```
 
-### Example 2
+For larger trees, use state vectors to send only operations the other peer is missing:
 
-```typescript
-import { RepTree } from "reptree";
+```ts
+const aliceVectors = alice.getStateVectors();
 
-// Create a new tree
-const tree = new RepTree("peer1");
-const root = tree.createRoot();
-root.name = "Project";
+if (aliceVectors) {
+  const opsForAlice = bob.getMissingOps(aliceVectors);
+  alice.merge(opsForAlice);
+}
+```
 
-// Create a folder structure with properties
-const docsFolder = root.newNamedChild("Docs");
-docsFolder.setProperties({
-  type: "folder",
-  icon: "folder-icon",
-});
+Property operations are compacted by `(nodeId, key)`: RepTree keeps the latest winning property operation for each property and uses the property state vector to describe that retained, sendable set. Move operations keep their history so the move CRDT can resolve structural conflicts.
 
-const imagesFolder = root.newNamedChild("Images");
-imagesFolder.setProperties({
-  type: "folder",
-  icon: "image-icon",
-});
+## Typed Nodes
 
-// Add files to folders
-const readmeFile = docsFolder.newNamedChild("README.md");
-readmeFile.setProperties({
-  type: "file",
-  size: 2048,
-  lastModified: "2023-10-15T14:22:10Z",
-  s3Path: "s3://my-bucket/docs/README.md",
-});
+You can bind a node to a live typed object. Reads and writes go through RepTree.
 
-const logoFile = imagesFolder.newNamedChild("logo.png");
-logoFile.setProperties({
-  type: "file",
-  size: 15360,
-  meta: { dimensions: "512x512", format: "png" },
-  s3Path: "s3://my-bucket/images/logo.png",
+```ts
+type Task = {
+  title: string;
+  done: boolean;
+};
+
+const task = root.newNamedChild("Task").bind<Task>();
+task.title = "Write README";
+task.done = false;
+
+task.$observe(() => {
+  console.log(task.title, task.done);
 });
+```
 
-// Move a file to a different folder
-logoFile.moveTo(docsFolder);
+Zod-style schemas are supported for runtime validation:
 
-// Get children of a folder
-const docsFolderContents = docsFolder.children;
+```ts
+import { z } from "zod";
 
-// Syncing between trees
-const otherTree = new RepTree("peer2");
-const ops = tree.getAllOps();
-otherTree.merge(ops);
+const TaskSchema = z.object({
+  title: z.string(),
+  done: z.boolean(),
+});
+
+const checkedTask = root.newNamedChild("Checked task").bind(TaskSchema);
+checkedTask.title = "Publish package";
+checkedTask.done = true;
 ```
 
-## CRDTs
+## Operation Model
+
+RepTree uses two conflict-free replicated data types:
+
+- A move tree CRDT for the tree structure, based on Kleppmann's [move operation paper](https://martin.kleppmann.com/papers/move-op.pdf).
+- A last-writer-wins (LWW) CRDT for node properties.
+
+Both streams have independent counters and state vectors. This keeps property-heavy workloads compact while preserving the move history needed for deterministic tree convergence.
+
+## Origin
 
-RepTree uses two conflict-free replicated data types (CRDTs):
-- A move tree CRDT for the tree structure (https://martin.kleppmann.com/papers/move-op.pdf).
-- A last-writer-wins (LWW) CRDT for properties.
+RepTree was created for [Sila](https://github.com/silaorg/sila), an open-source alternative to ChatGPT.
 
 ## License
 

package/dist/index.cjs

@@ -793,12 +793,63 @@ var StateVector = class _StateVector {
   updateFromOp(op) {
     this.update(op.id.peerId, op.id.counter);
   }
+  /**
+   * Removes a single operation ID from the state vector.
+   * Assumes ranges are sorted and non-overlapping.
+   *
+   * @param peerId The peer ID of the operation
+   * @param counter The counter value of the operation
+   * @returns true if a counter was removed, false if it was absent
+   */
+  remove(peerId, counter) {
+    const ranges = this.ranges[peerId];
+    if (!ranges) {
+      return false;
+    }
+    for (let i = 0; i < ranges.length; i++) {
+      const range = ranges[i];
+      const [start, end] = range;
+      if (counter < start) {
+        return false;
+      }
+      if (counter > end) {
+        continue;
+      }
+      if (start === end) {
+        ranges.splice(i, 1);
+      } else if (counter === start) {
+        range[0] = start + 1;
+      } else if (counter === end) {
+        range[1] = end - 1;
+      } else {
+        ranges.splice(i, 1, [start, counter - 1], [counter + 1, end]);
+      }
+      if (ranges.length === 0) {
+        delete this.ranges[peerId];
+      }
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Removes the operation ID from the state vector.
+   *
+   * @param op The operation to remove
+   * @returns true if the operation ID was removed, false if it was absent
+   */
+  removeFromOp(op) {
+    return this.remove(op.id.peerId, op.id.counter);
+  }
   /**
    * Returns the current state vector.
-   * Returns a readonly reference to the internal state.
+   * Returns a deep copy so callers cannot mutate internal state.
    */
   getState() {
-    return this.ranges;
+    const state = {};
+    for (const [peerId, peerRanges] of Object.entries(this.ranges)) {
+      state[peerId] = peerRanges.map((range) => [...range]);
+    }
+    return state;
   }
   /**
    * Calculates which operation ranges we have that the other state vector is missing
@@ -809,9 +860,8 @@ var StateVector = class _StateVector {
    */
   diff(other) {
     const missingRanges = [];
-    const theirState = other.getState();
     for (const [peerId, ourRanges] of Object.entries(this.ranges)) {
-      const theirRanges = theirState[peerId] || [];
+      const theirRanges = other.ranges[peerId] || [];
       const missing = subtractRanges(ourRanges, theirRanges);
       for (const [start, end] of missing) {
         if (start <= end) {
@@ -1181,23 +1231,6 @@ var _RepTree = class _RepTree {
       this.applyOperation(op);
     }
   }
-  /** Applies operations in an optimized way, sorting move ops by OpId to avoid undo-do-redo cycles */
-  applyOpsOptimizedForLotsOfMoves(ops) {
-    const newMoveOps = ops.filter((op) => isMoveNodeOp(op) && !this.knownOps.has(this.getOpKey(op)));
-    if (newMoveOps.length > 0) {
-      const allMoveOps = [...this.moveOps, ...newMoveOps];
-      allMoveOps.sort((a, b) => compareOpId(a.id, b.id));
-      for (let i = 0, len = allMoveOps.length; i < len; i++) {
-        const op = allMoveOps[i];
-        this.applyMove(op);
-      }
-    }
-    const propertyOps = ops.filter((op) => isAnyPropertyOp(op) && !this.knownOps.has(this.getOpKey(op)));
-    for (let i = 0, len = propertyOps.length; i < len; i++) {
-      const op = propertyOps[i];
-      this.applyProperty(op);
-    }
-  }
   compareStructure(other) {
     if (this.root?.id !== other.root?.id) {
       return false;
@@ -1220,16 +1253,29 @@ var _RepTree = class _RepTree {
     }
     return true;
   }
-  /** Checks if the given `ancestorId` is an ancestor of `childId` in the tree */
+  /** Checks whether moving `targetId` under `parentId` would create a cycle. */
+  wouldMoveCreateCycle(move) {
+    if (move.targetId === move.parentId) return true;
+    if (move.parentId === null) return false;
+    return this.hasAncestor(move.parentId, move.targetId);
+  }
+  /**
+   * Checks if the given `ancestorId` is an ancestor of `childId` in the tree.
+   *
+   * @deprecated Use `wouldMoveCreateCycle` for move validation.
+   */
   isAncestor(childId, ancestorId) {
-    let targetId = childId;
+    return this.hasAncestor(childId, ancestorId);
+  }
+  hasAncestor(nodeId, ancestorId) {
+    let targetId = nodeId;
     let node;
     const visitedNodes = /* @__PURE__ */ new Set();
     while (node = this.state.getNode(targetId)) {
       if (node.parentId === ancestorId) return true;
       if (!node.parentId) return false;
       if (visitedNodes.has(targetId)) {
-        console.error(`isAncestor: cycle detected in the tree structure.`);
+        console.error(`hasAncestor: cycle detected in the tree structure.`);
         return false;
       }
       visitedNodes.add(targetId);
@@ -1350,14 +1396,14 @@ var _RepTree = class _RepTree {
         this.pendingMovesWithMissingParent.set(op.parentId, []);
       }
       this.pendingMovesWithMissingParent.get(op.parentId).push(op);
-      this.markOpSeen(op, true);
+      this.markOpSeen(op);
       return;
     }
     this.updateMoveClock(op);
     const lastOp = this.moveOps.length > 0 ? this.moveOps[this.moveOps.length - 1] : null;
     if (lastOp === null || isOpIdGreaterThan(op.id, lastOp.id)) {
       this.moveOps.push(op);
-      this.reportOpAsApplied(op);
+      this.reportMoveOpAsApplied(op);
       this.tryToMove(op);
     } else {
       let targetIndex = this.moveOps.length;
@@ -1371,7 +1417,7 @@ var _RepTree = class _RepTree {
         }
       }
       this.moveOps.splice(targetIndex + 1, 0, op);
-      this.reportOpAsApplied(op);
+      this.reportMoveOpAsApplied(op);
       this.tryToMove(op);
       for (let i = targetIndex + 2; i < this.moveOps.length; i++) {
         this.tryToMove(this.moveOps[i]);
@@ -1379,16 +1425,16 @@ var _RepTree = class _RepTree {
     }
     this.applyPendingMovesForParent(op.targetId);
   }
-  setLLWPropertyAndItsOpId(op) {
-    this.propertyOpsByKey.set(`${op.key}@${op.targetId}`, op);
+  setLLWPropertyAndItsOpId(op, previousOp) {
+    this.propertyOpsByKey.set(this.getPropertyKey(op), op);
     this.state.setProperty(op.targetId, op.key, op.value);
-    this.reportOpAsApplied(op, false);
-    this.refreshPropStateVector();
+    this.recordRetainedPropertyOpInStateVector(op, previousOp);
+    this.reportPropertyOpAsApplied(op);
   }
   setTransientPropertyAndItsOpId(op) {
-    this.transientPropertiesAndTheirOpIds.set(`${op.key}@${op.targetId}`, op.id);
+    this.transientPropertiesAndTheirOpIds.set(this.getPropertyKey(op), op.id);
     this.state.setTransientProperty(op.targetId, op.key, op.value);
-    this.reportOpAsApplied(op, false);
+    this.reportPropertyOpAsApplied(op);
   }
   applyProperty(op) {
     const targetNode = this.state.getNode(op.targetId);
@@ -1400,30 +1446,31 @@ var _RepTree = class _RepTree {
         this.pendingPropertiesWithMissingNode.set(op.targetId, []);
       }
       this.pendingPropertiesWithMissingNode.get(op.targetId).push(op);
-      this.markOpSeen(op, false);
+      this.markOpSeen(op);
       return;
     }
     this.updatePropClock(op);
     this.applyLLWProperty(op, targetNode);
   }
   applyLLWProperty(op, targetNode) {
-    const prevTransientOpId = this.transientPropertiesAndTheirOpIds.get(`${op.key}@${op.targetId}`);
-    const prevOpId = this.propertyOpsByKey.get(`${op.key}@${op.targetId}`)?.id;
+    const propertyKey = this.getPropertyKey(op);
+    const prevTransientOpId = this.transientPropertiesAndTheirOpIds.get(propertyKey);
+    const previousOp = this.propertyOpsByKey.get(propertyKey);
     if (!op.transient) {
-      if (!prevOpId || isOpIdGreaterThan(op.id, prevOpId)) {
-        this.setLLWPropertyAndItsOpId(op);
+      if (!previousOp || isOpIdGreaterThan(op.id, previousOp.id)) {
+        this.setLLWPropertyAndItsOpId(op, previousOp);
       } else {
-        this.markOpSeen(op, false);
+        this.markOpSeen(op);
       }
       if (prevTransientOpId && isOpIdGreaterThan(op.id, prevTransientOpId)) {
-        this.transientPropertiesAndTheirOpIds.delete(`${op.key}@${op.targetId}`);
+        this.transientPropertiesAndTheirOpIds.delete(propertyKey);
         targetNode.removeTransientProperty(op.key);
       }
     } else {
       if (!prevTransientOpId || isOpIdGreaterThan(op.id, prevTransientOpId)) {
         this.setTransientPropertyAndItsOpId(op);
       } else {
-        this.markOpSeen(op, false);
+        this.markOpSeen(op);
       }
     }
   }
@@ -1434,18 +1481,21 @@ var _RepTree = class _RepTree {
       this.applyProperty(op);
     }
   }
-  markOpSeen(op, includeInStateVector) {
+  markOpSeen(op) {
     this.knownOps.add(this.getOpKey(op));
-    if (includeInStateVector && this._stateVectorEnabled) {
-      if (isMoveNodeOp(op)) {
-        this.moveStateVector.updateFromOp(op);
-      } else if (isAnyPropertyOp(op)) {
-        this.propStateVector.updateFromOp(op);
-      }
+  }
+  reportMoveOpAsApplied(op) {
+    this.markOpSeen(op);
+    if (this._stateVectorEnabled) {
+      this.moveStateVector.updateFromOp(op);
     }
+    this.reportOpAsApplied(op);
+  }
+  reportPropertyOpAsApplied(op) {
+    this.markOpSeen(op);
+    this.reportOpAsApplied(op);
   }
-  reportOpAsApplied(op, includeInStateVector = true) {
-    this.markOpSeen(op, includeInStateVector);
+  reportOpAsApplied(op) {
     for (const callback of this.opAppliedCallbacks) {
       callback(op);
     }
@@ -1455,8 +1505,7 @@ var _RepTree = class _RepTree {
     if (targetNode) {
       this.parentIdBeforeMove.set(op.id, targetNode.parentId);
     }
-    if (op.targetId === op.parentId) return;
-    if (op.parentId && this.isAncestor(op.parentId, op.targetId)) return;
+    if (this.wouldMoveCreateCycle(op)) return;
     this.state.moveNode(op.targetId, op.parentId);
     if (!targetNode) {
       const pendingProperties = this.pendingPropertiesWithMissingNode.get(op.targetId) || [];
@@ -1481,7 +1530,7 @@ var _RepTree = class _RepTree {
   // --- Range-Based State Vector Methods ---
   /**
    * Returns the current state vectors for move and property streams.
-   * Returns readonly references to the internal state vectors.
+   * Returns copies of the internal state vectors.
    */
   getStateVectors() {
     if (!this._stateVectorEnabled) {
@@ -1549,16 +1598,22 @@ var _RepTree = class _RepTree {
   getPropertyOps() {
     return Array.from(this.propertyOpsByKey.values());
   }
-  refreshPropStateVector() {
+  recordRetainedPropertyOpInStateVector(op, previousOp) {
     if (!this._stateVectorEnabled) {
       return;
     }
-    this.propStateVector = StateVector.fromOperations(this.getPropertyOps());
+    if (previousOp) {
+      this.propStateVector.removeFromOp(previousOp);
+    }
+    this.propStateVector.updateFromOp(op);
   }
   getOpKey(op) {
     const stream = isMoveNodeOp(op) ? "move" : "prop";
     return `${stream}:${opIdToString(op.id)}`;
   }
+  getPropertyKey(op) {
+    return `${op.key}@${op.targetId}`;
+  }
   filterOpsByRanges(ops, ranges) {
     const missingOps = [];
     for (const op of ops) {