@loro-extended/change 2.0.0 → 4.0.0

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

@@ -20,13 +20,11 @@ export class MovableListRef<
   }
 
   move(from: number, to: number): void {
-    this.assertMutable()
     this.container.move(from, to)
     this.commitIfAuto()
   }
 
   set(index: number, item: Exclude<Item, Container>) {
-    this.assertMutable()
     const result = this.container.set(index, item)
     this.commitIfAuto()
     return result

package/src/typed-refs/record-value-updates.test.ts

@@ -0,0 +1,214 @@
+import { describe, expect, it } from "vitest"
+import { change, createTypedDoc, Shape } from "../index.js"
+
+/**
+ * Regression tests for Shape.record() value updates across multiple change() calls.
+ *
+ * These tests ensure that value shapes in records are always read fresh from the
+ * underlying container, preventing stale cache issues when mutations occur in
+ * separate change() transactions.
+ *
+ * Fix: RecordRef.getOrCreateRef() no longer caches value shapes - it always reads
+ * from the container. Container shapes (handles) are still cached safely.
+ */
+describe("Record value updates across change() calls", () => {
+  describe("updating existing keys", () => {
+    it("updates value with .set() method", () => {
+      const Schema = Shape.doc({
+        input: Shape.record(Shape.plain.any()),
+      })
+
+      const doc = createTypedDoc(Schema)
+
+      change(doc, draft => {
+        draft.input.set("key1", 123)
+      })
+      expect(doc.input.get("key1")).toBe(123)
+
+      change(doc, draft => {
+        draft.input.set("key1", 456)
+      })
+      expect(doc.input.get("key1")).toBe(456)
+    })
+
+    it("updates value with indexed assignment", () => {
+      const Schema = Shape.doc({
+        input: Shape.record(Shape.plain.number()),
+      })
+
+      const doc = createTypedDoc(Schema)
+
+      change(doc, draft => {
+        draft.input.key1 = 100
+      })
+      expect(doc.input.key1).toBe(100)
+
+      change(doc, draft => {
+        draft.input.key1 = 200
+      })
+      expect(doc.input.key1).toBe(200)
+    })
+
+    it("handles multiple sequential updates to same key", () => {
+      const Schema = Shape.doc({
+        counter: Shape.record(Shape.plain.number()),
+      })
+
+      const doc = createTypedDoc(Schema)
+
+      for (let i = 1; i <= 5; i++) {
+        change(doc, draft => {
+          draft.counter.set("count", i)
+        })
+        expect(doc.counter.get("count")).toBe(i)
+      }
+    })
+  })
+
+  describe("deleting keys", () => {
+    it("removes key after delete", () => {
+      const Schema = Shape.doc({
+        input: Shape.record(Shape.plain.any()),
+      })
+
+      const doc = createTypedDoc(Schema)
+
+      change(doc, draft => {
+        draft.input.set("key1", "hello")
+      })
+      expect(doc.input.get("key1")).toBe("hello")
+
+      change(doc, draft => {
+        draft.input.delete("key1")
+      })
+      expect(doc.input.has("key1")).toBe(false)
+      expect(doc.input.get("key1")).toBeUndefined()
+    })
+  })
+
+  describe("toJSON() consistency", () => {
+    it("reflects updates in toJSON()", () => {
+      const Schema = Shape.doc({
+        input: Shape.record(Shape.plain.boolean()),
+      })
+
+      const doc = createTypedDoc(Schema)
+
+      change(doc, draft => {
+        draft.input.set("flag", false)
+      })
+      expect(doc.toJSON().input).toEqual({ flag: false })
+
+      change(doc, draft => {
+        draft.input.set("flag", true)
+      })
+      expect(doc.toJSON().input).toEqual({ flag: true })
+    })
+  })
+
+  describe("edge cases", () => {
+    it("handles setting same value then different value", () => {
+      const Schema = Shape.doc({
+        data: Shape.record(Shape.plain.number()),
+      })
+
+      const doc = createTypedDoc(Schema)
+
+      change(doc, draft => {
+        draft.data.set("x", 42)
+      })
+
+      change(doc, draft => {
+        draft.data.set("x", 42)
+      })
+
+      change(doc, draft => {
+        draft.data.set("x", 99)
+      })
+
+      expect(doc.data.get("x")).toBe(99)
+    })
+
+    it("handles alternating boolean values", () => {
+      const Schema = Shape.doc({
+        flags: Shape.record(Shape.plain.boolean()),
+      })
+
+      const doc = createTypedDoc(Schema)
+
+      change(doc, draft => {
+        draft.flags.set("active", false)
+      })
+      expect(doc.flags.get("active")).toBe(false)
+
+      change(doc, draft => {
+        draft.flags.set("active", true)
+      })
+      expect(doc.flags.get("active")).toBe(true)
+
+      change(doc, draft => {
+        draft.flags.set("active", false)
+      })
+      expect(doc.flags.get("active")).toBe(false)
+    })
+
+    it("handles null values", () => {
+      const Schema = Shape.doc({
+        nullable: Shape.record(Shape.plain.any()),
+      })
+
+      const doc = createTypedDoc(Schema)
+
+      change(doc, draft => {
+        draft.nullable.set("value", "initial")
+      })
+      expect(doc.nullable.get("value")).toBe("initial")
+
+      change(doc, draft => {
+        draft.nullable.set("value", null)
+      })
+      expect(doc.nullable.get("value")).toBe(null)
+    })
+
+    it("handles reading before first change", () => {
+      const Schema = Shape.doc({
+        data: Shape.record(Shape.plain.any()),
+      })
+
+      const doc = createTypedDoc(Schema)
+
+      expect(doc.data.get("key")).toBeUndefined()
+
+      change(doc, draft => {
+        draft.data.set("key", 100)
+      })
+      expect(doc.data.get("key")).toBe(100)
+
+      change(doc, draft => {
+        draft.data.set("key", 200)
+      })
+      expect(doc.data.get("key")).toBe(200)
+    })
+  })
+
+  describe("raw LoroDoc comparison", () => {
+    it("underlying CRDT operations work correctly", async () => {
+      const { LoroDoc } = await import("loro-crdt")
+
+      const doc = new LoroDoc()
+      const map = doc.getMap("input")
+
+      map.set("key", 123)
+      doc.commit()
+      expect(map.get("key")).toBe(123)
+
+      map.set("key", 456)
+      doc.commit()
+      expect(map.get("key")).toBe(456)
+
+      map.delete("key")
+      doc.commit()
+      expect(map.get("key")).toBeUndefined()
+    })
+  })
+})

package/src/typed-refs/record.ts

@@ -1,6 +1,5 @@
 import type { Container, LoroMap, Value } from "loro-crdt"
 import { deriveShapePlaceholder } from "../derive-placeholder.js"
-import { mergeValue } from "../overlay.js"
 import type {
   ContainerOrValueShape,
   ContainerShape,
@@ -16,7 +15,6 @@ import {
   createContainerTypedRef,
   hasContainerConstructor,
   serializeRefToJSON,
-  unwrapReadonlyPrimitive,
 } from "./utils.js"
 
 // Record typed ref
@@ -67,8 +65,8 @@ export class RecordRef<
       placeholder,
       getContainer: () =>
         this.container.getOrCreateContainer(key, new (LoroContainer as any)()),
-      readonly: this.readonly,
       autoCommit: this._params.autoCommit,
+      batchedMutation: this.batchedMutation,
       getDoc: this._params.getDoc,
     }
   }
@@ -96,43 +94,64 @@ export class RecordRef<
    * This is the method used for write operations.
    */
   getOrCreateRef(key: string): any {
-    let ref = this.refCache.get(key)
-    if (!ref) {
-      const shape = this.shape.shape
-      if (isContainerShape(shape)) {
-        ref = createContainerTypedRef(
-          this.getTypedRefParams(key, shape as ContainerShape),
-        )
-        // Cache container refs
-        this.refCache.set(key, ref)
-      } else {
-        // For value shapes, first try to get the value from the container
+    const shape = this.shape.shape
+
+    if (isValueShape(shape)) {
+      // When NOT in batchedMutation mode (direct access outside of change()), ALWAYS read fresh
+      // from container (NEVER cache). This ensures we always get the latest value
+      // from the CRDT, even when modified by a different ref instance (e.g., drafts from change())
+      //
+      // When in batchedMutation mode (inside change()), we cache value shapes so that
+      // mutations to nested objects persist back to the CRDT via absorbPlainValues()
+      if (!this.batchedMutation) {
         const containerValue = this.container.get(key)
         if (containerValue !== undefined) {
-          ref = containerValue as Value
+          return containerValue
+        }
+        // Fall back to placeholder if the container doesn't have the value
+        const placeholder = (this.placeholder as any)?.[key]
+        if (placeholder !== undefined) {
+          return placeholder
+        }
+        // Fall back to the default value from the shape
+        return (shape as any)._plain
+      }
+
+      // In batched mode (within change()), we cache value shapes so that
+      // mutations to nested objects persist back to the CRDT via absorbPlainValues()
+      let ref = this.refCache.get(key)
+      if (!ref) {
+        const containerValue = this.container.get(key)
+        if (containerValue !== undefined) {
+          // For objects, create a deep copy so mutations can be tracked
+          if (typeof containerValue === "object" && containerValue !== null) {
+            ref = JSON.parse(JSON.stringify(containerValue))
+          } else {
+            ref = containerValue as Value
+          }
         } else {
-          // Only fall back to placeholder if the container doesn't have the value
+          // Fall back to placeholder if the container doesn't have the value
           const placeholder = (this.placeholder as any)?.[key]
-          if (placeholder === undefined) {
-            // If it's a value type and not in container or placeholder,
-            // fallback to the default value from the shape
-            ref = (shape as any)._plain
-          } else {
+          if (placeholder !== undefined) {
             ref = placeholder as Value
+          } else {
+            // Fall back to the default value from the shape
+            ref = (shape as any)._plain
           }
         }
-        // Only cache primitive values if NOT readonly
-        if (ref !== undefined && !this.readonly) {
-          this.refCache.set(key, ref)
-        }
+        this.refCache.set(key, ref)
       }
+      return ref
     }
 
-    if (this.readonly && isContainerShape(this.shape.shape)) {
-      return unwrapReadonlyPrimitive(
-        ref as TypedRef<any>,
-        this.shape.shape as ContainerShape,
+    // For container shapes, we can safely cache the ref since it's a handle
+    // to the underlying Loro container, not a value copy.
+    let ref = this.refCache.get(key)
+    if (!ref) {
+      ref = createContainerTypedRef(
+        this.getTypedRefParams(key, shape as ContainerShape),
       )
+      this.refCache.set(key, ref)
     }
 
     return ref as any
@@ -143,7 +162,6 @@ export class RecordRef<
   }
 
   set(key: string, value: any): void {
-    this.assertMutable()
     if (isValueShape(this.shape.shape)) {
       this.container.set(key, value)
       this.refCache.set(key, value)
@@ -163,14 +181,12 @@ export class RecordRef<
   }
 
   setContainer<C extends Container>(key: string, container: C): C {
-    this.assertMutable()
     const result = this.container.setContainer(key, container)
     this.commitIfAuto()
     return result
   }
 
   delete(key: string): void {
-    this.assertMutable()
     this.container.delete(key)
     this.refCache.delete(key)
     this.commitIfAuto()
@@ -193,25 +209,6 @@ export class RecordRef<
   }
 
   toJSON(): Record<string, Infer<NestedShape>> {
-    // Fast path: readonly mode
-    if (this.readonly) {
-      const nativeJson = this.container.toJSON() as Record<string, any>
-      // For records, we need to overlay placeholders for each entry's nested shape
-      const result: Record<string, Infer<NestedShape>> = {}
-      for (const key of Object.keys(nativeJson)) {
-        // For records, the placeholder is always {}, so we need to derive
-        // the placeholder for the nested shape on the fly
-        const nestedPlaceholderValue = deriveShapePlaceholder(this.shape.shape)
-
-        result[key] = mergeValue(
-          this.shape.shape,
-          nativeJson[key],
-          nestedPlaceholderValue as Value,
-        ) as Infer<NestedShape>
-      }
-      return result
-    }
-
     return serializeRefToJSON(this, this.keys()) as Record<
       string,
       Infer<NestedShape>

package/src/typed-refs/struct-value-updates.test.ts

@@ -0,0 +1,200 @@
+import { describe, expect, it } from "vitest"
+import { change, createTypedDoc, Shape } from "../index.js"
+
+/**
+ * Tests for StructRef value updates across multiple change() calls.
+ *
+ * These tests verify that value shapes in structs are always read fresh from the
+ * underlying container, preventing stale cache issues when mutations occur in
+ * separate change() transactions.
+ *
+ * BUG: StructRef.getOrCreateRef() caches value shapes in propertyCache, causing
+ * stale values to be returned when the underlying container is modified by a
+ * different StructRef instance (e.g., drafts created by change()).
+ */
+describe("Struct value updates across change() calls", () => {
+  describe("updating existing properties", () => {
+    it("updates value property via direct assignment", () => {
+      const Schema = Shape.doc({
+        config: Shape.struct({
+          name: Shape.plain.string(),
+          count: Shape.plain.number(),
+        }),
+      })
+
+      const doc = createTypedDoc(Schema)
+
+      change(doc, draft => {
+        draft.config.name = "initial"
+        draft.config.count = 1
+      })
+      expect(doc.config.name).toBe("initial")
+      expect(doc.config.count).toBe(1)
+
+      // Second change - BUG: values stay at initial values
+      change(doc, draft => {
+        draft.config.name = "updated"
+        draft.config.count = 2
+      })
+      expect(doc.config.name).toBe("updated") // FAILS: returns "initial"
+      expect(doc.config.count).toBe(2) // FAILS: returns 1
+    })
+
+    it("handles multiple sequential updates to same property", () => {
+      const Schema = Shape.doc({
+        settings: Shape.struct({
+          value: Shape.plain.number(),
+        }),
+      })
+
+      const doc = createTypedDoc(Schema)
+
+      for (let i = 1; i <= 5; i++) {
+        change(doc, draft => {
+          draft.settings.value = i
+        })
+        expect(doc.settings.value).toBe(i) // FAILS on i > 1
+      }
+    })
+
+    it("updates boolean property", () => {
+      const Schema = Shape.doc({
+        flags: Shape.struct({
+          enabled: Shape.plain.boolean(),
+        }),
+      })
+
+      const doc = createTypedDoc(Schema)
+
+      change(doc, draft => {
+        draft.flags.enabled = true
+      })
+      expect(doc.flags.enabled).toBe(true)
+
+      change(doc, draft => {
+        draft.flags.enabled = false
+      })
+      expect(doc.flags.enabled).toBe(false) // FAILS: returns true
+    })
+  })
+
+  describe("nested structs", () => {
+    it("updates value in nested struct", () => {
+      const Schema = Shape.doc({
+        outer: Shape.struct({
+          inner: Shape.struct({
+            value: Shape.plain.number(),
+          }),
+        }),
+      })
+
+      const doc = createTypedDoc(Schema)
+
+      change(doc, draft => {
+        draft.outer.inner.value = 100
+      })
+      expect(doc.outer.inner.value).toBe(100)
+
+      change(doc, draft => {
+        draft.outer.inner.value = 200
+      })
+      expect(doc.outer.inner.value).toBe(200) // FAILS: returns 100
+    })
+  })
+
+  describe("struct inside record", () => {
+    it("updates value in struct that is a record value", () => {
+      const Schema = Shape.doc({
+        users: Shape.record(
+          Shape.struct({
+            name: Shape.plain.string(),
+            age: Shape.plain.number(),
+          }),
+        ),
+      })
+
+      const doc = createTypedDoc(Schema)
+
+      change(doc, draft => {
+        draft.users.user1 = { name: "Alice", age: 30 }
+      })
+      expect(doc.users.user1?.name).toBe("Alice")
+      expect(doc.users.user1?.age).toBe(30)
+
+      // Update the struct's value properties
+      change(doc, draft => {
+        const user = draft.users.getOrCreateRef("user1")
+        user.name = "Bob"
+        user.age = 25
+      })
+      expect(doc.users.user1?.name).toBe("Bob") // FAILS: returns "Alice"
+      expect(doc.users.user1?.age).toBe(25) // FAILS: returns 30
+    })
+  })
+
+  describe("toJSON() consistency", () => {
+    it("reflects updates in toJSON()", () => {
+      const Schema = Shape.doc({
+        data: Shape.struct({
+          status: Shape.plain.string(),
+        }),
+      })
+
+      const doc = createTypedDoc(Schema)
+
+      change(doc, draft => {
+        draft.data.status = "pending"
+      })
+      expect(doc.toJSON().data).toEqual({ status: "pending" })
+
+      change(doc, draft => {
+        draft.data.status = "complete"
+      })
+      expect(doc.toJSON().data).toEqual({ status: "complete" })
+    })
+  })
+
+  describe("reading before first change", () => {
+    it("reading before any change should not cause stale cache", () => {
+      const Schema = Shape.doc({
+        config: Shape.struct({
+          value: Shape.plain.number().placeholder(0),
+        }),
+      })
+
+      const doc = createTypedDoc(Schema)
+
+      // Read before any change - gets placeholder value
+      expect(doc.config.value).toBe(0)
+
+      // First set
+      change(doc, draft => {
+        draft.config.value = 100
+      })
+      expect(doc.config.value).toBe(100)
+
+      // Second set - this is the key test for the stale cache bug
+      change(doc, draft => {
+        draft.config.value = 200
+      })
+      expect(doc.config.value).toBe(200) // FAILS: returns 100
+    })
+  })
+
+  describe("comparison with raw LoroDoc", () => {
+    it("underlying CRDT operations work correctly", async () => {
+      const { LoroDoc } = await import("loro-crdt")
+
+      const doc = new LoroDoc()
+      const map = doc.getMap("config")
+
+      map.set("value", 123)
+      doc.commit()
+      expect(map.get("value")).toBe(123)
+
+      map.set("value", 456)
+      doc.commit()
+      expect(map.get("value")).toBe(456) // PASSES: raw Loro works fine
+    })
+  })
+})