reptree 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -18,6 +18,8 @@ declare class VertexState {
     getAllProperties(includingTransient?: boolean): ReadonlyArray<TreeVertexProperty>;
     removeProperty(key: string): void;
     removeTransientProperty(key: string): void;
+    getTransientProperties(): ReadonlyArray<TreeVertexProperty>;
+    clearAllTransientProperties(): void;
 }
 
 type TreeVertexId = string;
@@ -119,34 +121,61 @@ type BindOptions<T> = {
     aliases?: AliasRule[];
     includeInternalKeys?: boolean;
 };
+/**
+ * A bound vertex object that forwards reads/writes to a vertex.
+ * @param T - The type of the vertex.
+ */
 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) */
+    $vertex: Vertex;
     $id: string;
     $parentId: string | null;
     $parent: Vertex | undefined;
     $children: Vertex[];
     $childrenIds: string[];
-    /** Vertex methods (prefixed with $ to avoid conflicts) */
+    /**
+     * Apply transient edits that override reads but do not persist yet.
+     * @param fn
+     */
+    $useTransients(fn: (t: T) => void): void;
+    /**
+     * Promote current transient overlays to persistent values.
+     */
+    $commitTransients(): void;
+    /**
+     * Move the vertex to a new parent.
+     * @param parent - The new parent vertex or ID.
+     */
     $moveTo(parent: Vertex | BindedVertex<any> | string): void;
+    /**
+     * Delete the vertex.
+     */
     $delete(): void;
+    /**
+     * Observe changes to the vertex.
+     * @param listener - The listener function to call when changes occur.
+     */
     $observe(listener: (events: any[]) => void): () => void;
+    /**
+     * Observe changes to the children of the vertex.
+     * @param listener - The listener function to call when children change.
+     */
     $observeChildren(listener: (children: Vertex[]) => void): () => void;
+    /**
+     * Create a new child vertex.
+     * @param props - The properties to set on the new child vertex.
+     */
     $newChild(props?: Record<string, any> | object | null): Vertex;
+    /**
+     * Create a new named child vertex.
+     * @param name - The name of the new child vertex.
+     * @param props - The properties to set on the new child 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.
+ * Returns a live Proxy that forwards reads/writes to a vertex.
+ * - Reads reflect the latest CRDT state (including transients by default)
+ * - Writes persist to the CRDT with optional schema validation
  */
 declare function bindVertex<T extends Record<string, unknown>>(tree: RepTree, id: string, schemaOrOptions?: SchemaLike<T> | BindOptions<T>): BindedVertex<T>;
 
@@ -173,6 +202,7 @@ declare class Vertex {
     newNamedChild(name: string, props?: Record<string, VertexPropertyType> | object | null): Vertex;
     setProperty(key: string, value: VertexPropertyType): void;
     setTransientProperty(key: string, value: VertexPropertyType): void;
+    commitTransients(): void;
     setProperties(props: Record<string, VertexPropertyType> | object): void;
     getProperty(key: string, includingTransient?: boolean): VertexPropertyType | undefined;
     getProperties(): Record<string, VertexPropertyType>;
@@ -249,6 +279,7 @@ declare class RepTree {
     moveVertex(vertexId: string, parentId: string): void;
     deleteVertex(vertexId: string): void;
     setTransientVertexProperty(vertexId: string, key: string, value: VertexPropertyType): void;
+    commitTransients(vertexId: string): void;
     setVertexProperty(vertexId: string, key: string, value: VertexPropertyType): void;
     setVertexProperties(vertexId: string, props: Record<string, VertexPropertyType> | object): void;
     getVertexByPath(path: string): Vertex | undefined;

package/dist/index.d.ts

@@ -18,6 +18,8 @@ declare class VertexState {
     getAllProperties(includingTransient?: boolean): ReadonlyArray<TreeVertexProperty>;
     removeProperty(key: string): void;
     removeTransientProperty(key: string): void;
+    getTransientProperties(): ReadonlyArray<TreeVertexProperty>;
+    clearAllTransientProperties(): void;
 }
 
 type TreeVertexId = string;
@@ -119,34 +121,61 @@ type BindOptions<T> = {
     aliases?: AliasRule[];
     includeInternalKeys?: boolean;
 };
+/**
+ * A bound vertex object that forwards reads/writes to a vertex.
+ * @param T - The type of the vertex.
+ */
 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) */
+    $vertex: Vertex;
     $id: string;
     $parentId: string | null;
     $parent: Vertex | undefined;
     $children: Vertex[];
     $childrenIds: string[];
-    /** Vertex methods (prefixed with $ to avoid conflicts) */
+    /**
+     * Apply transient edits that override reads but do not persist yet.
+     * @param fn
+     */
+    $useTransients(fn: (t: T) => void): void;
+    /**
+     * Promote current transient overlays to persistent values.
+     */
+    $commitTransients(): void;
+    /**
+     * Move the vertex to a new parent.
+     * @param parent - The new parent vertex or ID.
+     */
     $moveTo(parent: Vertex | BindedVertex<any> | string): void;
+    /**
+     * Delete the vertex.
+     */
     $delete(): void;
+    /**
+     * Observe changes to the vertex.
+     * @param listener - The listener function to call when changes occur.
+     */
     $observe(listener: (events: any[]) => void): () => void;
+    /**
+     * Observe changes to the children of the vertex.
+     * @param listener - The listener function to call when children change.
+     */
     $observeChildren(listener: (children: Vertex[]) => void): () => void;
+    /**
+     * Create a new child vertex.
+     * @param props - The properties to set on the new child vertex.
+     */
     $newChild(props?: Record<string, any> | object | null): Vertex;
+    /**
+     * Create a new named child vertex.
+     * @param name - The name of the new child vertex.
+     * @param props - The properties to set on the new child 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.
+ * Returns a live Proxy that forwards reads/writes to a vertex.
+ * - Reads reflect the latest CRDT state (including transients by default)
+ * - Writes persist to the CRDT with optional schema validation
  */
 declare function bindVertex<T extends Record<string, unknown>>(tree: RepTree, id: string, schemaOrOptions?: SchemaLike<T> | BindOptions<T>): BindedVertex<T>;
 
@@ -173,6 +202,7 @@ declare class Vertex {
     newNamedChild(name: string, props?: Record<string, VertexPropertyType> | object | null): Vertex;
     setProperty(key: string, value: VertexPropertyType): void;
     setTransientProperty(key: string, value: VertexPropertyType): void;
+    commitTransients(): void;
     setProperties(props: Record<string, VertexPropertyType> | object): void;
     getProperty(key: string, includingTransient?: boolean): VertexPropertyType | undefined;
     getProperties(): Record<string, VertexPropertyType>;
@@ -249,6 +279,7 @@ declare class RepTree {
     moveVertex(vertexId: string, parentId: string): void;
     deleteVertex(vertexId: string): void;
     setTransientVertexProperty(vertexId: string, key: string, value: VertexPropertyType): void;
+    commitTransients(vertexId: string): void;
     setVertexProperty(vertexId: string, key: string, value: VertexPropertyType): void;
     setVertexProperties(vertexId: string, props: Record<string, VertexPropertyType> | object): void;
     getVertexByPath(path: string): Vertex | undefined;

package/dist/index.js

@@ -137,6 +137,12 @@ var VertexState = class {
   removeTransientProperty(key) {
     this.transientProperties = this.transientProperties.filter((p) => p.key !== key);
   }
+  getTransientProperties() {
+    return this.transientProperties;
+  }
+  clearAllTransientProperties() {
+    this.transientProperties = [];
+  }
 };
 
 // src/TreeState.ts
@@ -373,263 +379,124 @@ function buildAliasMaps(aliases) {
   }
   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";
-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);
+  const { publicToInternal } = buildAliasMaps(aliases);
+  const obj = {};
+  Object.defineProperties(obj, {
+    $vertex: { get: () => tree.getVertex(id), enumerable: false, configurable: true },
+    $id: { get: () => id, enumerable: false, configurable: true },
+    $parentId: { get: () => tree.getVertex(id)?.parentId ?? null, enumerable: false, configurable: true },
+    $parent: { get: () => tree.getVertex(id)?.parent, enumerable: false, configurable: true },
+    $children: { get: () => tree.getChildren(id), enumerable: false, configurable: true },
+    $childrenIds: { get: () => tree.getChildrenIds(id), enumerable: false, configurable: true },
+    $moveTo: {
+      value: (parent) => {
+        const parentId = typeof parent === "object" && parent !== null ? parent.id || parent.$id : parent;
+        tree.moveVertex(id, parentId);
+      },
+      enumerable: false,
+      configurable: true,
+      writable: false
+    },
+    $delete: { value: () => tree.deleteVertex(id), enumerable: false, configurable: true, writable: false },
+    $observe: { value: (listener) => tree.observe(id, listener), enumerable: false, configurable: true, writable: false },
+    $observeChildren: {
+      value: (listener) => tree.observe(id, (events) => {
+        if (events.some((e) => e.type === "children")) {
+          listener(tree.getChildren(id));
         }
-        if (prop === "$newNamedChild") {
-          if (!cachedMethods.has(prop)) {
-            cachedMethods.set(prop, (name, props) => {
-              const vertex = tree.getVertex(id);
-              return vertex?.newNamedChild(name, props);
-            });
+      }),
+      enumerable: false,
+      configurable: true,
+      writable: false
+    },
+    $newChild: { value: (props) => tree.getVertex(id).newChild(props), enumerable: false, configurable: true, writable: false },
+    $newNamedChild: { value: (name, props) => tree.getVertex(id).newNamedChild(name, props), enumerable: false, configurable: true, writable: false },
+    $useTransients: {
+      value: function(fn) {
+        const transientProxy = new Proxy({}, {
+          set(_, prop, value) {
+            if (typeof prop === "string") {
+              const rule = publicToInternal.get(prop);
+              const internalKey = rule?.internalKey ?? prop;
+              const internalValue = rule?.toInternal ? rule.toInternal(value) : value;
+              tree.setTransientVertexProperty(id, internalKey, internalValue);
+            }
+            return true;
+          },
+          get(_, prop) {
+            if (typeof prop !== "string") return void 0;
+            const rule = publicToInternal.get(prop);
+            const internalKey = rule?.internalKey ?? prop;
+            const rawValue = tree.getVertexProperty(id, internalKey, true);
+            return rule?.toPublic ? rule.toPublic(rawValue) : rawValue;
           }
-          return cachedMethods.get(prop);
+        });
+        fn(transientProxy);
+      },
+      enumerable: false,
+      configurable: true,
+      writable: false
+    },
+    $commitTransients: { value: () => tree.commitTransients(id), enumerable: false, configurable: true, writable: false },
+    equals: {
+      value: function(other) {
+        if (other && typeof other === "object" && "$id" in other) {
+          return other.$id === id;
         }
+        return false;
+      },
+      enumerable: false,
+      configurable: true,
+      writable: false
+    }
+  });
+  const proxy = new Proxy(obj, {
+    get(target, prop, receiver) {
+      if (typeof prop !== "string") {
+        return Reflect.get(target, prop, receiver);
       }
-      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;
+      if (prop in target) {
+        return Reflect.get(target, prop, receiver);
       }
-      return tree.getVertexProperty(id, prop);
+      const rule = publicToInternal.get(prop);
+      const internalKey = rule?.internalKey ?? prop;
+      const rawValue = tree.getVertexProperty(id, internalKey, true);
+      return rule?.toPublic ? rule.toPublic(rawValue) : rawValue;
     },
-    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;
+    set(target, prop, value) {
+      if (typeof prop !== "string") {
+        return Reflect.set(target, prop, value);
       }
       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];
+          if (!res.success) throw new Error(`Invalid value for ${prop}`);
+          value = res.data;
         }
       }
       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);
+      const internalKey = rule?.internalKey ?? prop;
+      const internalValue = rule?.toInternal ? rule.toInternal(value) : value;
+      tree.setVertexProperty(id, internalKey, internalValue);
       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)) {
+      if (typeof prop !== "string") {
         return true;
       }
       const rule = publicToInternal.get(prop);
-      if (rule) {
-        tree.setVertexProperty(id, rule.internalKey, void 0);
-        return true;
-      }
-      tree.setVertexProperty(id, prop, void 0);
+      const internalKey = rule?.internalKey ?? prop;
+      tree.setVertexProperty(id, internalKey, 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 };
     }
   });
+  return proxy;
 }
 
 // src/Vertex.ts
@@ -707,6 +574,9 @@ var Vertex = class _Vertex {
     }
     this.tree.setTransientVertexProperty(this.id, key, value);
   }
+  commitTransients() {
+    this.tree.commitTransients(this.id);
+  }
   setProperties(props) {
     for (const [key, value] of Object.entries(props)) {
       this.setProperty(key, value);
@@ -1183,6 +1053,20 @@ var _RepTree = class _RepTree {
     this.localOps.push(op);
     this.applyProperty(op);
   }
+  commitTransients(vertexId) {
+    const vertex = this.state.getVertex(vertexId);
+    if (!vertex) {
+      return;
+    }
+    const transientProps = vertex.getTransientProperties();
+    for (const prop of transientProps) {
+      this.setVertexProperty(vertexId, prop.key, prop.value);
+    }
+    for (const prop of transientProps) {
+      this.transientPropertiesAndTheirOpIds.delete(`${prop.key}@${vertexId}`);
+    }
+    vertex.clearAllTransientProperties();
+  }
   setVertexProperty(vertexId, key, value) {
     this.lamportClock++;
     let opValue;