reptree 0.2.3 → 0.3.0

package/dist/index.d.ts

@@ -107,13 +107,48 @@ type SchemaLike<T> = {
     parse?: (input: unknown) => T;
     shape?: Record<string, FieldSchemaLike>;
 };
+type AliasRule = {
+    publicKey: string;
+    internalKey: string;
+    toPublic?: (value: unknown) => unknown;
+    toInternal?: (value: unknown) => unknown;
+};
+declare const defaultAliases: AliasRule[];
+type BindOptions<T> = {
+    schema?: SchemaLike<T>;
+    aliases?: AliasRule[];
+    includeInternalKeys?: boolean;
+};
+type BindedVertex<T> = T & {
+    /**
+     * Create a transient proxy that can be used to write transient properties.
+     */
+    useTransient(fn: (t: T) => void): void;
+    /**
+     * Promote transient properties to persistent.
+     */
+    commitTransients(): void;
+    /** Vertex properties (prefixed with $ to avoid conflicts) */
+    $id: string;
+    $parentId: string | null;
+    $parent: Vertex | undefined;
+    $children: Vertex[];
+    $childrenIds: string[];
+    /** Vertex methods (prefixed with $ to avoid conflicts) */
+    $moveTo(parent: Vertex | BindedVertex<any> | string): void;
+    $delete(): void;
+    $observe(listener: (events: any[]) => void): () => void;
+    $observeChildren(listener: (children: Vertex[]) => void): () => void;
+    $newChild(props?: Record<string, any> | object | null): Vertex;
+    $newNamedChild(name: string, props?: Record<string, any> | object | null): Vertex;
+};
 /**
  * Returns a live object that proxies reads/writes to a vertex.
  * - Reads reflect the latest CRDT state.
  * - Writes persist to the CRDT.
  * - If a schema is provided, writes are validated. If a field schema exists in `schema.shape`, field-level validation is applied.
  */
-declare function bindVertex<T extends Record<string, unknown>>(tree: RepTree, id: string, schema?: SchemaLike<T>): T;
+declare function bindVertex<T extends Record<string, unknown>>(tree: RepTree, id: string, schemaOrOptions?: SchemaLike<T> | BindOptions<T>): BindedVertex<T>;
 
 /**
  * A wrapper class for VertexState that provides a more convenient API
@@ -150,8 +185,15 @@ declare class Vertex {
     observeChildrenAsTypedArray<T>(listener: (children: T[]) => void): () => void;
     delete(): void;
     moveTo(parent: Vertex): void;
-    /** Returns a live reactive object bound to this vertex. Optional schema validates writes. */
-    bind<T extends Record<string, unknown>>(schema?: SchemaLike<T>): T;
+    /** Returns a live reactive object bound to this vertex. Accepts schema or options. */
+    bind<T extends Record<string, unknown>>(schemaOrOptions?: SchemaLike<T> | BindOptions<T>): BindedVertex<T>;
+    /**
+     * 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
+     */
+    private static normalizePropsForCreation;
 }
 
 /**
@@ -355,4 +397,4 @@ declare class StateVector {
 
 declare function uuid(): string;
 
-export { type CRDTType, type MoveVertex, type OpId, type OpIdRange, RepTree, type SetVertexProperty, StateVector, TreeState, type TreeVertexId, type TreeVertexProperty, Vertex, type VertexChangeEvent, type VertexChildrenChangeEvent, type VertexMoveEvent, type VertexOperation, type VertexPropertyChangeEvent, type VertexPropertyType, type VertexPropertyTypeInOperation, VertexState, bindVertex, isAnyPropertyOp, isLWWPropertyOp, isModifyPropertyOp, isMoveVertexOp, newMoveVertexOp, newSetTransientVertexPropertyOp, newSetVertexPropertyOp, uuid };
+export { type AliasRule, type BindOptions, type BindedVertex, type CRDTType, 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, type VertexPropertyTypeInOperation, VertexState, bindVertex, defaultAliases, isAnyPropertyOp, isLWWPropertyOp, isModifyPropertyOp, isMoveVertexOp, newMoveVertexOp, newSetTransientVertexPropertyOp, newSetVertexPropertyOp, uuid };

package/dist/index.js

@@ -355,19 +355,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) {
@@ -376,7 +574,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;
@@ -384,20 +582,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 };
@@ -406,7 +633,8 @@ function bindVertex(tree, id, schema) {
 }
 
 // src/Vertex.ts
-var Vertex = class {
+import * as Y from "yjs";
+var Vertex = class _Vertex {
   constructor(tree, state) {
     this.tree = tree;
     this.state = state;
@@ -452,12 +680,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);
@@ -523,9 +757,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;
   }
 };
 
@@ -715,7 +1007,7 @@ var StateVector = class _StateVector {
 };
 
 // src/RepTree.ts
-import * as Y from "yjs";
+import * as Y2 from "yjs";
 var _RepTree = class _RepTree {
   /**
    * @param peerId - The peer ID of the current client. Should be unique across all peers.
@@ -877,8 +1169,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
@@ -894,8 +1186,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
@@ -1067,10 +1359,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) {
@@ -1174,7 +1466,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);
@@ -1254,13 +1546,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);
@@ -1387,6 +1679,7 @@ export {
   Vertex,
   VertexState,
   bindVertex,
+  defaultAliases,
   isAnyPropertyOp,
   isLWWPropertyOp,
   isModifyPropertyOp,