reptree 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -124,7 +124,7 @@ declare class RepTree {
     private static NULL_VERTEX_ID;
     private static DEFAULT_MAX_DEPTH;
     readonly peerId: string;
-    readonly rootVertexId: string;
+    private rootVertexId;
     private lamportClock;
     private state;
     private moveOps;
@@ -139,15 +139,16 @@ declare class RepTree {
     private opAppliedCallbacks;
     private maxDepth;
     private stateVector;
+    private _stateVectorEnabled;
     /**
-     * @param peerId - The peer ID of the current client
-     * @param ops - The operations to replicate an existing tree, if null - a new tree will be created
+     * @param peerId - The peer ID of the current client. Should be unique across all peers.
+     * @param ops - The operations to replicate an existing tree, if not provided - an empty tree will be created without a root vertex
      */
-    constructor(peerId: string, ops?: ReadonlyArray<VertexOperation> | null);
+    constructor(peerId: string, ops?: ReadonlyArray<VertexOperation>);
+    get root(): Vertex | undefined;
     getMoveOps(): ReadonlyArray<MoveVertex>;
     getAllOps(): ReadonlyArray<VertexOperation>;
     getVertex(vertexId: string): Vertex | undefined;
-    get rootVertex(): Vertex;
     getAllVertices(): ReadonlyArray<Vertex>;
     getParent(vertexId: string): Vertex | undefined;
     getChildren(vertexId: string): Vertex[];
@@ -157,6 +158,7 @@ declare class RepTree {
     getVertexProperties(vertexId: string): Readonly<TreeVertexProperty[]>;
     popLocalOps(): VertexOperation[];
     setMaxDepth(maxDepth: number): void;
+    createRoot(): Vertex;
     newVertex(parentId: string, props?: Record<string, VertexPropertyType> | object | null): Vertex;
     newNamedVertex(parentId: string, name: string, props?: Record<string, VertexPropertyType> | object | null): Vertex;
     moveVertex(vertexId: string, parentId: string): void;
@@ -193,26 +195,11 @@ declare class RepTree {
     private reportOpAsApplied;
     private tryToMove;
     private undoMove;
-    /**
-     * Updates the state vector with a newly applied operation.
-     * Assumes ranges are sorted and non-overlapping.
-     *
-     * @param op The operation that was just applied
-     */
-    private updateStateVector;
     /**
      * Returns the current state vector.
      * Returns a readonly reference to the internal state vector.
      */
-    getStateVector(): Readonly<Record<string, number[][]>>;
-    /**
-     * 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
-     */
-    private diffStateVectors;
+    getStateVector(): Readonly<Record<string, number[][]>> | null;
     /**
      * Determines which operations are needed to synchronize
      * with the provided state vector.
@@ -221,6 +208,15 @@ declare class RepTree {
      * @returns Operations that should be sent to the other peer, sorted by OpId.
      */
     getMissingOps(theirStateVector: Record<string, number[][]>): VertexOperation[];
+    /**
+     * Gets or sets whether state vector tracking is enabled
+     */
+    get stateVectorEnabled(): boolean;
+    /**
+     * Sets the state vector enabled status
+     * When enabled, rebuilds the state vector from existing operations if needed
+     */
+    set stateVectorEnabled(value: boolean);
 }
 
 declare class TreeState {
@@ -247,6 +243,63 @@ declare class TreeState {
     printTree(vertexId: TreeVertexId, indent?: string, isLast?: boolean): string;
 }
 
+/**
+ * StateVector tracks operations that have been applied using a range-based representation.
+ * It's used for synchronization between peers to determine which operations need to be sent.
+ */
+declare class StateVector {
+    private ranges;
+    /**
+     * Creates a new StateVector.
+     * @param initialState Optional initial state to copy from
+     */
+    constructor(initialState?: Record<string, number[][]>);
+    /**
+     * Updates the state vector with a newly applied operation.
+     * Assumes ranges are sorted and non-overlapping.
+     *
+     * @param peerId The peer ID of the operation
+     * @param counter The counter value of the operation
+     */
+    update(peerId: string, counter: number): void;
+    /**
+     * Updates the state vector with a newly applied operation.
+     *
+     * @param op The operation that was just applied
+     */
+    updateFromOp(op: VertexOperation): void;
+    /**
+     * Returns the current state vector.
+     * Returns a readonly reference to the internal state.
+     */
+    getState(): Readonly<Record<string, number[][]>>;
+    /**
+     * Calculates which operation ranges we have that the other state vector is missing
+     * by comparing state vectors.
+     *
+     * @param other The other state vector to compare against
+     * @returns Array of operation ID ranges that we have but they don't
+     */
+    diff(other: StateVector): OpIdRange[];
+    /**
+     * Checks if the state vector contains the given operation ID
+     *
+     * @param opId The operation ID to check
+     * @returns true if the operation is in the state vector, false otherwise
+     */
+    contains(opId: OpId): boolean;
+    /**
+     * Creates a copy of this state vector
+     */
+    clone(): StateVector;
+    /**
+     * Builds a state vector from an array of operations
+     * @param operations The operations to build the state vector from
+     * @returns A new StateVector instance
+     */
+    static fromOperations(operations: ReadonlyArray<VertexOperation>): StateVector;
+}
+
 declare function uuid(): string;
 
-export { type MoveVertex, OpId, type OpIdRange, RepTree, type SetVertexProperty, TreeState, type TreeVertexId, type TreeVertexProperty, Vertex, type VertexChangeEvent, type VertexChildrenChangeEvent, type VertexMoveEvent, type VertexOperation, type VertexPropertyChangeEvent, type VertexPropertyType, VertexState, isMoveVertexOp, isSetPropertyOp, newMoveVertexOp, newSetTransientVertexPropertyOp, newSetVertexPropertyOp, uuid };
+export { type MoveVertex, OpId, type OpIdRange, RepTree, type SetVertexProperty, StateVector, TreeState, type TreeVertexId, type TreeVertexProperty, Vertex, type VertexChangeEvent, type VertexChildrenChangeEvent, type VertexMoveEvent, type VertexOperation, type VertexPropertyChangeEvent, type VertexPropertyType, VertexState, isMoveVertexOp, isSetPropertyOp, newMoveVertexOp, newSetTransientVertexPropertyOp, newSetVertexPropertyOp, uuid };

package/dist/index.js

@@ -324,9 +324,21 @@ var TreeState = class {
       }
     }
     const children = this.getChildrenIds(vertexId);
-    for (let i = 0; i < children.length; i++) {
-      const childId = children[i];
-      const isLastChild = i === children.length - 1;
+    const sortedChildren = [...children].sort((a, b) => {
+      const vertexA = this.getVertex(a);
+      const vertexB = this.getVertex(b);
+      const nameA = vertexA?.getProperty("_n");
+      const nameB = vertexB?.getProperty("_n");
+      if (nameA && nameB) {
+        return nameA.localeCompare(nameB);
+      }
+      if (nameA) return -1;
+      if (nameB) return 1;
+      return a.localeCompare(b);
+    });
+    for (let i = 0; i < sortedChildren.length; i++) {
+      const childId = sortedChildren[i];
+      const isLastChild = i === sortedChildren.length - 1;
       result += this.printTree(childId, indent + (isLast ? "    " : "\u2502   "), isLastChild);
     }
     return result;
@@ -459,7 +471,7 @@ var Vertex = class {
   }
 };
 
-// src/RepTree.ts
+// src/StateVector.ts
 function subtractRanges(rangesA, rangesB) {
   if (rangesB.length === 0) return rangesA.map((r) => [...r]);
   if (rangesA.length === 0) return [];
@@ -492,12 +504,165 @@ function subtractRanges(rangesA, rangesB) {
   }
   return result;
 }
+var StateVector = class _StateVector {
+  /**
+   * Creates a new StateVector.
+   * @param initialState Optional initial state to copy from
+   */
+  constructor(initialState = {}) {
+    this.ranges = {};
+    for (const [peerId, peerRanges] of Object.entries(initialState)) {
+      this.ranges[peerId] = peerRanges.map((range) => [...range]);
+    }
+  }
+  /**
+   * Updates the state vector with a newly applied operation.
+   * Assumes ranges are sorted and non-overlapping.
+   * 
+   * @param peerId The peer ID of the operation
+   * @param counter The counter value of the operation
+   */
+  update(peerId, counter) {
+    if (!this.ranges[peerId]) {
+      this.ranges[peerId] = [];
+    }
+    const ranges = this.ranges[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 (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;
+      }
+    }
+    if (!rangeExtendedOrMerged) {
+      if (insertIndex === -1) {
+        insertIndex = ranges.length;
+      }
+      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--;
+      }
+      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);
+      }
+    }
+  }
+  /**
+   * Updates the state vector with a newly applied operation.
+   * 
+   * @param op The operation that was just applied
+   */
+  updateFromOp(op) {
+    this.update(op.id.peerId, op.id.counter);
+  }
+  /**
+   * Returns the current state vector.
+   * Returns a readonly reference to the internal state.
+   */
+  getState() {
+    return this.ranges;
+  }
+  /**
+   * Calculates which operation ranges we have that the other state vector is missing
+   * by comparing state vectors.
+   * 
+   * @param other The other state vector to compare against
+   * @returns Array of operation ID ranges that we have but they don't
+   */
+  diff(other) {
+    const missingRanges = [];
+    const theirState = other.getState();
+    for (const [peerId, ourRanges] of Object.entries(this.ranges)) {
+      const theirRanges = theirState[peerId] || [];
+      const missing = subtractRanges(ourRanges, theirRanges);
+      for (const [start, end] of missing) {
+        if (start <= end) {
+          missingRanges.push({
+            peerId,
+            start,
+            end
+          });
+        }
+      }
+    }
+    return missingRanges;
+  }
+  /**
+   * Checks if the state vector contains the given operation ID
+   * 
+   * @param opId The operation ID to check
+   * @returns true if the operation is in the state vector, false otherwise
+   */
+  contains(opId) {
+    const peerId = opId.peerId;
+    const counter = opId.counter;
+    if (!this.ranges[peerId]) {
+      return false;
+    }
+    for (const [start, end] of this.ranges[peerId]) {
+      if (counter >= start && counter <= end) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Creates a copy of this state vector
+   */
+  clone() {
+    return new _StateVector(this.ranges);
+  }
+  /**
+   * Builds a state vector from an array of operations
+   * @param operations The operations to build the state vector from
+   * @returns A new StateVector instance
+   */
+  static fromOperations(operations) {
+    const stateVector = new _StateVector();
+    for (const op of operations) {
+      stateVector.updateFromOp(op);
+    }
+    return stateVector;
+  }
+};
+
+// src/RepTree.ts
 var _RepTree = class _RepTree {
   /**
-   * @param peerId - The peer ID of the current client
-   * @param ops - The operations to replicate an existing tree, if null - a new tree will be created
+   * @param peerId - The peer ID of the current client. Should be unique across all peers.
+   * @param ops - The operations to replicate an existing tree, if not provided - an empty tree will be created without a root vertex
    */
-  constructor(peerId, ops = null) {
+  constructor(peerId, ops) {
     this.lamportClock = 0;
     this.moveOps = [];
     this.setPropertyOps = [];
@@ -510,30 +675,37 @@ var _RepTree = class _RepTree {
     this.parentIdBeforeMove = /* @__PURE__ */ new Map();
     this.opAppliedCallbacks = [];
     this.maxDepth = _RepTree.DEFAULT_MAX_DEPTH;
-    // State vector tracking operations from each peer
-    this.stateVector = {};
+    this._stateVectorEnabled = true;
     this.peerId = peerId;
     this.state = new TreeState();
-    if (ops != null && ops.length > 0) {
-      let rootMoveOp;
-      for (let i = 0; i < ops.length; i++) {
-        if (isMoveVertexOp(ops[i]) && ops[i].parentId === null) {
-          rootMoveOp = ops[i];
-          break;
-        }
-      }
-      if (rootMoveOp) {
-        this.rootVertexId = rootMoveOp.targetId;
-      } else {
-        throw new Error("The operations has to contain a move operation with a parentId as null to set the root vertex");
-      }
+    this.stateVector = new StateVector();
+    if (ops && ops.length > 0) {
       this.applyOps(ops);
-      this.ensureNullVertex();
+      const root = this.root;
+      if (!root) {
+        throw new Error("There has to be a root vertex in the operations");
+      }
     } else {
-      this.rootVertexId = this.newVertexInternalWithUUID(null);
       this.ensureNullVertex();
     }
   }
+  get root() {
+    if (!this.rootVertexId) {
+      const vertices = this.state.getAllVertices();
+      for (const vertex of vertices) {
+        if (vertex.parentId === null && vertex.id !== _RepTree.NULL_VERTEX_ID) {
+          this.rootVertexId = vertex.id;
+          return new Vertex(this, vertex);
+        }
+      }
+      return void 0;
+    }
+    const rootVertex = this.state.getVertex(this.rootVertexId);
+    if (!rootVertex) {
+      throw new Error("Root vertex not found");
+    }
+    return new Vertex(this, rootVertex);
+  }
   getMoveOps() {
     return this.moveOps;
   }
@@ -544,13 +716,6 @@ var _RepTree = class _RepTree {
     const vertex = this.state.getVertex(vertexId);
     return vertex ? new Vertex(this, vertex) : void 0;
   }
-  get rootVertex() {
-    const rootVertex = this.state.getVertex(this.rootVertexId);
-    if (!rootVertex) {
-      throw new Error("Root vertex not found");
-    }
-    return new Vertex(this, rootVertex);
-  }
   getAllVertices() {
     return this.state.getAllVertices().map((v) => new Vertex(this, v));
   }
@@ -601,6 +766,17 @@ var _RepTree = class _RepTree {
   setMaxDepth(maxDepth) {
     this.maxDepth = maxDepth;
   }
+  createRoot() {
+    if (this.rootVertexId) {
+      throw new Error("Root vertex already exists");
+    }
+    this.rootVertexId = this.newVertexInternalWithUUID(null);
+    const rootVertex = this.state.getVertex(this.rootVertexId);
+    if (!rootVertex) {
+      throw new Error("Root vertex not found");
+    }
+    return new Vertex(this, rootVertex);
+  }
   newVertex(parentId, props = null) {
     const typedProps = props;
     const vertexId = this.newVertexInternalWithUUID(parentId);
@@ -657,6 +833,9 @@ var _RepTree = class _RepTree {
     path = path.replace(/^\/+/, "");
     path = path.replace(/\/+$/, "");
     const pathParts = path.split("/");
+    if (!this.rootVertexId) {
+      return void 0;
+    }
     const root = this.state.getVertex(this.rootVertexId);
     if (!root) {
       throw new Error("The root vertex is not found");
@@ -678,6 +857,9 @@ var _RepTree = class _RepTree {
     return void 0;
   }
   printTree() {
+    if (!this.rootVertexId) {
+      return "";
+    }
     return this.state.printTree(this.rootVertexId);
   }
   merge(ops) {
@@ -701,6 +883,12 @@ var _RepTree = class _RepTree {
     }
   }
   compareStructure(other) {
+    if (this.root?.id !== other.root?.id) {
+      return false;
+    }
+    if (!this.rootVertexId) {
+      return true;
+    }
     return _RepTree.compareVertices(this.rootVertexId, this, other);
   }
   compareMoveOps(other) {
@@ -927,7 +1115,9 @@ var _RepTree = class _RepTree {
   }
   reportOpAsApplied(op) {
     this.knownOps.add(op.id.toString());
-    this.updateStateVector(op);
+    if (this._stateVectorEnabled) {
+      this.stateVector.updateFromOp(op);
+    }
     for (const callback of this.opAppliedCallbacks) {
       callback(op);
     }
@@ -961,99 +1151,15 @@ var _RepTree = class _RepTree {
     this.state.moveVertex(op.targetId, prevParentId);
   }
   // --- 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 (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;
-      }
-    }
-    if (!rangeExtendedOrMerged) {
-      if (insertIndex === -1) {
-        insertIndex = ranges.length;
-      }
-      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--;
-      }
-      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
-          });
-        }
-      }
+    if (!this._stateVectorEnabled) {
+      return null;
     }
-    return missingRanges;
+    return this.stateVector.getState();
   }
   /**
    * Determines which operations are needed to synchronize 
@@ -1063,7 +1169,11 @@ var _RepTree = class _RepTree {
    * @returns Operations that should be sent to the other peer, sorted by OpId.
    */
   getMissingOps(theirStateVector) {
-    const missingRanges = this.diffStateVectors(theirStateVector);
+    if (!this._stateVectorEnabled) {
+      return [...this.moveOps, ...this.setPropertyOps];
+    }
+    const otherStateVector = new StateVector(theirStateVector);
+    const missingRanges = this.stateVector.diff(otherStateVector);
     const missingOps = [];
     const allOps = [...this.moveOps, ...this.setPropertyOps];
     for (const op of allOps) {
@@ -1077,6 +1187,26 @@ var _RepTree = class _RepTree {
     missingOps.sort((a, b) => OpId.compare(a.id, b.id));
     return missingOps;
   }
+  /**
+   * Gets or sets whether state vector tracking is enabled
+   */
+  get stateVectorEnabled() {
+    return this._stateVectorEnabled;
+  }
+  /**
+   * Sets the state vector enabled status
+   * When enabled, rebuilds the state vector from existing operations if needed
+   */
+  set stateVectorEnabled(value) {
+    if (value === this._stateVectorEnabled) return;
+    if (value) {
+      this._stateVectorEnabled = true;
+      this.stateVector = StateVector.fromOperations([...this.moveOps, ...this.setPropertyOps]);
+    } else {
+      this._stateVectorEnabled = false;
+      this.stateVector = new StateVector();
+    }
+  }
 };
 _RepTree.NULL_VERTEX_ID = "0";
 _RepTree.DEFAULT_MAX_DEPTH = 1e5;
@@ -1084,6 +1214,7 @@ var RepTree = _RepTree;
 export {
   OpId,
   RepTree,
+  StateVector,
   TreeState,
   Vertex,
   VertexState,