@loro-extended/change 0.8.1 → 0.9.0

package/src/{draft-nodes → typed-refs}/proxy-handlers.ts

@@ -1,8 +1,8 @@
-import type { ListDraftNode } from "./list.js"
-import type { MovableListDraftNode } from "./movable-list.js"
-import type { RecordDraftNode } from "./record.js"
+import type { ListRef } from "./list.js"
+import type { MovableListRef } from "./movable-list.js"
+import type { RecordRef } from "./record.js"
 
-export const recordProxyHandler: ProxyHandler<RecordDraftNode<any>> = {
+export const recordProxyHandler: ProxyHandler<RecordRef<any>> = {
   get: (target, prop) => {
     if (typeof prop === "string" && !(prop in target)) {
       return target.get(prop)
@@ -38,7 +38,7 @@ export const recordProxyHandler: ProxyHandler<RecordDraftNode<any>> = {
   },
 }
 
-export const listProxyHandler: ProxyHandler<ListDraftNode<any>> = {
+export const listProxyHandler: ProxyHandler<ListRef<any>> = {
   get: (target, prop) => {
     if (typeof prop === "string") {
       const index = Number(prop)
@@ -62,26 +62,25 @@ export const listProxyHandler: ProxyHandler<ListDraftNode<any>> = {
   },
 }
 
-export const movableListProxyHandler: ProxyHandler<MovableListDraftNode<any>> =
-  {
-    get: (target, prop) => {
-      if (typeof prop === "string") {
-        const index = Number(prop)
-        if (!Number.isNaN(index)) {
-          return target.get(index)
-        }
+export const movableListProxyHandler: ProxyHandler<MovableListRef<any>> = {
+  get: (target, prop) => {
+    if (typeof prop === "string") {
+      const index = Number(prop)
+      if (!Number.isNaN(index)) {
+        return target.get(index)
       }
-      return Reflect.get(target, prop)
-    },
-    set: (target, prop, value) => {
-      if (typeof prop === "string") {
-        const index = Number(prop)
-        if (!Number.isNaN(index)) {
-          // MovableList supports set directly
-          target.set(index, value)
-          return true
-        }
+    }
+    return Reflect.get(target, prop)
+  },
+  set: (target, prop, value) => {
+    if (typeof prop === "string") {
+      const index = Number(prop)
+      if (!Number.isNaN(index)) {
+        // MovableList supports set directly
+        target.set(index, value)
+        return true
       }
-      return Reflect.set(target, prop, value)
-    },
-  }
+    }
+    return Reflect.set(target, prop, value)
+  },
+}

package/src/{draft-nodes → typed-refs}/record.test.ts

@@ -266,4 +266,73 @@ describe("Record Types", () => {
       expect(doc.toJSON().histories["user1"]).toEqual(["c"])
     })
   })
+
+  describe("Readonly access to non-existent keys", () => {
+    it("should not throw 'placeholder required' when accessing nested map values in a record", () => {
+      // This schema mirrors a real-world scenario:
+      // preferences: Record<string, { showTip: boolean }>
+      const schema = Shape.doc({
+        preferences: Shape.record(
+          Shape.map({
+            showTip: Shape.plain.boolean(),
+          }),
+        ),
+      })
+
+      const doc = new TypedDoc(schema)
+
+      // First, set a value for a specific peer
+      doc.change(d => {
+        d.preferences.peer1 = { showTip: true }
+      })
+
+      // This should work - accessing an existing key
+      expect(doc.value.preferences.peer1?.showTip).toBe(true)
+
+      // Accessing a non-existent key should NOT throw "placeholder required"
+      // It should return undefined so optional chaining works correctly
+      expect(() => {
+        const result = doc.value.preferences.nonexistent?.showTip
+        return result
+      }).not.toThrow()
+    })
+
+    it("should return undefined for non-existent record keys in readonly mode", () => {
+      const schema = Shape.doc({
+        preferences: Shape.record(
+          Shape.map({
+            showTip: Shape.plain.boolean(),
+          }),
+        ),
+      })
+
+      const doc = new TypedDoc(schema)
+
+      // Access a key that doesn't exist - should return undefined
+      const prefs = doc.value.preferences.nonexistent
+      expect(prefs).toBeUndefined()
+    })
+
+    it("should work with the exact user scenario pattern", () => {
+      // Exact reproduction of a user's schema and access pattern
+      const schema = Shape.doc({
+        preferences: Shape.record(
+          Shape.map({
+            showTip: Shape.plain.boolean(),
+          }),
+        ),
+      })
+
+      const doc = new TypedDoc(schema)
+      const myPeerId = "some-peer-id"
+
+      // This is the exact code pattern from the user's app:
+      // doc.preferences[myPeerId]?.showTip !== false
+      expect(() => {
+        const showTip = doc.value.preferences[myPeerId]?.showTip
+        const result = showTip !== false
+        return result
+      }).not.toThrow()
+    })
+  })
 })

package/src/{draft-nodes → typed-refs}/record.ts

@@ -8,6 +8,7 @@ import {
   LoroTree,
   type Value,
 } from "loro-crdt"
+import { deriveShapePlaceholder } from "../derive-placeholder.js"
 import type {
   ContainerOrValueShape,
   ContainerShape,
@@ -15,11 +16,8 @@ import type {
 } from "../shape.js"
 import type { Infer, InferDraftType } from "../types.js"
 import { isContainerShape, isValueShape } from "../utils/type-guards.js"
-import { DraftNode, type DraftNodeParams } from "./base.js"
-import {
-  assignPlainValueToDraftNode,
-  createContainerDraftNode,
-} from "./utils.js"
+import { TypedRef, type TypedRefParams } from "./base.js"
+import { assignPlainValueToTypedRef, createContainerTypedRef } from "./utils.js"
 
 const containerConstructor = {
   counter: LoroCounter,
@@ -31,12 +29,12 @@ const containerConstructor = {
   tree: LoroTree,
 } as const
 
-// Record draft node
-export class RecordDraftNode<
+// Record typed ref
+export class RecordRef<
   NestedShape extends ContainerOrValueShape,
-> extends DraftNode<any> {
+> extends TypedRef<any> {
   [key: string]: Infer<NestedShape> | any
-  private nodeCache = new Map<string, DraftNode<ContainerShape> | Value>()
+  private nodeCache = new Map<string, TypedRef<ContainerShape> | Value>()
 
   protected get shape(): RecordContainerShape<NestedShape> {
     return super.shape as RecordContainerShape<NestedShape>
@@ -48,8 +46,8 @@ export class RecordDraftNode<
 
   absorbPlainValues() {
     for (const [key, node] of this.nodeCache.entries()) {
-      if (node instanceof DraftNode) {
-        // Contains a DraftNode, not a plain Value: keep recursing
+      if (node instanceof TypedRef) {
+        // Contains a TypedRef, not a plain Value: keep recursing
         node.absorbPlainValues()
         continue
       }
@@ -59,11 +57,19 @@ export class RecordDraftNode<
     }
   }
 
-  getDraftNodeParams<S extends ContainerShape>(
+  getTypedRefParams<S extends ContainerShape>(
     key: string,
     shape: S,
-  ): DraftNodeParams<ContainerShape> {
-    const placeholder = (this.placeholder as any)?.[key]
+  ): TypedRefParams<ContainerShape> {
+    // First try to get placeholder from the Record's placeholder (if it has an entry for this key)
+    let placeholder = (this.placeholder as any)?.[key]
+
+    // If no placeholder exists for this key, derive one from the schema's shape
+    // This is critical for Records where the placeholder is always {} but nested
+    // containers need valid placeholders to fall back to for missing values
+    if (placeholder === undefined) {
+      placeholder = deriveShapePlaceholder(shape)
+    }
 
     const LoroContainer = containerConstructor[shape._type]
 
@@ -77,12 +83,22 @@ export class RecordDraftNode<
   }
 
   getOrCreateNode(key: string): any {
+    // For readonly mode with container shapes, check if the key exists first
+    // This allows optional chaining (?.) to work correctly for non-existent keys
+    // Similar to how ListRefBase.getMutableItem() handles non-existent indices
+    if (this.readonly && isContainerShape(this.shape.shape)) {
+      const existing = this.container.get(key)
+      if (existing === undefined) {
+        return undefined
+      }
+    }
+
     let node = this.nodeCache.get(key)
     if (!node) {
       const shape = this.shape.shape
       if (isContainerShape(shape)) {
-        node = createContainerDraftNode(
-          this.getDraftNodeParams(key, shape as ContainerShape),
+        node = createContainerTypedRef(
+          this.getTypedRefParams(key, shape as ContainerShape),
         )
         // Cache container nodes
         this.nodeCache.set(key, node)
@@ -127,7 +143,7 @@ export class RecordDraftNode<
   }
 
   set(key: string, value: any): void {
-    if (this.readonly) throw new Error("Cannot modify readonly doc")
+    if (this.readonly) throw new Error("Cannot modify readonly ref")
     if (isValueShape(this.shape.shape)) {
       this.container.set(key, value)
       this.nodeCache.set(key, value)
@@ -137,24 +153,24 @@ export class RecordDraftNode<
       if (value && typeof value === "object") {
         const node = this.getOrCreateNode(key)
 
-        if (assignPlainValueToDraftNode(node, value)) {
+        if (assignPlainValueToTypedRef(node, value)) {
           return
         }
       }
 
       throw new Error(
-        "Cannot set container directly, modify the draft node instead",
+        "Cannot set container directly, modify the typed ref instead",
       )
     }
   }
 
   setContainer<C extends Container>(key: string, container: C): C {
-    if (this.readonly) throw new Error("Cannot modify readonly doc")
+    if (this.readonly) throw new Error("Cannot modify readonly ref")
     return this.container.setContainer(key, container)
   }
 
   delete(key: string): void {
-    if (this.readonly) throw new Error("Cannot modify readonly doc")
+    if (this.readonly) throw new Error("Cannot modify readonly ref")
     this.container.delete(key)
     this.nodeCache.delete(key)
   }
@@ -174,4 +190,17 @@ export class RecordDraftNode<
   get size(): number {
     return this.container.size
   }
+
+  toJSON(): Record<string, any> {
+    const result: Record<string, any> = {}
+    for (const key of this.keys()) {
+      const value = this.get(key)
+      if (value && typeof value === "object" && "toJSON" in value) {
+        result[key] = (value as any).toJSON()
+      } else {
+        result[key] = value
+      }
+    }
+    return result
+  }
 }

package/src/{draft-nodes → typed-refs}/text.ts

@@ -1,18 +1,20 @@
 import type { TextContainerShape } from "../shape.js"
-import { DraftNode } from "./base.js"
+import { TypedRef } from "./base.js"
 
-// Text draft node
-export class TextDraftNode extends DraftNode<TextContainerShape> {
+// Text typed ref
+export class TextRef extends TypedRef<TextContainerShape> {
   absorbPlainValues() {
     // no plain values contained within
   }
 
   // Text methods
   insert(index: number, content: string): void {
+    if (this.readonly) throw new Error("Cannot modify readonly ref")
     this.container.insert(index, content)
   }
 
   delete(index: number, len: number): void {
+    if (this.readonly) throw new Error("Cannot modify readonly ref")
     this.container.delete(index, len)
   }
 
@@ -20,15 +22,22 @@ export class TextDraftNode extends DraftNode<TextContainerShape> {
     return this.container.toString()
   }
 
+  toJSON(): string {
+    return this.toString()
+  }
+
   update(text: string): void {
+    if (this.readonly) throw new Error("Cannot modify readonly ref")
     this.container.update(text)
   }
 
   mark(range: { start: number; end: number }, key: string, value: any): void {
+    if (this.readonly) throw new Error("Cannot modify readonly ref")
     this.container.mark(range, key, value)
   }
 
   unmark(range: { start: number; end: number }, key: string): void {
+    if (this.readonly) throw new Error("Cannot modify readonly ref")
     this.container.unmark(range, key)
   }
 
@@ -37,6 +46,7 @@ export class TextDraftNode extends DraftNode<TextContainerShape> {
   }
 
   applyDelta(delta: any[]): void {
+    if (this.readonly) throw new Error("Cannot modify readonly ref")
     this.container.applyDelta(delta)
   }
 

package/src/{draft-nodes → typed-refs}/tree.ts

@@ -1,21 +1,24 @@
 import type { TreeContainerShape } from "../shape.js"
-import { DraftNode } from "./base.js"
+import { TypedRef } from "./base.js"
 
-// Tree draft node
-export class TreeDraftNode<T extends TreeContainerShape> extends DraftNode<T> {
+// Tree typed ref
+export class TreeRef<T extends TreeContainerShape> extends TypedRef<T> {
   absorbPlainValues() {
     // TODO(duane): implement for trees
   }
 
   createNode(parent?: any, index?: number): any {
+    if (this.readonly) throw new Error("Cannot modify readonly ref")
     return this.container.createNode(parent, index)
   }
 
   move(target: any, parent?: any, index?: number): void {
+    if (this.readonly) throw new Error("Cannot modify readonly ref")
     this.container.move(target, parent, index)
   }
 
   delete(target: any): void {
+    if (this.readonly) throw new Error("Cannot modify readonly ref")
     this.container.delete(target)
   }
 

package/src/{draft-nodes → typed-refs}/utils.ts

@@ -8,57 +8,53 @@ import type {
   TextContainerShape,
   TreeContainerShape,
 } from "../shape.js"
-import type { DraftNode, DraftNodeParams } from "./base.js"
-import { CounterDraftNode } from "./counter.js"
-import { ListDraftNode } from "./list.js"
-import { MapDraftNode } from "./map.js"
-import { MovableListDraftNode } from "./movable-list.js"
+import type { TypedRef, TypedRefParams } from "./base.js"
+import { CounterRef } from "./counter.js"
+import { ListRef } from "./list.js"
+import { MapRef } from "./map.js"
+import { MovableListRef } from "./movable-list.js"
 import {
   listProxyHandler,
   movableListProxyHandler,
   recordProxyHandler,
 } from "./proxy-handlers.js"
-import { RecordDraftNode } from "./record.js"
-import { TextDraftNode } from "./text.js"
-import { TreeDraftNode } from "./tree.js"
+import { RecordRef } from "./record.js"
+import { TextRef } from "./text.js"
+import { TreeRef } from "./tree.js"
 
 // Generic catch-all overload
-export function createContainerDraftNode<T extends ContainerShape>(
-  params: DraftNodeParams<T>,
-): DraftNode<T>
+export function createContainerTypedRef<T extends ContainerShape>(
+  params: TypedRefParams<T>,
+): TypedRef<T>
 
 // Implementation
-export function createContainerDraftNode(
-  params: DraftNodeParams<ContainerShape>,
-): DraftNode<ContainerShape> {
+export function createContainerTypedRef(
+  params: TypedRefParams<ContainerShape>,
+): TypedRef<ContainerShape> {
   switch (params.shape._type) {
     case "counter":
-      return new CounterDraftNode(
-        params as DraftNodeParams<CounterContainerShape>,
-      )
+      return new CounterRef(params as TypedRefParams<CounterContainerShape>)
     case "list":
       return new Proxy(
-        new ListDraftNode(params as DraftNodeParams<ListContainerShape>),
+        new ListRef(params as TypedRefParams<ListContainerShape>),
         listProxyHandler,
       )
     case "map":
-      return new MapDraftNode(params as DraftNodeParams<MapContainerShape>)
+      return new MapRef(params as TypedRefParams<MapContainerShape>)
     case "movableList":
       return new Proxy(
-        new MovableListDraftNode(
-          params as DraftNodeParams<MovableListContainerShape>,
-        ),
+        new MovableListRef(params as TypedRefParams<MovableListContainerShape>),
         movableListProxyHandler,
       )
     case "record":
       return new Proxy(
-        new RecordDraftNode(params as DraftNodeParams<RecordContainerShape>),
+        new RecordRef(params as TypedRefParams<RecordContainerShape>),
         recordProxyHandler,
       )
     case "text":
-      return new TextDraftNode(params as DraftNodeParams<TextContainerShape>)
+      return new TextRef(params as TypedRefParams<TextContainerShape>)
     case "tree":
-      return new TreeDraftNode(params as DraftNodeParams<TreeContainerShape>)
+      return new TreeRef(params as TypedRefParams<TreeContainerShape>)
     default:
       throw new Error(
         `Unknown container type: ${(params.shape as ContainerShape)._type}`,
@@ -66,8 +62,8 @@ export function createContainerDraftNode(
   }
 }
 
-export function assignPlainValueToDraftNode(
-  node: DraftNode<any>,
+export function assignPlainValueToTypedRef(
+  node: TypedRef<any>,
   value: any,
 ): boolean {
   const shapeType = (node as any).shape._type

package/src/types.test.ts

@@ -1,7 +1,8 @@
-import { describe, expectTypeOf, it } from "vitest"
+import { describe, expect, expectTypeOf, it } from "vitest"
 import type { ContainerShape, ValueShape } from "./shape.js"
 import { Shape } from "./shape.js"
-import type { Infer } from "./types.js"
+import { createTypedDoc } from "./typed-doc.js"
+import type { DeepReadonly, Infer } from "./types.js"
 
 describe("Infer type helper", () => {
   it("infers DocShape plain type", () => {
@@ -186,3 +187,97 @@ describe("Infer type helper", () => {
     expectTypeOf<Result>().toEqualTypeOf<Expected>()
   })
 })
+
+describe("DeepReadonly type helper", () => {
+  it("Object.values returns clean types without toJSON function in union", () => {
+    const ParticipantSchema = Shape.plain.object({
+      id: Shape.plain.string(),
+      name: Shape.plain.string(),
+    })
+
+    const GroupSessionSchema = Shape.doc({
+      participants: Shape.record(ParticipantSchema),
+    })
+
+    const doc = createTypedDoc(GroupSessionSchema)
+
+    doc.change((root: any) => {
+      root.participants.set("p1", { id: "1", name: "Alice" })
+      root.participants.set("p2", { id: "2", name: "Bob" })
+    })
+
+    const participants = doc.value.participants
+
+    // Object.values should return clean types
+    const values = Object.values(participants)
+
+    type Participant = Infer<typeof ParticipantSchema>
+
+    // FIXED: Object.values now returns clean DeepReadonly<Participant>[]
+    // Previously it returned: (DeepReadonly<Participant> | (() => Record<...>))[]
+    expectTypeOf(values).toEqualTypeOf<DeepReadonly<Participant>[]>()
+
+    // Runtime check
+    expect(values).toHaveLength(2)
+    expect(values.map(p => p.name).sort()).toEqual(["Alice", "Bob"])
+  })
+
+  it("toJSON is still callable on Records", () => {
+    const ParticipantSchema = Shape.plain.object({
+      id: Shape.plain.string(),
+      name: Shape.plain.string(),
+    })
+
+    const GroupSessionSchema = Shape.doc({
+      participants: Shape.record(ParticipantSchema),
+    })
+
+    const doc = createTypedDoc(GroupSessionSchema)
+
+    doc.change((root: any) => {
+      root.participants.set("p1", { id: "1", name: "Alice" })
+    })
+
+    const participants = doc.value.participants
+
+    // toJSON should be callable
+    const json = participants.toJSON()
+
+    // Type check: toJSON returns the plain Record type
+    expectTypeOf(json).toEqualTypeOf<
+      Record<string, { id: string; name: string }>
+    >()
+
+    // Runtime check
+    expect(json).toEqual({ p1: { id: "1", name: "Alice" } })
+  })
+
+  it("toJSON is still callable on Maps", () => {
+    const MetaSchema = Shape.map({
+      title: Shape.plain.string(),
+      count: Shape.plain.number(),
+    })
+
+    const DocSchema = Shape.doc({
+      meta: MetaSchema,
+    })
+
+    const doc = createTypedDoc(DocSchema)
+
+    doc.change((root: any) => {
+      root.meta.title = "Test"
+      root.meta.count = 42
+    })
+
+    const meta = doc.value.meta
+
+    // toJSON should be callable
+    const json = meta.toJSON()
+
+    // Type check
+    expectTypeOf(json).toEqualTypeOf<{ title: string; count: number }>()
+
+    // Runtime check
+    expect(json).toEqual({ title: "Test", count: 42 })
+  })
+})

package/src/types.ts

@@ -36,7 +36,16 @@ import type { ContainerShape, DocShape, Shape } from "./shape.js"
  */
 export type Infer<T> = T extends Shape<infer P, any, any> ? P : never
 
-export type InferDraftType<T> = T extends Shape<any, infer D, any> ? D : never
+/**
+ * Infers the mutable type from any Shape.
+ * This is the type used within change() callbacks for mutation.
+ */
+export type InferMutableType<T> = T extends Shape<any, infer M, any> ? M : never
+
+/**
+ * @deprecated Use InferMutableType<T> instead
+ */
+export type InferDraftType<T> = InferMutableType<T>
 
 /**
  * Extracts the valid placeholder type from a shape.
@@ -48,10 +57,58 @@ export type InferPlaceholderType<T> = T extends Shape<any, any, infer P>
   ? P
   : never
 
-// Draft-specific type inference that properly handles the draft context
+/**
+ * Mutable type for use within change() callbacks.
+ * This is the type-safe wrapper around CRDT containers that allows mutation.
+ */
+export type Mutable<T extends DocShape<Record<string, ContainerShape>>> =
+  InferMutableType<T>
+
+/**
+ * @deprecated Use Mutable<T> instead
+ */
 export type Draft<T extends DocShape<Record<string, ContainerShape>>> =
-  InferDraftType<T>
+  Mutable<T>
 
-export type DeepReadonly<T> = {
-  readonly [P in keyof T]: DeepReadonly<T[P]>
+/**
+ * Interface for objects that have a toJSON method.
+ * This is separate from the data type to avoid polluting Object.values().
+ */
+export interface HasToJSON<T> {
+  toJSON(): T
 }
+
+/**
+ * Deep readonly wrapper for plain objects (no index signature).
+ * Includes toJSON() method.
+ */
+export 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.
+ */
+export 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
+ */
+export type DeepReadonly<T> = T extends any[]
+  ? ReadonlyArray<DeepReadonly<T[number]>> & HasToJSON<T>
+  : T extends object
+    ? string extends keyof T
+      ? DeepReadonlyRecord<T>
+      : DeepReadonlyObject<T>
+    : T