@loro-extended/change 0.6.0 → 0.8.0

package/src/draft-nodes/list-base.ts

@@ -84,7 +84,7 @@ export abstract class ListDraftNodeBase<
   ): DraftNodeParams<ContainerShape> {
     return {
       shape,
-      emptyState: undefined, // List items don't have empty state
+      placeholder: undefined, // List items don't have placeholder
       getContainer: () => {
         const containerItem = this.container.get(index)
         if (!containerItem || !isContainer(containerItem)) {
@@ -92,6 +92,7 @@ export abstract class ListDraftNodeBase<
         }
         return containerItem
       },
+      readonly: this.readonly,
     }
   }
 
@@ -142,7 +143,7 @@ export abstract class ListDraftNodeBase<
   }
 
   // Get item for return values - returns DraftItem that can be mutated
-  protected getDraftItem(index: number): DraftItem {
+  protected getDraftItem(index: number): any {
     // Check if we already have a cached item for this index
     let cachedItem = this.itemCache.get(index)
     if (cachedItem) {
@@ -167,14 +168,29 @@ export abstract class ListDraftNodeBase<
         // For primitives, just use the value directly
         cachedItem = containerItem
       }
-      this.itemCache.set(index, cachedItem)
+      // Only cache primitive values if NOT readonly
+      if (!this.readonly) {
+        this.itemCache.set(index, cachedItem)
+      }
       return cachedItem as DraftItem
     } else {
       // For container shapes, create a proper draft node using the new pattern
       cachedItem = createContainerDraftNode(
         this.getDraftNodeParams(index, this.shape.shape as ContainerShape),
       )
+      // Cache container nodes
       this.itemCache.set(index, cachedItem)
+
+      if (this.readonly) {
+        const shape = this.shape.shape as ContainerShape
+        if (shape._type === "counter") {
+          return (cachedItem as any).value
+        }
+        if (shape._type === "text") {
+          return (cachedItem as any).toString()
+        }
+      }
+
       return cachedItem as DraftItem
     }
   }
@@ -254,26 +270,31 @@ export abstract class ListDraftNodeBase<
   }
 
   insert(index: number, item: Item): void {
+    if (this.readonly) throw new Error("Cannot modify readonly doc")
     // Update cache indices before performing the insert operation
     this.updateCacheForInsert(index)
     this.insertWithConversion(index, item)
   }
 
   delete(index: number, len: number): void {
+    if (this.readonly) throw new Error("Cannot modify readonly doc")
     // Update cache indices before performing the delete operation
     this.updateCacheForDelete(index, len)
     this.container.delete(index, len)
   }
 
   push(item: Item): void {
+    if (this.readonly) throw new Error("Cannot modify readonly doc")
     this.pushWithConversion(item)
   }
 
   pushContainer(container: Container): Container {
+    if (this.readonly) throw new Error("Cannot modify readonly doc")
     return this.container.pushContainer(container)
   }
 
   insertContainer(index: number, container: Container): Container {
+    if (this.readonly) throw new Error("Cannot modify readonly doc")
     return this.container.insertContainer(index, container)
   }
 

package/src/draft-nodes/list.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest"
+import { createTypedDoc, Shape } from "../index.js"
+
+describe("ListDraftNode", () => {
+  describe("set via index", () => {
+    it("should allow setting a plain object for a list item via index", () => {
+      const schema = Shape.doc({
+        users: Shape.list(
+          Shape.map({
+            name: Shape.plain.string(),
+          }),
+        ),
+      })
+
+      const doc = createTypedDoc(schema)
+
+      doc.change(draft => {
+        draft.users.push({ name: "Alice" })
+
+        // Update via index
+        draft.users[0] = { name: "Bob" }
+      })
+
+      expect(doc.toJSON().users[0]).toEqual({ name: "Bob" })
+    })
+
+    it("should allow setting a primitive value via index", () => {
+      const schema = Shape.doc({
+        tags: Shape.list(Shape.plain.string()),
+      })
+
+      const doc = createTypedDoc(schema)
+
+      doc.change(draft => {
+        draft.tags.push("a")
+        draft.tags.push("b")
+        draft.tags[1] = "c"
+      })
+
+      expect(doc.toJSON().tags).toEqual(["a", "c"])
+    })
+  })
+})

package/src/draft-nodes/list.ts

@@ -1,11 +1,14 @@
 import type { LoroList } from "loro-crdt"
 import type { ContainerOrValueShape } from "../shape.js"
+import type { Infer } from "../types.js"
 import { ListDraftNodeBase } from "./list-base.js"
 
 // List draft node
 export class ListDraftNode<
   NestedShape extends ContainerOrValueShape,
 > extends ListDraftNodeBase<NestedShape> {
+  [index: number]: Infer<NestedShape>
+
   protected get container(): LoroList {
     return super.container as LoroList
   }

package/src/draft-nodes/map.ts

@@ -16,7 +16,10 @@ import type {
 } from "../shape.js"
 import { isContainerShape, isValueShape } from "../utils/type-guards.js"
 import { DraftNode, type DraftNodeParams } from "./base.js"
-import { createContainerDraftNode } from "./utils.js"
+import {
+  assignPlainValueToDraftNode,
+  createContainerDraftNode,
+} from "./utils.js"
 
 const containerConstructor = {
   counter: LoroCounter,
@@ -64,42 +67,66 @@ export class MapDraftNode<
     key: string,
     shape: S,
   ): DraftNodeParams<ContainerShape> {
-    const emptyState = (this.emptyState as any)?.[key]
+    const placeholder = (this.placeholder as any)?.[key]
 
     const LoroContainer = containerConstructor[shape._type]
 
     return {
       shape,
-      emptyState,
+      placeholder,
       getContainer: () =>
         this.container.getOrCreateContainer(key, new (LoroContainer as any)()),
+      readonly: this.readonly,
     }
   }
 
   getOrCreateNode<Shape extends ContainerShape | ValueShape>(
     key: string,
     shape: Shape,
-  ): Shape extends ContainerShape ? DraftNode<Shape> : Value {
+  ): any {
     let node = this.propertyCache.get(key)
     if (!node) {
       if (isContainerShape(shape)) {
         node = createContainerDraftNode(this.getDraftNodeParams(key, shape))
+        // We cache container nodes even in readonly mode because they are just handles
+        this.propertyCache.set(key, node)
       } else {
         // For value shapes, first try to get the value from the container
         const containerValue = this.container.get(key)
         if (containerValue !== undefined) {
           node = containerValue as Value
         } else {
-          // Only fall back to empty state if the container doesn't have the value
-          const emptyState = (this.emptyState as any)?.[key]
-          if (emptyState === undefined) {
-            throw new Error("empty state required")
+          // Only fall back to placeholder if the container doesn't have the value
+          const placeholder = (this.placeholder as any)?.[key]
+          if (placeholder === undefined) {
+            throw new Error("placeholder required")
           }
-          node = emptyState as Value
+          node = placeholder as Value
+        }
+
+        // In readonly mode, we DO NOT cache primitive values.
+        // This ensures we always get the latest value from the CRDT on next access.
+        if (!this.readonly) {
+          this.propertyCache.set(key, node)
         }
       }
       if (node === undefined) throw new Error("no container made")
-      this.propertyCache.set(key, node)
+    }
+
+    if (this.readonly && isContainerShape(shape)) {
+      // In readonly mode, if the container doesn't exist, return the placeholder
+      // This ensures we respect default values (e.g. counter: 1)
+      const existing = this.container.get(key)
+      if (existing === undefined) {
+        return (this.placeholder as any)?.[key]
+      }
+
+      if (shape._type === "counter") {
+        return (node as any).value
+      }
+      if (shape._type === "text") {
+        return (node as any).toString()
+      }
     }
 
     return node as Shape extends ContainerShape ? DraftNode<Shape> : Value
@@ -110,13 +137,24 @@ export class MapDraftNode<
       const shape = this.shape.shapes[key]
       Object.defineProperty(this, key, {
         get: () => this.getOrCreateNode(key, shape),
-        set: isValueShape(shape)
-          ? value => {
-              // console.log("set value", value)
-              this.container.set(key, value)
-              this.propertyCache.set(key, value)
+        set: value => {
+          if (this.readonly) throw new Error("Cannot modify readonly doc")
+          if (isValueShape(shape)) {
+            this.container.set(key, value)
+            this.propertyCache.set(key, value)
+          } else {
+            if (value && typeof value === "object") {
+              const node = this.getOrCreateNode(key, shape)
+
+              if (assignPlainValueToDraftNode(node as DraftNode<any>, value)) {
+                return
+              }
             }
-          : undefined,
+            throw new Error(
+              "Cannot set container directly, modify the draft node instead",
+            )
+          }
+        },
       })
     }
   }
@@ -127,14 +165,17 @@ export class MapDraftNode<
   }
 
   set(key: string, value: Value): void {
+    if (this.readonly) throw new Error("Cannot modify readonly doc")
     this.container.set(key, value)
   }
 
   setContainer<C extends Container>(key: string, container: C): C {
+    if (this.readonly) throw new Error("Cannot modify readonly doc")
     return this.container.setContainer(key, container)
   }
 
   delete(key: string): void {
+    if (this.readonly) throw new Error("Cannot modify readonly doc")
     this.container.delete(key)
   }
 

package/src/draft-nodes/movable-list.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest"
+import { createTypedDoc, Shape } from "../index.js"
+
+describe("MovableListDraftNode", () => {
+  describe("set via index", () => {
+    it("should allow setting a plain object for a list item via index", () => {
+      const schema = Shape.doc({
+        users: Shape.movableList(
+          Shape.map({
+            name: Shape.plain.string(),
+          }),
+        ),
+      })
+
+      const doc = createTypedDoc(schema)
+
+      doc.change(draft => {
+        draft.users.push({ name: "Alice" })
+
+        // Update via index
+        draft.users[0] = { name: "Bob" }
+      })
+
+      expect(doc.toJSON().users[0]).toEqual({ name: "Bob" })
+    })
+  })
+})

package/src/draft-nodes/movable-list.ts

@@ -1,5 +1,6 @@
 import type { Container, LoroMovableList } from "loro-crdt"
 import type { ContainerOrValueShape } from "../shape.js"
+import type { Infer } from "../types.js"
 import { ListDraftNodeBase } from "./list-base.js"
 
 // Movable list draft node
@@ -7,6 +8,8 @@ export class MovableListDraftNode<
   NestedShape extends ContainerOrValueShape,
   Item = NestedShape["_plain"],
 > extends ListDraftNodeBase<NestedShape> {
+  [index: number]: Infer<NestedShape>
+
   protected get container(): LoroMovableList {
     return super.container as LoroMovableList
   }
@@ -17,10 +20,12 @@ export class MovableListDraftNode<
   }
 
   move(from: number, to: number): void {
+    if (this.readonly) throw new Error("Cannot modify readonly doc")
     this.container.move(from, to)
   }
 
   set(index: number, item: Exclude<Item, Container>) {
+    if (this.readonly) throw new Error("Cannot modify readonly doc")
     return this.container.set(index, item)
   }
 }

package/src/draft-nodes/proxy-handlers.ts

@@ -0,0 +1,87 @@
+import type { ListDraftNode } from "./list.js"
+import type { MovableListDraftNode } from "./movable-list.js"
+import type { RecordDraftNode } from "./record.js"
+
+export const recordProxyHandler: ProxyHandler<RecordDraftNode<any>> = {
+  get: (target, prop) => {
+    if (typeof prop === "string" && !(prop in target)) {
+      return target.get(prop)
+    }
+    return Reflect.get(target, prop)
+  },
+  set: (target, prop, value) => {
+    if (typeof prop === "string" && !(prop in target)) {
+      target.set(prop, value)
+      return true
+    }
+    return Reflect.set(target, prop, value)
+  },
+  deleteProperty: (target, prop) => {
+    if (typeof prop === "string" && !(prop in target)) {
+      target.delete(prop)
+      return true
+    }
+    return Reflect.deleteProperty(target, prop)
+  },
+  ownKeys: target => {
+    return target.keys()
+  },
+  getOwnPropertyDescriptor: (target, prop) => {
+    if (typeof prop === "string" && target.has(prop)) {
+      return {
+        configurable: true,
+        enumerable: true,
+        value: target.get(prop),
+      }
+    }
+    return Reflect.getOwnPropertyDescriptor(target, prop)
+  },
+}
+
+export const listProxyHandler: ProxyHandler<ListDraftNode<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)) {
+        // For lists, assignment to index implies replacement
+        target.delete(index, 1)
+        target.insert(index, value)
+        return true
+      }
+    }
+    return Reflect.set(target, prop, value)
+  },
+}
+
+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)
+        }
+      }
+      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)
+    },
+  }

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest"
-import { Shape, TypedDoc } from "./index.js"
+import { Shape, TypedDoc } from "../index.js"
 
 describe("Record Types", () => {
   describe("Shape.record (Container)", () => {
@@ -8,14 +8,14 @@ describe("Record Types", () => {
         scores: Shape.record(Shape.counter()),
       })
 
-      const doc = new TypedDoc(schema, { scores: {} })
+      const doc = new TypedDoc(schema)
 
       doc.change(draft => {
         draft.scores.getOrCreateNode("alice").increment(10)
         draft.scores.getOrCreateNode("bob").increment(5)
       })
 
-      expect(doc.value.scores).toEqual({
+      expect(doc.toJSON().scores).toEqual({
         alice: 10,
         bob: 5,
       })
@@ -25,7 +25,7 @@ describe("Record Types", () => {
         draft.scores.delete("bob")
       })
 
-      expect(doc.value.scores).toEqual({
+      expect(doc.toJSON().scores).toEqual({
         alice: 15,
       })
     })
@@ -35,14 +35,14 @@ describe("Record Types", () => {
         notes: Shape.record(Shape.text()),
       })
 
-      const doc = new TypedDoc(schema, { notes: {} })
+      const doc = new TypedDoc(schema)
 
       doc.change(draft => {
         draft.notes.getOrCreateNode("todo").insert(0, "Buy milk")
         draft.notes.getOrCreateNode("reminders").insert(0, "Call mom")
       })
 
-      expect(doc.value.notes).toEqual({
+      expect(doc.toJSON().notes).toEqual({
         todo: "Buy milk",
         reminders: "Call mom",
       })
@@ -53,7 +53,7 @@ describe("Record Types", () => {
         groups: Shape.record(Shape.list(Shape.plain.string())),
       })
 
-      const doc = new TypedDoc(schema, { groups: {} })
+      const doc = new TypedDoc(schema)
 
       doc.change(draft => {
         const groupA = draft.groups.getOrCreateNode("groupA")
@@ -64,7 +64,7 @@ describe("Record Types", () => {
         groupB.push("charlie")
       })
 
-      expect(doc.value.groups).toEqual({
+      expect(doc.toJSON().groups).toEqual({
         groupA: ["alice", "bob"],
         groupB: ["charlie"],
       })
@@ -79,14 +79,14 @@ describe("Record Types", () => {
         }),
       })
 
-      const doc = new TypedDoc(schema, { wrapper: { config: {} } })
+      const doc = new TypedDoc(schema)
 
       doc.change(draft => {
         draft.wrapper.config.theme = "dark"
         draft.wrapper.config.lang = "en"
       })
 
-      expect(doc.value.wrapper.config).toEqual({
+      expect(doc.toJSON().wrapper.config).toEqual({
         theme: "dark",
         lang: "en",
       })
@@ -96,7 +96,7 @@ describe("Record Types", () => {
         draft.wrapper.config.lang = "fr"
       })
 
-      expect(doc.value.wrapper.config).toEqual({
+      expect(doc.toJSON().wrapper.config).toEqual({
         lang: "fr",
       })
     })
@@ -108,15 +108,14 @@ describe("Record Types", () => {
         }),
       })
 
-      // Empty state must use empty record - add initial data via change()
-      const doc = new TypedDoc(schema, { wrapper: { stats: {} } })
+      const doc = new TypedDoc(schema)
 
       doc.change(draft => {
         draft.wrapper.stats.visits = 100
         draft.wrapper.stats.clicks = 50
       })
 
-      expect(doc.value.wrapper.stats).toEqual({
+      expect(doc.toJSON().wrapper.stats).toEqual({
         visits: 100,
         clicks: 50,
       })
@@ -131,7 +130,7 @@ describe("Record Types", () => {
         }),
       })
 
-      const doc = new TypedDoc(schema, { wrapper: { settings: {} } })
+      const doc = new TypedDoc(schema)
 
       doc.change(draft => {
         draft.wrapper.settings.ui = {
@@ -144,7 +143,7 @@ describe("Record Types", () => {
         }
       })
 
-      expect(doc.value.wrapper.settings).toEqual({
+      expect(doc.toJSON().wrapper.settings).toEqual({
         ui: {
           darkMode: true,
           sidebar: false,
@@ -168,7 +167,7 @@ describe("Record Types", () => {
         ),
       })
 
-      const doc = new TypedDoc(schema, { users: {} })
+      const doc = new TypedDoc(schema)
 
       doc.change(draft => {
         const alice = draft.users.getOrCreateNode("u1")
@@ -180,10 +179,91 @@ describe("Record Types", () => {
         bob.age = 25
       })
 
-      expect(doc.value.users).toEqual({
+      expect(doc.toJSON().users).toEqual({
         u1: { name: "Alice", age: 30 },
         u2: { name: "Bob", age: 25 },
       })
     })
+
+    it("should allow setting a plain object for a record with map values", () => {
+      const schema = Shape.doc({
+        participants: Shape.record(
+          Shape.map({
+            id: Shape.plain.string(),
+            role: Shape.plain.string(),
+            name: Shape.plain.string(),
+            color: Shape.plain.string(),
+          }),
+        ),
+      })
+
+      const doc = new TypedDoc(schema)
+
+      doc.change(draft => {
+        draft.participants["student-1"] = {
+          id: "student-1",
+          role: "student",
+          name: "Alice",
+          color: "indigo",
+        }
+      })
+
+      expect(doc.toJSON().participants["student-1"]).toEqual({
+        id: "student-1",
+        role: "student",
+        name: "Alice",
+        color: "indigo",
+      })
+    })
+
+    it("should allow setting a plain object for a record with nested map values", () => {
+      const schema = Shape.doc({
+        data: Shape.record(
+          Shape.map({
+            info: Shape.map({
+              name: Shape.plain.string(),
+            }),
+          }),
+        ),
+      })
+
+      const doc = new TypedDoc(schema)
+
+      doc.change(draft => {
+        draft.data["item-1"] = {
+          info: {
+            name: "Item 1",
+          },
+        }
+      })
+
+      expect(doc.toJSON().data["item-1"]).toEqual({
+        info: {
+          name: "Item 1",
+        },
+      })
+    })
+
+    it("should allow setting a plain array for a record with list values", () => {
+      const schema = Shape.doc({
+        histories: Shape.record(Shape.list(Shape.plain.string())),
+      })
+
+      const doc = new TypedDoc(schema)
+
+      doc.change(draft => {
+        draft.histories.user1 = ["a", "b"]
+      })
+
+      expect(doc.toJSON().histories.user1).toEqual(["a", "b"])
+
+      doc.change(draft => {
+        // biome-ignore lint/complexity/useLiteralKeys: tests indexed assignment
+        draft.histories["user1"] = ["c"]
+      })
+
+      // biome-ignore lint/complexity/useLiteralKeys: tests indexed assignment
+      expect(doc.toJSON().histories["user1"]).toEqual(["c"])
+    })
   })
 })