@loro-extended/change 3.0.0 → 5.0.0

package/src/typed-refs/list-ref-value-updates.test.ts

@@ -0,0 +1,213 @@
+import { describe, expect, it } from "vitest"
+import { change, createTypedDoc, Shape } from "../index.js"
+
+/**
+ * Tests for List value updates across multiple change() calls.
+ *
+ * ListRefBase has a different caching pattern than RecordRef/StructRef:
+ * - It caches items in itemCache
+ * - The cache is cleared in absorbPlainValues() after each change()
+ *
+ * However, there may still be stale cache issues if:
+ * 1. Items are accessed outside of change() (populating the cache)
+ * 2. Items are modified in a change() (different list instance)
+ * 3. Items are accessed again outside of change() (stale cache?)
+ *
+ * Note: Lists don't support direct item modification like records/structs.
+ * To "update" an item, you typically delete and re-insert, or modify
+ * nested container properties.
+ */
+describe("List value updates across change() calls", () => {
+  describe("primitive value lists", () => {
+    it("reads updated values after delete and insert", () => {
+      const Schema = Shape.doc({
+        numbers: Shape.list(Shape.plain.number()),
+      })
+
+      const doc = createTypedDoc(Schema)
+
+      change(doc, draft => {
+        draft.numbers.push(100)
+        draft.numbers.push(200)
+        draft.numbers.push(300)
+      })
+      expect(doc.numbers.get(0)).toBe(100)
+      expect(doc.numbers.get(1)).toBe(200)
+      expect(doc.numbers.get(2)).toBe(300)
+
+      // Modify by deleting and inserting
+      change(doc, draft => {
+        draft.numbers.delete(1, 1) // Remove 200
+        draft.numbers.insert(1, 999) // Insert 999 at position 1
+      })
+      expect(doc.numbers.get(0)).toBe(100)
+      expect(doc.numbers.get(1)).toBe(999) // Should be 999, not 200
+      expect(doc.numbers.get(2)).toBe(300)
+    })
+
+    it("reads correct values after multiple push operations", () => {
+      const Schema = Shape.doc({
+        items: Shape.list(Shape.plain.string()),
+      })
+
+      const doc = createTypedDoc(Schema)
+
+      change(doc, draft => {
+        draft.items.push("first")
+      })
+      expect(doc.items.get(0)).toBe("first")
+
+      change(doc, draft => {
+        draft.items.push("second")
+      })
+      expect(doc.items.get(0)).toBe("first")
+      expect(doc.items.get(1)).toBe("second")
+
+      change(doc, draft => {
+        draft.items.push("third")
+      })
+      expect(doc.items.get(0)).toBe("first")
+      expect(doc.items.get(1)).toBe("second")
+      expect(doc.items.get(2)).toBe("third")
+    })
+  })
+
+  describe("object value lists", () => {
+    it("reads updated object values after modification", () => {
+      const Schema = Shape.doc({
+        items: Shape.list(
+          Shape.plain.object({
+            name: Shape.plain.string(),
+            value: Shape.plain.number(),
+          }),
+        ),
+      })
+
+      const doc = createTypedDoc(Schema)
+
+      change(doc, draft => {
+        draft.items.push({ name: "item1", value: 100 })
+      })
+
+      // Access item outside of change() - this may populate cache
+      const item0 = doc.items.get(0)
+      expect(item0?.name).toBe("item1")
+      expect(item0?.value).toBe(100)
+
+      // Modify by replacing the item
+      change(doc, draft => {
+        draft.items.delete(0, 1)
+        draft.items.insert(0, { name: "updated", value: 999 })
+      })
+
+      // Read again - should see updated values
+      const item0After = doc.items.get(0)
+      expect(item0After?.name).toBe("updated")
+      expect(item0After?.value).toBe(999)
+    })
+  })
+
+  describe("list of structs (container shapes)", () => {
+    it("reads updated struct properties after modification", () => {
+      const Schema = Shape.doc({
+        users: Shape.list(
+          Shape.struct({
+            name: Shape.plain.string(),
+            age: Shape.plain.number(),
+          }),
+        ),
+      })
+
+      const doc = createTypedDoc(Schema)
+
+      change(doc, draft => {
+        draft.users.push({ name: "Alice", age: 30 })
+      })
+
+      // Access outside of change()
+      expect(doc.users.get(0)?.name).toBe("Alice")
+      expect(doc.users.get(0)?.age).toBe(30)
+
+      // Modify the struct's properties in a new change()
+      change(doc, draft => {
+        const user = draft.users.get(0)
+        if (user) {
+          user.name = "Bob"
+          user.age = 25
+        }
+      })
+
+      // Read again - should see updated values
+      // This tests if the cached StructRef returns stale values
+      expect(doc.users.get(0)?.name).toBe("Bob") // May fail due to StructRef cache
+      expect(doc.users.get(0)?.age).toBe(25) // May fail due to StructRef cache
+    })
+
+    it("handles multiple updates to same struct in list", () => {
+      const Schema = Shape.doc({
+        items: Shape.list(
+          Shape.struct({
+            count: Shape.plain.number(),
+          }),
+        ),
+      })
+
+      const doc = createTypedDoc(Schema)
+
+      change(doc, draft => {
+        draft.items.push({ count: 0 })
+      })
+
+      // Multiple updates
+      for (let i = 1; i <= 5; i++) {
+        change(doc, draft => {
+          const item = draft.items.get(0)
+          if (item) {
+            item.count = i
+          }
+        })
+        expect(doc.items.get(0)?.count).toBe(i) // May fail on i > 1
+      }
+    })
+  })
+
+  describe("toJSON() consistency", () => {
+    it("reflects updates in toJSON()", () => {
+      const Schema = Shape.doc({
+        values: Shape.list(Shape.plain.number()),
+      })
+
+      const doc = createTypedDoc(Schema)
+
+      change(doc, draft => {
+        draft.values.push(1)
+        draft.values.push(2)
+      })
+      expect(doc.toJSON().values).toEqual([1, 2])
+
+      change(doc, draft => {
+        draft.values.delete(0, 1)
+        draft.values.insert(0, 99)
+      })
+      expect(doc.toJSON().values).toEqual([99, 2])
+    })
+  })
+
+  describe("comparison with raw LoroDoc", () => {
+    it("underlying CRDT operations work correctly", async () => {
+      const { LoroDoc } = await import("loro-crdt")
+
+      const doc = new LoroDoc()
+      const list = doc.getList("items")
+
+      list.push(100)
+      doc.commit()
+      expect(list.get(0)).toBe(100)
+
+      list.delete(0, 1)
+      list.insert(0, 999)
+      doc.commit()
+      expect(list.get(0)).toBe(999) // PASSES: raw Loro works fine
+    })
+  })
+})

package/src/typed-refs/{list.ts → list-ref.ts}

@@ -1,9 +1,12 @@
-import type { LoroList } from "loro-crdt"
 import type { ContainerOrValueShape } from "../shape.js"
 import type { InferMutableType } from "../types.js"
-import { ListRefBase } from "./list-base.js"
+import type { TypedRefParams } from "./base.js"
+import { ListRefBase } from "./list-ref-base.js"
+import { ListRefInternals } from "./list-ref-internals.js"
 
-// List typed ref
+/**
+ * List typed ref - thin facade that delegates to ListRefInternals.
+ */
 export class ListRef<
   NestedShape extends ContainerOrValueShape,
 > extends ListRefBase<NestedShape> {
@@ -12,13 +15,9 @@ export class ListRef<
   // TypeScript may require type assertions for plain value assignments.
   [index: number]: InferMutableType<NestedShape> | undefined
 
-  protected get container(): LoroList {
-    return super.container as LoroList
-  }
-
-  protected absorbValueAtIndex(index: number, value: any): void {
-    // LoroList doesn't have set method, need to delete and insert
-    this.container.delete(index, 1)
-    this.container.insert(index, value)
+  protected override createInternals(
+    params: TypedRefParams<any>,
+  ): ListRefInternals<NestedShape> {
+    return new ListRefInternals(params)
   }
 }

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

@@ -0,0 +1,38 @@
+import type { LoroMovableList } from "loro-crdt"
+import type { ContainerOrValueShape } from "../shape.js"
+import { ListRefBaseInternals } from "./list-ref-base.js"
+
+// ============================================================================
+// MovableListRefInternals - Internal implementation class
+// ============================================================================
+
+/**
+ * Internal implementation for MovableListRef.
+ * Extends ListRefBaseInternals with LoroMovableList-specific methods.
+ */
+export class MovableListRefInternals<
+  NestedShape extends ContainerOrValueShape,
+  Item = NestedShape["_plain"],
+  MutableItem = NestedShape["_mutable"],
+> extends ListRefBaseInternals<NestedShape, Item, MutableItem> {
+  /** Absorb value at specific index for LoroMovableList */
+  override absorbValueAtIndex(index: number, value: unknown): void {
+    // LoroMovableList has set method
+    const container = this.getContainer() as LoroMovableList
+    container.set(index, value)
+  }
+
+  /** Move an item from one index to another */
+  move(from: number, to: number): void {
+    const container = this.getContainer() as LoroMovableList
+    container.move(from, to)
+    this.commitIfAuto()
+  }
+
+  /** Set an item at a specific index */
+  set(index: number, item: unknown): void {
+    const container = this.getContainer() as LoroMovableList
+    container.set(index, item)
+    this.commitIfAuto()
+  }
+}

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

@@ -0,0 +1,31 @@
+import type { Container } from "loro-crdt"
+import type { ContainerOrValueShape } from "../shape.js"
+import type { InferMutableType } from "../types.js"
+import { INTERNAL_SYMBOL, type TypedRefParams } from "./base.js"
+import { ListRefBase } from "./list-ref-base.js"
+import { MovableListRefInternals } from "./movable-list-ref-internals.js"
+
+/**
+ * Movable list typed ref - thin facade that delegates to MovableListRefInternals.
+ */
+export class MovableListRef<
+  NestedShape extends ContainerOrValueShape,
+  Item = NestedShape["_plain"],
+> extends ListRefBase<NestedShape> {
+  declare [INTERNAL_SYMBOL]: MovableListRefInternals<NestedShape>;
+  [index: number]: InferMutableType<NestedShape> | undefined
+
+  protected override createInternals(
+    params: TypedRefParams<any>,
+  ): MovableListRefInternals<NestedShape> {
+    return new MovableListRefInternals(params)
+  }
+
+  move(from: number, to: number): void {
+    this[INTERNAL_SYMBOL].move(from, to)
+  }
+
+  set(index: number, item: Exclude<Item, Container>) {
+    this[INTERNAL_SYMBOL].set(index, item)
+  }
+}

package/src/typed-refs/proxy-handlers.ts

@@ -1,15 +1,18 @@
-import type { ListRef } from "./list.js"
-import type { MovableListRef } from "./movable-list.js"
-import type { RecordRef } from "./record.js"
+import { INTERNAL_SYMBOL } from "./base.js"
+import type { ListRef } from "./list-ref.js"
+import type { MovableListRef } from "./movable-list-ref.js"
+import type { RecordRef } from "./record-ref.js"
+import type { RecordRefInternals } from "./record-ref-internals.js"
 
 export const recordProxyHandler: ProxyHandler<RecordRef<any>> = {
   get: (target, prop) => {
     if (typeof prop === "string" && !(prop in target)) {
       // Use getRef for reading - returns undefined for non-existent keys
-      return target.getRef(prop)
+      return (target[INTERNAL_SYMBOL] as RecordRefInternals<any>).getRef(prop)
     }
     return Reflect.get(target, prop)
   },
+
   set: (target, prop, value) => {
     if (typeof prop === "string" && !(prop in target)) {
       target.set(prop, value)
@@ -17,6 +20,7 @@ export const recordProxyHandler: ProxyHandler<RecordRef<any>> = {
     }
     return Reflect.set(target, prop, value)
   },
+
   deleteProperty: (target, prop) => {
     if (typeof prop === "string" && !(prop in target)) {
       target.delete(prop)
@@ -24,6 +28,7 @@ export const recordProxyHandler: ProxyHandler<RecordRef<any>> = {
     }
     return Reflect.deleteProperty(target, prop)
   },
+
   // Support `in` operator for checking key existence
   has: (target, prop) => {
     if (typeof prop === "string") {
@@ -36,9 +41,11 @@ export const recordProxyHandler: ProxyHandler<RecordRef<any>> = {
     }
     return Reflect.has(target, prop)
   },
+
   ownKeys: target => {
     return target.keys()
   },
+
   getOwnPropertyDescriptor: (target, prop) => {
     if (typeof prop === "string" && target.has(prop)) {
       return {
@@ -61,6 +68,7 @@ export const listProxyHandler: ProxyHandler<ListRef<any>> = {
     }
     return Reflect.get(target, prop)
   },
+
   set: (target, prop, value) => {
     if (typeof prop === "string") {
       const index = Number(prop)
@@ -85,6 +93,7 @@ export const movableListProxyHandler: ProxyHandler<MovableListRef<any>> = {
     }
     return Reflect.get(target, prop)
   },
+
   set: (target, prop, value) => {
     if (typeof prop === "string") {
       const index = Number(prop)

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

@@ -0,0 +1,216 @@
+import type {
+  Container,
+  LoroDoc,
+  LoroMap,
+  Subscription,
+  Value,
+} from "loro-crdt"
+import { deriveShapePlaceholder } from "../derive-placeholder.js"
+import type { LoroMapRef } from "../loro.js"
+import type {
+  ContainerOrValueShape,
+  ContainerShape,
+  RecordContainerShape,
+} from "../shape.js"
+import { isContainerShape, 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 RecordRef.
+ * Contains all logic, state, and implementation details.
+ */
+export class RecordRefInternals<
+  NestedShape extends ContainerOrValueShape,
+> extends BaseRefInternals<any> {
+  private refCache = new Map<string, TypedRef<ContainerShape> | Value>()
+
+  /** Get typed ref params for creating child refs at a key */
+  getTypedRefParams(
+    key: string,
+    shape: ContainerShape,
+  ): TypedRefParams<ContainerShape> {
+    // First try to get placeholder from the Record's placeholder (if it has an entry for this key)
+    let placeholder = (this.getPlaceholder() 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)
+    }
+
+    // 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 a ref for a key without creating (returns undefined for non-existent container keys) */
+  getRef(key: string): unknown {
+    const recordShape = this.getShape() as RecordContainerShape<NestedShape>
+    const shape = recordShape.shape
+    const container = this.getContainer() as LoroMap
+
+    // For container shapes, check if the key exists first
+    // This allows optional chaining (?.) to work correctly for non-existent keys
+    if (isContainerShape(shape)) {
+      const existing = container.get(key)
+      if (existing === undefined) {
+        return undefined
+      }
+    }
+
+    return this.getOrCreateRef(key)
+  }
+
+  /** Get or create a ref for a key (always creates for container shapes) */
+  getOrCreateRef(key: string): unknown {
+    const recordShape = this.getShape() as RecordContainerShape<NestedShape>
+    const shape = recordShape.shape
+    const container = this.getContainer() as LoroMap
+
+    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.getBatchedMutation()) {
+        const containerValue = container.get(key)
+        if (containerValue !== undefined) {
+          return containerValue
+        }
+        // Fall back to placeholder if the container doesn't have the value
+        const placeholder = (this.getPlaceholder() 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 = 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 {
+          // Fall back to placeholder if the container doesn't have the value
+          const placeholder = (this.getPlaceholder() as any)?.[key]
+          if (placeholder !== undefined) {
+            ref = placeholder as Value
+          } else {
+            // Fall back to the default value from the shape
+            ref = (shape as any)._plain
+          }
+        }
+        this.refCache.set(key, ref)
+      }
+      return ref
+    }
+
+    // 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
+  }
+
+  /** Set a value at a key */
+  set(key: string, value: any): void {
+    const recordShape = this.getShape() as RecordContainerShape<NestedShape>
+    const shape = recordShape.shape
+    const container = this.getContainer() as LoroMap
+
+    if (isValueShape(shape)) {
+      container.set(key, value)
+      this.refCache.set(key, value)
+      this.commitIfAuto()
+    } else {
+      // For container shapes, try to assign the plain value
+      // Use getOrCreateRef to ensure the container is created
+      const ref = this.getOrCreateRef(key)
+      if (assignPlainValueToTypedRef(ref as TypedRef<any>, value)) {
+        this.commitIfAuto()
+        return
+      }
+      throw new Error(
+        "Cannot set container directly, modify the typed ref instead",
+      )
+    }
+  }
+
+  /** Delete a key */
+  delete(key: string): void {
+    const container = this.getContainer() as LoroMap
+    container.delete(key)
+    this.refCache.delete(key)
+    this.commitIfAuto()
+  }
+
+  /** Absorb mutated plain values back into Loro containers */
+  absorbPlainValues(): void {
+    absorbCachedPlainValues(this.refCache, () => this.getContainer() as LoroMap)
+  }
+
+  /** Create the loro namespace for record */
+  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
+      },
+    }
+  }
+}