reptree 0.1.1 → 0.1.2

package/README.md

@@ -8,11 +8,12 @@ A tree data structure using CRDTs for seamless replication between peers.
 
 ## Description
 
-RepTree is a tree data structure for storing vertices with properties.
-It uses 2 conflict-free replicated data types (CRDTs) to manage seamless replication between peers:
+RepTree uses 2 conflict-free replicated data types (CRDTs) to manage seamless replication between peers:
 - A move tree CRDT is used for the tree structure (https://martin.kleppmann.com/papers/move-op.pdf).
 - A last writer wins (LWW) CRDT is used for properties.
 
+RepTree can also be viewed as a hierarchical, distributed database. For more details on its database capabilities, see [RepTree as a Database](docs/database.md).
+
 ## Installation
 
 ```bash
@@ -29,17 +30,44 @@ const tree = new RepTree('peer1');
 
 // Root vertex is created automatically
 const rootVertex = tree.rootVertex;
-const rootId = rootVertex.id;
-
-// Add child vertices
-const childVertex = tree.newVertex(rootId);
-const childId = childVertex.id;
-
-// Set properties
-tree.setVertexProperty(childId, 'name', 'Child Node');
-
-// Move vertices
-tree.moveVertex(childId, anotherParentId);
+rootVertex.name = 'Project';
+
+// Create a folder structure with properties
+const docsFolder = rootVertex.newNamedChild('Docs');
+docsFolder.setProperties({
+  type: 'folder',
+  icon: 'folder-icon'
+});
+
+const imagesFolder = rootVertex.newNamedChild('Images');
+imagesFolder.setProperties({
+  type: 'folder',
+  icon: 'image-icon'
+});
+
+// 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'
+});
+
+const logoFile = imagesFolder.newNamedChild('logo.png');
+logoFile.setProperties({
+  type: 'file',
+  size: 15360,
+  dimensions: '512x512',
+  format: 'png',
+  s3Path: 's3://my-bucket/images/logo.png'
+});
+
+// Move a file to a different folder
+logoFile.moveTo(docsFolder);
+
+// Get children of a folder
+const docsFolderContents = docsFolder.children;
 
 // Syncing between trees
 const otherTree = new RepTree('peer2');

package/dist/index.cjs

@@ -496,6 +496,38 @@ var Vertex = class {
 };
 
 // src/RepTree.ts
+function subtractRanges(rangesA, rangesB) {
+  if (rangesB.length === 0) return rangesA.map((r) => [...r]);
+  if (rangesA.length === 0) return [];
+  const result = [];
+  let indexB = 0;
+  for (const rangeA of rangesA) {
+    let currentStart = rangeA[0];
+    const endA = rangeA[1];
+    while (indexB < rangesB.length && rangesB[indexB][1] < currentStart) {
+      indexB++;
+    }
+    while (indexB < rangesB.length && rangesB[indexB][0] <= endA) {
+      const startB = rangesB[indexB][0];
+      const endB = rangesB[indexB][1];
+      if (currentStart < startB) {
+        result.push([currentStart, Math.min(endA, startB - 1)]);
+      }
+      currentStart = Math.max(currentStart, endB + 1);
+      if (currentStart > endA) break;
+      if (endB >= endA) break;
+      if (endB < currentStart) {
+        indexB++;
+      } else if (startB >= currentStart) {
+        indexB++;
+      }
+    }
+    if (currentStart <= endA) {
+      result.push([currentStart, endA]);
+    }
+  }
+  return result;
+}
 var _RepTree = class _RepTree {
   /**
    * @param peerId - The peer ID of the current client
@@ -510,10 +542,12 @@ var _RepTree = class _RepTree {
     this.localOps = [];
     this.pendingMovesWithMissingParent = /* @__PURE__ */ new Map();
     this.pendingPropertiesWithMissingVertex = /* @__PURE__ */ new Map();
-    this.appliedOps = /* @__PURE__ */ new Set();
+    this.knownOps = /* @__PURE__ */ new Set();
     this.parentIdBeforeMove = /* @__PURE__ */ new Map();
     this.opAppliedCallbacks = [];
     this.maxDepth = _RepTree.DEFAULT_MAX_DEPTH;
+    // State vector tracking operations from each peer
+    this.stateVector = {};
     this.peerId = peerId;
     this.state = new TreeState();
     if (ops != null && ops.length > 0) {
@@ -530,10 +564,10 @@ var _RepTree = class _RepTree {
         throw new Error("The operations has to contain a move operation with a parentId as null to set the root vertex");
       }
       this.applyOps(ops);
-      this.ensureTrashVertex();
+      this.ensureNullVertex();
     } else {
       this.rootVertexId = this.newVertexInternalWithUUID(null);
-      this.ensureTrashVertex();
+      this.ensureNullVertex();
     }
   }
   getMoveOps() {
@@ -635,7 +669,7 @@ var _RepTree = class _RepTree {
     this.applyMove(op);
   }
   deleteVertex(vertexId) {
-    this.moveVertex(vertexId, _RepTree.TRASH_VERTEX_ID);
+    this.moveVertex(vertexId, _RepTree.NULL_VERTEX_ID);
   }
   setTransientVertexProperty(vertexId, key, value) {
     this.lamportClock++;
@@ -685,6 +719,23 @@ var _RepTree = class _RepTree {
   merge(ops) {
     this.applyOps(ops);
   }
+  /** Applies operations in an optimized way, sorting move ops by OpId to avoid undo-do-redo cycles */
+  applyOpsOptimizedForLotsOfMoves(ops) {
+    const newMoveOps = ops.filter((op) => isMoveVertexOp(op) && !this.knownOps.has(op.id.toString()));
+    if (newMoveOps.length > 0) {
+      const allMoveOps = [...this.moveOps, ...newMoveOps];
+      allMoveOps.sort((a, b) => OpId.compare(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) => isSetPropertyOp(op) && !this.knownOps.has(op.id.toString()));
+    for (let i = 0, len = propertyOps.length; i < len; i++) {
+      const op = propertyOps[i];
+      this.applyProperty(op);
+    }
+  }
   compareStructure(other) {
     return _RepTree.compareVertices(this.rootVertexId, this, other);
   }
@@ -795,8 +846,8 @@ var _RepTree = class _RepTree {
     const vertexId = uuid();
     return this.newVertexInternal(vertexId, parentId);
   }
-  ensureTrashVertex() {
-    const vertexId = _RepTree.TRASH_VERTEX_ID;
+  ensureNullVertex() {
+    const vertexId = _RepTree.NULL_VERTEX_ID;
     if (this.state.getVertex(vertexId)) {
       return;
     }
@@ -808,6 +859,19 @@ var _RepTree = class _RepTree {
       this.lamportClock = operation.id.counter;
     }
   }
+  applyPendingMovesForParent(parentId) {
+    if (!this.state.getVertex(parentId)) {
+      return;
+    }
+    const pendingMoves = this.pendingMovesWithMissingParent.get(parentId);
+    if (!pendingMoves) {
+      return;
+    }
+    this.pendingMovesWithMissingParent.delete(parentId);
+    for (const pendingOp of pendingMoves) {
+      this.applyMove(pendingOp);
+    }
+  }
   applyMove(op) {
     if (op.parentId !== null && !this.state.getVertex(op.parentId)) {
       if (!this.pendingMovesWithMissingParent.has(op.parentId)) {
@@ -842,15 +906,52 @@ var _RepTree = class _RepTree {
     }
     this.applyPendingMovesForParent(op.targetId);
   }
-  reportOpAsApplied(op) {
-    this.appliedOps.add(op.id.toString());
-    for (const callback of this.opAppliedCallbacks) {
-      callback(op);
+  setPropertyAndItsOpId(op) {
+    this.propertiesAndTheirOpIds.set(`${op.key}@${op.targetId}`, op.id);
+    this.state.setProperty(op.targetId, op.key, op.value);
+    this.reportOpAsApplied(op);
+  }
+  setTransientPropertyAndItsOpId(op) {
+    this.transientPropertiesAndTheirOpIds.set(`${op.key}@${op.targetId}`, op.id);
+    this.state.setTransientProperty(op.targetId, op.key, op.value);
+    this.reportOpAsApplied(op);
+  }
+  applyProperty(op) {
+    const targetVertex = this.state.getVertex(op.targetId);
+    if (!targetVertex) {
+      if (op.transient) {
+        return;
+      }
+      if (!this.pendingPropertiesWithMissingVertex.has(op.targetId)) {
+        this.pendingPropertiesWithMissingVertex.set(op.targetId, []);
+      }
+      this.pendingPropertiesWithMissingVertex.get(op.targetId).push(op);
+      return;
+    }
+    this.updateLamportClock(op);
+    const prevTransientOpId = this.transientPropertiesAndTheirOpIds.get(`${op.key}@${op.targetId}`);
+    const prevProp = targetVertex.getProperty(op.key);
+    const prevOpId = this.propertiesAndTheirOpIds.get(`${op.key}@${op.targetId}`);
+    if (!op.transient) {
+      this.setPropertyOps.push(op);
+      if (!prevProp || !prevOpId || op.id.isGreaterThan(prevOpId)) {
+        this.setPropertyAndItsOpId(op);
+      } else {
+        this.knownOps.add(op.id.toString());
+      }
+      if (prevTransientOpId && op.id.isGreaterThan(prevTransientOpId)) {
+        this.transientPropertiesAndTheirOpIds.delete(`${op.key}@${op.targetId}`);
+        targetVertex.removeTransientProperty(op.key);
+      }
+    } else {
+      if (!prevTransientOpId || op.id.isGreaterThan(prevTransientOpId)) {
+        this.setTransientPropertyAndItsOpId(op);
+      }
     }
   }
   applyOps(ops) {
     for (const op of ops) {
-      if (this.appliedOps.has(op.id.toString())) {
+      if (this.knownOps.has(op.id.toString())) {
         continue;
       }
       if (isMoveVertexOp(op)) {
@@ -860,34 +961,11 @@ var _RepTree = class _RepTree {
       }
     }
   }
-  /** Applies operations in an optimized way, sorting move ops by OpId to avoid undo-do-redo cycles */
-  applyOpsOptimizedForLotsOfMoves(ops) {
-    const newMoveOps = ops.filter((op) => isMoveVertexOp(op) && !this.appliedOps.has(op.id.toString()));
-    if (newMoveOps.length > 0) {
-      const allMoveOps = [...this.moveOps, ...newMoveOps];
-      allMoveOps.sort((a, b) => OpId.compare(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) => isSetPropertyOp(op) && !this.appliedOps.has(op.id.toString()));
-    for (let i = 0, len = propertyOps.length; i < len; i++) {
-      const op = propertyOps[i];
-      this.applyProperty(op);
-    }
-  }
-  applyPendingMovesForParent(parentId) {
-    if (!this.state.getVertex(parentId)) {
-      return;
-    }
-    const pendingMoves = this.pendingMovesWithMissingParent.get(parentId);
-    if (!pendingMoves) {
-      return;
-    }
-    this.pendingMovesWithMissingParent.delete(parentId);
-    for (const pendingOp of pendingMoves) {
-      this.applyMove(pendingOp);
+  reportOpAsApplied(op) {
+    this.knownOps.add(op.id.toString());
+    this.updateStateVector(op);
+    for (const callback of this.opAppliedCallbacks) {
+      callback(op);
     }
   }
   tryToMove(op) {
@@ -900,6 +978,7 @@ var _RepTree = class _RepTree {
     this.state.moveVertex(op.targetId, op.parentId);
     if (!targetVertex) {
       const pendingProperties = this.pendingPropertiesWithMissingVertex.get(op.targetId) || [];
+      this.pendingPropertiesWithMissingVertex.delete(op.targetId);
       for (const prop of pendingProperties) {
         this.setPropertyAndItsOpId(prop);
       }
@@ -917,49 +996,125 @@ var _RepTree = class _RepTree {
     }
     this.state.moveVertex(op.targetId, prevParentId);
   }
-  setPropertyAndItsOpId(op) {
-    this.propertiesAndTheirOpIds.set(`${op.key}@${op.targetId}`, op.id);
-    this.state.setProperty(op.targetId, op.key, op.value);
-    this.reportOpAsApplied(op);
-  }
-  setTransientPropertyAndItsOpId(op) {
-    this.transientPropertiesAndTheirOpIds.set(`${op.key}@${op.targetId}`, op.id);
-    this.state.setTransientProperty(op.targetId, op.key, op.value);
-    this.reportOpAsApplied(op);
-  }
-  applyProperty(op) {
-    const targetVertex = this.state.getVertex(op.targetId);
-    if (!targetVertex) {
-      if (op.transient) {
-        return;
+  // --- Range-Based State Vector Methods --- 
+  /**
+   * Updates the state vector with a newly applied operation.
+   * Assumes ranges are sorted and non-overlapping.
+   * 
+   * @param op The operation that was just applied
+   */
+  updateStateVector(op) {
+    const peerId = op.id.peerId;
+    const counter = op.id.counter;
+    if (!this.stateVector[peerId]) {
+      this.stateVector[peerId] = [];
+    }
+    const ranges = this.stateVector[peerId];
+    if (ranges.length === 0) {
+      ranges.push([counter, counter]);
+      return;
+    }
+    let rangeExtendedOrMerged = false;
+    let insertIndex = -1;
+    for (let i = 0; i < ranges.length; i++) {
+      const range = ranges[i];
+      if (counter >= range[0] && counter <= range[1]) {
+        rangeExtendedOrMerged = true;
+        break;
       }
-      if (!this.pendingPropertiesWithMissingVertex.has(op.targetId)) {
-        this.pendingPropertiesWithMissingVertex.set(op.targetId, []);
+      if (counter === range[0] - 1) {
+        range[0] = counter;
+        rangeExtendedOrMerged = true;
+        if (i > 0 && range[0] === ranges[i - 1][1] + 1) {
+          ranges[i - 1][1] = range[1];
+          ranges.splice(i, 1);
+        }
+        break;
+      }
+      if (counter === range[1] + 1) {
+        range[1] = counter;
+        rangeExtendedOrMerged = true;
+        if (i < ranges.length - 1 && range[1] + 1 === ranges[i + 1][0]) {
+          range[1] = ranges[i + 1][1];
+          ranges.splice(i + 1, 1);
+        }
+        break;
+      }
+      if (counter < range[0] && insertIndex === -1) {
+        insertIndex = i;
       }
-      this.pendingPropertiesWithMissingVertex.get(op.targetId).push(op);
-      return;
     }
-    this.updateLamportClock(op);
-    const prevTransientOpId = this.transientPropertiesAndTheirOpIds.get(`${op.key}@${op.targetId}`);
-    const prevProp = targetVertex.getProperty(op.key);
-    const prevOpId = this.propertiesAndTheirOpIds.get(`${op.key}@${op.targetId}`);
-    if (!op.transient) {
-      this.setPropertyOps.push(op);
-      if (!prevProp || !prevOpId || op.id.isGreaterThan(prevOpId)) {
-        this.setPropertyAndItsOpId(op);
+    if (!rangeExtendedOrMerged) {
+      if (insertIndex === -1) {
+        insertIndex = ranges.length;
       }
-      if (prevTransientOpId && op.id.isGreaterThan(prevTransientOpId)) {
-        this.transientPropertiesAndTheirOpIds.delete(`${op.key}@${op.targetId}`);
-        targetVertex.removeTransientProperty(op.key);
+      ranges.splice(insertIndex, 0, [counter, counter]);
+      if (insertIndex > 0 && ranges[insertIndex][0] === ranges[insertIndex - 1][1] + 1) {
+        ranges[insertIndex - 1][1] = ranges[insertIndex][1];
+        ranges.splice(insertIndex, 1);
+        insertIndex--;
       }
-    } else {
-      if (!prevTransientOpId || op.id.isGreaterThan(prevTransientOpId)) {
-        this.setTransientPropertyAndItsOpId(op);
+      if (insertIndex < ranges.length - 1 && ranges[insertIndex][1] + 1 === ranges[insertIndex + 1][0]) {
+        ranges[insertIndex][1] = ranges[insertIndex + 1][1];
+        ranges.splice(insertIndex + 1, 1);
+      }
+    }
+  }
+  /**
+   * Returns the current state vector.
+   * Returns a readonly reference to the internal state vector.
+   */
+  getStateVector() {
+    return this.stateVector;
+  }
+  /**
+   * Calculates which operation ranges we have that the other peer is missing
+   * by comparing state vectors.
+   * 
+   * @param theirStateVector The state vector from another peer
+   * @returns Array of operation ID ranges that we have but they don't
+   */
+  diffStateVectors(theirStateVector) {
+    const missingRanges = [];
+    for (const [peerId, ourRanges] of Object.entries(this.stateVector)) {
+      const theirRanges = theirStateVector[peerId] || [];
+      const missing = subtractRanges(ourRanges, theirRanges);
+      for (const [start, end] of missing) {
+        if (start <= end) {
+          missingRanges.push({
+            peerId,
+            start,
+            end
+          });
+        }
+      }
+    }
+    return missingRanges;
+  }
+  /**
+   * Determines which operations are needed to synchronize 
+   * with the provided state vector.
+   * 
+   * @param theirStateVector The state vector from another peer
+   * @returns Operations that should be sent to the other peer, sorted by OpId.
+   */
+  getMissingOps(theirStateVector) {
+    const missingRanges = this.diffStateVectors(theirStateVector);
+    const missingOps = [];
+    const allOps = [...this.moveOps, ...this.setPropertyOps];
+    for (const op of allOps) {
+      for (const range of missingRanges) {
+        if (op.id.peerId === range.peerId && op.id.counter >= range.start && op.id.counter <= range.end) {
+          missingOps.push(op);
+          break;
+        }
       }
     }
+    missingOps.sort((a, b) => OpId.compare(a.id, b.id));
+    return missingOps;
   }
 };
-_RepTree.TRASH_VERTEX_ID = "t";
+_RepTree.NULL_VERTEX_ID = "0";
 _RepTree.DEFAULT_MAX_DEPTH = 1e5;
 var RepTree = _RepTree;
 // Annotate the CommonJS export names for ESM import in node: