reptree 0.7.0 → 0.8.1

package/dist/index.d.cts

@@ -1,7 +1,24 @@
+/**
+ * An identifier for an operation. We use them to compare and order operations.
+ * It uses a counter as a Lamport clock and a peer ID in case if ops have the same counter - in that case the ops will be compared by peer ID.
+ * Lamport clock (Lamport timestamp): https://en.wikipedia.org/wiki/Lamport_timestamp
+ */
 interface OpId {
     readonly counter: number;
     readonly peerId: string;
 }
+declare function createOpId(counter: number, peerId: string): OpId;
+/**
+ * Compares two operation IDs.
+ * @param opIdA - The first operation ID.
+ * @param opIdB - The second operation ID.
+ * @returns 1 if opIdA is greater than opIdB, -1 if opIdA is less than opIdB, 0 if they are equal.
+ */
+declare function compareOpId(opIdA: OpId | string, opIdB: OpId | string): number;
+declare function equalsOpId(opIdA: OpId | string | null, opIdB: OpId | string | null): boolean;
+declare function tryParseOpIdStr(opIdStr: string): OpId;
+declare function isOpIdGreaterThan(opIdA: OpId | string, opIdB: OpId | string): boolean;
+declare function opIdToString(opId: OpId): string;
 
 declare class VertexState {
     readonly id: string;
@@ -163,33 +180,62 @@ declare function bindVertex<T extends Record<string, unknown>>(tree: RepTree, id
  * for working with vertices in a RepTree.
  */
 declare class Vertex {
-    private tree;
     private state;
+    private _tree;
     constructor(tree: RepTree, state: VertexState);
+    /** Returns the tree this vertex belongs to. */
+    get tree(): RepTree;
+    private set tree(value);
+    /** Returns the ID of this vertex. */
     get id(): string;
+    /** Returns the name of this vertex. The name is stored as a property with the key 'name'. */
     get name(): string | undefined;
+    /** Sets the name of this vertex. The name is stored as a property with the key 'name'. */
     set name(name: string);
+    /** Returns the creation date of this vertex. The creation date is stored as a property with the key '_c'. */
     get createdAt(): Date;
-    get path(): string;
+    /** Returns the ID of the parent vertex of this vertex. */
     get parentId(): string | null;
+    /** Returns the parent vertex of this vertex. */
     get parent(): Vertex | undefined;
+    /** Returns the children vertices of this vertex. */
     get children(): Vertex[];
+    /** Returns the IDs of the children vertices of this vertex. */
     get childrenIds(): string[];
+    /** Returns the ancestors of this vertex. The first element is the root vertex.
+     * E.g root -> grandparent -> parent.
+     * Doesn't include this vertex in the array.
+     */
+    get ancestors(): Vertex[];
+    /** Returns the ID of the root vertex of the tree this vertex belongs to. */
+    get treeId(): string;
+    /** Returns the root vertex of the tree this vertex belongs to. */
+    get root(): Vertex;
     getAsTypedObject<T>(): T;
     getChildrenAsTypedArray<T>(): T[];
+    /** Creates a new child vertex of this vertex. */
     newChild(props?: Record<string, VertexPropertyType> | object | null): Vertex;
+    /** Creates a new named child vertex of this vertex. */
     newNamedChild(name: string, props?: Record<string, VertexPropertyType> | object | null): Vertex;
+    /** Sets a property on this vertex. */
     setProperty(key: string, value: VertexPropertyType): void;
+    /** Sets a transient property on this vertex. Transient properties are not persisted to the tree and are not included in the state vector. */
     setTransientProperty(key: string, value: VertexPropertyType): void;
+    /** Promotes all transient (temporary) properties to persistent properties. */
     commitTransients(): void;
+    /** Sets multiple properties on this vertex. */
     setProperties(props: Record<string, VertexPropertyType> | object): void;
+    /** Returns the value of a property on this vertex. */
     getProperty(key: string, includingTransient?: boolean): VertexPropertyType | undefined;
+    /** Returns all properties on this vertex. */
     getProperties(): Record<string, VertexPropertyType>;
     findAllChildrenWithProperty(key: string, value: VertexPropertyType): Vertex[];
     findFirstChildVertexWithProperty(key: string, value: VertexPropertyType): Vertex | undefined;
     findFirstTypedChildWithProperty<T>(key: string, value: VertexPropertyType): T | undefined;
     findAllTypedChildrenWithProperty<T>(key: string, value: VertexPropertyType): T[];
+    /** Observes changes to this vertex. */
     observe(listener: (events: VertexChangeEvent[]) => void): () => void;
+    /** Observes changes to the children of this vertex. */
     observeChildren(listener: (children: Vertex[]) => void): () => void;
     observeChildrenAsTypedArray<T>(listener: (children: T[]) => void): () => void;
     delete(): void;
@@ -242,6 +288,7 @@ declare class RepTree {
     getParent(vertexId: string): Vertex | undefined;
     getChildren(vertexId: string): Vertex[];
     getChildrenIds(vertexId: string): string[];
+    /** Returns the ancestors of the given vertex. The first element is the root vertex. */
     getAncestors(vertexId: string): Vertex[];
     getVertexProperty(vertexId: string, key: string, includingTransient?: boolean): VertexPropertyType | undefined;
     getVertexProperties(vertexId: string): Readonly<TreeVertexProperty[]>;
@@ -414,4 +461,4 @@ declare class StateVector {
 
 declare function uuid(): string;
 
-export { type BindOptions, type BindedVertex, type JsonPrimitive, type JsonValue, type MoveVertex, type OpId, type OpIdRange, RepTree, type SchemaLike, type SetVertexProperty, StateVector, TreeState, type TreeVertexId, type TreeVertexProperty, Vertex, type VertexChangeEvent, type VertexChildrenChangeEvent, type VertexMoveEvent, type VertexOperation, type VertexPropertyChangeEvent, type VertexPropertyType, VertexState, bindVertex, isAnyPropertyOp, isMoveVertexOp, newMoveVertexOp, newSetTransientVertexPropertyOp, newSetVertexPropertyOp, uuid };
+export { type BindOptions, type BindedVertex, type JsonPrimitive, type JsonValue, type MoveVertex, type OpId, type OpIdRange, RepTree, type SchemaLike, type SetVertexProperty, StateVector, TreeState, type TreeVertexId, type TreeVertexProperty, Vertex, type VertexChangeEvent, type VertexChildrenChangeEvent, type VertexMoveEvent, type VertexOperation, type VertexPropertyChangeEvent, type VertexPropertyType, VertexState, bindVertex, compareOpId, createOpId, equalsOpId, isAnyPropertyOp, isMoveVertexOp, isOpIdGreaterThan, newMoveVertexOp, newSetTransientVertexPropertyOp, newSetVertexPropertyOp, opIdToString, tryParseOpIdStr, uuid };

package/dist/index.d.ts

@@ -1,7 +1,24 @@
+/**
+ * An identifier for an operation. We use them to compare and order operations.
+ * It uses a counter as a Lamport clock and a peer ID in case if ops have the same counter - in that case the ops will be compared by peer ID.
+ * Lamport clock (Lamport timestamp): https://en.wikipedia.org/wiki/Lamport_timestamp
+ */
 interface OpId {
     readonly counter: number;
     readonly peerId: string;
 }
+declare function createOpId(counter: number, peerId: string): OpId;
+/**
+ * Compares two operation IDs.
+ * @param opIdA - The first operation ID.
+ * @param opIdB - The second operation ID.
+ * @returns 1 if opIdA is greater than opIdB, -1 if opIdA is less than opIdB, 0 if they are equal.
+ */
+declare function compareOpId(opIdA: OpId | string, opIdB: OpId | string): number;
+declare function equalsOpId(opIdA: OpId | string | null, opIdB: OpId | string | null): boolean;
+declare function tryParseOpIdStr(opIdStr: string): OpId;
+declare function isOpIdGreaterThan(opIdA: OpId | string, opIdB: OpId | string): boolean;
+declare function opIdToString(opId: OpId): string;
 
 declare class VertexState {
     readonly id: string;
@@ -163,33 +180,62 @@ declare function bindVertex<T extends Record<string, unknown>>(tree: RepTree, id
  * for working with vertices in a RepTree.
  */
 declare class Vertex {
-    private tree;
     private state;
+    private _tree;
     constructor(tree: RepTree, state: VertexState);
+    /** Returns the tree this vertex belongs to. */
+    get tree(): RepTree;
+    private set tree(value);
+    /** Returns the ID of this vertex. */
     get id(): string;
+    /** Returns the name of this vertex. The name is stored as a property with the key 'name'. */
     get name(): string | undefined;
+    /** Sets the name of this vertex. The name is stored as a property with the key 'name'. */
     set name(name: string);
+    /** Returns the creation date of this vertex. The creation date is stored as a property with the key '_c'. */
     get createdAt(): Date;
-    get path(): string;
+    /** Returns the ID of the parent vertex of this vertex. */
     get parentId(): string | null;
+    /** Returns the parent vertex of this vertex. */
     get parent(): Vertex | undefined;
+    /** Returns the children vertices of this vertex. */
     get children(): Vertex[];
+    /** Returns the IDs of the children vertices of this vertex. */
     get childrenIds(): string[];
+    /** Returns the ancestors of this vertex. The first element is the root vertex.
+     * E.g root -> grandparent -> parent.
+     * Doesn't include this vertex in the array.
+     */
+    get ancestors(): Vertex[];
+    /** Returns the ID of the root vertex of the tree this vertex belongs to. */
+    get treeId(): string;
+    /** Returns the root vertex of the tree this vertex belongs to. */
+    get root(): Vertex;
     getAsTypedObject<T>(): T;
     getChildrenAsTypedArray<T>(): T[];
+    /** Creates a new child vertex of this vertex. */
     newChild(props?: Record<string, VertexPropertyType> | object | null): Vertex;
+    /** Creates a new named child vertex of this vertex. */
     newNamedChild(name: string, props?: Record<string, VertexPropertyType> | object | null): Vertex;
+    /** Sets a property on this vertex. */
     setProperty(key: string, value: VertexPropertyType): void;
+    /** Sets a transient property on this vertex. Transient properties are not persisted to the tree and are not included in the state vector. */
     setTransientProperty(key: string, value: VertexPropertyType): void;
+    /** Promotes all transient (temporary) properties to persistent properties. */
     commitTransients(): void;
+    /** Sets multiple properties on this vertex. */
     setProperties(props: Record<string, VertexPropertyType> | object): void;
+    /** Returns the value of a property on this vertex. */
     getProperty(key: string, includingTransient?: boolean): VertexPropertyType | undefined;
+    /** Returns all properties on this vertex. */
     getProperties(): Record<string, VertexPropertyType>;
     findAllChildrenWithProperty(key: string, value: VertexPropertyType): Vertex[];
     findFirstChildVertexWithProperty(key: string, value: VertexPropertyType): Vertex | undefined;
     findFirstTypedChildWithProperty<T>(key: string, value: VertexPropertyType): T | undefined;
     findAllTypedChildrenWithProperty<T>(key: string, value: VertexPropertyType): T[];
+    /** Observes changes to this vertex. */
     observe(listener: (events: VertexChangeEvent[]) => void): () => void;
+    /** Observes changes to the children of this vertex. */
     observeChildren(listener: (children: Vertex[]) => void): () => void;
     observeChildrenAsTypedArray<T>(listener: (children: T[]) => void): () => void;
     delete(): void;
@@ -242,6 +288,7 @@ declare class RepTree {
     getParent(vertexId: string): Vertex | undefined;
     getChildren(vertexId: string): Vertex[];
     getChildrenIds(vertexId: string): string[];
+    /** Returns the ancestors of the given vertex. The first element is the root vertex. */
     getAncestors(vertexId: string): Vertex[];
     getVertexProperty(vertexId: string, key: string, includingTransient?: boolean): VertexPropertyType | undefined;
     getVertexProperties(vertexId: string): Readonly<TreeVertexProperty[]>;
@@ -414,4 +461,4 @@ declare class StateVector {
 
 declare function uuid(): string;
 
-export { type BindOptions, type BindedVertex, type JsonPrimitive, type JsonValue, type MoveVertex, type OpId, type OpIdRange, RepTree, type SchemaLike, type SetVertexProperty, StateVector, TreeState, type TreeVertexId, type TreeVertexProperty, Vertex, type VertexChangeEvent, type VertexChildrenChangeEvent, type VertexMoveEvent, type VertexOperation, type VertexPropertyChangeEvent, type VertexPropertyType, VertexState, bindVertex, isAnyPropertyOp, isMoveVertexOp, newMoveVertexOp, newSetTransientVertexPropertyOp, newSetVertexPropertyOp, uuid };
+export { type BindOptions, type BindedVertex, type JsonPrimitive, type JsonValue, type MoveVertex, type OpId, type OpIdRange, RepTree, type SchemaLike, type SetVertexProperty, StateVector, TreeState, type TreeVertexId, type TreeVertexProperty, Vertex, type VertexChangeEvent, type VertexChildrenChangeEvent, type VertexMoveEvent, type VertexOperation, type VertexPropertyChangeEvent, type VertexPropertyType, VertexState, bindVertex, compareOpId, createOpId, equalsOpId, isAnyPropertyOp, isMoveVertexOp, isOpIdGreaterThan, newMoveVertexOp, newSetTransientVertexPropertyOp, newSetVertexPropertyOp, opIdToString, tryParseOpIdStr, uuid };

package/dist/index.js

@@ -464,18 +464,29 @@ function bindVertex(tree, id, schemaOrOptions) {
 // src/Vertex.ts
 var Vertex = class _Vertex {
   constructor(tree, state) {
-    this.tree = tree;
     this.state = state;
+    this._tree = tree;
   }
+  /** Returns the tree this vertex belongs to. */
+  get tree() {
+    return this._tree;
+  }
+  set tree(value) {
+    this._tree = value;
+  }
+  /** Returns the ID of this vertex. */
   get id() {
     return this.state.id;
   }
+  /** Returns the name of this vertex. The name is stored as a property with the key 'name'. */
   get name() {
     return this.getProperty("name");
   }
+  /** Sets the name of this vertex. The name is stored as a property with the key 'name'. */
   set name(name) {
     this.tree.setVertexProperty(this.id, "name", name);
   }
+  /** Returns the creation date of this vertex. The creation date is stored as a property with the key '_c'. */
   get createdAt() {
     const createdAt = this.getProperty("_c");
     if (!createdAt) {
@@ -483,30 +494,51 @@ var Vertex = class _Vertex {
     }
     return new Date(createdAt);
   }
-  get path() {
-    throw new Error("Not implemented");
-  }
+  /** Returns the ID of the parent vertex of this vertex. */
   get parentId() {
     return this.state.parentId;
   }
+  /** Returns the parent vertex of this vertex. */
   get parent() {
     if (!this.parentId) {
       return void 0;
     }
     return this.tree.getVertex(this.parentId);
   }
+  /** Returns the children vertices of this vertex. */
   get children() {
     return this.tree.getChildren(this.id);
   }
+  /** Returns the IDs of the children vertices of this vertex. */
   get childrenIds() {
     return this.tree.getChildrenIds(this.id);
   }
+  /** Returns the ancestors of this vertex. The first element is the root vertex.
+   * E.g root -> grandparent -> parent.
+   * Doesn't include this vertex in the array.
+   */
+  get ancestors() {
+    return this.tree.getAncestors(this.id);
+  }
+  /** Returns the ID of the root vertex of the tree this vertex belongs to. */
+  get treeId() {
+    return this.root.id;
+  }
+  /** Returns the root vertex of the tree this vertex belongs to. */
+  get root() {
+    const root = this.tree.root;
+    if (!root) {
+      throw new Error("Root vertex of the tree is not set");
+    }
+    return root;
+  }
   getAsTypedObject() {
     return this.getProperties();
   }
   getChildrenAsTypedArray() {
     return this.children.map((v) => v.getAsTypedObject());
   }
+  /** Creates a new child vertex of this vertex. */
   newChild(props) {
     if (props && typeof props === "object" && "children" in props) {
       throw new Error("Passing children inside props is not supported at the moment");
@@ -514,6 +546,7 @@ var Vertex = class _Vertex {
     const normalized = _Vertex.normalizePropsForCreation(props);
     return this.tree.newVertex(this.id, normalized);
   }
+  /** Creates a new named child vertex of this vertex. */
   newNamedChild(name, props) {
     if (props && typeof props === "object" && "children" in props) {
       throw new Error("Passing children inside props is not supported at the moment");
@@ -521,6 +554,7 @@ var Vertex = class _Vertex {
     const normalized = _Vertex.normalizePropsForCreation(props);
     return this.tree.newNamedVertex(this.id, name, normalized);
   }
+  /** Sets a property on this vertex. */
   setProperty(key, value) {
     const existingValue = this.getProperty(key, false);
     if (existingValue === value) {
@@ -528,6 +562,7 @@ var Vertex = class _Vertex {
     }
     this.tree.setVertexProperty(this.id, key, value);
   }
+  /** Sets a transient property on this vertex. Transient properties are not persisted to the tree and are not included in the state vector. */
   setTransientProperty(key, value) {
     const existingValue = this.getProperty(key);
     if (existingValue === value) {
@@ -535,17 +570,21 @@ var Vertex = class _Vertex {
     }
     this.tree.setTransientVertexProperty(this.id, key, value);
   }
+  /** Promotes all transient (temporary) properties to persistent properties. */
   commitTransients() {
     this.tree.commitTransients(this.id);
   }
+  /** Sets multiple properties on this vertex. */
   setProperties(props) {
     for (const [key, value] of Object.entries(props)) {
       this.setProperty(key, value);
     }
   }
+  /** Returns the value of a property on this vertex. */
   getProperty(key, includingTransient = true) {
     return this.tree.getVertexProperty(this.id, key, includingTransient);
   }
+  /** Returns all properties on this vertex. */
   getProperties() {
     const props = {};
     this.tree.getVertexProperties(this.id).forEach((p) => {
@@ -565,10 +604,12 @@ var Vertex = class _Vertex {
   findAllTypedChildrenWithProperty(key, value) {
     return this.findAllChildrenWithProperty(key, value).map((c) => c.getAsTypedObject());
   }
+  /** Observes changes to this vertex. */
   observe(listener) {
     const unobserve = this.tree.observe(this.id, listener);
     return () => unobserve();
   }
+  /** Observes changes to the children of this vertex. */
   observeChildren(listener) {
     const unobserve = this.tree.observe(this.id, (events) => {
       if (events.some((e) => e.type === "children")) {
@@ -898,7 +939,6 @@ var _RepTree = class _RepTree {
     this.setPropertyOps = [];
     this.propertiesAndTheirOpIds = /* @__PURE__ */ new Map();
     this.transientPropertiesAndTheirOpIds = /* @__PURE__ */ new Map();
-    // Observers for non-structural properties are not used
     this.localOps = [];
     this.pendingMovesWithMissingParent = /* @__PURE__ */ new Map();
     this.pendingPropertiesWithMissingVertex = /* @__PURE__ */ new Map();
@@ -963,6 +1003,7 @@ var _RepTree = class _RepTree {
   getChildrenIds(vertexId) {
     return this.state.getChildrenIds(vertexId);
   }
+  /** Returns the ancestors of the given vertex. The first element is the root vertex. */
   getAncestors(vertexId) {
     const ancestors = [];
     let currentVertex = this.state.getVertex(vertexId);
@@ -1517,11 +1558,17 @@ export {
   Vertex,
   VertexState,
   bindVertex,
+  compareOpId,
+  createOpId,
+  equalsOpId,
   isAnyPropertyOp,
   isMoveVertexOp,
+  isOpIdGreaterThan,
   newMoveVertexOp,
   newSetTransientVertexPropertyOp,
   newSetVertexPropertyOp,
+  opIdToString,
+  tryParseOpIdStr,
   uuid
 };
 //# sourceMappingURL=index.js.map