@loro-extended/change 0.9.1 → 1.0.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { LoroList, LoroMovableList, Container, LoroMap, Value, LoroText, LoroCounter, LoroTree, LoroDoc } from 'loro-crdt';
+import { LoroDoc, LoroCounter, LoroList, LoroMovableList, Container, LoroMap, Value, LoroText, LoroTree } from 'loro-crdt';
 
 /**
  * Infers the plain (JSON-serializable) type from any Shape.
@@ -9,7 +9,7 @@ import { LoroList, LoroMovableList, Container, LoroMap, Value, LoroText, LoroCou
  * @example
  * ```typescript
  * const ChatSchema = Shape.doc({
- *   messages: Shape.list(Shape.map({
+ *   messages: Shape.list(Shape.struct({
  *     id: Shape.plain.string(),
  *     content: Shape.text(),
  *   })),
@@ -19,9 +19,9 @@ import { LoroList, LoroMovableList, Container, LoroMap, Value, LoroText, LoroCou
  * type ChatDoc = Infer<typeof ChatSchema>
  * // Result: { messages: { id: string; content: string }[] }
  *
- * const PresenceSchema = Shape.plain.object({
+ * const PresenceSchema = Shape.plain.struct({
  *   name: Shape.plain.string(),
- *   cursor: Shape.plain.object({ x: Shape.plain.number(), y: Shape.plain.number() }),
+ *   cursor: Shape.plain.struct({ x: Shape.plain.number(), y: Shape.plain.number() }),
  * })
  *
  * // Extract the presence type
@@ -35,10 +35,6 @@ type Infer<T> = T extends Shape<infer P, any, any> ? P : never;
  * This is the type used within change() callbacks for mutation.
  */
 type InferMutableType<T> = T extends Shape<any, infer M, any> ? M : never;
-/**
- * @deprecated Use InferMutableType<T> instead
- */
-type InferDraftType<T> = InferMutableType<T>;
 /**
  * Extracts the valid placeholder type from a shape.
  *
@@ -47,53 +43,18 @@ type InferDraftType<T> = InferMutableType<T>;
  */
 type InferPlaceholderType<T> = T extends Shape<any, any, infer P> ? P : never;
 /**
- * Mutable type for use within change() callbacks.
+ * Mutable type for use within change() callbacks and direct mutations on doc.value.
  * This is the type-safe wrapper around CRDT containers that allows mutation.
  */
 type Mutable<T extends DocShape<Record<string, ContainerShape>>> = InferMutableType<T>;
-/**
- * @deprecated Use Mutable<T> instead
- */
-type Draft<T extends DocShape<Record<string, ContainerShape>>> = Mutable<T>;
-/**
- * Interface for objects that have a toJSON method.
- * This is separate from the data type to avoid polluting Object.values().
- */
-interface HasToJSON<T> {
-    toJSON(): T;
-}
-/**
- * Deep readonly wrapper for plain objects (no index signature).
- * Includes toJSON() method.
- */
-type DeepReadonlyObject<T extends object> = {
-    readonly [P in keyof T]: DeepReadonly<T[P]>;
-} & HasToJSON<T>;
-/**
- * Deep readonly wrapper for Record types (with string index signature).
- * The toJSON() method is available but NOT part of the index signature,
- * so Object.values() returns clean types.
- */
-type DeepReadonlyRecord<T> = {
-    readonly [K in keyof T]: DeepReadonly<T[K]>;
-} & HasToJSON<Record<string, T[keyof T]>>;
-/**
- * Deep readonly wrapper that makes all properties readonly recursively
- * and adds a toJSON() method for JSON serialization.
- *
- * For arrays: Returns ReadonlyArray with toJSON()
- * For objects with string index signature (Records): toJSON() is available
- *   but doesn't pollute Object.values() type inference
- * For plain objects: Returns readonly properties with toJSON()
- * For primitives: Returns as-is
- */
-type DeepReadonly<T> = T extends any[] ? ReadonlyArray<DeepReadonly<T[number]>> & HasToJSON<T> : T extends object ? string extends keyof T ? DeepReadonlyRecord<T> : DeepReadonlyObject<T> : T;
 
 type TypedRefParams<Shape extends DocShape | ContainerShape> = {
     shape: Shape;
     placeholder?: Infer<Shape>;
     getContainer: () => ShapeToContainer<Shape>;
     readonly?: boolean;
+    autoCommit?: boolean;
+    getDoc?: () => LoroDoc;
 };
 declare abstract class TypedRef<Shape extends DocShape | ContainerShape> {
     protected _params: TypedRefParams<Shape>;
@@ -103,20 +64,37 @@ declare abstract class TypedRef<Shape extends DocShape | ContainerShape> {
     protected get shape(): Shape;
     protected get placeholder(): Infer<Shape> | undefined;
     protected get readonly(): boolean;
+    protected get autoCommit(): boolean;
+    protected get doc(): LoroDoc | undefined;
+    /**
+     * Commits changes if autoCommit is enabled.
+     * Call this after any mutation operation.
+     */
+    protected commitIfAuto(): void;
     /**
      * Throws an error if this ref is in readonly mode.
      * Call this at the start of any mutating method.
+     * @deprecated Mutations are always allowed now; this will be removed.
      */
     protected assertMutable(): void;
     protected get container(): ShapeToContainer<Shape>;
 }
 
 declare class CounterRef extends TypedRef<CounterContainerShape> {
+    private _materialized;
+    protected get container(): LoroCounter;
     absorbPlainValues(): void;
-    increment(value: number): void;
-    decrement(value: number): void;
+    increment(value?: number): void;
+    decrement(value?: number): void;
+    /**
+     * Returns the counter value.
+     * If the counter hasn't been materialized (no operations performed),
+     * returns the placeholder value if available.
+     */
     get value(): number;
+    valueOf(): number;
     toJSON(): number;
+    [Symbol.toPrimitive](hint: string): number | string;
 }
 
 declare abstract class ListRefBase<NestedShape extends ContainerOrValueShape, Item = NestedShape["_plain"], MutableItem = NestedShape["_mutable"]> extends TypedRef<any> {
@@ -158,26 +136,6 @@ declare class ListRef<NestedShape extends ContainerOrValueShape> extends ListRef
     protected absorbValueAtIndex(index: number, value: any): void;
 }
 
-declare class MapRef<NestedShapes extends Record<string, ContainerOrValueShape>> extends TypedRef<any> {
-    private propertyCache;
-    constructor(params: TypedRefParams<MapContainerShape<NestedShapes>>);
-    protected get shape(): MapContainerShape<NestedShapes>;
-    protected get container(): LoroMap;
-    absorbPlainValues(): void;
-    getTypedRefParams<S extends ContainerShape>(key: string, shape: S): TypedRefParams<ContainerShape>;
-    getOrCreateRef<Shape extends ContainerShape | ValueShape>(key: string, shape: Shape): any;
-    private createLazyProperties;
-    toJSON(): any;
-    get(key: string): any;
-    set(key: string, value: Value): void;
-    setContainer<C extends Container>(key: string, container: C): C;
-    delete(key: string): void;
-    has(key: string): boolean;
-    keys(): string[];
-    values(): any[];
-    get size(): number;
-}
-
 declare class MovableListRef<NestedShape extends ContainerOrValueShape, Item = NestedShape["_plain"]> extends ListRefBase<NestedShape> {
     [index: number]: Infer<NestedShape>;
     protected get container(): LoroMovableList;
@@ -193,6 +151,16 @@ declare class RecordRef<NestedShape extends ContainerOrValueShape> extends Typed
     protected get container(): LoroMap;
     absorbPlainValues(): void;
     getTypedRefParams<S extends ContainerShape>(key: string, shape: S): TypedRefParams<ContainerShape>;
+    /**
+     * Gets an existing ref for a key, or returns undefined if the key doesn't exist.
+     * Used for reading operations where we want optional chaining to work.
+     */
+    getRef(key: string): any;
+    /**
+     * Gets or creates a ref for a key.
+     * Always creates the container if it doesn't exist.
+     * This is the method used for write operations.
+     */
     getOrCreateRef(key: string): any;
     get(key: string): InferMutableType<NestedShape>;
     set(key: string, value: any): void;
@@ -202,15 +170,48 @@ declare class RecordRef<NestedShape extends ContainerOrValueShape> extends Typed
     keys(): string[];
     values(): any[];
     get size(): number;
-    toJSON(): Record<string, any>;
+    toJSON(): Record<string, Infer<NestedShape>>;
+}
+
+/**
+ * Typed ref for struct containers (objects with fixed keys).
+ * Uses LoroMap as the underlying container.
+ */
+declare class StructRef<NestedShapes extends Record<string, ContainerOrValueShape>> extends TypedRef<any> {
+    private propertyCache;
+    constructor(params: TypedRefParams<StructContainerShape<NestedShapes>>);
+    protected get shape(): StructContainerShape<NestedShapes>;
+    protected get container(): LoroMap;
+    absorbPlainValues(): void;
+    getTypedRefParams<S extends ContainerShape>(key: string, shape: S): TypedRefParams<ContainerShape>;
+    getOrCreateRef<Shape extends ContainerShape | ValueShape>(key: string, shape: Shape): any;
+    private createLazyProperties;
+    toJSON(): Infer<StructContainerShape<NestedShapes>>;
+    get(key: string): any;
+    set(key: string, value: Value): void;
+    setContainer<C extends Container>(key: string, container: C): C;
+    delete(key: string): void;
+    has(key: string): boolean;
+    keys(): string[];
+    values(): any[];
+    get size(): number;
 }
 
 declare class TextRef extends TypedRef<TextContainerShape> {
+    private _materialized;
+    protected get container(): LoroText;
     absorbPlainValues(): void;
     insert(index: number, content: string): void;
     delete(index: number, len: number): void;
+    /**
+     * Returns the text content.
+     * If the text hasn't been materialized (no operations performed),
+     * returns the placeholder value if available.
+     */
     toString(): string;
+    valueOf(): string;
     toJSON(): string;
+    [Symbol.toPrimitive](_hint: string): string;
     update(text: string): void;
     mark(range: {
         start: number;
@@ -256,21 +257,30 @@ interface MovableListContainerShape<NestedShape extends ContainerOrValueShape =
     readonly _type: "movableList";
     readonly shape: NestedShape;
 }
-interface MapContainerShape<NestedShapes extends Record<string, ContainerOrValueShape> = Record<string, ContainerOrValueShape>> extends Shape<{
+/**
+ * @deprecated Use StructContainerShape instead. MapContainerShape is an alias for backward compatibility.
+ */
+type MapContainerShape<NestedShapes extends Record<string, ContainerOrValueShape> = Record<string, ContainerOrValueShape>> = StructContainerShape<NestedShapes>;
+/**
+ * Container shape for objects with fixed keys (structs).
+ * This is the preferred way to define fixed-key objects.
+ * Uses LoroMap as the underlying container.
+ */
+interface StructContainerShape<NestedShapes extends Record<string, ContainerOrValueShape> = Record<string, ContainerOrValueShape>> extends Shape<{
     [K in keyof NestedShapes]: NestedShapes[K]["_plain"];
-}, MapRef<NestedShapes> & {
+}, StructRef<NestedShapes> & {
     [K in keyof NestedShapes]: NestedShapes[K]["_mutable"];
 }, {
     [K in keyof NestedShapes]: NestedShapes[K]["_placeholder"];
 }> {
-    readonly _type: "map";
+    readonly _type: "struct";
     readonly shapes: NestedShapes;
 }
 interface RecordContainerShape<NestedShape extends ContainerOrValueShape = ContainerOrValueShape> extends Shape<Record<string, NestedShape["_plain"]>, RecordRef<NestedShape>, Record<string, never>> {
     readonly _type: "record";
     readonly shape: NestedShape;
 }
-type ContainerShape = CounterContainerShape | ListContainerShape | MapContainerShape | MovableListContainerShape | RecordContainerShape | TextContainerShape | TreeContainerShape;
+type ContainerShape = 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";
@@ -297,7 +307,16 @@ interface Uint8ArrayValueShape extends Shape<Uint8Array, Uint8Array, Uint8Array>
     readonly _type: "value";
     readonly valueType: "uint8array";
 }
-interface ObjectValueShape<T extends Record<string, ValueShape> = Record<string, ValueShape>> extends Shape<{
+/**
+ * @deprecated Use StructValueShape instead. ObjectValueShape is an alias for backward compatibility.
+ */
+type ObjectValueShape<T extends Record<string, ValueShape> = Record<string, ValueShape>> = StructValueShape<T>;
+/**
+ * Value shape for objects with fixed keys (structs).
+ * This is the preferred way to define fixed-key plain value objects.
+ * Identical structure to ObjectValueShape but with valueType: "struct".
+ */
+interface StructValueShape<T extends Record<string, ValueShape> = Record<string, ValueShape>> extends Shape<{
     [K in keyof T]: T[K]["_plain"];
 }, {
     [K in keyof T]: T[K]["_mutable"];
@@ -305,7 +324,7 @@ interface ObjectValueShape<T extends Record<string, ValueShape> = Record<string,
     [K in keyof T]: T[K]["_placeholder"];
 }> {
     readonly _type: "value";
-    readonly valueType: "object";
+    readonly valueType: "struct";
     readonly shape: T;
 }
 interface RecordValueShape<T extends ValueShape = ValueShape> extends Shape<Record<string, T["_plain"]>, Record<string, T["_mutable"]>, Record<string, never>> {
@@ -336,13 +355,13 @@ interface UnionValueShape<T extends ValueShape[] = ValueShape[]> extends Shape<T
  * @typeParam K - The discriminant key (e.g., "type")
  * @typeParam T - A record mapping discriminant values to their object shapes
  */
-interface DiscriminatedUnionValueShape<K extends string = string, T extends Record<string, ObjectValueShape> = Record<string, ObjectValueShape>, Plain = T[keyof T]["_plain"], Mutable = T[keyof T]["_mutable"], Placeholder = T[keyof T]["_placeholder"]> extends Shape<Plain, Mutable, Placeholder> {
+interface DiscriminatedUnionValueShape<K extends string = string, T extends Record<string, StructValueShape> = Record<string, StructValueShape>, Plain = T[keyof T]["_plain"], Mutable = T[keyof T]["_mutable"], Placeholder = T[keyof T]["_placeholder"]> extends Shape<Plain, Mutable, Placeholder> {
     readonly _type: "value";
     readonly valueType: "discriminatedUnion";
     readonly discriminantKey: K;
     readonly variants: T;
 }
-type ValueShape = StringValueShape | NumberValueShape | BooleanValueShape | NullValueShape | UndefinedValueShape | Uint8ArrayValueShape | ObjectValueShape | RecordValueShape | ArrayValueShape | UnionValueShape | DiscriminatedUnionValueShape;
+type ValueShape = StringValueShape | NumberValueShape | BooleanValueShape | NullValueShape | UndefinedValueShape | Uint8ArrayValueShape | StructValueShape | RecordValueShape | ArrayValueShape | UnionValueShape | DiscriminatedUnionValueShape;
 type ContainerOrValueShape = ContainerShape | ValueShape;
 interface Shape<Plain, Mutable, Placeholder = Plain> {
     readonly _type: string;
@@ -361,11 +380,29 @@ declare const Shape: {
     doc: <T extends Record<string, ContainerShape>>(shape: T) => DocShape<T>;
     counter: () => WithPlaceholder<CounterContainerShape>;
     list: <T extends ContainerOrValueShape>(shape: T) => ListContainerShape<T>;
-    map: <T extends Record<string, ContainerOrValueShape>>(shape: T) => MapContainerShape<T>;
+    /**
+     * Creates a struct container shape for objects with fixed keys.
+     * This is the preferred way to define fixed-key objects.
+     *
+     * @example
+     * ```typescript
+     * const UserSchema = Shape.doc({
+     *   user: Shape.struct({
+     *     name: Shape.text(),
+     *     age: Shape.counter(),
+     *   }),
+     * })
+     * ```
+     */
+    struct: <T extends Record<string, ContainerOrValueShape>>(shape: T) => StructContainerShape<T>;
+    /**
+     * @deprecated Use `Shape.struct` instead. `Shape.struct` will be removed in a future version.
+     */
+    map: <T extends Record<string, ContainerOrValueShape>>(shape: T) => StructContainerShape<T>;
     record: <T extends ContainerOrValueShape>(shape: T) => RecordContainerShape<T>;
     movableList: <T extends ContainerOrValueShape>(shape: T) => MovableListContainerShape<T>;
     text: () => WithPlaceholder<TextContainerShape>;
-    tree: <T extends MapContainerShape>(shape: T) => TreeContainerShape;
+    tree: <T extends MapContainerShape | StructContainerShape>(shape: T) => TreeContainerShape;
     plain: {
         string: <T extends string = string>(...options: T[]) => WithPlaceholder<StringValueShape<T>>;
         number: () => WithPlaceholder<NumberValueShape>;
@@ -373,7 +410,23 @@ declare const Shape: {
         null: () => NullValueShape;
         undefined: () => UndefinedValueShape;
         uint8Array: () => Uint8ArrayValueShape;
-        object: <T extends Record<string, ValueShape>>(shape: T) => ObjectValueShape<T>;
+        /**
+         * Creates a struct value shape for plain objects with fixed keys.
+         * This is the preferred way to define fixed-key plain value objects.
+         *
+         * @example
+         * ```typescript
+         * const PointSchema = Shape.plain.struct({
+         *   x: Shape.plain.number(),
+         *   y: Shape.plain.number(),
+         * })
+         * ```
+         */
+        struct: <T extends Record<string, ValueShape>>(shape: T) => 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>;
         union: <T extends ValueShape[]>(shapes: T) => WithPlaceholder<UnionValueShape<T>>;
@@ -382,15 +435,15 @@ declare const Shape: {
          *
          * @example
          * ```typescript
-         * const ClientPresenceShape = Shape.plain.object({
+         * const ClientPresenceShape = Shape.plain.struct({
          *   type: Shape.plain.string("client"),
          *   name: Shape.plain.string(),
-         *   input: Shape.plain.object({ force: Shape.plain.number(), angle: Shape.plain.number() }),
+         *   input: Shape.plain.struct({ force: Shape.plain.number(), angle: Shape.plain.number() }),
          * })
          *
-         * const ServerPresenceShape = Shape.plain.object({
+         * const ServerPresenceShape = Shape.plain.struct({
          *   type: Shape.plain.string("server"),
-         *   cars: Shape.plain.record(Shape.plain.object({ x: Shape.plain.number(), y: Shape.plain.number() })),
+         *   cars: Shape.plain.record(Shape.plain.struct({ x: Shape.plain.number(), y: Shape.plain.number() })),
          *   tick: Shape.plain.number(),
          * })
          *
@@ -403,10 +456,10 @@ declare const Shape: {
          * @param discriminantKey - The key used to discriminate between variants (e.g., "type")
          * @param variants - A record mapping discriminant values to their object shapes
          */
-        discriminatedUnion: <K extends string, T extends Record<string, ObjectValueShape>>(discriminantKey: K, variants: T) => WithPlaceholder<DiscriminatedUnionValueShape<K, T>>;
+        discriminatedUnion: <K extends string, T extends Record<string, StructValueShape>>(discriminantKey: K, variants: T) => WithPlaceholder<DiscriminatedUnionValueShape<K, T>>;
     };
 };
-type ShapeToContainer<T extends DocShape | ContainerShape> = T extends TextContainerShape ? LoroText : T extends CounterContainerShape ? LoroCounter : T extends ListContainerShape ? LoroList : T extends MovableListContainerShape ? LoroMovableList : T extends MapContainerShape | RecordContainerShape ? LoroMap : T extends TreeContainerShape ? LoroTree : never;
+type ShapeToContainer<T extends DocShape | ContainerShape> = T extends TextContainerShape ? LoroText : T extends CounterContainerShape ? LoroCounter : T extends ListContainerShape ? LoroList : T extends MovableListContainerShape ? LoroMovableList : T extends StructContainerShape | RecordContainerShape ? LoroMap : T extends TreeContainerShape ? LoroTree : never;
 
 /**
  * Derives the placeholder state from a schema by composing placeholder values.
@@ -423,6 +476,227 @@ declare function derivePlaceholder<T extends DocShape>(schema: T): InferPlacehol
  */
 declare function deriveShapePlaceholder(shape: ContainerOrValueShape): unknown;
 
+/** biome-ignore-all lint/suspicious/noExplicitAny: JSON Patch values can be any type */
+
+type JsonPatchAddOperation = {
+    op: "add";
+    path: string | (string | number)[];
+    value: any;
+};
+type JsonPatchRemoveOperation = {
+    op: "remove";
+    path: string | (string | number)[];
+};
+type JsonPatchReplaceOperation = {
+    op: "replace";
+    path: string | (string | number)[];
+    value: any;
+};
+type JsonPatchMoveOperation = {
+    op: "move";
+    path: string | (string | number)[];
+    from: string | (string | number)[];
+};
+type JsonPatchCopyOperation = {
+    op: "copy";
+    path: string | (string | number)[];
+    from: string | (string | number)[];
+};
+type JsonPatchTestOperation = {
+    op: "test";
+    path: string | (string | number)[];
+    value: any;
+};
+type JsonPatchOperation = JsonPatchAddOperation | JsonPatchRemoveOperation | JsonPatchReplaceOperation | JsonPatchMoveOperation | JsonPatchCopyOperation | JsonPatchTestOperation;
+type JsonPatch = JsonPatchOperation[];
+
+/** biome-ignore-all lint/suspicious/noExplicitAny: fix later */
+
+/**
+ * Meta-operations namespace for TypedDoc.
+ * Access via doc.$ to perform batch operations, serialization, etc.
+ */
+declare class TypedDocMeta<Shape extends DocShape> {
+    private internal;
+    constructor(internal: TypedDocInternal<Shape>);
+    /**
+     * The primary method of mutating typed documents.
+     * Batches multiple mutations into a single transaction.
+     * All changes commit together at the end.
+     *
+     * Use this for:
+     * - Find-and-mutate operations (required due to JS limitations)
+     * - Performance (fewer commits)
+     * - Atomic undo (all changes = one undo step)
+     *
+     * Returns the doc for chaining.
+     */
+    change(fn: (draft: Mutable<Shape>) => void): TypedDoc<Shape>;
+    /**
+     * Returns the full plain JavaScript object representation of the document.
+     * This is an expensive O(N) operation that serializes the entire document.
+     */
+    toJSON(): Infer<Shape>;
+    /**
+     * Apply JSON Patch operations to the document
+     *
+     * @param patch - Array of JSON Patch operations (RFC 6902)
+     * @param pathPrefix - Optional path prefix for scoped operations
+     * @returns Updated document value
+     */
+    applyPatch(patch: JsonPatch, pathPrefix?: (string | number)[]): TypedDoc<Shape>;
+    /**
+     * Access the underlying LoroDoc for advanced operations.
+     */
+    get loroDoc(): LoroDoc;
+    /**
+     * Access the document schema shape.
+     */
+    get docShape(): Shape;
+    /**
+     * Get raw CRDT value without placeholder overlay.
+     */
+    get rawValue(): any;
+}
+/**
+ * Internal TypedDoc implementation (not directly exposed to users).
+ * Users interact with the proxied version that provides direct schema access.
+ */
+declare class TypedDocInternal<Shape extends DocShape> {
+    private shape;
+    private placeholder;
+    private doc;
+    private _valueRef;
+    proxy: TypedDoc<Shape> | null;
+    constructor(shape: Shape, doc?: LoroDoc);
+    get value(): Mutable<Shape>;
+    toJSON(): Infer<Shape>;
+    change(fn: (draft: Mutable<Shape>) => void): void;
+    applyPatch(patch: JsonPatch, pathPrefix?: (string | number)[]): void;
+    get loroDoc(): LoroDoc;
+    get docShape(): Shape;
+    get rawValue(): any;
+}
+/**
+ * The proxied TypedDoc type that provides direct schema access.
+ * Schema properties are accessed directly on the doc object.
+ * Meta-operations are available via the $ namespace.
+ *
+ * @example
+ * ```typescript
+ * const doc = createTypedDoc(schema);
+ *
+ * // Direct schema access
+ * doc.count.increment(5);
+ * doc.title.insert(0, "Hello");
+ *
+ * // Serialize to JSON (works on doc and all refs)
+ * const snapshot = doc.toJSON();
+ * const users = doc.users.toJSON();
+ *
+ * // Meta-operations via $ (escape hatch)
+ * doc.$.change(draft => { ... });
+ * doc.$.loroDoc;
+ * ```
+ */
+type TypedDoc<Shape extends DocShape> = Mutable<Shape> & {
+    /**
+     * Meta-operations namespace.
+     * Use for change(), loroDoc, etc.
+     */
+    $: TypedDocMeta<Shape>;
+    /**
+     * Returns the full plain JavaScript object representation of the document.
+     * This is an O(N) operation that serializes the entire document.
+     *
+     * @example
+     * ```typescript
+     * const snapshot = doc.toJSON();
+     * console.log(snapshot.count); // number
+     * ```
+     */
+    toJSON(): Infer<Shape>;
+};
+/**
+ * Creates a new TypedDoc with the given schema.
+ * Returns a proxied document where schema properties are accessed directly.
+ *
+ * @param shape - The document schema (with optional .placeholder() values)
+ * @param existingDoc - Optional existing LoroDoc to wrap
+ * @returns A proxied TypedDoc with direct schema access and $ namespace
+ *
+ * @example
+ * ```typescript
+ * const schema = Shape.doc({
+ *   title: Shape.text(),
+ *   count: Shape.counter(),
+ * });
+ *
+ * const doc = createTypedDoc(schema);
+ *
+ * // Direct mutations (auto-commit)
+ * doc.count.increment(5);
+ * doc.title.insert(0, "Hello");
+ *
+ * // Batched mutations are committed together via `change`
+ * doc.$.change(draft => {
+ *   draft.count.increment(10);
+ *   draft.title.update("World");
+ * });
+ *
+ * // Get plain JSON
+ * const snapshot = doc.toJSON();
+ * ```
+ */
+declare function createTypedDoc<Shape extends DocShape>(shape: Shape, existingDoc?: LoroDoc): TypedDoc<Shape>;
+
+/**
+ * The primary method of mutating typed documents.
+ * Batches multiple mutations into a single transaction.
+ * All changes commit together at the end.
+ *
+ * Use this for:
+ * - Find-and-mutate operations (required due to JS limitations)
+ * - Performance (fewer commits)
+ * - Atomic undo (all changes = one undo step)
+ *
+ * Returns the doc for chaining.
+ *
+ * @param doc - The TypedDoc to mutate
+ * @param fn - Function that performs mutations on the draft
+ * @returns The same TypedDoc for chaining
+ *
+ * @example
+ * ```typescript
+ * import { change } from "@loro-extended/change"
+ *
+ * // Chainable API
+ * change(doc, draft => {
+ *   draft.count.increment(10)
+ *   draft.title.update("Hello")
+ * })
+ *   .count.increment(5)  // Optional: continue mutating
+ *   .toJSON()            // Optional: get last item snapshot when needed
+ * ```
+ */
+declare function change<Shape extends DocShape>(doc: TypedDoc<Shape>, fn: (draft: Mutable<Shape>) => void): TypedDoc<Shape>;
+/**
+ * Access the underlying LoroDoc for advanced operations.
+ *
+ * @param doc - The TypedDoc to unwrap
+ * @returns The underlying LoroDoc instance
+ *
+ * @example
+ * ```typescript
+ * import { getLoroDoc } from "@loro-extended/change"
+ *
+ * const loroDoc = getLoroDoc(doc)
+ * const version = loroDoc.version()
+ * loroDoc.subscribe(() => console.log("changed"))
+ * ```
+ */
+declare function getLoroDoc<Shape extends DocShape>(doc: TypedDoc<Shape>): LoroDoc;
+
 /**
  * Overlays CRDT state with placeholder defaults
  */
@@ -491,88 +765,6 @@ interface PresenceInterface {
     subscribe: (cb: (values: ObjectValue) => void) => () => void;
 }
 
-/** biome-ignore-all lint/suspicious/noExplicitAny: JSON Patch values can be any type */
-
-type JsonPatchAddOperation = {
-    op: "add";
-    path: string | (string | number)[];
-    value: any;
-};
-type JsonPatchRemoveOperation = {
-    op: "remove";
-    path: string | (string | number)[];
-};
-type JsonPatchReplaceOperation = {
-    op: "replace";
-    path: string | (string | number)[];
-    value: any;
-};
-type JsonPatchMoveOperation = {
-    op: "move";
-    path: string | (string | number)[];
-    from: string | (string | number)[];
-};
-type JsonPatchCopyOperation = {
-    op: "copy";
-    path: string | (string | number)[];
-    from: string | (string | number)[];
-};
-type JsonPatchTestOperation = {
-    op: "test";
-    path: string | (string | number)[];
-    value: any;
-};
-type JsonPatchOperation = JsonPatchAddOperation | JsonPatchRemoveOperation | JsonPatchReplaceOperation | JsonPatchMoveOperation | JsonPatchCopyOperation | JsonPatchTestOperation;
-type JsonPatch = JsonPatchOperation[];
-
-/** biome-ignore-all lint/suspicious/noExplicitAny: fix later */
-
-declare class TypedDoc<Shape extends DocShape> {
-    private shape;
-    private placeholder;
-    private doc;
-    /**
-     * Creates a new TypedDoc with the given schema.
-     * Placeholder state is automatically derived from the schema's placeholder values.
-     *
-     * @param shape - The document schema (with optional .placeholder() values)
-     * @param doc - Optional existing LoroDoc to wrap
-     */
-    constructor(shape: Shape, doc?: LoroDoc);
-    /**
-     * Returns a read-only, live view of the document.
-     * Accessing properties on this object will read directly from the underlying CRDT.
-     * This is efficient (O(1) per access) and always up-to-date.
-     */
-    get value(): DeepReadonly<Infer<Shape>>;
-    /**
-     * Returns the full plain JavaScript object representation of the document.
-     * This is an expensive O(N) operation that serializes the entire document.
-     */
-    toJSON(): Infer<Shape>;
-    change(fn: (draft: Draft<Shape>) => void): Infer<Shape>;
-    /**
-     * Apply JSON Patch operations to the document
-     *
-     * @param patch - Array of JSON Patch operations (RFC 6902)
-     * @param pathPrefix - Optional path prefix for scoped operations
-     * @returns Updated document value
-     *
-     * @example
-     * ```typescript
-     * const result = typedDoc.applyPatch([
-     *   { op: 'add', path: '/users/0/name', value: 'Alice' },
-     *   { op: 'replace', path: '/settings/theme', value: 'dark' }
-     * ])
-     * ```
-     */
-    applyPatch(patch: JsonPatch, pathPrefix?: (string | number)[]): Infer<Shape>;
-    get loroDoc(): LoroDoc;
-    get docShape(): Shape;
-    get rawValue(): any;
-}
-declare function createTypedDoc<Shape extends DocShape>(shape: Shape, existingDoc?: LoroDoc): TypedDoc<Shape>;
-
 /**
  * A strongly-typed wrapper around a PresenceInterface.
  * Provides type-safe access to presence data with automatic placeholder merging.
@@ -624,4 +816,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 DeepReadonly, type DiscriminatedUnionValueShape, type DocShape, type Draft, type Infer, type InferDraftType, 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 TextContainerShape, type TreeContainerShape, TypedDoc, TypedPresence, type UnionValueShape, type ValueShape, type WithPlaceholder, createPlaceholderProxy, createTypedDoc, derivePlaceholder, deriveShapePlaceholder, mergeValue, overlayPlaceholder, validatePlaceholder };
+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 };