reptree 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -49,6 +49,14 @@ type VertexChildrenChangeEvent = VertexChangeEvent & {
     type: 'children';
     children: VertexState[];
 };
+/**
+ * Type definition for operation ID range used in state vectors
+ */
+interface OpIdRange {
+    peerId: string;
+    start: number;
+    end: number;
+}
 
 interface MoveVertex {
     id: OpId;
@@ -106,11 +114,6 @@ declare class Vertex {
     moveTo(parent: Vertex): void;
 }
 
-/**
- * MIT License
- * Copyright (c) 2024 Dmitry Kury (d@dkury.com)
- */
-
 /**
  * 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.
@@ -118,10 +121,10 @@ declare class Vertex {
  * A last writer wins (LWW) CRDT is used for properties.
  */
 declare class RepTree {
-    private static TRASH_VERTEX_ID;
+    private static NULL_VERTEX_ID;
     private static DEFAULT_MAX_DEPTH;
     readonly peerId: string;
-    readonly rootVertexId: string;
+    private rootVertexId;
     private lamportClock;
     private state;
     private moveOps;
@@ -131,19 +134,21 @@ declare class RepTree {
     private localOps;
     private pendingMovesWithMissingParent;
     private pendingPropertiesWithMissingVertex;
-    private appliedOps;
+    private knownOps;
     private parentIdBeforeMove;
     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
      */
     constructor(peerId: string, ops?: ReadonlyArray<VertexOperation> | null);
+    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[];
@@ -153,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;
@@ -164,6 +170,8 @@ declare class RepTree {
     private getVertexByPathArray;
     printTree(): string;
     merge(ops: ReadonlyArray<VertexOperation>): void;
+    /** Applies operations in an optimized way, sorting move ops by OpId to avoid undo-do-redo cycles */
+    private applyOpsOptimizedForLotsOfMoves;
     compareStructure(other: RepTree): boolean;
     compareMoveOps(other: RepTree): boolean;
     /** Checks if the given `ancestorId` is an ancestor of `childId` in the tree */
@@ -175,20 +183,40 @@ declare class RepTree {
     static compareVertices(vertexId: string, treeA: RepTree, treeB: RepTree): boolean;
     private newVertexInternal;
     private newVertexInternalWithUUID;
-    private ensureTrashVertex;
+    private ensureNullVertex;
     /** Updates the lamport clock with the counter value of the operation */
     private updateLamportClock;
-    private applyMove;
-    private reportOpAsApplied;
-    private applyOps;
-    /** Applies operations in an optimized way, sorting move ops by OpId to avoid undo-do-redo cycles */
-    private applyOpsOptimizedForLotsOfMoves;
     private applyPendingMovesForParent;
-    private tryToMove;
-    private undoMove;
+    private applyMove;
     private setPropertyAndItsOpId;
     private setTransientPropertyAndItsOpId;
     private applyProperty;
+    private applyOps;
+    private reportOpAsApplied;
+    private tryToMove;
+    private undoMove;
+    /**
+     * Returns the current state vector.
+     * Returns a readonly reference to the internal state vector.
+     */
+    getStateVector(): Readonly<Record<string, number[][]>> | null;
+    /**
+     * 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: 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 {
@@ -215,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, 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 };