@loro-extended/change 1.0.1 → 2.0.0

package/dist/index.d.ts

@@ -61,6 +61,11 @@ declare abstract class TypedRef<Shape extends DocShape | ContainerShape> {
     protected _cachedContainer?: ShapeToContainer<Shape>;
     constructor(_params: TypedRefParams<Shape>);
     abstract absorbPlainValues(): void;
+    /**
+     * Serializes the ref to a plain JSON-compatible value.
+     * Returns the plain type inferred from the shape.
+     */
+    abstract toJSON(): Infer<Shape>;
     protected get shape(): Shape;
     protected get placeholder(): Infer<Shape> | undefined;
     protected get readonly(): boolean;
@@ -121,7 +126,7 @@ declare abstract class ListRefBase<NestedShape extends ContainerOrValueShape, It
     push(item: Item): void;
     pushContainer(container: Container): Container;
     insertContainer(index: number, container: Container): Container;
-    get(index: number): MutableItem;
+    get(index: number): MutableItem | undefined;
     toArray(): Item[];
     toJSON(): Item[];
     [Symbol.iterator](): IterableIterator<MutableItem>;
@@ -131,13 +136,13 @@ declare abstract class ListRefBase<NestedShape extends ContainerOrValueShape, It
 }
 
 declare class ListRef<NestedShape extends ContainerOrValueShape> extends ListRefBase<NestedShape> {
-    [index: number]: Infer<NestedShape>;
+    [index: number]: InferMutableType<NestedShape> | undefined;
     protected get container(): LoroList;
     protected absorbValueAtIndex(index: number, value: any): void;
 }
 
 declare class MovableListRef<NestedShape extends ContainerOrValueShape, Item = NestedShape["_plain"]> extends ListRefBase<NestedShape> {
-    [index: number]: Infer<NestedShape>;
+    [index: number]: InferMutableType<NestedShape> | undefined;
     protected get container(): LoroMovableList;
     protected absorbValueAtIndex(index: number, value: any): void;
     move(from: number, to: number): void;
@@ -145,7 +150,7 @@ declare class MovableListRef<NestedShape extends ContainerOrValueShape, Item = N
 }
 
 declare class RecordRef<NestedShape extends ContainerOrValueShape> extends TypedRef<any> {
-    [key: string]: Infer<NestedShape> | any;
+    [key: string]: InferMutableType<NestedShape> | undefined | any;
     private refCache;
     protected get shape(): RecordContainerShape<NestedShape>;
     protected get container(): LoroMap;
@@ -162,7 +167,7 @@ declare class RecordRef<NestedShape extends ContainerOrValueShape> extends Typed
      * This is the method used for write operations.
      */
     getOrCreateRef(key: string): any;
-    get(key: string): InferMutableType<NestedShape>;
+    get(key: string): InferMutableType<NestedShape> | undefined;
     set(key: string, value: any): void;
     setContainer<C extends Container>(key: string, container: C): C;
     delete(key: string): void;
@@ -229,6 +234,13 @@ declare class TextRef extends TypedRef<TextContainerShape> {
 type WithPlaceholder<S extends Shape<any, any, any>> = S & {
     placeholder(value: S["_placeholder"]): S;
 };
+/**
+ * Type for value shapes that support the .nullable() method.
+ * Returns a union of null and the original shape with null as the default placeholder.
+ */
+type WithNullable<S extends ValueShape> = {
+    nullable(): WithPlaceholder<UnionValueShape<[NullValueShape, S]>>;
+};
 interface DocShape<NestedShapes extends Record<string, ContainerShape> = Record<string, ContainerShape>> extends Shape<{
     [K in keyof NestedShapes]: NestedShapes[K]["_plain"];
 }, {
@@ -280,7 +292,22 @@ interface RecordContainerShape<NestedShape extends ContainerOrValueShape = Conta
     readonly _type: "record";
     readonly shape: NestedShape;
 }
-type ContainerShape = CounterContainerShape | ListContainerShape | MovableListContainerShape | RecordContainerShape | StructContainerShape | TextContainerShape | TreeContainerShape;
+/**
+ * Container escape hatch - represents "any LoroContainer".
+ * 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
+ * })
+ * ```
+ */
+interface AnyContainerShape extends Shape<unknown, unknown, undefined> {
+    readonly _type: "any";
+}
+type ContainerShape = AnyContainerShape | CounterContainerShape | ListContainerShape | MovableListContainerShape | RecordContainerShape | StructContainerShape | TextContainerShape | TreeContainerShape;
 type ContainerType = ContainerShape["_type"];
 interface StringValueShape<T extends string = string> extends Shape<T, T, T> {
     readonly _type: "value";
@@ -361,7 +388,22 @@ interface DiscriminatedUnionValueShape<K extends string = string, T extends Reco
     readonly discriminantKey: K;
     readonly variants: T;
 }
-type ValueShape = StringValueShape | NumberValueShape | BooleanValueShape | NullValueShape | UndefinedValueShape | Uint8ArrayValueShape | StructValueShape | RecordValueShape | ArrayValueShape | UnionValueShape | DiscriminatedUnionValueShape;
+/**
+ * Value escape hatch - represents "any Loro Value".
+ * Use this when you need to accept any valid Loro value type.
+ *
+ * @example
+ * ```typescript
+ * const FlexiblePresenceShape = Shape.plain.struct({
+ *   cursor: Shape.plain.any(), // accept any value type
+ * })
+ * ```
+ */
+interface AnyValueShape extends Shape<Value, Value, undefined> {
+    readonly _type: "value";
+    readonly valueType: "any";
+}
+type ValueShape = AnyValueShape | StringValueShape | NumberValueShape | BooleanValueShape | NullValueShape | UndefinedValueShape | Uint8ArrayValueShape | StructValueShape | RecordValueShape | ArrayValueShape | UnionValueShape | DiscriminatedUnionValueShape;
 type ContainerOrValueShape = ContainerShape | ValueShape;
 interface Shape<Plain, Mutable, Placeholder = Plain> {
     readonly _type: string;
@@ -378,6 +420,22 @@ interface Shape<Plain, Mutable, Placeholder = Plain> {
  */
 declare const Shape: {
     doc: <T extends Record<string, ContainerShape>>(shape: T) => DocShape<T>;
+    /**
+     * 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: () => AnyContainerShape;
     counter: () => WithPlaceholder<CounterContainerShape>;
     list: <T extends ContainerOrValueShape>(shape: T) => ListContainerShape<T>;
     /**
@@ -404,12 +462,37 @@ declare const Shape: {
     text: () => WithPlaceholder<TextContainerShape>;
     tree: <T extends MapContainerShape | StructContainerShape>(shape: T) => TreeContainerShape;
     plain: {
-        string: <T extends string = string>(...options: T[]) => WithPlaceholder<StringValueShape<T>>;
-        number: () => WithPlaceholder<NumberValueShape>;
-        boolean: () => WithPlaceholder<BooleanValueShape>;
+        string: <T extends string = string>(...options: T[]) => WithPlaceholder<StringValueShape<T>> & WithNullable<StringValueShape<T>>;
+        number: () => WithPlaceholder<NumberValueShape> & WithNullable<NumberValueShape>;
+        boolean: () => WithPlaceholder<BooleanValueShape> & WithNullable<BooleanValueShape>;
         null: () => NullValueShape;
         undefined: () => UndefinedValueShape;
-        uint8Array: () => Uint8ArrayValueShape;
+        uint8Array: () => Uint8ArrayValueShape & WithNullable<Uint8ArrayValueShape>;
+        /**
+         * 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: () => Uint8ArrayValueShape & WithNullable<Uint8ArrayValueShape>;
+        /**
+         * 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: () => AnyValueShape;
         /**
          * Creates a struct value shape for plain objects with fixed keys.
          * This is the preferred way to define fixed-key plain value objects.
@@ -422,13 +505,13 @@ declare const Shape: {
          * })
          * ```
          */
-        struct: <T extends Record<string, ValueShape>>(shape: T) => StructValueShape<T>;
+        struct: <T extends Record<string, ValueShape>>(shape: T) => StructValueShape<T> & WithNullable<StructValueShape<T>>;
         /**
          * @deprecated Use `Shape.plain.struct` instead. `Shape.plain.struct` will be removed in a future version.
          */
-        object: <T extends Record<string, ValueShape>>(shape: T) => StructValueShape<T>;
-        record: <T extends ValueShape>(shape: T) => RecordValueShape<T>;
-        array: <T extends ValueShape>(shape: T) => ArrayValueShape<T>;
+        object: <T extends Record<string, ValueShape>>(shape: T) => StructValueShape<T> & WithNullable<StructValueShape<T>>;
+        record: <T extends ValueShape>(shape: T) => RecordValueShape<T> & WithNullable<RecordValueShape<T>>;
+        array: <T extends ValueShape>(shape: T) => ArrayValueShape<T> & WithNullable<ArrayValueShape<T>>;
         union: <T extends ValueShape[]>(shapes: T) => WithPlaceholder<UnionValueShape<T>>;
         /**
          * Creates a discriminated union shape for type-safe tagged unions.
@@ -712,103 +795,125 @@ declare function overlayPlaceholder<Shape extends DocShape>(shape: Shape, crdtVa
  */
 declare function mergeValue<Shape extends ContainerShape | ValueShape>(shape: Shape, crdtValue: Value, placeholderValue: Value): Value;
 
+type PathSegment = {
+    type: "property";
+    key: string;
+} | {
+    type: "each";
+} | {
+    type: "index";
+    index: number;
+} | {
+    type: "key";
+    key: string;
+};
+interface PathSelector<T> {
+    readonly __resultType: T;
+    readonly __segments: PathSegment[];
+}
+interface ListPathNode<Item extends ContainerOrValueShape, InArray extends boolean> extends PathSelector<WrapType<Infer<Item>[], InArray>> {
+    /** Select all items (wildcard) - sets InArray to true for children */
+    readonly $each: PathNode<Item, true>;
+    /** Select item at specific index (supports negative indices: -1 = last, -2 = second-to-last, etc.) */
+    $at(index: number): PathNode<Item, InArray>;
+    /** Select first item (alias for $at(0)) */
+    readonly $first: PathNode<Item, InArray>;
+    /** Select last item (alias for $at(-1)) */
+    readonly $last: PathNode<Item, InArray>;
+}
+type StructPathNode<Shapes extends Record<string, ContainerOrValueShape>, InArray extends boolean> = PathSelector<WrapType<{
+    [K in keyof Shapes]: Infer<Shapes[K]>;
+}, InArray>> & {
+    readonly [K in keyof Shapes]: PathNode<Shapes[K], InArray>;
+};
+interface RecordPathNode<Item extends ContainerOrValueShape, InArray extends boolean> extends PathSelector<WrapType<Record<string, Infer<Item>>, InArray>> {
+    /** Select all values (wildcard) - sets InArray to true for children */
+    readonly $each: PathNode<Item, true>;
+    /** Select value at specific key */
+    $key(key: string): PathNode<Item, InArray>;
+}
+type TextPathNode<InArray extends boolean> = PathSelector<WrapType<string, InArray>>;
+type CounterPathNode<InArray extends boolean> = PathSelector<WrapType<number, InArray>>;
+type TerminalPathNode<T, InArray extends boolean> = PathSelector<WrapType<T, InArray>>;
+type WrapType<T, InArray extends boolean> = InArray extends true ? T[] : T;
+type PathNode<S extends ContainerOrValueShape, InArray extends boolean> = S extends ListContainerShape<infer Item> ? ListPathNode<Item, InArray> : S extends MovableListContainerShape<infer Item> ? ListPathNode<Item, InArray> : S extends StructContainerShape<infer Shapes> ? StructPathNode<Shapes, InArray> : S extends RecordContainerShape<infer Item> ? RecordPathNode<Item, InArray> : S extends TextContainerShape ? TextPathNode<InArray> : S extends CounterContainerShape ? CounterPathNode<InArray> : S extends ValueShape ? TerminalPathNode<Infer<S>, InArray> : never;
+type PathBuilder<D extends DocShape> = {
+    readonly [K in keyof D["shapes"]]: PathNode<D["shapes"][K], false>;
+};
+
 /**
- * Creates a proxy around a placeholder value (plain object/array) that mimics
- * the behavior of TypedRef, specifically adding a .toJSON() method.
+ * Creates a path builder for a given document shape.
  *
- * This ensures consistent UX where users can call .toJSON() on document state
- * regardless of whether it's loading (placeholder) or loaded (live ref).
+ * The path builder provides a type-safe DSL for selecting paths within
+ * a document. The resulting PathSelector can be compiled to a JSONPath
+ * string for use with subscribeJsonpath.
+ *
+ * @example
+ * ```typescript
+ * const docShape = Shape.doc({
+ *   books: Shape.list(Shape.struct({
+ *     title: Shape.text(),
+ *     price: Shape.plain.number(),
+ *   })),
+ * })
+ *
+ * const builder = createPathBuilder(docShape)
+ * const selector = builder.books.$each.title
+ * // selector.__segments = [
+ * //   { type: "property", key: "books" },
+ * //   { type: "each" },
+ * //   { type: "property", key: "title" }
+ * // ]
+ * ```
  */
-declare function createPlaceholderProxy<T extends object>(target: T): T;
+declare function createPathBuilder<D extends DocShape>(docShape: D): PathBuilder<D>;
 
 /**
- * A record of string keys to Loro values, used for presence data.
+ * Compiles path segments to a JSONPath string.
+ *
+ * @example
+ * ```typescript
+ * const segments = [
+ *   { type: "property", key: "books" },
+ *   { type: "each" },
+ *   { type: "property", key: "title" }
+ * ]
+ * compileToJsonPath(segments) // => '$.books[*].title'
+ * ```
  */
-type ObjectValue = Record<string, Value>;
+declare function compileToJsonPath(segments: PathSegment[]): string;
 /**
- * Interface for presence management that can be implemented by different backends.
- * This abstraction allows TypedPresence to work with any presence provider.
+ * Check if the path contains any wildcard segments.
+ * Paths with wildcards need deep equality checking for change detection.
  */
-interface PresenceInterface {
-    /**
-     * Set multiple presence values at once.
-     */
-    set: (values: ObjectValue) => void;
-    /**
-     * Get a single presence value by key.
-     */
-    get: (key: string) => Value;
-    /**
-     * The current peer's presence state.
-     */
-    readonly self: ObjectValue;
-    /**
-     * Other peers' presence states, keyed by peer ID.
-     * Does NOT include self. Use this for iterating over remote peers.
-     */
-    readonly peers: Map<string, ObjectValue>;
-    /**
-     * All peers' presence states, keyed by peer ID (includes self).
-     * @deprecated Use `peers` and `self` separately. This property is synthesized
-     * from `peers` and `self` for backward compatibility.
-     */
-    readonly all: Record<string, ObjectValue>;
-    /**
-     * Set a single raw value by key (escape hatch for arbitrary keys).
-     */
-    setRaw: (key: string, value: Value) => void;
-    /**
-     * Subscribe to presence changes.
-     * @param cb Callback that receives the aggregated presence values
-     * @returns Unsubscribe function
-     */
-    subscribe: (cb: (values: ObjectValue) => void) => () => void;
-}
+declare function hasWildcard(segments: PathSegment[]): boolean;
 
 /**
- * A strongly-typed wrapper around a PresenceInterface.
- * Provides type-safe access to presence data with automatic placeholder merging.
+ * Evaluate a path selector against a TypedDoc to get the current value.
+ * Returns the value(s) at the path, properly typed.
  *
- * @typeParam S - The shape of the presence data
+ * @example
+ * ```typescript
+ * const selector = builder.books.$each.title
+ * const titles = evaluatePath(doc, selector)
+ * // titles: string[]
+ * ```
  */
-declare class TypedPresence<S extends ContainerShape | ValueShape> {
-    shape: S;
-    private presence;
-    private placeholder;
-    constructor(shape: S, presence: PresenceInterface);
-    /**
-     * Get the current peer's presence state with placeholder values merged in.
-     */
-    get self(): Infer<S>;
-    /**
-     * Get other peers' presence states with placeholder values merged in.
-     * Does NOT include self. Use this for iterating over remote peers.
-     */
-    get peers(): Map<string, Infer<S>>;
-    /**
-     * 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(): Record<string, Infer<S>>;
-    /**
-     * Set presence values for the current peer.
-     */
-    set(value: Partial<Infer<S>>): void;
-    /**
-     * 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: (state: {
-        self: Infer<S>;
-        peers: Map<string, Infer<S>>;
-        /** @deprecated Use `peers` and `self` separately */
-        all: Record<string, Infer<S>>;
-    }) => void): () => void;
-}
+declare function evaluatePath<D extends DocShape, T>(doc: TypedDoc<D>, selector: PathSelector<T>): T;
+/**
+ * Evaluate path segments against a plain JavaScript value.
+ * This is the core recursive evaluation logic.
+ */
+declare function evaluatePathOnValue(value: unknown, segments: PathSegment[]): unknown;
+
+/**
+ * Creates a proxy around a placeholder value (plain object/array) that mimics
+ * the behavior of TypedRef, specifically adding a .toJSON() method.
+ *
+ * This ensures consistent UX where users can call .toJSON() on document state
+ * regardless of whether it's loading (placeholder) or loaded (live ref).
+ */
+declare function createPlaceholderProxy<T extends object>(target: T): T;
 
 /**
  * Validates placeholder against schema structure without using Zod
@@ -816,4 +921,4 @@ declare class TypedPresence<S extends ContainerShape | ValueShape> {
  */
 declare function validatePlaceholder<T extends DocShape>(placeholder: unknown, schema: T): Infer<T>;
 
-export { type ArrayValueShape, type ContainerOrValueShape, type ContainerShape, type CounterContainerShape, type DiscriminatedUnionValueShape, type DocShape, type Infer, type InferMutableType, type InferPlaceholderType, type ListContainerShape, type MapContainerShape, type MovableListContainerShape, type Mutable, type ObjectValue, type ObjectValueShape, type PresenceInterface, type RecordContainerShape, type RecordValueShape, type ContainerType as RootContainerType, Shape, type StructContainerShape, type StructValueShape, type TextContainerShape, type TreeContainerShape, type TypedDoc, TypedPresence, type UnionValueShape, type ValueShape, type WithPlaceholder, change, createPlaceholderProxy, createTypedDoc, derivePlaceholder, deriveShapePlaceholder, getLoroDoc, mergeValue, overlayPlaceholder, validatePlaceholder };
+export { type AnyContainerShape, type AnyValueShape, type ArrayValueShape, type ContainerOrValueShape, type ContainerShape, type CounterContainerShape, type DiscriminatedUnionValueShape, type DocShape, type Infer, type InferMutableType, type InferPlaceholderType, type ListContainerShape, type MapContainerShape, type MovableListContainerShape, type Mutable, type ObjectValueShape, type PathBuilder, type PathNode, type PathSegment, type PathSelector, type RecordContainerShape, type RecordValueShape, type ContainerType as RootContainerType, Shape, type StructContainerShape, type StructValueShape, type TextContainerShape, type TreeContainerShape, type TypedDoc, type UnionValueShape, type ValueShape, type WithNullable, type WithPlaceholder, change, compileToJsonPath, createPathBuilder, createPlaceholderProxy, createTypedDoc, derivePlaceholder, deriveShapePlaceholder, evaluatePath, evaluatePathOnValue, getLoroDoc, hasWildcard, mergeValue, overlayPlaceholder, validatePlaceholder };