@loro-extended/change 2.0.0 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loro-extended/change",
-  "version": "2.0.0",
+  "version": "4.0.0",
   "description": "A schema-driven, type-safe wrapper for Loro CRDT that provides natural JavaScript syntax for collaborative data mutations",
   "author": "Duane Johnson",
   "license": "MIT",

package/src/index.ts

@@ -61,6 +61,8 @@ export type {
   Infer,
   InferMutableType,
   InferPlaceholderType,
+  // InferRaw<T> preserves type alias names (like TreeNodeJSON) in hover displays
+  InferRaw,
   Mutable,
 } from "./types.js"
 // Utility exports

package/src/overlay.ts

@@ -1,9 +1,12 @@
-import type { Value } from "loro-crdt"
+import type { TreeID, Value } from "loro-crdt"
 import { deriveShapePlaceholder } from "./derive-placeholder.js"
 import type {
   ContainerShape,
   DiscriminatedUnionValueShape,
   DocShape,
+  StructContainerShape,
+  TreeContainerShape,
+  TreeNodeJSON,
   ValueShape,
 } from "./shape.js"
 import { isObjectValue } from "./utils/type-guards.js"
@@ -110,8 +113,14 @@ export function mergeValue<Shape extends ContainerShape | ValueShape>(
 
       return result
     }
-    case "tree":
-      return crdtValue !== undefined ? crdtValue : (placeholderValue ?? [])
+    case "tree": {
+      if (crdtValue === undefined) {
+        return placeholderValue ?? []
+      }
+      // Transform Loro's native tree format to our typed format
+      const treeShape = shape as TreeContainerShape
+      return transformTreeNodes(crdtValue as any[], treeShape.shape) as any
+    }
     case "record": {
       if (!isObjectValue(crdtValue) && crdtValue !== undefined) {
         throw new Error("record crdt must be object")
@@ -206,3 +215,53 @@ function mergeDiscriminatedUnion(
 
   return mergeValue(variantShape, crdtValue, effectivePlaceholderValue as Value)
 }
+
+/**
+ * Loro's native tree node format from toJSON()
+ */
+interface LoroTreeNodeJSON {
+  id: string
+  parent: string | null
+  index: number
+  fractional_index: string
+  meta: Record<string, Value>
+  children: LoroTreeNodeJSON[]
+}
+
+/**
+ * Transforms Loro's native tree format to our typed TreeNodeJSON format.
+ * - Renames `meta` to `data`
+ * - Renames `fractional_index` to `fractionalIndex`
+ * - Applies placeholder merging to node data
+ */
+function transformTreeNodes<DataShape extends StructContainerShape>(
+  nodes: LoroTreeNodeJSON[],
+  dataShape: DataShape,
+): TreeNodeJSON<DataShape>[] {
+  const dataPlaceholder = deriveShapePlaceholder(dataShape) as Value
+
+  return nodes.map(node => transformTreeNode(node, dataShape, dataPlaceholder))
+}
+
+/**
+ * Transforms a single tree node and its children recursively.
+ */
+function transformTreeNode<DataShape extends StructContainerShape>(
+  node: LoroTreeNodeJSON,
+  dataShape: DataShape,
+  dataPlaceholder: Value,
+): TreeNodeJSON<DataShape> {
+  // Merge the node's meta (data) with the placeholder
+  const mergedData = mergeValue(dataShape, node.meta, dataPlaceholder)
+
+  return {
+    id: node.id as TreeID,
+    parent: node.parent as TreeID | null,
+    index: node.index,
+    fractionalIndex: node.fractional_index,
+    data: mergedData as DataShape["_plain"],
+    children: node.children.map(child =>
+      transformTreeNode(child, dataShape, dataPlaceholder),
+    ),
+  }
+}

package/src/shape.ts

@@ -7,6 +7,7 @@ import type {
   LoroMovableList,
   LoroText,
   LoroTree,
+  TreeID,
   Value,
 } from "loro-crdt"
 
@@ -17,6 +18,9 @@ import type { RecordRef } from "./typed-refs/record.js"
 import type { StructRef } from "./typed-refs/struct.js"
 import type { TextRef } from "./typed-refs/text.js"
 
+// Note: TreeRef is not imported here to avoid circular dependency.
+// The TreeContainerShape uses a placeholder type that gets resolved at runtime.
+
 export interface Shape<Plain, Mutable, Placeholder = Plain> {
   readonly _type: string
   readonly _plain: Plain
@@ -59,11 +63,48 @@ export interface CounterContainerShape
   extends Shape<number, CounterRef, number> {
   readonly _type: "counter"
 }
-export interface TreeContainerShape<NestedShape = ContainerOrValueShape>
-  extends Shape<any, any, never[]> {
+/**
+ * JSON representation of a tree node with typed data.
+ * Used for serialization (toJSON) of tree structures.
+ */
+export type TreeNodeJSON<DataShape extends StructContainerShape> = {
+  id: TreeID
+  parent: TreeID | null
+  index: number
+  fractionalIndex: string
+  data: DataShape["_plain"]
+  children: TreeNodeJSON<DataShape>[]
+}
+
+/**
+ * Container shape for tree (forest) structures.
+ * Each node in the tree has typed metadata stored in a LoroMap.
+ *
+ * Note: The Mutable type (second generic parameter) is `any` here to avoid
+ * circular dependency with TreeRef. The actual type is resolved at runtime
+ * and through the InferMutableType helper.
+ *
+ * @example
+ * ```typescript
+ * const StateNodeDataShape = Shape.struct({
+ *   name: Shape.text(),
+ *   facts: Shape.record(Shape.plain.any()),
+ * })
+ *
+ * const Schema = Shape.doc({
+ *   states: Shape.tree(StateNodeDataShape),
+ * })
+ * ```
+ */
+export interface TreeContainerShape<
+  DataShape extends StructContainerShape = StructContainerShape,
+> extends Shape<TreeNodeJSON<DataShape>[], any, never[]> {
   readonly _type: "tree"
-  // TODO(duane): What does a tree contain? One type, or many?
-  readonly shape: NestedShape
+  /**
+   * The shape of each node's data (metadata).
+   * This is a StructContainerShape that defines the typed properties on node.data.
+   */
+  readonly shape: DataShape
 }
 
 // Container schemas using interfaces for recursive references
@@ -469,12 +510,32 @@ export const Shape = {
     })
   },
 
-  tree: <T extends MapContainerShape | StructContainerShape>(
-    shape: T,
-  ): TreeContainerShape => ({
+  /**
+   * Creates a tree container shape for hierarchical data structures.
+   * Each node in the tree has typed metadata defined by the data shape.
+   *
+   * @example
+   * ```typescript
+   * const StateNodeDataShape = Shape.struct({
+   *   name: Shape.text(),
+   *   facts: Shape.record(Shape.plain.any()),
+   * })
+   *
+   * const Schema = Shape.doc({
+   *   states: Shape.tree(StateNodeDataShape),
+   * })
+   *
+   * doc.$.change(draft => {
+   *   const root = draft.states.createNode({ name: "idle", facts: {} })
+   *   const child = root.createNode({ name: "running", facts: {} })
+   *   child.data.name = "active"
+   * })
+   * ```
+   */
+  tree: <T extends StructContainerShape>(shape: T): TreeContainerShape<T> => ({
     _type: "tree" as const,
     shape,
-    _plain: {} as any,
+    _plain: [] as any,
     _mutable: {} as any,
     _placeholder: [] as never[],
   }),

package/src/typed-doc.ts

@@ -130,6 +130,7 @@ class TypedDocInternal<Shape extends DocShape> {
       placeholder: this.placeholder as any,
       doc: this.doc,
       autoCommit: false,
+      batchedMutation: true, // Enable value shape caching for find-and-mutate patterns
     })
     fn(draft as unknown as Mutable<Shape>)
     draft.absorbPlainValues()

package/src/typed-refs/base.ts

@@ -6,9 +6,9 @@ export type TypedRefParams<Shape extends DocShape | ContainerShape> = {
   shape: Shape
   placeholder?: Infer<Shape>
   getContainer: () => ShapeToContainer<Shape>
-  readonly?: boolean // DEPRECATED - remove in future
-  autoCommit?: boolean // NEW: auto-commit after mutations
-  getDoc?: () => LoroDoc // NEW: needed for auto-commit
+  autoCommit?: boolean // Auto-commit after mutations
+  batchedMutation?: boolean // True when inside change() block - enables value shape caching for find-and-mutate patterns
+  getDoc?: () => LoroDoc // Needed for auto-commit
 }
 
 // Base class for all typed refs
@@ -33,14 +33,14 @@ export abstract class TypedRef<Shape extends DocShape | ContainerShape> {
     return this._params.placeholder
   }
 
-  protected get readonly(): boolean {
-    return !!this._params.readonly
-  }
-
   protected get autoCommit(): boolean {
     return !!this._params.autoCommit
   }
 
+  protected get batchedMutation(): boolean {
+    return !!this._params.batchedMutation
+  }
+
   protected get doc(): LoroDoc | undefined {
     return this._params.getDoc?.()
   }
@@ -55,17 +55,6 @@ export abstract class TypedRef<Shape extends DocShape | ContainerShape> {
     }
   }
 
-  /**
-   * Throws an error if this ref is in readonly mode.
-   * Call this at the start of any mutating method.
-   * @deprecated Mutations are always allowed now; this will be removed.
-   */
-  protected assertMutable(): void {
-    if (this.readonly) {
-      throw new Error("Cannot modify readonly ref")
-    }
-  }
-
   protected get container(): ShapeToContainer<Shape> {
     if (!this._cachedContainer) {
       const container = this._params.getContainer()

package/src/typed-refs/counter.ts

@@ -16,14 +16,12 @@ export class CounterRef extends TypedRef<CounterContainerShape> {
   }
 
   increment(value: number = 1): void {
-    this.assertMutable()
     this._materialized = true
     this.container.increment(value)
     this.commitIfAuto()
   }
 
   decrement(value: number = 1): void {
-    this.assertMutable()
     this._materialized = true
     this.container.decrement(value)
     this.commitIfAuto()

package/src/typed-refs/doc.ts

@@ -2,11 +2,7 @@ import type { LoroDoc } from "loro-crdt"
 import type { Infer } from "../index.js"
 import type { ContainerShape, DocShape } from "../shape.js"
 import { TypedRef, type TypedRefParams } from "./base.js"
-import {
-  createContainerTypedRef,
-  serializeRefToJSON,
-  unwrapReadonlyPrimitive,
-} from "./utils.js"
+import { createContainerTypedRef, serializeRefToJSON } from "./utils.js"
 
 const containerGetter = {
   counter: "getCounter",
@@ -30,6 +26,7 @@ export class DocRef<Shape extends DocShape> extends TypedRef<Shape> {
     _params: Omit<TypedRefParams<Shape>, "getContainer" | "getDoc"> & {
       doc: LoroDoc
       autoCommit?: boolean
+      batchedMutation?: boolean
     },
   ) {
     super({
@@ -64,8 +61,8 @@ export class DocRef<Shape extends DocShape> extends TypedRef<Shape> {
       shape,
       placeholder: this.requiredPlaceholder[key],
       getContainer: () => getter(key),
-      readonly: this.readonly,
       autoCommit: this._params.autoCommit,
+      batchedMutation: this.batchedMutation,
       getDoc: () => this._doc,
     }
   }
@@ -74,17 +71,6 @@ export class DocRef<Shape extends DocShape> extends TypedRef<Shape> {
     key: string,
     shape: ContainerShape,
   ): TypedRef<ContainerShape> | number | string {
-    if (
-      this.readonly &&
-      (shape._type === "counter" || shape._type === "text")
-    ) {
-      // Check if the container exists in the doc without creating it
-      const shallow = this._doc.getShallowValue()
-      if (!shallow[key]) {
-        return this.requiredPlaceholder[key] as any
-      }
-    }
-
     let ref = this.propertyCache.get(key)
 
     if (!ref) {
@@ -92,10 +78,6 @@ export class DocRef<Shape extends DocShape> extends TypedRef<Shape> {
       this.propertyCache.set(key, ref)
     }
 
-    if (this.readonly) {
-      return unwrapReadonlyPrimitive(ref, shape)
-    }
-
     return ref
   }
 

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

@@ -14,7 +14,7 @@ import {
   isValueShape,
 } from "../utils/type-guards.js"
 import { TypedRef, type TypedRefParams } from "./base.js"
-import { createContainerTypedRef, unwrapReadonlyPrimitive } from "./utils.js"
+import { createContainerTypedRef } from "./utils.js"
 
 // Shared logic for list operations
 export abstract class ListRefBase<
@@ -98,8 +98,8 @@ export abstract class ListRefBase<
         }
         return containerItem
       },
-      readonly: this.readonly,
       autoCommit: this._params.autoCommit,
+      batchedMutation: this.batchedMutation,
       getDoc: this._params.getDoc,
     }
   }
@@ -152,12 +152,6 @@ export abstract class ListRefBase<
 
   // Get item for return values - returns MutableItem that can be mutated
   protected getMutableItem(index: number): any {
-    // Check if we already have a cached item for this index
-    let cachedItem = this.itemCache.get(index)
-    if (cachedItem) {
-      return cachedItem
-    }
-
     // Get the raw container item
     const containerItem = this.container.get(index)
     if (containerItem === undefined) {
@@ -165,6 +159,24 @@ export abstract class ListRefBase<
     }
 
     if (isValueShape(this.shape.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 found/filtered items persist back to the CRDT via absorbPlainValues()
+      if (!this.batchedMutation) {
+        return containerItem as MutableItem
+      }
+
+      // In batched mode (within change()), we need to cache value shapes
+      // so that mutations to found/filtered items persist back to the CRDT
+      // via absorbPlainValues() at the end of change()
+      let cachedItem = this.itemCache.get(index)
+      if (cachedItem) {
+        return cachedItem
+      }
+
       // For value shapes, we need to ensure mutations persist
       // The key insight: we must return the SAME object for the same index
       // so that mutations to filtered/found items persist back to the cache
@@ -176,28 +188,20 @@ export abstract class ListRefBase<
         // For primitives, just use the value directly
         cachedItem = containerItem
       }
-      // Only cache primitive values if NOT readonly
-      if (!this.readonly) {
-        this.itemCache.set(index, cachedItem)
-      }
+      this.itemCache.set(index, cachedItem)
       return cachedItem as MutableItem
-    } else {
-      // For container shapes, create a proper typed ref using the new pattern
+    }
+
+    // Container shapes: safe to cache (handles)
+    let cachedItem = this.itemCache.get(index)
+    if (!cachedItem) {
       cachedItem = createContainerTypedRef(
         this.getTypedRefParams(index, this.shape.shape as ContainerShape),
       )
-      // Cache container refs
       this.itemCache.set(index, cachedItem)
-
-      if (this.readonly) {
-        return unwrapReadonlyPrimitive(
-          cachedItem,
-          this.shape.shape as ContainerShape,
-        )
-      }
-
-      return cachedItem as MutableItem
     }
+
+    return cachedItem as MutableItem
   }
 
   // Array-like methods for better developer experience
@@ -301,7 +305,6 @@ export abstract class ListRefBase<
   }
 
   insert(index: number, item: Item): void {
-    this.assertMutable()
     // Update cache indices before performing the insert operation
     this.updateCacheForInsert(index)
     this.insertWithConversion(index, item)
@@ -309,7 +312,6 @@ export abstract class ListRefBase<
   }
 
   delete(index: number, len: number): void {
-    this.assertMutable()
     // Update cache indices before performing the delete operation
     this.updateCacheForDelete(index, len)
     this.container.delete(index, len)
@@ -317,20 +319,17 @@ export abstract class ListRefBase<
   }
 
   push(item: Item): void {
-    this.assertMutable()
     this.pushWithConversion(item)
     this.commitIfAuto()
   }
 
   pushContainer(container: Container): Container {
-    this.assertMutable()
     const result = this.container.pushContainer(container)
     this.commitIfAuto()
     return result
   }
 
   insertContainer(index: number, container: Container): Container {
-    this.assertMutable()
     const result = this.container.insertContainer(index, container)
     this.commitIfAuto()
     return result

package/src/typed-refs/list-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
+    })
+  })
+})