@loro-extended/change 1.0.1 → 2.0.0

package/dist/index.js

@@ -8,6 +8,9 @@ function derivePlaceholder(schema) {
 }
 function deriveShapePlaceholder(shape) {
   switch (shape._type) {
+    // Any container - no placeholder (undefined)
+    case "any":
+      return void 0;
     // Leaf containers - use _placeholder directly
     case "text":
       return shape._placeholder;
@@ -36,6 +39,9 @@ function deriveShapePlaceholder(shape) {
 }
 function deriveValueShapePlaceholder(shape) {
   switch (shape.valueType) {
+    // Any value - no placeholder (undefined)
+    case "any":
+      return void 0;
     // Leaf values - use _placeholder directly
     case "string":
       return shape._placeholder;
@@ -146,6 +152,12 @@ function overlayPlaceholder(shape, crdtValue, placeholderValue) {
   return result;
 }
 function mergeValue(shape, crdtValue, placeholderValue) {
+  if (shape._type === "any") {
+    return crdtValue;
+  }
+  if (shape._type === "value" && shape.valueType === "any") {
+    return crdtValue;
+  }
   if (crdtValue === void 0 && placeholderValue === void 0) {
     throw new Error("either crdt or placeholder value must be defined");
   }
@@ -247,6 +259,154 @@ function mergeDiscriminatedUnion(shape, crdtValue, placeholderValue) {
   return mergeValue(variantShape, crdtValue, effectivePlaceholderValue);
 }
 
+// src/path-builder.ts
+function createPathSelector(segments) {
+  return {
+    __resultType: void 0,
+    __segments: segments
+  };
+}
+function createPathNode(shape, segments) {
+  const selector = createPathSelector(segments);
+  if (shape._type === "text" || shape._type === "counter") {
+    return selector;
+  }
+  if (shape._type === "value") {
+    return selector;
+  }
+  if (shape._type === "list" || shape._type === "movableList") {
+    return Object.assign(selector, {
+      get $each() {
+        return createPathNode(shape.shape, [...segments, { type: "each" }]);
+      },
+      $at(index) {
+        return createPathNode(shape.shape, [
+          ...segments,
+          { type: "index", index }
+        ]);
+      },
+      get $first() {
+        return createPathNode(shape.shape, [
+          ...segments,
+          { type: "index", index: 0 }
+        ]);
+      },
+      get $last() {
+        return createPathNode(shape.shape, [
+          ...segments,
+          { type: "index", index: -1 }
+        ]);
+      }
+    });
+  }
+  if (shape._type === "struct") {
+    const props = {};
+    for (const key in shape.shapes) {
+      Object.defineProperty(props, key, {
+        get() {
+          return createPathNode(shape.shapes[key], [
+            ...segments,
+            { type: "property", key }
+          ]);
+        },
+        enumerable: true
+      });
+    }
+    return Object.assign(selector, props);
+  }
+  if (shape._type === "record") {
+    return Object.assign(selector, {
+      get $each() {
+        return createPathNode(shape.shape, [...segments, { type: "each" }]);
+      },
+      $key(key) {
+        return createPathNode(shape.shape, [...segments, { type: "key", key }]);
+      }
+    });
+  }
+  return selector;
+}
+function createPathBuilder(docShape) {
+  const builder = {};
+  for (const key in docShape.shapes) {
+    Object.defineProperty(builder, key, {
+      get() {
+        return createPathNode(docShape.shapes[key], [{ type: "property", key }]);
+      },
+      enumerable: true
+    });
+  }
+  return builder;
+}
+
+// src/path-compiler.ts
+function compileToJsonPath(segments) {
+  let path = "$";
+  for (const segment of segments) {
+    switch (segment.type) {
+      case "property":
+        if (/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(segment.key)) {
+          path += `.${segment.key}`;
+        } else {
+          path += `["${escapeJsonPathKey(segment.key)}"]`;
+        }
+        break;
+      case "each":
+        path += "[*]";
+        break;
+      case "index":
+        path += `[${segment.index}]`;
+        break;
+      case "key":
+        path += `["${escapeJsonPathKey(segment.key)}"]`;
+        break;
+    }
+  }
+  return path;
+}
+function escapeJsonPathKey(key) {
+  return key.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function hasWildcard(segments) {
+  return segments.some((s) => s.type === "each");
+}
+
+// src/path-evaluator.ts
+function evaluatePath(doc, selector) {
+  const json = doc.$.toJSON();
+  return evaluatePathOnValue(json, selector.__segments);
+}
+function evaluatePathOnValue(value, segments) {
+  if (segments.length === 0) {
+    return value;
+  }
+  const [segment, ...rest] = segments;
+  switch (segment.type) {
+    case "property":
+    case "key":
+      if (value == null) return void 0;
+      if (typeof value !== "object") return void 0;
+      return evaluatePathOnValue(
+        value[segment.key],
+        rest
+      );
+    case "index": {
+      if (!Array.isArray(value)) return void 0;
+      const index = segment.index < 0 ? value.length + segment.index : segment.index;
+      if (index < 0 || index >= value.length) return void 0;
+      return evaluatePathOnValue(value[index], rest);
+    }
+    case "each":
+      if (Array.isArray(value)) {
+        return value.map((item) => evaluatePathOnValue(item, rest));
+      }
+      if (typeof value === "object" && value !== null) {
+        return Object.values(value).map((item) => evaluatePathOnValue(item, rest));
+      }
+      return [];
+  }
+}
+
 // src/placeholder-proxy.ts
 function createPlaceholderProxy(target) {
   const cache = /* @__PURE__ */ new Map();
@@ -270,6 +430,29 @@ function createPlaceholderProxy(target) {
 }
 
 // src/shape.ts
+function makeNullable(shape) {
+  const nullShape = {
+    _type: "value",
+    valueType: "null",
+    _plain: null,
+    _mutable: null,
+    _placeholder: null
+  };
+  const base = {
+    _type: "value",
+    valueType: "union",
+    shapes: [nullShape, shape],
+    _plain: null,
+    _mutable: null,
+    _placeholder: null
+    // Default placeholder is null
+  };
+  return Object.assign(base, {
+    placeholder(value) {
+      return { ...base, _placeholder: value };
+    }
+  });
+}
 var Shape = {
   doc: (shape) => ({
     _type: "doc",
@@ -278,6 +461,27 @@ var Shape = {
     _mutable: {},
     _placeholder: {}
   }),
+  /**
+   * Creates an "any" container shape - an escape hatch for untyped containers.
+   * Use this when integrating with external libraries that manage their own document structure.
+   *
+   * @example
+   * ```typescript
+   * // loro-prosemirror manages its own structure
+   * const ProseMirrorDocShape = Shape.doc({
+   *   doc: Shape.any(), // opt out of typing for this container
+   * })
+   *
+   * const handle = repo.get(docId, ProseMirrorDocShape, CursorPresenceShape)
+   * // handle.doc.doc is typed as `unknown` - you're on your own
+   * ```
+   */
+  any: () => ({
+    _type: "any",
+    _plain: void 0,
+    _mutable: void 0,
+    _placeholder: void 0
+  }),
   // CRDTs are represented by Loro Containers--they converge on state using Loro's
   // various CRDT algorithms
   counter: () => {
@@ -382,6 +586,9 @@ var Shape = {
       return Object.assign(base, {
         placeholder(value) {
           return { ...base, _placeholder: value };
+        },
+        nullable() {
+          return makeNullable(base);
         }
       });
     },
@@ -396,6 +603,9 @@ var Shape = {
       return Object.assign(base, {
         placeholder(value) {
           return { ...base, _placeholder: value };
+        },
+        nullable() {
+          return makeNullable(base);
         }
       });
     },
@@ -410,6 +620,9 @@ var Shape = {
       return Object.assign(base, {
         placeholder(value) {
           return { ...base, _placeholder: value };
+        },
+        nullable() {
+          return makeNullable(base);
         }
       });
     },
@@ -427,12 +640,63 @@ var Shape = {
       _mutable: void 0,
       _placeholder: void 0
     }),
-    uint8Array: () => ({
+    uint8Array: () => {
+      const base = {
+        _type: "value",
+        valueType: "uint8array",
+        _plain: new Uint8Array(),
+        _mutable: new Uint8Array(),
+        _placeholder: new Uint8Array()
+      };
+      return Object.assign(base, {
+        nullable() {
+          return makeNullable(base);
+        }
+      });
+    },
+    /**
+     * Alias for `uint8Array()` - creates a shape for binary data.
+     * Use this for better discoverability when working with binary data like cursor positions.
+     *
+     * @example
+     * ```typescript
+     * const CursorPresenceShape = Shape.plain.struct({
+     *   anchor: Shape.plain.bytes().nullable(),
+     *   focus: Shape.plain.bytes().nullable(),
+     * })
+     * ```
+     */
+    bytes: () => {
+      const base = {
+        _type: "value",
+        valueType: "uint8array",
+        _plain: new Uint8Array(),
+        _mutable: new Uint8Array(),
+        _placeholder: new Uint8Array()
+      };
+      return Object.assign(base, {
+        nullable() {
+          return makeNullable(base);
+        }
+      });
+    },
+    /**
+     * Creates an "any" value shape - an escape hatch for untyped values.
+     * Use this when you need to accept any valid Loro value type.
+     *
+     * @example
+     * ```typescript
+     * const FlexiblePresenceShape = Shape.plain.struct({
+     *   metadata: Shape.plain.any(), // accept any value type
+     * })
+     * ```
+     */
+    any: () => ({
       _type: "value",
-      valueType: "uint8array",
-      _plain: new Uint8Array(),
-      _mutable: new Uint8Array(),
-      _placeholder: new Uint8Array()
+      valueType: "any",
+      _plain: void 0,
+      _mutable: void 0,
+      _placeholder: void 0
     }),
     /**
      * Creates a struct value shape for plain objects with fixed keys.
@@ -446,41 +710,69 @@ var Shape = {
      * })
      * ```
      */
-    struct: (shape) => ({
-      _type: "value",
-      valueType: "struct",
-      shape,
-      _plain: {},
-      _mutable: {},
-      _placeholder: {}
-    }),
+    struct: (shape) => {
+      const base = {
+        _type: "value",
+        valueType: "struct",
+        shape,
+        _plain: {},
+        _mutable: {},
+        _placeholder: {}
+      };
+      return Object.assign(base, {
+        nullable() {
+          return makeNullable(base);
+        }
+      });
+    },
     /**
      * @deprecated Use `Shape.plain.struct` instead. `Shape.plain.struct` will be removed in a future version.
      */
-    object: (shape) => ({
-      _type: "value",
-      valueType: "struct",
-      shape,
-      _plain: {},
-      _mutable: {},
-      _placeholder: {}
-    }),
-    record: (shape) => ({
-      _type: "value",
-      valueType: "record",
-      shape,
-      _plain: {},
-      _mutable: {},
-      _placeholder: {}
-    }),
-    array: (shape) => ({
-      _type: "value",
-      valueType: "array",
-      shape,
-      _plain: [],
-      _mutable: [],
-      _placeholder: []
-    }),
+    object: (shape) => {
+      const base = {
+        _type: "value",
+        valueType: "struct",
+        shape,
+        _plain: {},
+        _mutable: {},
+        _placeholder: {}
+      };
+      return Object.assign(base, {
+        nullable() {
+          return makeNullable(base);
+        }
+      });
+    },
+    record: (shape) => {
+      const base = {
+        _type: "value",
+        valueType: "record",
+        shape,
+        _plain: {},
+        _mutable: {},
+        _placeholder: {}
+      };
+      return Object.assign(base, {
+        nullable() {
+          return makeNullable(base);
+        }
+      });
+    },
+    array: (shape) => {
+      const base = {
+        _type: "value",
+        valueType: "array",
+        shape,
+        _plain: [],
+        _mutable: [],
+        _placeholder: []
+      };
+      return Object.assign(base, {
+        nullable() {
+          return makeNullable(base);
+        }
+      });
+    },
     // Special value type that helps make things like `string | null` representable
     // TODO(duane): should this be a more general type for containers too?
     union: (shapes) => {
@@ -1408,6 +1700,11 @@ var RecordRef = class extends TypedRef {
     if (placeholder === void 0) {
       placeholder = deriveShapePlaceholder(shape);
     }
+    if (!hasContainerConstructor(shape._type)) {
+      throw new Error(
+        `Cannot create typed ref for shape type "${shape._type}". Use Shape.any() only at the document root level.`
+      );
+    }
     const LoroContainer = containerConstructor[shape._type];
     return {
       shape,
@@ -1550,6 +1847,11 @@ var StructRef = class extends TypedRef {
   }
   getTypedRefParams(key, shape) {
     const placeholder = this.placeholder?.[key];
+    if (!hasContainerConstructor(shape._type)) {
+      throw new Error(
+        `Cannot create typed ref for shape type "${shape._type}". Use Shape.any() only at the document root level.`
+      );
+    }
     const LoroContainer = containerConstructor[shape._type];
     return {
       shape,
@@ -1746,6 +2048,9 @@ var TextRef = class extends TypedRef {
 var TreeRef = class extends TypedRef {
   absorbPlainValues() {
   }
+  toJSON() {
+    return this.container.toJSON();
+  }
   createNode(parent, index) {
     this.assertMutable();
     return this.container.createNode(parent, index);
@@ -1778,6 +2083,9 @@ var containerConstructor = {
   text: LoroText2,
   tree: LoroTree
 };
+function hasContainerConstructor(type) {
+  return type in containerConstructor;
+}
 function unwrapReadonlyPrimitive(ref, shape) {
   if (shape._type === "counter") {
     return ref.value;
@@ -1917,7 +2225,13 @@ var DocRef = class extends TypedRef {
     this.createLazyProperties();
   }
   getTypedRefParams(key, shape) {
-    const getter = this._doc[containerGetter[shape._type]].bind(this._doc);
+    if (shape._type === "any") {
+      throw new Error(
+        `Cannot get typed ref params for "any" shape type. The "any" shape is an escape hatch for untyped containers and should be accessed directly via loroDoc.`
+      );
+    }
+    const getterName = containerGetter[shape._type];
+    const getter = this._doc[getterName].bind(this._doc);
     return {
       shape,
       placeholder: this.requiredPlaceholder[key],
@@ -1972,6 +2286,9 @@ function validateValue(value, schema, path = "") {
     throw new Error(`Invalid schema at path ${path}: missing _type`);
   }
   const currentPath = path || "root";
+  if (schema._type === "any") {
+    return value;
+  }
   if (schema._type === "text") {
     if (typeof value !== "string") {
       throw new Error(
@@ -2039,6 +2356,9 @@ function validateValue(value, schema, path = "") {
   if (schema._type === "value") {
     const valueSchema = schema;
     switch (valueSchema.valueType) {
+      // AnyValueShape - no validation, accept anything
+      case "any":
+        return value;
       case "string": {
         if (typeof value !== "string") {
           throw new Error(
@@ -2352,85 +2672,19 @@ function createTypedDoc(shape, existingDoc) {
   internal.proxy = proxy;
   return proxy;
 }
-
-// src/typed-presence.ts
-var TypedPresence = class {
-  constructor(shape, presence) {
-    this.shape = shape;
-    this.presence = presence;
-    this.placeholder = deriveShapePlaceholder(shape);
-  }
-  placeholder;
-  /**
-   * Get the current peer's presence state with placeholder values merged in.
-   */
-  get self() {
-    return mergeValue(
-      this.shape,
-      this.presence.self,
-      this.placeholder
-    );
-  }
-  /**
-   * Get other peers' presence states with placeholder values merged in.
-   * Does NOT include self. Use this for iterating over remote peers.
-   */
-  get peers() {
-    const result = /* @__PURE__ */ new Map();
-    for (const [peerId, value] of this.presence.peers) {
-      result.set(
-        peerId,
-        mergeValue(this.shape, value, this.placeholder)
-      );
-    }
-    return result;
-  }
-  /**
-   * Get all peers' presence states with placeholder values merged in.
-   * @deprecated Use `peers` and `self` separately. This property is synthesized
-   * from `peers` and `self` for backward compatibility.
-   */
-  get all() {
-    const result = {};
-    const all = this.presence.all;
-    for (const peerId of Object.keys(all)) {
-      result[peerId] = mergeValue(
-        this.shape,
-        all[peerId],
-        this.placeholder
-      );
-    }
-    return result;
-  }
-  /**
-   * Set presence values for the current peer.
-   */
-  set(value) {
-    this.presence.set(value);
-  }
-  /**
-   * Subscribe to presence changes.
-   * The callback is called immediately with the current state, then on each change.
-   *
-   * @param cb Callback that receives the typed presence state
-   * @returns Unsubscribe function
-   */
-  subscribe(cb) {
-    cb({ self: this.self, peers: this.peers, all: this.all });
-    return this.presence.subscribe(() => {
-      cb({ self: this.self, peers: this.peers, all: this.all });
-    });
-  }
-};
 export {
   Shape,
-  TypedPresence,
   change,
+  compileToJsonPath,
+  createPathBuilder,
   createPlaceholderProxy,
   createTypedDoc,
   derivePlaceholder,
   deriveShapePlaceholder,
+  evaluatePath,
+  evaluatePathOnValue,
   getLoroDoc,
+  hasWildcard,
   mergeValue,
   overlayPlaceholder,
   validatePlaceholder