reptree 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -1,3 +1,8 @@
+/**
+ * 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;
@@ -163,33 +168,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 +276,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[]>;

package/dist/index.d.ts

@@ -1,3 +1,8 @@
+/**
+ * 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;
@@ -163,33 +168,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 +276,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[]>;

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);