reptree 0.2.1 → 0.2.3

package/README.md

@@ -23,6 +23,30 @@ npm install reptree
 
 ## Usage
 
+### Reactive vertex with Zod (optional)
+
+```ts
+import { RepTree, bindVertex } from 'reptree';
+import { z } from 'zod';
+
+const tree = new RepTree('peer1');
+const root = tree.createRoot();
+const v = root.newChild();
+
+const Person = z.object({ name: z.string(), age: z.number().int().min(0) });
+
+// Helper function form
+const person = bindVertex(tree, v.id, Person);
+
+// Or via instance method on Vertex
+// const person = v.bind(Person);
+
+person.name = 'Alice'; // validated and persisted
+person.age = 33;       // validated and persisted
+```
+
+For more, see `docs/reactive-vertices.md`. 
+
 ```typescript
 import { RepTree } from 'reptree';
 

package/dist/index.cjs

@@ -30,12 +30,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  OpId: () => OpId,
   RepTree: () => RepTree,
   StateVector: () => StateVector,
   TreeState: () => TreeState,
   Vertex: () => Vertex,
   VertexState: () => VertexState,
+  bindVertex: () => bindVertex,
   isAnyPropertyOp: () => isAnyPropertyOp,
   isLWWPropertyOp: () => isLWWPropertyOp,
   isModifyPropertyOp: () => isModifyPropertyOp,
@@ -48,54 +48,51 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/OpId.ts
-var OpId = class _OpId {
-  constructor(counter, peerId) {
-    this.counter = counter;
-    this.peerId = peerId;
-  }
-  static compare(opIdA, opIdB) {
-    if (!(opIdA instanceof _OpId)) {
-      const parsedA = _OpId.tryParseStr(opIdA);
-      if (!parsedA) throw new Error(`Invalid OpId string: ${opIdA}`);
-      opIdA = parsedA;
-    }
-    if (!(opIdB instanceof _OpId)) {
-      const parsedB = _OpId.tryParseStr(opIdB);
-      if (!parsedB) throw new Error(`Invalid OpId string: ${opIdB}`);
-      opIdB = parsedB;
-    }
-    const counterA = opIdA.counter;
-    const counterB = opIdB.counter;
-    if (counterA > counterB) {
-      return 1;
-    } else if (counterA < counterB) {
-      return -1;
-    } else {
-      return opIdA.peerId.localeCompare(opIdB.peerId);
-    }
-  }
-  static equals(opIdA, opIdB) {
-    if (opIdA === opIdB) {
-      return true;
-    } else if (!opIdA || !opIdB) {
-      return false;
-    }
-    return _OpId.compare(opIdA, opIdB) === 0;
-  }
-  static tryParseStr(opIdStr) {
-    const parts = opIdStr.split("@");
-    if (parts.length !== 2) {
-      throw new Error(`Invalid OpId string: ${opIdStr}`);
-    }
-    return new _OpId(parseInt(parts[0], 10), parts[1]);
+function createOpId(counter, peerId) {
+  return { counter, peerId };
+}
+function compareOpId(opIdA, opIdB) {
+  if (typeof opIdA === "string") {
+    const parsedA = tryParseOpIdStr(opIdA);
+    if (!parsedA) throw new Error(`Invalid OpId string: ${opIdA}`);
+    opIdA = parsedA;
+  }
+  if (typeof opIdB === "string") {
+    const parsedB = tryParseOpIdStr(opIdB);
+    if (!parsedB) throw new Error(`Invalid OpId string: ${opIdB}`);
+    opIdB = parsedB;
+  }
+  const counterA = opIdA.counter;
+  const counterB = opIdB.counter;
+  if (counterA > counterB) {
+    return 1;
+  } else if (counterA < counterB) {
+    return -1;
+  } else {
+    return opIdA.peerId.localeCompare(opIdB.peerId);
   }
-  isGreaterThan(opId) {
-    return _OpId.compare(this, opId) === 1;
+}
+function equalsOpId(opIdA, opIdB) {
+  if (opIdA === opIdB) {
+    return true;
+  } else if (!opIdA || !opIdB) {
+    return false;
   }
-  toString() {
-    return `${this.counter}@${this.peerId}`;
+  return compareOpId(opIdA, opIdB) === 0;
+}
+function tryParseOpIdStr(opIdStr) {
+  const parts = opIdStr.split("@");
+  if (parts.length !== 2) {
+    throw new Error(`Invalid OpId string: ${opIdStr}`);
   }
-};
+  return createOpId(parseInt(parts[0], 10), parts[1]);
+}
+function isOpIdGreaterThan(opIdA, opIdB) {
+  return compareOpId(opIdA, opIdB) === 1;
+}
+function opIdToString(opId) {
+  return `${opId.counter}@${opId.peerId}`;
+}
 
 // src/operations.ts
 function isMoveVertexOp(op) {
@@ -111,13 +108,13 @@ function isModifyPropertyOp(op) {
   return "key" in op && "value" in op && typeof op.value === "object" && op.value !== null && "type" in op.value;
 }
 function newMoveVertexOp(clock, peerId, targetId, parentId) {
-  return { id: new OpId(clock, peerId), targetId, parentId };
+  return { id: createOpId(clock, peerId), targetId, parentId };
 }
 function newSetVertexPropertyOp(clock, peerId, targetId, key, value) {
-  return { id: new OpId(clock, peerId), targetId, key, value, transient: false };
+  return { id: createOpId(clock, peerId), targetId, key, value, transient: false };
 }
 function newSetTransientVertexPropertyOp(clock, peerId, targetId, key, value) {
-  return { id: new OpId(clock, peerId), targetId, key, value, transient: true };
+  return { id: createOpId(clock, peerId), targetId, key, value, transient: true };
 }
 
 // src/VertexState.ts
@@ -406,6 +403,57 @@ function uuid() {
   return removeDashes(crypto.randomUUID());
 }
 
+// src/reactive.ts
+function toObject(tree, id) {
+  const obj = {};
+  for (const { key, value } of tree.getVertexProperties(id)) obj[key] = value;
+  return obj;
+}
+function bindVertex(tree, id, schema) {
+  return new Proxy({}, {
+    get(_target, prop) {
+      if (typeof prop !== "string") return void 0;
+      return tree.getVertexProperty(id, prop);
+    },
+    set(_target, prop, value) {
+      if (typeof prop !== "string") return true;
+      if (schema?.shape && schema.shape[prop]) {
+        const field = schema.shape[prop];
+        if (field.safeParse) {
+          const res = field.safeParse(value);
+          if (!res.success) throw new Error(`Invalid value for ${String(prop)}`);
+          value = res.data ?? value;
+        }
+      } else if (schema?.safeParse) {
+        const next = { ...toObject(tree, id), [prop]: value };
+        const res = schema.safeParse(next);
+        if (!res.success) throw new Error(`Invalid value for ${String(prop)}`);
+        const parsed = res.data;
+        if (parsed && Object.prototype.hasOwnProperty.call(parsed, prop)) {
+          value = parsed[prop];
+        }
+      }
+      tree.setVertexProperty(id, prop, value);
+      return true;
+    },
+    deleteProperty(_target, prop) {
+      if (typeof prop !== "string") return true;
+      tree.setVertexProperty(id, prop, void 0);
+      return true;
+    },
+    has(_target, prop) {
+      if (typeof prop !== "string") return false;
+      return !!schema?.shape && Object.prototype.hasOwnProperty.call(schema.shape, prop);
+    },
+    ownKeys() {
+      return Object.keys(schema?.shape ?? {});
+    },
+    getOwnPropertyDescriptor() {
+      return { enumerable: true, configurable: true };
+    }
+  });
+}
+
 // src/Vertex.ts
 var Vertex = class {
   constructor(tree, state) {
@@ -524,6 +572,10 @@ var Vertex = class {
   moveTo(parent) {
     this.tree.moveVertex(this.id, parent.id);
   }
+  /** Returns a live reactive object bound to this vertex. Optional schema validates writes. */
+  bind(schema) {
+    return bindVertex(this.tree, this.id, schema);
+  }
 };
 
 // src/StateVector.ts
@@ -949,7 +1001,7 @@ var _RepTree = class _RepTree {
   }
   applyOps(ops) {
     for (const op of ops) {
-      if (this.knownOps.has(op.id.toString())) {
+      if (this.knownOps.has(opIdToString(op.id))) {
         continue;
       }
       this.applyOperation(op);
@@ -957,16 +1009,16 @@ 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.knownOps.has(op.id.toString()));
+    const newMoveOps = ops.filter((op) => isMoveVertexOp(op) && !this.knownOps.has(opIdToString(op.id)));
     if (newMoveOps.length > 0) {
       const allMoveOps = [...this.moveOps, ...newMoveOps];
-      allMoveOps.sort((a, b) => OpId.compare(a.id, b.id));
+      allMoveOps.sort((a, b) => compareOpId(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) => isAnyPropertyOp(op) && !this.knownOps.has(op.id.toString()));
+    const propertyOps = ops.filter((op) => isAnyPropertyOp(op) && !this.knownOps.has(opIdToString(op.id)));
     for (let i = 0, len = propertyOps.length; i < len; i++) {
       const op = propertyOps[i];
       this.applyProperty(op);
@@ -988,7 +1040,7 @@ var _RepTree = class _RepTree {
       return false;
     }
     for (let i = 0; i < movesA.length; i++) {
-      if (!OpId.equals(movesA[i].id, movesB[i].id)) {
+      if (!equalsOpId(movesA[i].id, movesB[i].id)) {
         return false;
       }
     }
@@ -1133,7 +1185,7 @@ var _RepTree = class _RepTree {
     }
     this.updateLamportClock(op);
     const lastOp = this.moveOps.length > 0 ? this.moveOps[this.moveOps.length - 1] : null;
-    if (lastOp === null || op.id.isGreaterThan(lastOp.id)) {
+    if (lastOp === null || isOpIdGreaterThan(op.id, lastOp.id)) {
       this.moveOps.push(op);
       this.reportOpAsApplied(op);
       this.tryToMove(op);
@@ -1142,7 +1194,7 @@ var _RepTree = class _RepTree {
       for (let i = this.moveOps.length - 1; i >= 0; i--) {
         const moveOp = this.moveOps[i];
         targetIndex = i;
-        if (op.id.isGreaterThan(moveOp.id)) {
+        if (isOpIdGreaterThan(op.id, moveOp.id)) {
           break;
         } else {
           this.undoMove(moveOp);
@@ -1225,17 +1277,17 @@ var _RepTree = class _RepTree {
     const prevOpId = this.propertiesAndTheirOpIds.get(`${op.key}@${op.targetId}`);
     if (!op.transient) {
       this.setPropertyOps.push(op);
-      if (!prevOpId || op.id.isGreaterThan(prevOpId)) {
+      if (!prevOpId || isOpIdGreaterThan(op.id, prevOpId)) {
         this.setLLWPropertyAndItsOpId(op);
       } else {
-        this.knownOps.add(op.id.toString());
+        this.knownOps.add(opIdToString(op.id));
       }
-      if (prevTransientOpId && op.id.isGreaterThan(prevTransientOpId)) {
+      if (prevTransientOpId && isOpIdGreaterThan(op.id, prevTransientOpId)) {
         this.transientPropertiesAndTheirOpIds.delete(`${op.key}@${op.targetId}`);
         targetVertex.removeTransientProperty(op.key);
       }
     } else {
-      if (!prevTransientOpId || op.id.isGreaterThan(prevTransientOpId)) {
+      if (!prevTransientOpId || isOpIdGreaterThan(op.id, prevTransientOpId)) {
         this.setTransientPropertyAndItsOpId(op);
       }
     }
@@ -1270,7 +1322,7 @@ var _RepTree = class _RepTree {
     }
   }
   reportOpAsApplied(op) {
-    this.knownOps.add(op.id.toString());
+    this.knownOps.add(opIdToString(op.id));
     if (this._stateVectorEnabled) {
       this.stateVector.updateFromOp(op);
     }
@@ -1297,7 +1349,7 @@ var _RepTree = class _RepTree {
   undoMove(op) {
     const targetVertex = this.state.getVertex(op.targetId);
     if (!targetVertex) {
-      console.error(`An attempt to undo move operation ${op.id.toString()} failed because the target vertex ${op.targetId} not found`);
+      console.error(`An attempt to undo move operation ${opIdToString(op.id)} failed because the target vertex ${op.targetId} not found`);
       return;
     }
     const prevParentId = this.parentIdBeforeMove.get(op.id);
@@ -1340,7 +1392,7 @@ var _RepTree = class _RepTree {
         }
       }
     }
-    missingOps.sort((a, b) => OpId.compare(a.id, b.id));
+    missingOps.sort((a, b) => compareOpId(a.id, b.id));
     return missingOps;
   }
   /**
@@ -1363,17 +1415,28 @@ var _RepTree = class _RepTree {
       this.stateVector = new StateVector();
     }
   }
+  /**
+   * Parses the vertex properties with a provided schema that has a `parse` method (e.g., Zod schema)
+   */
+  parseVertex(vertexId, schema) {
+    const propsArray = this.getVertexProperties(vertexId);
+    const propsObject = {};
+    for (const { key, value } of propsArray) {
+      propsObject[key] = value;
+    }
+    return schema.parse(propsObject);
+  }
 };
 _RepTree.NULL_VERTEX_ID = "0";
 var RepTree = _RepTree;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  OpId,
   RepTree,
   StateVector,
   TreeState,
   Vertex,
   VertexState,
+  bindVertex,
   isAnyPropertyOp,
   isLWWPropertyOp,
   isModifyPropertyOp,