@loro-extended/change 0.9.1 → 1.0.1

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

@@ -5,7 +5,8 @@ import type { RecordRef } from "./record.js"
 export const recordProxyHandler: ProxyHandler<RecordRef<any>> = {
   get: (target, prop) => {
     if (typeof prop === "string" && !(prop in target)) {
-      return target.get(prop)
+      // Use getRef for reading - returns undefined for non-existent keys
+      return target.getRef(prop)
     }
     return Reflect.get(target, prop)
   },
@@ -23,6 +24,18 @@ 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") {
+      // Check if it's a method/property on the class first
+      if (prop in target) {
+        return true
+      }
+      // Otherwise check the underlying container
+      return target.has(prop)
+    }
+    return Reflect.has(target, prop)
+  },
   ownKeys: target => {
     return target.keys()
   },

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

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest"
-import { Shape, TypedDoc } from "../index.js"
+import { change } from "../functional-helpers.js"
+import { createTypedDoc, Shape } from "../index.js"
 
 describe("Record Types", () => {
   describe("Shape.record (Container)", () => {
@@ -8,9 +9,9 @@ describe("Record Types", () => {
         scores: Shape.record(Shape.counter()),
       })
 
-      const doc = new TypedDoc(schema)
+      const doc = createTypedDoc(schema)
 
-      doc.change(draft => {
+      change(doc, draft => {
         draft.scores.getOrCreateRef("alice").increment(10)
         draft.scores.getOrCreateRef("bob").increment(5)
       })
@@ -20,7 +21,7 @@ describe("Record Types", () => {
         bob: 5,
       })
 
-      doc.change(draft => {
+      change(doc, draft => {
         draft.scores.getOrCreateRef("alice").increment(5)
         draft.scores.delete("bob")
       })
@@ -35,9 +36,9 @@ describe("Record Types", () => {
         notes: Shape.record(Shape.text()),
       })
 
-      const doc = new TypedDoc(schema)
+      const doc = createTypedDoc(schema)
 
-      doc.change(draft => {
+      change(doc, draft => {
         draft.notes.getOrCreateRef("todo").insert(0, "Buy milk")
         draft.notes.getOrCreateRef("reminders").insert(0, "Call mom")
       })
@@ -53,9 +54,9 @@ describe("Record Types", () => {
         groups: Shape.record(Shape.list(Shape.plain.string())),
       })
 
-      const doc = new TypedDoc(schema)
+      const doc = createTypedDoc(schema)
 
-      doc.change(draft => {
+      change(doc, draft => {
         const groupA = draft.groups.getOrCreateRef("groupA")
         groupA.push("alice")
         groupA.push("bob")
@@ -74,14 +75,14 @@ describe("Record Types", () => {
   describe("Shape.plain.record (Value)", () => {
     it("should handle record of plain strings", () => {
       const schema = Shape.doc({
-        wrapper: Shape.map({
+        wrapper: Shape.struct({
           config: Shape.plain.record(Shape.plain.string()),
         }),
       })
 
-      const doc = new TypedDoc(schema)
+      const doc = createTypedDoc(schema)
 
-      doc.change(draft => {
+      change(doc, draft => {
         draft.wrapper.config.theme = "dark"
         draft.wrapper.config.lang = "en"
       })
@@ -91,7 +92,7 @@ describe("Record Types", () => {
         lang: "en",
       })
 
-      doc.change(draft => {
+      change(doc, draft => {
         delete draft.wrapper.config.theme
         draft.wrapper.config.lang = "fr"
       })
@@ -103,14 +104,14 @@ describe("Record Types", () => {
 
     it("should handle record of plain numbers", () => {
       const schema = Shape.doc({
-        wrapper: Shape.map({
+        wrapper: Shape.struct({
           stats: Shape.plain.record(Shape.plain.number()),
         }),
       })
 
-      const doc = new TypedDoc(schema)
+      const doc = createTypedDoc(schema)
 
-      doc.change(draft => {
+      change(doc, draft => {
         draft.wrapper.stats.visits = 100
         draft.wrapper.stats.clicks = 50
       })
@@ -123,16 +124,16 @@ describe("Record Types", () => {
 
     it("should handle nested records", () => {
       const schema = Shape.doc({
-        wrapper: Shape.map({
+        wrapper: Shape.struct({
           settings: Shape.plain.record(
             Shape.plain.record(Shape.plain.boolean()),
           ),
         }),
       })
 
-      const doc = new TypedDoc(schema)
+      const doc = createTypedDoc(schema)
 
-      doc.change(draft => {
+      change(doc, draft => {
         draft.wrapper.settings.ui = {
           darkMode: true,
           sidebar: false,
@@ -160,16 +161,16 @@ describe("Record Types", () => {
     it("should handle record of maps", () => {
       const schema = Shape.doc({
         users: Shape.record(
-          Shape.map({
+          Shape.struct({
             name: Shape.plain.string(),
             age: Shape.plain.number(),
           }),
         ),
       })
 
-      const doc = new TypedDoc(schema)
+      const doc = createTypedDoc(schema)
 
-      doc.change(draft => {
+      change(doc, draft => {
         const alice = draft.users.getOrCreateRef("u1")
         alice.name = "Alice"
         alice.age = 30
@@ -188,7 +189,7 @@ describe("Record Types", () => {
     it("should allow setting a plain object for a record with map values", () => {
       const schema = Shape.doc({
         participants: Shape.record(
-          Shape.map({
+          Shape.struct({
             id: Shape.plain.string(),
             role: Shape.plain.string(),
             name: Shape.plain.string(),
@@ -197,9 +198,9 @@ describe("Record Types", () => {
         ),
       })
 
-      const doc = new TypedDoc(schema)
+      const doc = createTypedDoc(schema)
 
-      doc.change(draft => {
+      change(doc, draft => {
         draft.participants["student-1"] = {
           id: "student-1",
           role: "student",
@@ -219,17 +220,17 @@ describe("Record Types", () => {
     it("should allow setting a plain object for a record with nested map values", () => {
       const schema = Shape.doc({
         data: Shape.record(
-          Shape.map({
-            info: Shape.map({
+          Shape.struct({
+            info: Shape.struct({
               name: Shape.plain.string(),
             }),
           }),
         ),
       })
 
-      const doc = new TypedDoc(schema)
+      const doc = createTypedDoc(schema)
 
-      doc.change(draft => {
+      change(doc, draft => {
         draft.data["item-1"] = {
           info: {
             name: "Item 1",
@@ -249,15 +250,15 @@ describe("Record Types", () => {
         histories: Shape.record(Shape.list(Shape.plain.string())),
       })
 
-      const doc = new TypedDoc(schema)
+      const doc = createTypedDoc(schema)
 
-      doc.change(draft => {
+      change(doc, draft => {
         draft.histories.user1 = ["a", "b"]
       })
 
       expect(doc.toJSON().histories.user1).toEqual(["a", "b"])
 
-      doc.change(draft => {
+      change(doc, draft => {
         // biome-ignore lint/complexity/useLiteralKeys: tests indexed assignment
         draft.histories["user1"] = ["c"]
       })
@@ -265,6 +266,70 @@ describe("Record Types", () => {
       // biome-ignore lint/complexity/useLiteralKeys: tests indexed assignment
       expect(doc.toJSON().histories["user1"]).toEqual(["c"])
     })
+
+    it("should allow setting a plain string for a record of text", () => {
+      const schema = Shape.doc({
+        notes: Shape.record(Shape.text()),
+      })
+
+      const doc = createTypedDoc(schema)
+
+      change(doc, draft => {
+        draft.notes.set("note-1", "Hello World")
+        draft.notes["note-2"] = "Another note"
+      })
+
+      expect(doc.toJSON().notes).toEqual({
+        "note-1": "Hello World",
+        "note-2": "Another note",
+      })
+    })
+
+    it("should allow setting a plain number for a record of counter", () => {
+      const schema = Shape.doc({
+        scores: Shape.record(Shape.counter()),
+      })
+
+      const doc = createTypedDoc(schema)
+
+      change(doc, draft => {
+        draft.scores.set("alice", 100)
+        draft.scores.bob = 50
+      })
+
+      expect(doc.toJSON().scores).toEqual({
+        alice: 100,
+        bob: 50,
+      })
+    })
+
+    it("should allow setting a plain object with text fields for a record of maps", () => {
+      const schema = Shape.doc({
+        users: Shape.record(
+          Shape.struct({
+            userId: Shape.plain.string(),
+            displayName: Shape.text(),
+            email: Shape.plain.string(),
+          }),
+        ),
+      })
+
+      const doc = createTypedDoc(schema)
+
+      change(doc, draft => {
+        draft.users.set("user-123", {
+          userId: "user-123",
+          displayName: "Test User",
+          email: "test@example.com",
+        })
+      })
+
+      expect(doc.toJSON().users["user-123"]).toEqual({
+        userId: "user-123",
+        displayName: "Test User",
+        email: "test@example.com",
+      })
+    })
   })
 
   describe("Readonly access to non-existent keys", () => {
@@ -273,26 +338,26 @@ describe("Record Types", () => {
       // preferences: Record<string, { showTip: boolean }>
       const schema = Shape.doc({
         preferences: Shape.record(
-          Shape.map({
+          Shape.struct({
             showTip: Shape.plain.boolean(),
           }),
         ),
       })
 
-      const doc = new TypedDoc(schema)
+      const doc = createTypedDoc(schema)
 
       // First, set a value for a specific peer
-      doc.change(d => {
+      change(doc, d => {
         d.preferences.peer1 = { showTip: true }
       })
 
       // This should work - accessing an existing key
-      expect(doc.value.preferences.peer1?.showTip).toBe(true)
+      expect(doc.preferences.peer1?.showTip).toBe(true)
 
       // Accessing a non-existent key should NOT throw "placeholder required"
       // It should return undefined so optional chaining works correctly
       expect(() => {
-        const result = doc.value.preferences.nonexistent?.showTip
+        const result = doc.preferences.nonexistent?.showTip
         return result
       }).not.toThrow()
     })
@@ -300,16 +365,16 @@ describe("Record Types", () => {
     it("should return undefined for non-existent record keys in readonly mode", () => {
       const schema = Shape.doc({
         preferences: Shape.record(
-          Shape.map({
+          Shape.struct({
             showTip: Shape.plain.boolean(),
           }),
         ),
       })
 
-      const doc = new TypedDoc(schema)
+      const doc = createTypedDoc(schema)
 
       // Access a key that doesn't exist - should return undefined
-      const prefs = doc.value.preferences.nonexistent
+      const prefs = doc.preferences.nonexistent
       expect(prefs).toBeUndefined()
     })
 
@@ -317,19 +382,19 @@ describe("Record Types", () => {
       // Exact reproduction of a user's schema and access pattern
       const schema = Shape.doc({
         preferences: Shape.record(
-          Shape.map({
+          Shape.struct({
             showTip: Shape.plain.boolean(),
           }),
         ),
       })
 
-      const doc = new TypedDoc(schema)
+      const doc = createTypedDoc(schema)
       const myPeerId = "some-peer-id"
 
       // This is the exact code pattern from the user's app:
       // doc.preferences[myPeerId]?.showTip !== false
       expect(() => {
-        const showTip = doc.value.preferences[myPeerId]?.showTip
+        const showTip = doc.preferences[myPeerId]?.showTip
         const result = showTip !== false
         return result
       }).not.toThrow()

package/src/typed-refs/record.ts

@@ -59,20 +59,34 @@ export class RecordRef<
       getContainer: () =>
         this.container.getOrCreateContainer(key, new (LoroContainer as any)()),
       readonly: this.readonly,
+      autoCommit: this._params.autoCommit,
+      getDoc: this._params.getDoc,
     }
   }
 
-  getOrCreateRef(key: string): any {
-    // For readonly mode with container shapes, check if the key exists first
+  /**
+   * Gets an existing ref for a key, or returns undefined if the key doesn't exist.
+   * Used for reading operations where we want optional chaining to work.
+   */
+  getRef(key: string): any {
+    // For container shapes, check if the key exists first
     // This allows optional chaining (?.) to work correctly for non-existent keys
-    // Similar to how ListRefBase.getMutableItem() handles non-existent indices
-    if (this.readonly && isContainerShape(this.shape.shape)) {
+    if (isContainerShape(this.shape.shape)) {
       const existing = this.container.get(key)
       if (existing === undefined) {
         return undefined
       }
     }
 
+    return this.getOrCreateRef(key)
+  }
+
+  /**
+   * Gets or creates a ref for a key.
+   * Always creates the container if it doesn't exist.
+   * 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
@@ -116,7 +130,7 @@ export class RecordRef<
   }
 
   get(key: string): InferMutableType<NestedShape> {
-    return this.getOrCreateRef(key)
+    return this.getRef(key)
   }
 
   set(key: string, value: any): void {
@@ -124,17 +138,15 @@ export class RecordRef<
     if (isValueShape(this.shape.shape)) {
       this.container.set(key, value)
       this.refCache.set(key, value)
+      this.commitIfAuto()
     } else {
-      // For containers, we can't set them directly usually.
-      // But if the user passes a plain object that matches the shape, maybe we should convert it?
-      if (value && typeof value === "object") {
-        const ref = this.getOrCreateRef(key)
-
-        if (assignPlainValueToTypedRef(ref, value)) {
-          return
-        }
+      // 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, value)) {
+        this.commitIfAuto()
+        return
       }
-
       throw new Error(
         "Cannot set container directly, modify the typed ref instead",
       )
@@ -143,13 +155,16 @@ export class RecordRef<
 
   setContainer<C extends Container>(key: string, container: C): C {
     this.assertMutable()
-    return this.container.setContainer(key, container)
+    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()
   }
 
   has(key: string): boolean {
@@ -168,12 +183,12 @@ export class RecordRef<
     return this.container.size
   }
 
-  toJSON(): Record<string, any> {
+  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, any> = {}
+      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
@@ -183,11 +198,14 @@ export class RecordRef<
           this.shape.shape,
           nativeJson[key],
           nestedPlaceholderValue as Value,
-        )
+        ) as Infer<NestedShape>
       }
       return result
     }
 
-    return serializeRefToJSON(this, this.keys())
+    return serializeRefToJSON(this, this.keys()) as Record<
+      string,
+      Infer<NestedShape>
+    >
   }
 }

package/src/typed-refs/{map.ts → struct.ts}

@@ -3,9 +3,10 @@ import { mergeValue } from "../overlay.js"
 import type {
   ContainerOrValueShape,
   ContainerShape,
-  MapContainerShape,
+  StructContainerShape,
   ValueShape,
 } from "../shape.js"
+import type { Infer } from "../types.js"
 import { isContainerShape, isValueShape } from "../utils/type-guards.js"
 import { TypedRef, type TypedRefParams } from "./base.js"
 import {
@@ -17,19 +18,22 @@ import {
   unwrapReadonlyPrimitive,
 } from "./utils.js"
 
-// Map typed ref
-export class MapRef<
+/**
+ * Typed ref for struct containers (objects with fixed keys).
+ * Uses LoroMap as the underlying container.
+ */
+export class StructRef<
   NestedShapes extends Record<string, ContainerOrValueShape>,
 > extends TypedRef<any> {
   private propertyCache = new Map<string, TypedRef<ContainerShape> | Value>()
 
-  constructor(params: TypedRefParams<MapContainerShape<NestedShapes>>) {
+  constructor(params: TypedRefParams<StructContainerShape<NestedShapes>>) {
     super(params)
     this.createLazyProperties()
   }
 
-  protected get shape(): MapContainerShape<NestedShapes> {
-    return super.shape as MapContainerShape<NestedShapes>
+  protected get shape(): StructContainerShape<NestedShapes> {
+    return super.shape as StructContainerShape<NestedShapes>
   }
 
   protected get container(): LoroMap {
@@ -54,6 +58,8 @@ export class MapRef<
       getContainer: () =>
         this.container.getOrCreateContainer(key, new (LoroContainer as any)()),
       readonly: this.readonly,
+      autoCommit: this._params.autoCommit,
+      getDoc: this._params.getDoc,
     }
   }
 
@@ -115,12 +121,10 @@ export class MapRef<
             this.container.set(key, value)
             this.propertyCache.set(key, value)
           } else {
-            if (value && typeof value === "object") {
-              const ref = this.getOrCreateRef(key, shape)
-
-              if (assignPlainValueToTypedRef(ref as TypedRef<any>, value)) {
-                return
-              }
+            // For container shapes, try to assign the plain value
+            const ref = this.getOrCreateRef(key, shape)
+            if (assignPlainValueToTypedRef(ref as TypedRef<any>, value)) {
+              return
             }
             throw new Error(
               "Cannot set container directly, modify the typed ref instead",
@@ -132,15 +136,22 @@ export class MapRef<
     }
   }
 
-  toJSON(): any {
+  toJSON(): Infer<StructContainerShape<NestedShapes>> {
     // Fast path: readonly mode
     if (this.readonly) {
       const nativeJson = this.container.toJSON() as Value
       // Overlay placeholders for missing properties
-      return mergeValue(this.shape, nativeJson, this.placeholder as Value)
+      return mergeValue(
+        this.shape,
+        nativeJson,
+        this.placeholder as Value,
+      ) as Infer<StructContainerShape<NestedShapes>>
     }
 
-    return serializeRefToJSON(this as any, Object.keys(this.shape.shapes))
+    return serializeRefToJSON(
+      this as any,
+      Object.keys(this.shape.shapes),
+    ) as Infer<StructContainerShape<NestedShapes>>
   }
 
   // TODO(duane): return correct type here
@@ -151,16 +162,20 @@ export class MapRef<
   set(key: string, value: Value): void {
     this.assertMutable()
     this.container.set(key, value)
+    this.commitIfAuto()
   }
 
   setContainer<C extends Container>(key: string, container: C): C {
     this.assertMutable()
-    return this.container.setContainer(key, container)
+    const result = this.container.setContainer(key, container)
+    this.commitIfAuto()
+    return result
   }
 
   delete(key: string): void {
     this.assertMutable()
     this.container.delete(key)
+    this.commitIfAuto()
   }
 
   has(key: string): boolean {