@loro-extended/change 5.3.0 → 5.4.0

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

@@ -1,6 +1,7 @@
 import type {
   Container,
   LoroDoc,
+  LoroEventBatch,
   LoroMap,
   Subscription,
   Value,
@@ -166,9 +167,10 @@ export class RecordRefInternals<
     } else {
       // For container shapes, try to assign the plain value
       // Use getOrCreateRef to ensure the container is created
+      // assignPlainValueToTypedRef handles batching and commits internally
       const ref = this.getOrCreateRef(key)
       if (assignPlainValueToTypedRef(ref as TypedRef<any>, value)) {
-        this.commitIfAuto()
+        // Don't call commitIfAuto here - assignPlainValueToTypedRef handles it
         return
       }
       throw new Error(
@@ -185,6 +187,106 @@ export class RecordRefInternals<
     this.commitIfAuto()
   }
 
+  /**
+   * Replace entire contents with new values.
+   * Keys not in `values` are removed.
+   */
+  replace(values: Record<string, any>): void {
+    const container = this.getContainer() as LoroMap
+    const currentKeys = new Set(container.keys())
+    const newKeys = new Set(Object.keys(values))
+
+    // Suppress auto-commit during batch operations
+    const wasSuppressed = this.isSuppressAutoCommit()
+    if (!wasSuppressed) {
+      this.setSuppressAutoCommit(true)
+    }
+
+    try {
+      // Delete keys that are not in the new values
+      for (const key of currentKeys) {
+        if (!newKeys.has(key)) {
+          container.delete(key)
+          this.refCache.delete(key)
+        }
+      }
+
+      // Set new/updated values
+      for (const key of newKeys) {
+        this.set(key, values[key])
+      }
+    } finally {
+      // Restore auto-commit state
+      if (!wasSuppressed) {
+        this.setSuppressAutoCommit(false)
+      }
+    }
+
+    // Commit once after all operations
+    this.commitIfAuto()
+  }
+
+  /**
+   * Merge values into record.
+   * Existing keys not in `values` are kept.
+   */
+  merge(values: Record<string, any>): void {
+    // Suppress auto-commit during batch operations
+    const wasSuppressed = this.isSuppressAutoCommit()
+    if (!wasSuppressed) {
+      this.setSuppressAutoCommit(true)
+    }
+
+    try {
+      // Set new/updated values (no deletions)
+      for (const key of Object.keys(values)) {
+        this.set(key, values[key])
+      }
+    } finally {
+      // Restore auto-commit state
+      if (!wasSuppressed) {
+        this.setSuppressAutoCommit(false)
+      }
+    }
+
+    // Commit once after all operations
+    this.commitIfAuto()
+  }
+
+  /**
+   * Remove all entries from the record.
+   */
+  clear(): void {
+    const container = this.getContainer() as LoroMap
+    const keys = container.keys()
+
+    if (keys.length === 0) {
+      return // No-op on empty record
+    }
+
+    // Suppress auto-commit during batch operations
+    const wasSuppressed = this.isSuppressAutoCommit()
+    if (!wasSuppressed) {
+      this.setSuppressAutoCommit(true)
+    }
+
+    try {
+      // Delete all keys
+      for (const key of keys) {
+        container.delete(key)
+        this.refCache.delete(key)
+      }
+    } finally {
+      // Restore auto-commit state
+      if (!wasSuppressed) {
+        this.setSuppressAutoCommit(false)
+      }
+    }
+
+    // Commit once after all operations
+    this.commitIfAuto()
+  }
+
   /** Absorb mutated plain values back into Loro containers */
   absorbPlainValues(): void {
     absorbCachedPlainValues(this.refCache, () => this.getContainer() as LoroMap)
@@ -200,7 +302,7 @@ export class RecordRefInternals<
       get container(): LoroMap {
         return self.getContainer() as LoroMap
       },
-      subscribe(callback: (event: unknown) => void): Subscription {
+      subscribe(callback: (event: LoroEventBatch) => void): Subscription {
         return (self.getContainer() as LoroMap).subscribe(callback)
       },
       setContainer(key: string, container: Container): Container {

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

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest"
 import { change } from "../functional-helpers.js"
-import { createTypedDoc, Shape } from "../index.js"
+import { createTypedDoc, loro, Shape } from "../index.js"
 
 describe("Record Types", () => {
   describe("Shape.record (Container)", () => {
@@ -405,4 +405,525 @@ describe("Record Types", () => {
       }).not.toThrow()
     })
   })
+
+  describe("RecordRef values() and entries() methods", () => {
+    it("should return properly typed values for value-shaped records", () => {
+      const schema = Shape.doc({
+        scores: Shape.record(Shape.plain.number()),
+      })
+
+      const doc = createTypedDoc(schema)
+
+      change(doc, draft => {
+        draft.scores.alice = 100
+        draft.scores.bob = 50
+      })
+
+      const values = doc.scores.values()
+      expect(values).toEqual([100, 50])
+
+      // Type check: values should be number[]
+      const _typeCheck: number[] = values
+    })
+
+    it("should return properly typed entries for value-shaped records", () => {
+      const schema = Shape.doc({
+        scores: Shape.record(Shape.plain.number()),
+      })
+
+      const doc = createTypedDoc(schema)
+
+      change(doc, draft => {
+        draft.scores.alice = 100
+        draft.scores.bob = 50
+      })
+
+      const entries = doc.scores.entries()
+      expect(entries).toEqual([
+        ["alice", 100],
+        ["bob", 50],
+      ])
+
+      // Type check: entries should be [string, number][]
+      const _typeCheck: [string, number][] = entries
+    })
+
+    it("should return properly typed refs for container-shaped records", () => {
+      const schema = Shape.doc({
+        players: Shape.record(
+          Shape.struct({
+            name: Shape.plain.string(),
+            score: Shape.plain.number(),
+          }),
+        ),
+      })
+
+      const doc = createTypedDoc(schema)
+
+      change(doc, draft => {
+        draft.players.alice = { name: "Alice", score: 100 }
+        draft.players.bob = { name: "Bob", score: 50 }
+      })
+
+      const values = doc.players.values()
+      expect(values.length).toBe(2)
+      // Values should be StructRefs that we can access properties on
+      expect(values[0].name).toBe("Alice")
+      expect(values[0].score).toBe(100)
+      expect(values[1].name).toBe("Bob")
+      expect(values[1].score).toBe(50)
+    })
+
+    it("should return properly typed entries for container-shaped records", () => {
+      const schema = Shape.doc({
+        players: Shape.record(
+          Shape.struct({
+            name: Shape.plain.string(),
+            score: Shape.plain.number(),
+          }),
+        ),
+      })
+
+      const doc = createTypedDoc(schema)
+
+      change(doc, draft => {
+        draft.players.alice = { name: "Alice", score: 100 }
+        draft.players.bob = { name: "Bob", score: 50 }
+      })
+
+      const entries = doc.players.entries()
+      expect(entries.length).toBe(2)
+      expect(entries[0][0]).toBe("alice")
+      expect(entries[0][1].name).toBe("Alice")
+      expect(entries[1][0]).toBe("bob")
+      expect(entries[1][1].name).toBe("Bob")
+    })
+
+    it("should return empty arrays for empty records", () => {
+      const schema = Shape.doc({
+        scores: Shape.record(Shape.plain.number()),
+      })
+
+      const doc = createTypedDoc(schema)
+
+      expect(doc.scores.values()).toEqual([])
+      expect(doc.scores.entries()).toEqual([])
+    })
+  })
+
+  describe("RecordRef bulk update methods", () => {
+    describe("replace()", () => {
+      it("should clear all entries when replacing with empty object", () => {
+        const schema = Shape.doc({
+          scores: Shape.record(Shape.plain.number()),
+        })
+
+        const doc = createTypedDoc(schema)
+
+        change(doc, draft => {
+          draft.scores.alice = 100
+          draft.scores.bob = 50
+        })
+
+        expect(doc.toJSON().scores).toEqual({ alice: 100, bob: 50 })
+
+        change(doc, draft => {
+          draft.scores.replace({})
+        })
+
+        expect(doc.toJSON().scores).toEqual({})
+      })
+
+      it("should add new entries", () => {
+        const schema = Shape.doc({
+          scores: Shape.record(Shape.plain.number()),
+        })
+
+        const doc = createTypedDoc(schema)
+
+        change(doc, draft => {
+          draft.scores.replace({
+            alice: 100,
+            bob: 50,
+          })
+        })
+
+        expect(doc.toJSON().scores).toEqual({ alice: 100, bob: 50 })
+      })
+
+      it("should update existing entries", () => {
+        const schema = Shape.doc({
+          scores: Shape.record(Shape.plain.number()),
+        })
+
+        const doc = createTypedDoc(schema)
+
+        change(doc, draft => {
+          draft.scores.alice = 100
+          draft.scores.bob = 50
+        })
+
+        change(doc, draft => {
+          draft.scores.replace({
+            alice: 200,
+            bob: 75,
+          })
+        })
+
+        expect(doc.toJSON().scores).toEqual({ alice: 200, bob: 75 })
+      })
+
+      it("should remove entries not in the new object", () => {
+        const schema = Shape.doc({
+          scores: Shape.record(Shape.plain.number()),
+        })
+
+        const doc = createTypedDoc(schema)
+
+        change(doc, draft => {
+          draft.scores.alice = 100
+          draft.scores.bob = 50
+          draft.scores.charlie = 25
+        })
+
+        change(doc, draft => {
+          draft.scores.replace({
+            alice: 150,
+            // bob and charlie are removed
+          })
+        })
+
+        expect(doc.toJSON().scores).toEqual({ alice: 150 })
+      })
+
+      it("should handle nested struct values", () => {
+        const schema = Shape.doc({
+          players: Shape.record(
+            Shape.struct({
+              name: Shape.plain.string(),
+              score: Shape.plain.number(),
+            }),
+          ),
+        })
+
+        const doc = createTypedDoc(schema)
+
+        change(doc, draft => {
+          draft.players.replace({
+            alice: { name: "Alice", score: 100 },
+            bob: { name: "Bob", score: 50 },
+          })
+        })
+
+        expect(doc.toJSON().players).toEqual({
+          alice: { name: "Alice", score: 100 },
+          bob: { name: "Bob", score: 50 },
+        })
+      })
+
+      it("should batch all operations into a single commit", () => {
+        const schema = Shape.doc({
+          scores: Shape.record(Shape.plain.number()),
+        })
+
+        const doc = createTypedDoc(schema)
+
+        change(doc, draft => {
+          draft.scores.alice = 100
+          draft.scores.bob = 50
+        })
+
+        // Track subscription calls
+        let subscriptionCount = 0
+        const unsub = loro(doc.scores).subscribe(() => {
+          subscriptionCount++
+        })
+
+        change(doc, draft => {
+          draft.scores.replace({
+            charlie: 75,
+            dave: 25,
+          })
+        })
+
+        // Should only have one subscription notification for the batched operation
+        expect(subscriptionCount).toBe(1)
+        unsub()
+      })
+    })
+
+    describe("merge()", () => {
+      it("should add new entries", () => {
+        const schema = Shape.doc({
+          scores: Shape.record(Shape.plain.number()),
+        })
+
+        const doc = createTypedDoc(schema)
+
+        change(doc, draft => {
+          draft.scores.merge({
+            alice: 100,
+            bob: 50,
+          })
+        })
+
+        expect(doc.toJSON().scores).toEqual({ alice: 100, bob: 50 })
+      })
+
+      it("should update existing entries", () => {
+        const schema = Shape.doc({
+          scores: Shape.record(Shape.plain.number()),
+        })
+
+        const doc = createTypedDoc(schema)
+
+        change(doc, draft => {
+          draft.scores.alice = 100
+          draft.scores.bob = 50
+        })
+
+        change(doc, draft => {
+          draft.scores.merge({
+            alice: 200,
+          })
+        })
+
+        expect(doc.toJSON().scores).toEqual({ alice: 200, bob: 50 })
+      })
+
+      it("should NOT remove entries not in the new object", () => {
+        const schema = Shape.doc({
+          scores: Shape.record(Shape.plain.number()),
+        })
+
+        const doc = createTypedDoc(schema)
+
+        change(doc, draft => {
+          draft.scores.alice = 100
+          draft.scores.bob = 50
+        })
+
+        change(doc, draft => {
+          draft.scores.merge({
+            charlie: 75,
+          })
+        })
+
+        expect(doc.toJSON().scores).toEqual({
+          alice: 100,
+          bob: 50,
+          charlie: 75,
+        })
+      })
+
+      it("should handle nested struct values", () => {
+        const schema = Shape.doc({
+          players: Shape.record(
+            Shape.struct({
+              name: Shape.plain.string(),
+              score: Shape.plain.number(),
+            }),
+          ),
+        })
+
+        const doc = createTypedDoc(schema)
+
+        change(doc, draft => {
+          draft.players.alice = { name: "Alice", score: 100 }
+        })
+
+        change(doc, draft => {
+          draft.players.merge({
+            bob: { name: "Bob", score: 50 },
+          })
+        })
+
+        expect(doc.toJSON().players).toEqual({
+          alice: { name: "Alice", score: 100 },
+          bob: { name: "Bob", score: 50 },
+        })
+      })
+
+      it("should batch all operations into a single commit", () => {
+        const schema = Shape.doc({
+          scores: Shape.record(Shape.plain.number()),
+        })
+
+        const doc = createTypedDoc(schema)
+
+        // Track subscription calls
+        let subscriptionCount = 0
+        const unsub = loro(doc.scores).subscribe(() => {
+          subscriptionCount++
+        })
+
+        change(doc, draft => {
+          draft.scores.merge({
+            alice: 100,
+            bob: 50,
+            charlie: 25,
+          })
+        })
+
+        // Should only have one subscription notification for the batched operation
+        expect(subscriptionCount).toBe(1)
+        unsub()
+      })
+    })
+
+    describe("clear()", () => {
+      it("should remove all entries", () => {
+        const schema = Shape.doc({
+          scores: Shape.record(Shape.plain.number()),
+        })
+
+        const doc = createTypedDoc(schema)
+
+        change(doc, draft => {
+          draft.scores.alice = 100
+          draft.scores.bob = 50
+          draft.scores.charlie = 25
+        })
+
+        expect(doc.toJSON().scores).toEqual({
+          alice: 100,
+          bob: 50,
+          charlie: 25,
+        })
+
+        change(doc, draft => {
+          draft.scores.clear()
+        })
+
+        expect(doc.toJSON().scores).toEqual({})
+      })
+
+      it("should be a no-op on empty record", () => {
+        const schema = Shape.doc({
+          scores: Shape.record(Shape.plain.number()),
+        })
+
+        const doc = createTypedDoc(schema)
+
+        expect(doc.toJSON().scores).toEqual({})
+
+        // Should not throw
+        change(doc, draft => {
+          draft.scores.clear()
+        })
+
+        expect(doc.toJSON().scores).toEqual({})
+      })
+
+      it("should batch all operations into a single commit", () => {
+        const schema = Shape.doc({
+          scores: Shape.record(Shape.plain.number()),
+        })
+
+        const doc = createTypedDoc(schema)
+
+        change(doc, draft => {
+          draft.scores.alice = 100
+          draft.scores.bob = 50
+          draft.scores.charlie = 25
+        })
+
+        // Track subscription calls
+        let subscriptionCount = 0
+        const unsub = loro(doc.scores).subscribe(() => {
+          subscriptionCount++
+        })
+
+        change(doc, draft => {
+          draft.scores.clear()
+        })
+
+        // Should only have one subscription notification for the batched operation
+        expect(subscriptionCount).toBe(1)
+        unsub()
+      })
+    })
+
+    describe("container-valued records", () => {
+      it("should work with replace() on record of structs", () => {
+        const schema = Shape.doc({
+          players: Shape.record(
+            Shape.struct({
+              name: Shape.plain.string(),
+              score: Shape.counter(),
+            }),
+          ),
+        })
+
+        const doc = createTypedDoc(schema)
+
+        change(doc, draft => {
+          draft.players.alice = { name: "Alice", score: 100 }
+          draft.players.bob = { name: "Bob", score: 50 }
+        })
+
+        change(doc, draft => {
+          draft.players.replace({
+            charlie: { name: "Charlie", score: 75 },
+          })
+        })
+
+        expect(doc.toJSON().players).toEqual({
+          charlie: { name: "Charlie", score: 75 },
+        })
+      })
+
+      it("should work with merge() on record of structs", () => {
+        const schema = Shape.doc({
+          players: Shape.record(
+            Shape.struct({
+              name: Shape.plain.string(),
+              score: Shape.counter(),
+            }),
+          ),
+        })
+
+        const doc = createTypedDoc(schema)
+
+        change(doc, draft => {
+          draft.players.alice = { name: "Alice", score: 100 }
+        })
+
+        change(doc, draft => {
+          draft.players.merge({
+            bob: { name: "Bob", score: 50 },
+          })
+        })
+
+        expect(doc.toJSON().players).toEqual({
+          alice: { name: "Alice", score: 100 },
+          bob: { name: "Bob", score: 50 },
+        })
+      })
+
+      it("should work with clear() on record of structs", () => {
+        const schema = Shape.doc({
+          players: Shape.record(
+            Shape.struct({
+              name: Shape.plain.string(),
+              score: Shape.counter(),
+            }),
+          ),
+        })
+
+        const doc = createTypedDoc(schema)
+
+        change(doc, draft => {
+          draft.players.alice = { name: "Alice", score: 100 }
+          draft.players.bob = { name: "Bob", score: 50 }
+        })
+
+        change(doc, draft => {
+          draft.players.clear()
+        })
+
+        expect(doc.toJSON().players).toEqual({})
+      })
+    })
+  })
 })