reptree 0.2.2 → 0.2.4

package/README.md

@@ -23,6 +23,43 @@ 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
+```
+
+#### Aliases for internal fields
+
+- `name` ↔ `_n`
+- `createdAt` ↔ `_c` (Date exposed, ISO stored)
+
+These aliases are applied by default when using `bindVertex` or `vertex.bind()`.
+
+```ts
+person.name = 'Alice';          // writes _n
+person.createdAt = new Date();  // writes _c (ISO)
+console.log(person.createdAt instanceof Date); // true
+```
+
+For more, see `docs/reactive-vertices.md`. 
+
 ```typescript
 import { RepTree } from 'reptree';
 
@@ -74,6 +111,15 @@ const ops = tree.getAllOps();
 otherTree.merge(ops);
 ```
 
+### Creating children with normalized props
+
+`vertex.newChild(props)` and `vertex.newNamedChild(name, props)` accept plain objects. RepTree will:
+
+- Map `name` → `_n`, `createdAt` (Date) → `_c` (ISO)
+- Filter unsupported types (non-primitive objects except Y.Doc)
+- Ignore `props.name` if `newNamedChild` has an explicit `name`
+- Forbid nested children in props for now
+
 ## Yjs Integration
 
 RepTree supports [Yjs](https://github.com/yjs/yjs) documents as vertex properties, enabling real-time collaborative editing with a variety of shared data types:

package/dist/index.cjs

@@ -35,6 +35,8 @@ __export(index_exports, {
   TreeState: () => TreeState,
   Vertex: () => Vertex,
   VertexState: () => VertexState,
+  bindVertex: () => bindVertex,
+  defaultAliases: () => defaultAliases,
   isAnyPropertyOp: () => isAnyPropertyOp,
   isLWWPropertyOp: () => isLWWPropertyOp,
   isModifyPropertyOp: () => isModifyPropertyOp,
@@ -402,8 +404,211 @@ function uuid() {
   return removeDashes(crypto.randomUUID());
 }
 
+// src/reactive.ts
+var defaultAliases = [
+  { publicKey: "name", internalKey: "_n" },
+  {
+    publicKey: "createdAt",
+    internalKey: "_c",
+    toPublic: (v) => typeof v === "string" ? new Date(v) : v,
+    toInternal: (v) => v instanceof Date ? v.toISOString() : v
+  }
+];
+function buildAliasMaps(aliases) {
+  const publicToInternal = /* @__PURE__ */ new Map();
+  const internalToPublic = /* @__PURE__ */ new Map();
+  for (const rule of aliases) {
+    publicToInternal.set(rule.publicKey, rule);
+    internalToPublic.set(rule.internalKey, rule);
+  }
+  return { publicToInternal, internalToPublic };
+}
+function toPublicObject(tree, id, internalToPublic) {
+  const obj = {};
+  for (const { key, value } of tree.getVertexProperties(id)) {
+    const rule = internalToPublic.get(key);
+    if (rule) {
+      const converted = rule.toPublic ? rule.toPublic(value) : value;
+      obj[rule.publicKey] = converted;
+    } else {
+      obj[key] = value;
+    }
+  }
+  return obj;
+}
+var RESERVED_METHOD_USE_TRANSIENT = "useTransient";
+var RESERVED_METHOD_COMMIT_TRANSIENTS = "commitTransients";
+function bindVertex(tree, id, schemaOrOptions) {
+  const isOptions = typeof schemaOrOptions === "object" && schemaOrOptions !== null && (Object.prototype.hasOwnProperty.call(schemaOrOptions, "aliases") || Object.prototype.hasOwnProperty.call(schemaOrOptions, "includeInternalKeys") || Object.prototype.hasOwnProperty.call(schemaOrOptions, "schema"));
+  const options = isOptions ? schemaOrOptions : { schema: schemaOrOptions };
+  const schema = options.schema;
+  const aliases = options.aliases ?? defaultAliases;
+  const includeInternalKeys = options.includeInternalKeys ?? false;
+  const { publicToInternal, internalToPublic } = buildAliasMaps(aliases);
+  return new Proxy({}, {
+    get(_target, prop) {
+      if (prop === RESERVED_METHOD_USE_TRANSIENT) {
+        return (fn) => {
+          const transientProxy = new Proxy({}, {
+            get(_t, p) {
+              if (typeof p !== "string") return void 0;
+              const rule2 = publicToInternal.get(p);
+              if (rule2) {
+                const raw = tree.getVertexProperty(id, rule2.internalKey);
+                return rule2.toPublic ? rule2.toPublic(raw) : raw;
+              }
+              return tree.getVertexProperty(id, p);
+            },
+            set(_t, p, value) {
+              if (typeof p !== "string") return true;
+              if (schema?.shape && schema.shape[p]) {
+                const field = schema.shape[p];
+                if (field.safeParse) {
+                  const res = field.safeParse(value);
+                  if (!res.success) throw new Error(`Invalid value for ${String(p)}`);
+                  value = res.data ?? value;
+                }
+              } else if (schema?.safeParse) {
+                const next = { ...toPublicObject(tree, id, internalToPublic), [p]: value };
+                const res = schema.safeParse(next);
+                if (!res.success) throw new Error(`Invalid value for ${String(p)}`);
+                const parsed = res.data;
+                if (parsed && Object.prototype.hasOwnProperty.call(parsed, p)) {
+                  value = parsed[p];
+                }
+              }
+              const rule2 = publicToInternal.get(p);
+              if (rule2) {
+                const converted = rule2.toInternal ? rule2.toInternal(value) : value;
+                tree.setTransientVertexProperty(id, rule2.internalKey, converted);
+                return true;
+              }
+              tree.setTransientVertexProperty(id, p, value);
+              return true;
+            },
+            deleteProperty(_t, p) {
+              if (typeof p !== "string") return true;
+              const rule2 = publicToInternal.get(p);
+              if (rule2) {
+                tree.setTransientVertexProperty(id, rule2.internalKey, void 0);
+                return true;
+              }
+              tree.setTransientVertexProperty(id, p, void 0);
+              return true;
+            }
+          });
+          fn(transientProxy);
+        };
+      }
+      if (prop === RESERVED_METHOD_COMMIT_TRANSIENTS) {
+        return () => {
+          const entries = tree.getVertexProperties(id);
+          const currentPublic = schema?.safeParse ? toPublicObject(tree, id, internalToPublic) : void 0;
+          for (const { key: internalKey, value: overlayValue } of entries) {
+            const persistentValue = tree.getVertexProperty(id, internalKey, false);
+            if (overlayValue === persistentValue) continue;
+            const aliasRule = internalToPublic.get(internalKey);
+            const publicKey = aliasRule ? aliasRule.publicKey : internalKey;
+            const publicValue = aliasRule && aliasRule.toPublic ? aliasRule.toPublic(overlayValue) : overlayValue;
+            let valueToPersistInternal = overlayValue;
+            if (schema?.shape && schema.shape[publicKey]) {
+              const field = schema.shape[publicKey];
+              if (field.safeParse) {
+                const res = field.safeParse(publicValue);
+                if (!res.success) throw new Error(`Invalid value for ${String(publicKey)}`);
+                const coerced = res.data;
+                const maybeInternal = aliasRule && aliasRule.toInternal ? aliasRule.toInternal(coerced) : coerced;
+                valueToPersistInternal = maybeInternal;
+              }
+            } else if (schema?.safeParse && currentPublic) {
+              const nextPublic = { ...currentPublic, [publicKey]: publicValue };
+              const res = schema.safeParse(nextPublic);
+              if (!res.success) throw new Error("Invalid values for commitTransients");
+              const parsed = res.data;
+              const parsedPublic = Object.prototype.hasOwnProperty.call(parsed, publicKey) ? parsed[publicKey] : publicValue;
+              const maybeInternal = aliasRule && aliasRule.toInternal ? aliasRule.toInternal(parsedPublic) : parsedPublic;
+              valueToPersistInternal = maybeInternal;
+            }
+            tree.setVertexProperty(id, internalKey, valueToPersistInternal);
+          }
+        };
+      }
+      if (typeof prop !== "string") return void 0;
+      const rule = publicToInternal.get(prop);
+      if (rule) {
+        const raw = tree.getVertexProperty(id, rule.internalKey);
+        return rule.toPublic ? rule.toPublic(raw) : raw;
+      }
+      return tree.getVertexProperty(id, prop);
+    },
+    set(_target, prop, value) {
+      if (typeof prop !== "string") return true;
+      if (prop === RESERVED_METHOD_USE_TRANSIENT || prop === RESERVED_METHOD_COMMIT_TRANSIENTS) {
+        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 = { ...toPublicObject(tree, id, internalToPublic), [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];
+        }
+      }
+      const rule = publicToInternal.get(prop);
+      if (rule) {
+        const converted = rule.toInternal ? rule.toInternal(value) : value;
+        tree.setVertexProperty(id, rule.internalKey, converted);
+        return true;
+      }
+      tree.setVertexProperty(id, prop, value);
+      return true;
+    },
+    deleteProperty(_target, prop) {
+      if (typeof prop !== "string") return true;
+      if (prop === RESERVED_METHOD_USE_TRANSIENT || prop === RESERVED_METHOD_COMMIT_TRANSIENTS) {
+        return true;
+      }
+      const rule = publicToInternal.get(prop);
+      if (rule) {
+        tree.setVertexProperty(id, rule.internalKey, void 0);
+        return true;
+      }
+      tree.setVertexProperty(id, prop, void 0);
+      return true;
+    },
+    has(_target, prop) {
+      if (typeof prop !== "string") return false;
+      if (schema?.shape && Object.prototype.hasOwnProperty.call(schema.shape, prop)) return true;
+      if (includeInternalKeys) {
+        return publicToInternal.has(prop) || internalToPublic.has(prop);
+      }
+      return false;
+    },
+    ownKeys() {
+      const keys = /* @__PURE__ */ new Set();
+      for (const k of Object.keys(schema?.shape ?? {})) keys.add(k);
+      if (includeInternalKeys) {
+        for (const rule of aliases) keys.add(rule.internalKey);
+      }
+      return Array.from(keys);
+    },
+    getOwnPropertyDescriptor() {
+      return { enumerable: true, configurable: true };
+    }
+  });
+}
+
 // src/Vertex.ts
-var Vertex = class {
+var Y = __toESM(require("yjs"), 1);
+var Vertex = class _Vertex {
   constructor(tree, state) {
     this.tree = tree;
     this.state = state;
@@ -449,12 +654,18 @@ var Vertex = class {
     return this.children.map((v) => v.getAsTypedObject());
   }
   newChild(props) {
-    const typedProps = props;
-    return this.tree.newVertex(this.id, typedProps);
+    if (props && typeof props === "object" && "children" in props) {
+      throw new Error("Passing children inside props is not supported at the moment");
+    }
+    const normalized = _Vertex.normalizePropsForCreation(props);
+    return this.tree.newVertex(this.id, normalized);
   }
   newNamedChild(name, props) {
-    const typedProps = props;
-    return this.tree.newNamedVertex(this.id, name, typedProps);
+    if (props && typeof props === "object" && "children" in props) {
+      throw new Error("Passing children inside props is not supported at the moment");
+    }
+    const normalized = _Vertex.normalizePropsForCreation(props, name);
+    return this.tree.newNamedVertex(this.id, name, normalized);
   }
   setProperty(key, value) {
     const existingValue = this.getProperty(key, false);
@@ -520,6 +731,68 @@ var Vertex = class {
   moveTo(parent) {
     this.tree.moveVertex(this.id, parent.id);
   }
+  /** Returns a live reactive object bound to this vertex. Accepts schema or options. */
+  bind(schemaOrOptions) {
+    return bindVertex(this.tree, this.id, schemaOrOptions);
+  }
+  /**
+   * Normalizes an input props object for vertex creation:
+   * - Aliases name -> _n, createdAt -> _c (Date -> ISO string)
+   * - Filters unsupported field types with a console warning
+   * - When a name param is provided to newNamedChild, ignores conflicting name in props
+   */
+  static normalizePropsForCreation(props, explicitName) {
+    if (!props) return null;
+    const input = props;
+    const out = {};
+    const skipped = [];
+    for (const [rawKey, rawValue] of Object.entries(input)) {
+      if (rawValue === void 0) {
+        continue;
+      }
+      if (rawKey === "children") continue;
+      let key = rawKey;
+      if (rawKey === "name") {
+        if (explicitName !== void 0) {
+          console.warn('newNamedChild: "name" in props is ignored because a name argument was provided');
+          continue;
+        }
+        key = "_n";
+      } else if (rawKey === "createdAt") {
+        key = "_c";
+      }
+      let value = rawValue;
+      if (key === "_c") {
+        if (value instanceof Date) {
+          value = value.toISOString();
+        } else if (typeof value === "string") {
+        } else {
+          skipped.push(rawKey);
+          continue;
+        }
+      }
+      const isPrimitive = (v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean";
+      if (Array.isArray(value)) {
+        if (!value.every(isPrimitive)) {
+          skipped.push(rawKey);
+          continue;
+        }
+      } else if (typeof value === "object" && value !== null) {
+        if (!(value instanceof Y.Doc)) {
+          skipped.push(rawKey);
+          continue;
+        }
+      } else if (!isPrimitive(value)) {
+        skipped.push(rawKey);
+        continue;
+      }
+      out[key] = value;
+    }
+    if (skipped.length > 0) {
+      console.warn(`Some fields were skipped due to unsupported types: ${skipped.join(", ")}`);
+    }
+    return Object.keys(out).length > 0 ? out : null;
+  }
 };
 
 // src/StateVector.ts
@@ -708,7 +981,7 @@ var StateVector = class _StateVector {
 };
 
 // src/RepTree.ts
-var Y = __toESM(require("yjs"), 1);
+var Y2 = __toESM(require("yjs"), 1);
 var _RepTree = class _RepTree {
   /**
    * @param peerId - The peer ID of the current client. Should be unique across all peers.
@@ -870,8 +1143,8 @@ var _RepTree = class _RepTree {
   setTransientVertexProperty(vertexId, key, value) {
     this.lamportClock++;
     let opValue;
-    if (value instanceof Y.Doc) {
-      const state = Y.encodeStateAsUpdate(value);
+    if (value instanceof Y2.Doc) {
+      const state = Y2.encodeStateAsUpdate(value);
       opValue = {
         type: "yjs",
         value: state
@@ -887,8 +1160,8 @@ var _RepTree = class _RepTree {
   setVertexProperty(vertexId, key, value) {
     this.lamportClock++;
     let opValue;
-    if (value instanceof Y.Doc) {
-      const state = Y.encodeStateAsUpdate(value);
+    if (value instanceof Y2.Doc) {
+      const state = Y2.encodeStateAsUpdate(value);
       opValue = {
         type: "yjs",
         value: state
@@ -1060,10 +1333,10 @@ var _RepTree = class _RepTree {
         if (!propB) {
           return false;
         }
-        if (propA.value instanceof Y.Doc && propB.value instanceof Y.Doc) {
-          const snapshotA = Y.snapshot(propA.value);
-          const snapshotB = Y.snapshot(propB.value);
-          if (!Y.equalSnapshots(snapshotA, snapshotB)) {
+        if (propA.value instanceof Y2.Doc && propB.value instanceof Y2.Doc) {
+          const snapshotA = Y2.snapshot(propA.value);
+          const snapshotB = Y2.snapshot(propB.value);
+          if (!Y2.equalSnapshots(snapshotA, snapshotB)) {
             return false;
           }
         } else if (propA.value !== propB.value) {
@@ -1167,7 +1440,7 @@ var _RepTree = class _RepTree {
     const propertyKey = `${key}@${vertexId}`;
     if (this.yjsObservers.has(propertyKey)) {
       const existingDoc = this.getVertexProperty(vertexId, key);
-      if (existingDoc instanceof Y.Doc) {
+      if (existingDoc instanceof Y2.Doc) {
         existingDoc.off("update", this.yjsObservers.get(propertyKey));
       }
       this.yjsObservers.delete(propertyKey);
@@ -1247,13 +1520,13 @@ var _RepTree = class _RepTree {
       throw new Error("Unknown CRDT type");
     }
     const ydoc = targetVertex.getProperty(op.key);
-    if (ydoc instanceof Y.Doc) {
-      Y.applyUpdate(ydoc, crdtValue.value);
+    if (ydoc instanceof Y2.Doc) {
+      Y2.applyUpdate(ydoc, crdtValue.value);
     } else {
-      const newDoc = new Y.Doc();
+      const newDoc = new Y2.Doc();
       this.setupYjsObserver(newDoc, op.targetId, op.key);
       this.state.setProperty(op.targetId, op.key, newDoc);
-      Y.applyUpdate(newDoc, crdtValue.value);
+      Y2.applyUpdate(newDoc, crdtValue.value);
     }
     this.propertiesAndTheirOpIds.set(`${op.key}@${op.targetId}`, op.id);
     this.reportOpAsApplied(op);
@@ -1359,6 +1632,17 @@ 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;
@@ -1369,6 +1653,8 @@ var RepTree = _RepTree;
   TreeState,
   Vertex,
   VertexState,
+  bindVertex,
+  defaultAliases,
   isAnyPropertyOp,
   isLWWPropertyOp,
   isModifyPropertyOp,