reptree 0.2.3 → 0.3.0

package/README.md

@@ -26,7 +26,7 @@ npm install reptree
 ### Reactive vertex with Zod (optional)
 
 ```ts
-import { RepTree, bindVertex } from 'reptree';
+import { RepTree } from 'reptree';
 import { z } from 'zod';
 
 const tree = new RepTree('peer1');
@@ -35,16 +35,25 @@ 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);
+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 `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
@@ -98,6 +107,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

@@ -36,6 +36,7 @@ __export(index_exports, {
   Vertex: () => Vertex,
   VertexState: () => VertexState,
   bindVertex: () => bindVertex,
+  defaultAliases: () => defaultAliases,
   isAnyPropertyOp: () => isAnyPropertyOp,
   isLWWPropertyOp: () => isLWWPropertyOp,
   isModifyPropertyOp: () => isModifyPropertyOp,
@@ -404,19 +405,217 @@ function uuid() {
 }
 
 // src/reactive.ts
-function toObject(tree, id) {
+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)) obj[key] = value;
+  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;
 }
-function bindVertex(tree, id, schema) {
+var RESERVED_METHOD_USE_TRANSIENT = "useTransient";
+var RESERVED_METHOD_COMMIT_TRANSIENTS = "commitTransients";
+var VERTEX_PROPS = ["$id", "$parentId", "$parent", "$children", "$childrenIds"];
+var VERTEX_METHODS = ["$moveTo", "$delete", "$observe", "$observeChildren", "$newChild", "$newNamedChild"];
+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);
+  const cachedMethods = /* @__PURE__ */ new Map();
   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") {
+        if (prop === "$id") return id;
+        if (prop === "$parentId") return tree.getVertex(id)?.parentId ?? null;
+        if (prop === "$parent") {
+          const vertex = tree.getVertex(id);
+          return vertex?.parent;
+        }
+        if (prop === "$children") return tree.getChildren(id);
+        if (prop === "$childrenIds") return tree.getChildrenIds(id);
+        if (prop === "$moveTo") {
+          if (!cachedMethods.has(prop)) {
+            cachedMethods.set(prop, (parent) => {
+              const parentId = typeof parent === "object" && parent !== null ? parent.id || parent.$id : parent;
+              tree.moveVertex(id, parentId);
+            });
+          }
+          return cachedMethods.get(prop);
+        }
+        if (prop === "$delete") {
+          if (!cachedMethods.has(prop)) {
+            cachedMethods.set(prop, () => tree.deleteVertex(id));
+          }
+          return cachedMethods.get(prop);
+        }
+        if (prop === "$observe") {
+          if (!cachedMethods.has(prop)) {
+            cachedMethods.set(prop, (listener) => tree.observe(id, listener));
+          }
+          return cachedMethods.get(prop);
+        }
+        if (prop === "$observeChildren") {
+          if (!cachedMethods.has(prop)) {
+            cachedMethods.set(prop, (listener) => {
+              return tree.observe(id, (events) => {
+                if (events.some((e) => e.type === "children")) {
+                  listener(tree.getChildren(id));
+                }
+              });
+            });
+          }
+          return cachedMethods.get(prop);
+        }
+        if (prop === "$newChild") {
+          if (!cachedMethods.has(prop)) {
+            cachedMethods.set(prop, (props) => {
+              const vertex = tree.getVertex(id);
+              return vertex?.newChild(props);
+            });
+          }
+          return cachedMethods.get(prop);
+        }
+        if (prop === "$newNamedChild") {
+          if (!cachedMethods.has(prop)) {
+            cachedMethods.set(prop, (name, props) => {
+              const vertex = tree.getVertex(id);
+              return vertex?.newNamedChild(name, props);
+            });
+          }
+          return cachedMethods.get(prop);
+        }
+      }
       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 (VERTEX_PROPS.includes(prop)) {
+        return true;
+      }
+      if (VERTEX_METHODS.includes(prop)) {
+        return true;
+      }
       if (schema?.shape && schema.shape[prop]) {
         const field = schema.shape[prop];
         if (field.safeParse) {
@@ -425,7 +624,7 @@ function bindVertex(tree, id, schema) {
           value = res.data ?? value;
         }
       } else if (schema?.safeParse) {
-        const next = { ...toObject(tree, id), [prop]: value };
+        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;
@@ -433,20 +632,49 @@ function bindVertex(tree, id, schema) {
           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;
+      }
+      if (VERTEX_PROPS.includes(prop)) {
+        return true;
+      }
+      if (VERTEX_METHODS.includes(prop)) {
+        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;
-      return !!schema?.shape && Object.prototype.hasOwnProperty.call(schema.shape, prop);
+      if (schema?.shape && Object.prototype.hasOwnProperty.call(schema.shape, prop)) return true;
+      if (includeInternalKeys) {
+        return publicToInternal.has(prop) || internalToPublic.has(prop);
+      }
+      return false;
     },
     ownKeys() {
-      return Object.keys(schema?.shape ?? {});
+      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 };
@@ -455,7 +683,8 @@ function bindVertex(tree, id, schema) {
 }
 
 // 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;
@@ -501,12 +730,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);
@@ -572,9 +807,67 @@ 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);
+  /** 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;
   }
 };
 
@@ -764,7 +1057,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.
@@ -926,8 +1219,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
@@ -943,8 +1236,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
@@ -1116,10 +1409,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) {
@@ -1223,7 +1516,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);
@@ -1303,13 +1596,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);
@@ -1437,6 +1730,7 @@ var RepTree = _RepTree;
   Vertex,
   VertexState,
   bindVertex,
+  defaultAliases,
   isAnyPropertyOp,
   isLWWPropertyOp,
   isModifyPropertyOp,