@loro-extended/change 3.0.0 → 5.0.0

package/src/typed-refs/record-ref-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.test.ts → record-ref.test.ts}

@@ -12,8 +12,9 @@ describe("Record Types", () => {
       const doc = createTypedDoc(schema)
 
       change(doc, draft => {
-        draft.scores.getOrCreateRef("alice").increment(10)
-        draft.scores.getOrCreateRef("bob").increment(5)
+        // Use get() to access container refs - it creates if not exists
+        draft.scores.get("alice")?.increment(10)
+        draft.scores.get("bob")?.increment(5)
       })
 
       expect(doc.toJSON().scores).toEqual({
@@ -22,7 +23,7 @@ describe("Record Types", () => {
       })
 
       change(doc, draft => {
-        draft.scores.getOrCreateRef("alice").increment(5)
+        draft.scores.get("alice")?.increment(5)
         draft.scores.delete("bob")
       })
 
@@ -39,8 +40,8 @@ describe("Record Types", () => {
       const doc = createTypedDoc(schema)
 
       change(doc, draft => {
-        draft.notes.getOrCreateRef("todo").insert(0, "Buy milk")
-        draft.notes.getOrCreateRef("reminders").insert(0, "Call mom")
+        draft.notes.get("todo")?.insert(0, "Buy milk")
+        draft.notes.get("reminders")?.insert(0, "Call mom")
       })
 
       expect(doc.toJSON().notes).toEqual({
@@ -57,12 +58,12 @@ describe("Record Types", () => {
       const doc = createTypedDoc(schema)
 
       change(doc, draft => {
-        const groupA = draft.groups.getOrCreateRef("groupA")
-        groupA.push("alice")
-        groupA.push("bob")
+        const groupA = draft.groups.get("groupA")
+        groupA?.push("alice")
+        groupA?.push("bob")
 
-        const groupB = draft.groups.getOrCreateRef("groupB")
-        groupB.push("charlie")
+        const groupB = draft.groups.get("groupB")
+        groupB?.push("charlie")
       })
 
       expect(doc.toJSON().groups).toEqual({
@@ -171,13 +172,17 @@ describe("Record Types", () => {
       const doc = createTypedDoc(schema)
 
       change(doc, draft => {
-        const alice = draft.users.getOrCreateRef("u1")
-        alice.name = "Alice"
-        alice.age = 30
+        const alice = draft.users.get("u1")
+        if (alice) {
+          alice.name = "Alice"
+          alice.age = 30
+        }
 
-        const bob = draft.users.getOrCreateRef("u2")
-        bob.name = "Bob"
-        bob.age = 25
+        const bob = draft.users.get("u2")
+        if (bob) {
+          bob.name = "Bob"
+          bob.age = 25
+        }
       })
 
       expect(doc.toJSON().users).toEqual({

package/src/typed-refs/record-ref.ts

@@ -0,0 +1,80 @@
+import type { Container, LoroMap } from "loro-crdt"
+import type { ContainerOrValueShape } from "../shape.js"
+import type { Infer, InferMutableType } from "../types.js"
+import { INTERNAL_SYMBOL, TypedRef, type TypedRefParams } from "./base.js"
+import { RecordRefInternals } from "./record-ref-internals.js"
+import { serializeRefToJSON } from "./utils.js"
+
+/**
+ * Record typed ref - thin facade that delegates to RecordRefInternals.
+ */
+export class RecordRef<
+  NestedShape extends ContainerOrValueShape,
+> extends TypedRef<any> {
+  [key: string]: InferMutableType<NestedShape> | undefined | any
+
+  [INTERNAL_SYMBOL]: RecordRefInternals<NestedShape>
+
+  constructor(params: TypedRefParams<any>) {
+    super()
+    this[INTERNAL_SYMBOL] = new RecordRefInternals(params)
+  }
+
+  /** Set a value at a key */
+  set(key: string, value: any): void {
+    this[INTERNAL_SYMBOL].set(key, value)
+  }
+
+  /** Delete a key */
+  delete(key: string): void {
+    this[INTERNAL_SYMBOL].delete(key)
+  }
+
+  get(key: string): InferMutableType<NestedShape> | undefined {
+    // In batched mutation mode (inside change()), use getOrCreateRef to create containers
+    // This allows patterns like: draft.scores.get("alice")!.increment(10)
+    if (this[INTERNAL_SYMBOL].getBatchedMutation()) {
+      return this[INTERNAL_SYMBOL].getOrCreateRef(key) as
+        | InferMutableType<NestedShape>
+        | undefined
+    }
+    // In readonly mode, use getRef which returns undefined for non-existent keys
+    return this[INTERNAL_SYMBOL].getRef(key) as
+      | InferMutableType<NestedShape>
+      | undefined
+  }
+
+  setContainer<C extends Container>(key: string, container: C): C {
+    const loroContainer = this[INTERNAL_SYMBOL].getContainer() as LoroMap
+    const result = loroContainer.setContainer(key, container)
+    this[INTERNAL_SYMBOL].commitIfAuto()
+    return result
+  }
+
+  has(key: string): boolean {
+    const container = this[INTERNAL_SYMBOL].getContainer() as LoroMap
+    return container.get(key) !== undefined
+  }
+
+  keys(): string[] {
+    const container = this[INTERNAL_SYMBOL].getContainer() as LoroMap
+    return container.keys()
+  }
+
+  values(): any[] {
+    const container = this[INTERNAL_SYMBOL].getContainer() as LoroMap
+    return container.values()
+  }
+
+  get size(): number {
+    const container = this[INTERNAL_SYMBOL].getContainer() as LoroMap
+    return container.size
+  }
+
+  toJSON(): Record<string, Infer<NestedShape>> {
+    return serializeRefToJSON(this, this.keys()) as Record<
+      string,
+      Infer<NestedShape>
+    >
+  }
+}

package/src/typed-refs/struct-ref-internals.ts

@@ -0,0 +1,195 @@
+import type {
+  Container,
+  LoroDoc,
+  LoroMap,
+  Subscription,
+  Value,
+} from "loro-crdt"
+import type { LoroMapRef } from "../loro.js"
+import type {
+  ContainerOrValueShape,
+  ContainerShape,
+  StructContainerShape,
+  ValueShape,
+} from "../shape.js"
+import { isValueShape } from "../utils/type-guards.js"
+import { BaseRefInternals, type TypedRef, type TypedRefParams } from "./base.js"
+import {
+  absorbCachedPlainValues,
+  assignPlainValueToTypedRef,
+  containerConstructor,
+  createContainerTypedRef,
+  hasContainerConstructor,
+} from "./utils.js"
+
+/**
+ * Internal implementation for StructRef.
+ * Contains all logic, state, and implementation details.
+ */
+export class StructRefInternals<
+  NestedShapes extends Record<string, ContainerOrValueShape>,
+> extends BaseRefInternals<any> {
+  private propertyCache = new Map<string, TypedRef<ContainerShape> | Value>()
+
+  /** Get typed ref params for creating child refs at a key */
+  getTypedRefParams(
+    key: string,
+    shape: ContainerShape,
+  ): TypedRefParams<ContainerShape> {
+    const placeholder = (this.getPlaceholder() 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]
+    const container = this.getContainer() as LoroMap
+
+    return {
+      shape,
+      placeholder,
+      getContainer: () =>
+        container.getOrCreateContainer(key, new (LoroContainer as any)()),
+      autoCommit: this.getAutoCommit(),
+      batchedMutation: this.getBatchedMutation(),
+      getDoc: () => this.getDoc(),
+    }
+  }
+
+  /** Get or create a ref for a key */
+  getOrCreateRef<Shape extends ContainerShape | ValueShape>(
+    key: string,
+    shape?: Shape,
+  ): unknown {
+    const structShape = this.getShape() as StructContainerShape<NestedShapes>
+    const actualShape = shape || structShape.shapes[key]
+    const container = this.getContainer() as LoroMap
+
+    if (isValueShape(actualShape)) {
+      // 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.getBatchedMutation()) {
+        const containerValue = container.get(key)
+        if (containerValue !== undefined) {
+          return containerValue
+        }
+        // Only fall back to placeholder if the container doesn't have the value
+        const placeholder = (this.getPlaceholder() as any)?.[key]
+        if (placeholder === undefined) {
+          throw new Error("placeholder required")
+        }
+        return placeholder
+      }
+
+      // 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.propertyCache.get(key)
+      if (!ref) {
+        const containerValue = 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
+          const placeholder = (this.getPlaceholder() as any)?.[key]
+          if (placeholder === undefined) {
+            throw new Error("placeholder required")
+          }
+          ref = placeholder as Value
+        }
+        this.propertyCache.set(key, ref)
+      }
+      return ref
+    }
+
+    // Container shapes: safe to cache (handles)
+    let ref = this.propertyCache.get(key)
+    if (!ref) {
+      ref = createContainerTypedRef(
+        this.getTypedRefParams(key, actualShape as ContainerShape),
+      )
+      this.propertyCache.set(key, ref)
+    }
+
+    return ref as Shape extends ContainerShape ? TypedRef<Shape> : Value
+  }
+
+  /** Set a property value */
+  setPropertyValue(key: string, value: unknown): void {
+    const structShape = this.getShape() as StructContainerShape<NestedShapes>
+    const shape = structShape.shapes[key]
+    const container = this.getContainer() as LoroMap
+
+    if (!shape) {
+      throw new Error(`Unknown property: ${key}`)
+    }
+
+    if (isValueShape(shape)) {
+      container.set(key, value)
+      this.propertyCache.set(key, value as Value)
+      this.commitIfAuto()
+    } else {
+      // For container shapes, try to assign the plain value
+      const ref = this.getOrCreateRef(key, shape)
+      if (assignPlainValueToTypedRef(ref as TypedRef<any>, value)) {
+        this.commitIfAuto()
+        return
+      }
+      throw new Error(
+        "Cannot set container directly, modify the typed ref instead",
+      )
+    }
+  }
+
+  /** Delete a property */
+  deleteProperty(key: string): void {
+    const container = this.getContainer() as LoroMap
+    container.delete(key)
+    this.propertyCache.delete(key)
+    this.commitIfAuto()
+  }
+
+  /** Absorb mutated plain values back into Loro containers */
+  absorbPlainValues(): void {
+    absorbCachedPlainValues(
+      this.propertyCache,
+      () => this.getContainer() as LoroMap,
+    )
+  }
+
+  /** Create the loro namespace for struct */
+  protected override createLoroNamespace(): LoroMapRef {
+    const self = this
+    return {
+      get doc(): LoroDoc {
+        return self.getDoc()
+      },
+      get container(): LoroMap {
+        return self.getContainer() as LoroMap
+      },
+      subscribe(callback: (event: unknown) => void): Subscription {
+        return (self.getContainer() as LoroMap).subscribe(callback)
+      },
+      setContainer(key: string, container: Container): Container {
+        const result = (self.getContainer() as LoroMap).setContainer(
+          key,
+          container,
+        )
+        self.commitIfAuto()
+        return result
+      },
+    }
+  }
+}