reptree 0.2.2 → 0.2.4

package/dist/index.d.ts

@@ -89,6 +89,54 @@ declare function newMoveVertexOp(clock: number, peerId: string, targetId: string
 declare function newSetVertexPropertyOp(clock: number, peerId: string, targetId: string, key: string, value: VertexPropertyTypeInOperation): SetVertexProperty;
 declare function newSetTransientVertexPropertyOp(clock: number, peerId: string, targetId: string, key: string, value: VertexPropertyTypeInOperation): SetVertexProperty;
 
+type FieldSchemaLike = {
+    safeParse?: (input: unknown) => {
+        success: true;
+        data: unknown;
+    } | {
+        success: false;
+    };
+};
+type SchemaLike<T> = {
+    safeParse?: (input: unknown) => {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+    };
+    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;
+};
+/**
+ * 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, schemaOrOptions?: SchemaLike<T> | BindOptions<T>): BindedVertex<T>;
+
 /**
  * A wrapper class for VertexState that provides a more convenient API
  * for working with vertices in a RepTree.
@@ -124,6 +172,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. 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;
 }
 
 /**
@@ -236,6 +293,12 @@ declare class RepTree {
      * When enabled, rebuilds the state vector from existing operations if needed
      */
     set stateVectorEnabled(value: boolean);
+    /**
+     * Parses the vertex properties with a provided schema that has a `parse` method (e.g., Zod schema)
+     */
+    parseVertex<T>(vertexId: string, schema: {
+        parse: (data: unknown) => T;
+    }): T;
 }
 
 declare class TreeState {
@@ -321,4 +384,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, 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

@@ -354,8 +354,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 {
+import * as Y from "yjs";
+var Vertex = class _Vertex {
   constructor(tree, state) {
     this.tree = tree;
     this.state = state;
@@ -401,12 +604,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);
@@ -472,6 +681,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
@@ -660,7 +931,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.
@@ -822,8 +1093,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
@@ -839,8 +1110,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
@@ -1012,10 +1283,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) {
@@ -1119,7 +1390,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);
@@ -1199,13 +1470,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);
@@ -1311,6 +1582,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;
@@ -1320,6 +1602,8 @@ export {
   TreeState,
   Vertex,
   VertexState,
+  bindVertex,
+  defaultAliases,
   isAnyPropertyOp,
   isLWWPropertyOp,
   isModifyPropertyOp,