@loro-extended/change 1.0.1 → 2.0.0

package/src/shape.ts

@@ -7,6 +7,7 @@ import type {
   LoroMovableList,
   LoroText,
   LoroTree,
+  Value,
 } from "loro-crdt"
 
 import type { CounterRef } from "./typed-refs/counter.js"
@@ -28,6 +29,14 @@ export 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.
+ */
+export type WithNullable<S extends ValueShape> = {
+  nullable(): WithPlaceholder<UnionValueShape<[NullValueShape, S]>>
+}
+
 export interface DocShape<
   NestedShapes extends Record<string, ContainerShape> = Record<
     string,
@@ -120,7 +129,24 @@ export interface RecordContainerShape<
   readonly shape: NestedShape
 }
 
+/**
+ * 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
+ * })
+ * ```
+ */
+export interface AnyContainerShape extends Shape<unknown, unknown, undefined> {
+  readonly _type: "any"
+}
+
 export type ContainerShape =
+  | AnyContainerShape
   | CounterContainerShape
   | ListContainerShape
   | MovableListContainerShape
@@ -242,8 +268,25 @@ export interface DiscriminatedUnionValueShape<
   readonly variants: T
 }
 
+/**
+ * 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
+ * })
+ * ```
+ */
+export interface AnyValueShape extends Shape<Value, Value, undefined> {
+  readonly _type: "value"
+  readonly valueType: "any"
+}
+
 // Union of all ValueShapes - these can only contain other ValueShapes, not ContainerShapes
 export type ValueShape =
+  | AnyValueShape
   | StringValueShape
   | NumberValueShape
   | BooleanValueShape
@@ -258,6 +301,41 @@ export type ValueShape =
 
 export type ContainerOrValueShape = ContainerShape | ValueShape
 
+/**
+ * Creates a nullable version of a value shape.
+ * @internal
+ */
+function makeNullable<S extends ValueShape>(
+  shape: S,
+): WithPlaceholder<UnionValueShape<[NullValueShape, S]>> {
+  const nullShape: NullValueShape = {
+    _type: "value" as const,
+    valueType: "null" as const,
+    _plain: null,
+    _mutable: null,
+    _placeholder: null,
+  }
+
+  const base: UnionValueShape<[NullValueShape, S]> = {
+    _type: "value" as const,
+    valueType: "union" as const,
+    shapes: [nullShape, shape] as [NullValueShape, S],
+    _plain: null as any,
+    _mutable: null as any,
+    _placeholder: null as any, // Default placeholder is null
+  }
+
+  return Object.assign(base, {
+    placeholder(
+      value: S["_placeholder"] | null,
+    ): UnionValueShape<[NullValueShape, S]> {
+      return { ...base, _placeholder: value } as UnionValueShape<
+        [NullValueShape, S]
+      >
+    },
+  })
+}
+
 /**
  * The LoroShape factory object
  *
@@ -274,6 +352,28 @@ export const Shape = {
     _placeholder: {} as any,
   }),
 
+  /**
+   * 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 => ({
+    _type: "any" as const,
+    _plain: undefined as unknown,
+    _mutable: undefined as unknown,
+    _placeholder: undefined,
+  }),
+
   // CRDTs are represented by Loro Containers--they converge on state using Loro's
   // various CRDT algorithms
   counter: (): WithPlaceholder<CounterContainerShape> => {
@@ -386,7 +486,8 @@ export const Shape = {
   plain: {
     string: <T extends string = string>(
       ...options: T[]
-    ): WithPlaceholder<StringValueShape<T>> => {
+    ): WithPlaceholder<StringValueShape<T>> &
+      WithNullable<StringValueShape<T>> => {
       const base: StringValueShape<T> = {
         _type: "value" as const,
         valueType: "string" as const,
@@ -399,10 +500,16 @@ export const Shape = {
         placeholder(value: T): StringValueShape<T> {
           return { ...base, _placeholder: value }
         },
+        nullable(): WithPlaceholder<
+          UnionValueShape<[NullValueShape, StringValueShape<T>]>
+        > {
+          return makeNullable(base)
+        },
       })
     },
 
-    number: (): WithPlaceholder<NumberValueShape> => {
+    number: (): WithPlaceholder<NumberValueShape> &
+      WithNullable<NumberValueShape> => {
       const base: NumberValueShape = {
         _type: "value" as const,
         valueType: "number" as const,
@@ -414,10 +521,16 @@ export const Shape = {
         placeholder(value: number): NumberValueShape {
           return { ...base, _placeholder: value }
         },
+        nullable(): WithPlaceholder<
+          UnionValueShape<[NullValueShape, NumberValueShape]>
+        > {
+          return makeNullable(base)
+        },
       })
     },
 
-    boolean: (): WithPlaceholder<BooleanValueShape> => {
+    boolean: (): WithPlaceholder<BooleanValueShape> &
+      WithNullable<BooleanValueShape> => {
       const base: BooleanValueShape = {
         _type: "value" as const,
         valueType: "boolean" as const,
@@ -429,6 +542,11 @@ export const Shape = {
         placeholder(value: boolean): BooleanValueShape {
           return { ...base, _placeholder: value }
         },
+        nullable(): WithPlaceholder<
+          UnionValueShape<[NullValueShape, BooleanValueShape]>
+        > {
+          return makeNullable(base)
+        },
       })
     },
 
@@ -448,12 +566,70 @@ export const Shape = {
       _placeholder: undefined,
     }),
 
-    uint8Array: (): Uint8ArrayValueShape => ({
+    uint8Array: (): Uint8ArrayValueShape &
+      WithNullable<Uint8ArrayValueShape> => {
+      const base: Uint8ArrayValueShape = {
+        _type: "value" as const,
+        valueType: "uint8array" as const,
+        _plain: new Uint8Array(),
+        _mutable: new Uint8Array(),
+        _placeholder: new Uint8Array(),
+      }
+      return Object.assign(base, {
+        nullable(): WithPlaceholder<
+          UnionValueShape<[NullValueShape, Uint8ArrayValueShape]>
+        > {
+          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: (): Uint8ArrayValueShape & WithNullable<Uint8ArrayValueShape> => {
+      const base: Uint8ArrayValueShape = {
+        _type: "value" as const,
+        valueType: "uint8array" as const,
+        _plain: new Uint8Array(),
+        _mutable: new Uint8Array(),
+        _placeholder: new Uint8Array(),
+      }
+      return Object.assign(base, {
+        nullable(): WithPlaceholder<
+          UnionValueShape<[NullValueShape, Uint8ArrayValueShape]>
+        > {
+          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: (): AnyValueShape => ({
       _type: "value" as const,
-      valueType: "uint8array" as const,
-      _plain: new Uint8Array(),
-      _mutable: new Uint8Array(),
-      _placeholder: new Uint8Array(),
+      valueType: "any" as const,
+      _plain: undefined as unknown as Value,
+      _mutable: undefined as unknown as Value,
+      _placeholder: undefined,
     }),
 
     /**
@@ -470,46 +646,86 @@ export const Shape = {
      */
     struct: <T extends Record<string, ValueShape>>(
       shape: T,
-    ): StructValueShape<T> => ({
-      _type: "value" as const,
-      valueType: "struct" as const,
-      shape,
-      _plain: {} as any,
-      _mutable: {} as any,
-      _placeholder: {} as any,
-    }),
+    ): StructValueShape<T> & WithNullable<StructValueShape<T>> => {
+      const base: StructValueShape<T> = {
+        _type: "value" as const,
+        valueType: "struct" as const,
+        shape,
+        _plain: {} as any,
+        _mutable: {} as any,
+        _placeholder: {} as any,
+      }
+      return Object.assign(base, {
+        nullable(): WithPlaceholder<
+          UnionValueShape<[NullValueShape, StructValueShape<T>]>
+        > {
+          return makeNullable(base)
+        },
+      })
+    },
 
     /**
      * @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> => ({
-      _type: "value" as const,
-      valueType: "struct" as const,
-      shape,
-      _plain: {} as any,
-      _mutable: {} as any,
-      _placeholder: {} as any,
-    }),
+    ): StructValueShape<T> & WithNullable<StructValueShape<T>> => {
+      const base: StructValueShape<T> = {
+        _type: "value" as const,
+        valueType: "struct" as const,
+        shape,
+        _plain: {} as any,
+        _mutable: {} as any,
+        _placeholder: {} as any,
+      }
+      return Object.assign(base, {
+        nullable(): WithPlaceholder<
+          UnionValueShape<[NullValueShape, StructValueShape<T>]>
+        > {
+          return makeNullable(base)
+        },
+      })
+    },
 
-    record: <T extends ValueShape>(shape: T): RecordValueShape<T> => ({
-      _type: "value" as const,
-      valueType: "record" as const,
-      shape,
-      _plain: {} as any,
-      _mutable: {} as any,
-      _placeholder: {} as Record<string, never>,
-    }),
+    record: <T extends ValueShape>(
+      shape: T,
+    ): RecordValueShape<T> & WithNullable<RecordValueShape<T>> => {
+      const base: RecordValueShape<T> = {
+        _type: "value" as const,
+        valueType: "record" as const,
+        shape,
+        _plain: {} as any,
+        _mutable: {} as any,
+        _placeholder: {} as Record<string, never>,
+      }
+      return Object.assign(base, {
+        nullable(): WithPlaceholder<
+          UnionValueShape<[NullValueShape, RecordValueShape<T>]>
+        > {
+          return makeNullable(base)
+        },
+      })
+    },
 
-    array: <T extends ValueShape>(shape: T): ArrayValueShape<T> => ({
-      _type: "value" as const,
-      valueType: "array" as const,
-      shape,
-      _plain: [] as any,
-      _mutable: [] as any,
-      _placeholder: [] as never[],
-    }),
+    array: <T extends ValueShape>(
+      shape: T,
+    ): ArrayValueShape<T> & WithNullable<ArrayValueShape<T>> => {
+      const base: ArrayValueShape<T> = {
+        _type: "value" as const,
+        valueType: "array" as const,
+        shape,
+        _plain: [] as any,
+        _mutable: [] as any,
+        _placeholder: [] as never[],
+      }
+      return Object.assign(base, {
+        nullable(): WithPlaceholder<
+          UnionValueShape<[NullValueShape, ArrayValueShape<T>]>
+        > {
+          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?

package/src/typed-refs/base.ts

@@ -19,6 +19,12 @@ export abstract class TypedRef<Shape extends DocShape | ContainerShape> {
 
   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 {
     return this._params.shape
   }

package/src/typed-refs/counter.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest"
+import { change } from "../functional-helpers.js"
 import { Shape } from "../shape.js"
 import { createTypedDoc } from "../typed-doc.js"
 
@@ -57,7 +58,7 @@ describe("Counter Ref", () => {
     })
     const doc = createTypedDoc(schema)
 
-    doc.$.change(draft => {
+    change(doc, draft => {
       draft.counter.increment(5)
     })
 

package/src/typed-refs/doc.ts

@@ -16,7 +16,9 @@ const containerGetter = {
   struct: "getMap", // Structs use LoroMap as their underlying container
   text: "getText",
   tree: "getTree",
-} as const
+} as const satisfies Record<string, keyof LoroDoc>
+
+type ContainerGetterKey = keyof typeof containerGetter
 
 // Doc Ref class -- the actual object passed to the change `mutation` function
 export class DocRef<Shape extends DocShape> extends TypedRef<Shape> {
@@ -47,7 +49,16 @@ export class DocRef<Shape extends DocShape> extends TypedRef<Shape> {
     key: string,
     shape: S,
   ): TypedRefParams<ContainerShape> {
-    const getter = this._doc[containerGetter[shape._type]].bind(this._doc)
+    // Handle "any" shape type - it's an escape hatch that doesn't have a specific getter
+    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 as ContainerGetterKey]
+    const getter = this._doc[getterName].bind(this._doc)
 
     return {
       shape,

package/src/typed-refs/json-compatibility.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, it, vi } from "vitest"
 import { change } from "../functional-helpers.js"
 import { Shape } from "../shape.js"
 import { createTypedDoc } from "../typed-doc.js"
+import type { Mutable } from "../types.js"
 
 const MessageSchema = Shape.struct({
   id: Shape.plain.string(),
@@ -257,4 +258,30 @@ describe("JSON Compatibility", () => {
       expect(root.messages[0].content.toJSON()).toBe("A")
     })
   })
+
+  it("should expose toJSON() in Mutable type signature", () => {
+    const doc = createTypedDoc(ChatSchema)
+
+    // This test verifies that TypeScript sees toJSON() on Mutable types
+    // If this compiles, the type fix is working correctly
+    change(doc, (root: Mutable<typeof ChatSchema>) => {
+      root.meta.title = "Type Test"
+      root.messages.push({ id: "1", content: "Hello", timestamp: 123 })
+
+      // These should all compile without errors - toJSON() is visible on the type
+      const metaJson: { title: string; count: number } = root.meta.toJSON()
+      const messagesJson: Array<{
+        id: string
+        content: string
+        timestamp: number
+      }> = root.messages.toJSON()
+      const countJson: number = root.meta.count.toJSON()
+
+      expect(metaJson).toEqual({ title: "Type Test", count: 0 })
+      expect(messagesJson).toEqual([
+        { id: "1", content: "Hello", timestamp: 123 },
+      ])
+      expect(countJson).toBe(0)
+    })
+  })
 })

package/src/typed-refs/list-base.ts

@@ -336,7 +336,7 @@ export abstract class ListRefBase<
     return result
   }
 
-  get(index: number): MutableItem {
+  get(index: number): MutableItem | undefined {
     return this.getMutableItem(index)
   }
 

package/src/typed-refs/list.test.ts

@@ -19,7 +19,7 @@ describe("ListRef", () => {
         draft.users.push({ name: "Alice" })
 
         // Update via index
-        draft.users[0] = { name: "Bob" }
+        ;(draft.users as any)[0] = { name: "Bob" }
       })
 
       expect(doc.toJSON().users[0]).toEqual({ name: "Bob" })

package/src/typed-refs/list.ts

@@ -1,13 +1,16 @@
 import type { LoroList } from "loro-crdt"
 import type { ContainerOrValueShape } from "../shape.js"
-import type { Infer } from "../types.js"
+import type { InferMutableType } from "../types.js"
 import { ListRefBase } from "./list-base.js"
 
 // List typed ref
 export class ListRef<
   NestedShape extends ContainerOrValueShape,
 > extends ListRefBase<NestedShape> {
-  [index: number]: Infer<NestedShape>
+  // Returns the mutable type which has toJSON() and other ref methods.
+  // For assignment, the proxy handler accepts plain values and converts them.
+  // TypeScript may require type assertions for plain value assignments.
+  [index: number]: InferMutableType<NestedShape> | undefined
 
   protected get container(): LoroList {
     return super.container as LoroList

package/src/typed-refs/movable-list.test.ts

@@ -19,7 +19,7 @@ describe("MovableListRef", () => {
         draft.users.push({ name: "Alice" })
 
         // Update via index
-        draft.users[0] = { name: "Bob" }
+        ;(draft.users as any)[0] = { name: "Bob" }
       })
 
       expect(doc.toJSON().users[0]).toEqual({ name: "Bob" })

package/src/typed-refs/movable-list.ts

@@ -1,6 +1,6 @@
 import type { Container, LoroMovableList } from "loro-crdt"
 import type { ContainerOrValueShape } from "../shape.js"
-import type { Infer } from "../types.js"
+import type { InferMutableType } from "../types.js"
 import { ListRefBase } from "./list-base.js"
 
 // Movable list typed ref
@@ -8,7 +8,7 @@ export class MovableListRef<
   NestedShape extends ContainerOrValueShape,
   Item = NestedShape["_plain"],
 > extends ListRefBase<NestedShape> {
-  [index: number]: Infer<NestedShape>
+  [index: number]: InferMutableType<NestedShape> | undefined
 
   protected get container(): LoroMovableList {
     return super.container as LoroMovableList

package/src/typed-refs/record.ts

@@ -14,6 +14,7 @@ import {
   assignPlainValueToTypedRef,
   containerConstructor,
   createContainerTypedRef,
+  hasContainerConstructor,
   serializeRefToJSON,
   unwrapReadonlyPrimitive,
 } from "./utils.js"
@@ -22,7 +23,7 @@ import {
 export class RecordRef<
   NestedShape extends ContainerOrValueShape,
 > extends TypedRef<any> {
-  [key: string]: Infer<NestedShape> | any
+  [key: string]: InferMutableType<NestedShape> | undefined | any
   private refCache = new Map<string, TypedRef<ContainerShape> | Value>()
 
   protected get shape(): RecordContainerShape<NestedShape> {
@@ -51,6 +52,14 @@ export class RecordRef<
       placeholder = deriveShapePlaceholder(shape)
     }
 
+    // AnyContainerShape is an escape hatch - it doesn't have a constructor
+    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 {
@@ -129,7 +138,7 @@ export class RecordRef<
     return ref as any
   }
 
-  get(key: string): InferMutableType<NestedShape> {
+  get(key: string): InferMutableType<NestedShape> | undefined {
     return this.getRef(key)
   }
 

package/src/typed-refs/struct.ts

@@ -14,6 +14,7 @@ import {
   assignPlainValueToTypedRef,
   containerConstructor,
   createContainerTypedRef,
+  hasContainerConstructor,
   serializeRefToJSON,
   unwrapReadonlyPrimitive,
 } from "./utils.js"
@@ -50,6 +51,14 @@ export class StructRef<
   ): TypedRefParams<ContainerShape> {
     const placeholder = (this.placeholder as any)?.[key]
 
+    // AnyContainerShape is an escape hatch - it doesn't have a constructor
+    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 {

package/src/typed-refs/tree.ts

@@ -1,4 +1,5 @@
 import type { TreeContainerShape } from "../shape.js"
+import type { Infer } from "../types.js"
 import { TypedRef } from "./base.js"
 
 // Tree typed ref
@@ -7,6 +8,11 @@ export class TreeRef<T extends TreeContainerShape> extends TypedRef<T> {
     // TODO(duane): implement for trees
   }
 
+  toJSON(): Infer<T> {
+    // TODO(duane): implement proper tree serialization
+    return this.container.toJSON() as Infer<T>
+  }
+
   createNode(parent?: any, index?: number): any {
     this.assertMutable()
     return this.container.createNode(parent, index)

package/src/typed-refs/utils.ts

@@ -34,6 +34,9 @@ import { TreeRef } from "./tree.js"
 /**
  * Mapping from container shape types to their Loro constructor classes.
  * Used when creating new containers via getOrCreateContainer().
+ *
+ * Note: "any" is not included because AnyContainerShape is an escape hatch
+ * that doesn't create typed refs - it returns raw Loro containers.
  */
 export const containerConstructor = {
   counter: LoroCounter,
@@ -45,6 +48,16 @@ export const containerConstructor = {
   tree: LoroTree,
 } as const
 
+/**
+ * Type guard to check if a container shape type has a constructor.
+ * Returns false for "any" which is an escape hatch.
+ */
+export function hasContainerConstructor(
+  type: string,
+): type is keyof typeof containerConstructor {
+  return type in containerConstructor
+}
+
 /**
  * Unwraps a TypedRef to its primitive value for readonly access.
  * Counter refs return their numeric value, Text refs return their string.