@loro-extended/change 0.9.1 → 1.0.1

package/src/conversion.test.ts

@@ -298,7 +298,7 @@ describe("Conversion Functions", () => {
 
   describe("convertInputToNode - Map Conversion", () => {
     it("should convert object to LoroMap with value properties", () => {
-      const shape = Shape.map({
+      const shape = Shape.struct({
         name: Shape.plain.string(),
         age: Shape.plain.number(),
         active: Shape.plain.boolean(),
@@ -322,7 +322,7 @@ describe("Conversion Functions", () => {
     })
 
     it("should convert object to LoroMap with container properties", () => {
-      const shape = Shape.map({
+      const shape = Shape.struct({
         title: Shape.text(),
         count: Shape.counter(),
       })
@@ -343,7 +343,7 @@ describe("Conversion Functions", () => {
     })
 
     it("should handle empty object", () => {
-      const shape = Shape.map({})
+      const shape = Shape.struct({})
       const result = convertInputToRef({}, shape)
 
       expect(isLoroMap(result as any)).toBe(true)
@@ -352,7 +352,7 @@ describe("Conversion Functions", () => {
     })
 
     it("should handle object with extra properties not in schema", () => {
-      const shape = Shape.map({
+      const shape = Shape.struct({
         name: Shape.plain.string(),
       })
 
@@ -371,10 +371,10 @@ describe("Conversion Functions", () => {
     })
 
     it("should handle nested map structures", () => {
-      const shape = Shape.map({
-        user: Shape.map({
+      const shape = Shape.struct({
+        user: Shape.struct({
           name: Shape.plain.string(),
-          profile: Shape.map({
+          profile: Shape.struct({
             bio: Shape.text(),
           }),
         }),
@@ -398,7 +398,7 @@ describe("Conversion Functions", () => {
     })
 
     it("should return plain object for value shape", () => {
-      const shape = Shape.plain.object({
+      const shape = Shape.plain.struct({
         name: Shape.plain.string(),
         age: Shape.plain.number(),
       })
@@ -412,7 +412,7 @@ describe("Conversion Functions", () => {
     })
 
     it("should throw error for non-object input", () => {
-      const shape = Shape.map({
+      const shape = Shape.struct({
         name: Shape.plain.string(),
       })
 
@@ -446,7 +446,7 @@ describe("Conversion Functions", () => {
 
     it("should handle complex value shapes", () => {
       const arrayShape = Shape.plain.array(Shape.plain.string())
-      const objectShape = Shape.plain.object({
+      const objectShape = Shape.plain.struct({
         name: Shape.plain.string(),
         count: Shape.plain.number(),
       })
@@ -470,7 +470,7 @@ describe("Conversion Functions", () => {
 
   describe("convertInputToNode - Error Cases", () => {
     it("should throw error for tree type (unimplemented)", () => {
-      const shape = Shape.tree(Shape.map({}))
+      const shape = Shape.tree(Shape.struct({}))
 
       expect(() => convertInputToRef({}, shape)).toThrow(
         "tree type unimplemented",
@@ -489,9 +489,9 @@ describe("Conversion Functions", () => {
   describe("convertInputToNode - Complex Nested Structures", () => {
     it("should handle deeply nested container structures", () => {
       const shape = Shape.list(
-        Shape.map({
+        Shape.struct({
           title: Shape.text(),
-          metadata: Shape.map({
+          metadata: Shape.struct({
             views: Shape.counter(),
             tags: Shape.list(Shape.plain.string()),
           }),
@@ -523,12 +523,12 @@ describe("Conversion Functions", () => {
     })
 
     it("should handle mixed container and value types", () => {
-      const shape = Shape.map({
+      const shape = Shape.struct({
         plainString: Shape.plain.string(),
         plainArray: Shape.plain.array(Shape.plain.number()),
         loroText: Shape.text(),
         loroList: Shape.list(Shape.plain.string()),
-        nestedMap: Shape.map({
+        nestedMap: Shape.struct({
           counter: Shape.counter(),
           plainBool: Shape.plain.boolean(),
         }),
@@ -573,7 +573,7 @@ describe("Conversion Functions", () => {
 
     it("should handle movable lists with complex items", () => {
       const shape = Shape.movableList(
-        Shape.map({
+        Shape.struct({
           id: Shape.plain.string(),
           title: Shape.text(),
           completed: Shape.plain.boolean(),
@@ -604,7 +604,7 @@ describe("Conversion Functions", () => {
 
     it("should handle empty containers", () => {
       const emptyListShape = Shape.list(Shape.plain.string())
-      const emptyMapShape = Shape.map({})
+      const emptyMapShape = Shape.struct({})
       const emptyMovableListShape = Shape.movableList(Shape.plain.number())
 
       const emptyList = convertInputToRef([], emptyListShape)
@@ -662,7 +662,7 @@ describe("Conversion Functions", () => {
         input[`prop${i}`] = `value${i}`
       }
 
-      const shape = Shape.map(shapes)
+      const shape = Shape.struct(shapes)
       const result = convertInputToRef(input, shape)
 
       expect(isLoroMap(result as any)).toBe(true)
@@ -708,7 +708,7 @@ describe("Conversion Functions", () => {
 
     it("should handle recursive structures without infinite loops", () => {
       // Test that the conversion doesn't get stuck in infinite recursion
-      const shape = Shape.map({
+      const shape = Shape.struct({
         name: Shape.plain.string(),
         children: Shape.list(Shape.plain.string()), // Not recursive, but nested
       })

package/src/conversion.ts

@@ -11,11 +11,11 @@ import type {
   ArrayValueShape,
   ContainerOrValueShape,
   ListContainerShape,
-  MapContainerShape,
   MovableListContainerShape,
-  ObjectValueShape,
   RecordContainerShape,
   RecordValueShape,
+  StructContainerShape,
+  StructValueShape,
 } from "./shape.js"
 import {
   isContainer,
@@ -97,11 +97,11 @@ function convertMovableListInput(
 }
 
 /**
- * Converts object input to LoroMap container
+ * Converts object input to LoroMap container (Struct)
  */
-function convertMapInput(
+function convertStructInput(
   value: { [key: string]: Value },
-  shape: MapContainerShape | ObjectValueShape,
+  shape: StructContainerShape | StructValueShape,
 ): LoroMap | { [key: string]: Value } {
   if (!isContainerShape(shape)) {
     return value
@@ -186,12 +186,12 @@ export function convertInputToRef<Shape extends ContainerOrValueShape>(
 
       return convertMovableListInput(value, shape)
     }
-    case "map": {
+    case "struct": {
       if (!isObjectValue(value)) {
         throw new Error("object expected")
       }
 
-      return convertMapInput(value, shape)
+      return convertStructInput(value, shape)
     }
     case "record": {
       if (!isObjectValue(value)) {

package/src/derive-placeholder.test.ts

@@ -29,7 +29,7 @@ describe("derivePlaceholder", () => {
 
   it("composes nested map placeholders", () => {
     const schema = Shape.doc({
-      settings: Shape.map({
+      settings: Shape.struct({
         theme: Shape.plain.string().placeholder("dark"),
         fontSize: Shape.plain.number().placeholder(14),
       }),
@@ -65,7 +65,7 @@ describe("derivePlaceholder", () => {
 
   it("handles plain value shapes with defaults", () => {
     const schema = Shape.doc({
-      config: Shape.map({
+      config: Shape.struct({
         name: Shape.plain.string(),
         count: Shape.plain.number(),
         enabled: Shape.plain.boolean(),
@@ -85,7 +85,7 @@ describe("derivePlaceholder", () => {
 
   it("handles plain value shapes with custom placeholders", () => {
     const schema = Shape.doc({
-      config: Shape.map({
+      config: Shape.struct({
         name: Shape.plain.string().placeholder("default-name"),
         count: Shape.plain.number().placeholder(42),
         enabled: Shape.plain.boolean().placeholder(true),
@@ -103,8 +103,8 @@ describe("derivePlaceholder", () => {
 
   it("handles nested plain objects", () => {
     const schema = Shape.doc({
-      user: Shape.map({
-        profile: Shape.plain.object({
+      user: Shape.struct({
+        profile: Shape.plain.struct({
           name: Shape.plain.string().placeholder("Anonymous"),
           age: Shape.plain.number().placeholder(0),
         }),
@@ -123,7 +123,7 @@ describe("derivePlaceholder", () => {
 
   it("handles plain arrays as empty", () => {
     const schema = Shape.doc({
-      tags: Shape.map({
+      tags: Shape.struct({
         items: Shape.plain.array(Shape.plain.string()),
       }),
     })
@@ -137,7 +137,7 @@ describe("derivePlaceholder", () => {
 
   it("handles plain records as empty", () => {
     const schema = Shape.doc({
-      metadata: Shape.map({
+      metadata: Shape.struct({
         values: Shape.plain.record(Shape.plain.number()),
       }),
     })
@@ -151,7 +151,7 @@ describe("derivePlaceholder", () => {
 
   it("handles union types by deriving from first variant", () => {
     const schema = Shape.doc({
-      value: Shape.map({
+      value: Shape.struct({
         data: Shape.plain.union([Shape.plain.string(), Shape.plain.null()]),
       }),
     })
@@ -165,7 +165,7 @@ describe("derivePlaceholder", () => {
 
   it("handles union types with explicit placeholder", () => {
     const schema = Shape.doc({
-      value: Shape.map({
+      value: Shape.struct({
         data: Shape.plain
           .union([Shape.plain.string(), Shape.plain.null()])
           .placeholder(null),
@@ -191,7 +191,7 @@ describe("derivePlaceholder", () => {
 
   it("handles tree containers as empty arrays", () => {
     const schema = Shape.doc({
-      hierarchy: Shape.tree(Shape.map({ name: Shape.text() })),
+      hierarchy: Shape.tree(Shape.struct({ name: Shape.text() })),
     })
 
     expect(derivePlaceholder(schema)).toEqual({
@@ -201,11 +201,11 @@ describe("derivePlaceholder", () => {
 
   it("handles complex nested structures", () => {
     const schema = Shape.doc({
-      article: Shape.map({
+      article: Shape.struct({
         title: Shape.text().placeholder("Untitled Article"),
-        metadata: Shape.map({
+        metadata: Shape.struct({
           views: Shape.counter().placeholder(0),
-          author: Shape.plain.object({
+          author: Shape.plain.struct({
             name: Shape.plain.string().placeholder("Anonymous"),
             email: Shape.plain.string(),
           }),
@@ -231,7 +231,7 @@ describe("derivePlaceholder", () => {
 
   it("handles string literal options", () => {
     const schema = Shape.doc({
-      status: Shape.map({
+      status: Shape.struct({
         value: Shape.plain.string("active", "inactive", "pending"),
       }),
     })

package/src/derive-placeholder.ts

@@ -42,7 +42,7 @@ export function deriveShapePlaceholder(shape: ContainerOrValueShape): unknown {
       return {}
 
     // Structured container - recurse into nested shapes
-    case "map": {
+    case "struct": {
       const result: Record<string, unknown> = {}
       for (const [key, nestedShape] of Object.entries(shape.shapes)) {
         result[key] = deriveShapePlaceholder(nestedShape)
@@ -74,8 +74,8 @@ function deriveValueShapePlaceholder(shape: ValueShape): unknown {
     case "uint8array":
       return shape._placeholder
 
-    // Structured value - recurse into nested shapes (like map)
-    case "object": {
+    // Structured value - recurse into nested shapes (like struct)
+    case "struct": {
       const result: Record<string, unknown> = {}
       for (const [key, nestedShape] of Object.entries(shape.shape)) {
         result[key] = deriveValueShapePlaceholder(nestedShape)

package/src/discriminated-union-assignability.test.ts

@@ -8,35 +8,35 @@ describe("Discriminated Union Placeholder Issue", () => {
 
     const SessionPhaseSchema = Shape.plain
       .discriminatedUnion("phase", {
-        "not-started": Shape.plain.object({
+        "not-started": Shape.plain.struct({
           phase: Shape.plain.string("not-started"),
         }),
 
-        lobby: Shape.plain.object({
+        lobby: Shape.plain.struct({
           phase: Shape.plain.string("lobby"),
         }),
-        "lobby-paused": Shape.plain.object({
+        "lobby-paused": Shape.plain.struct({
           phase: Shape.plain.string("lobby-paused"),
           reason: PauseReasonSchema,
         }),
 
-        active: Shape.plain.object({
+        active: Shape.plain.struct({
           phase: Shape.plain.string("active"),
           mode: ActiveModeSchema,
         }),
-        "active-paused": Shape.plain.object({
+        "active-paused": Shape.plain.struct({
           phase: Shape.plain.string("active-paused"),
           mode: ActiveModeSchema,
           reason: PauseReasonSchema,
         }),
 
-        ended: Shape.plain.object({
+        ended: Shape.plain.struct({
           phase: Shape.plain.string("ended"),
         }),
       })
       .placeholder({ phase: "not-started" })
 
-    const PhaseTransitionSchema = Shape.map({
+    const PhaseTransitionSchema = Shape.struct({
       phase: SessionPhaseSchema,
     })
 

package/src/discriminated-union-tojson.test.ts

@@ -1,7 +1,8 @@
 import { LoroDoc, LoroMap } from "loro-crdt"
 import { describe, expect, it } from "vitest"
+import { change } from "./functional-helpers.js"
 import { Shape } from "./shape.js"
-import { createTypedDoc, TypedDoc } from "./typed-doc.js"
+import { createTypedDoc } from "./typed-doc.js"
 
 /**
  * This test file reproduces the "placeholder required" error reported by users
@@ -14,16 +15,16 @@ import { createTypedDoc, TypedDoc } from "./typed-doc.js"
  */
 describe("Record with Map entries - placeholder required bug", () => {
   // Reproduce the user's schema structure
-  const StudentTomStateSchema = Shape.map({
+  const StudentTomStateSchema = Shape.struct({
     peerId: Shape.plain.string(),
     authorName: Shape.plain.string(),
     authorColor: Shape.plain.string(),
     intentionHistory: Shape.list(
-      Shape.map({
+      Shape.struct({
         observedAt: Shape.plain.number(),
         messageTimestamp: Shape.plain.number(),
         predictions: Shape.list(
-          Shape.map({
+          Shape.struct({
             horizon: Shape.plain.string("now", "soon", "future"),
             value: Shape.plain.string(),
           }),
@@ -31,11 +32,11 @@ describe("Record with Map entries - placeholder required bug", () => {
       }),
     ),
     emotionHistory: Shape.list(
-      Shape.map({
+      Shape.struct({
         observedAt: Shape.plain.number(),
         messageTimestamp: Shape.plain.number(),
         predictions: Shape.list(
-          Shape.map({
+          Shape.struct({
             horizon: Shape.plain.string("now", "soon", "future"),
             value: Shape.plain.string(),
           }),
@@ -63,16 +64,12 @@ describe("Record with Map entries - placeholder required bug", () => {
     // Note: authorColor is NOT set - this should fall back to placeholder
 
     // Now wrap it with TypedDoc
-    const typedDoc = new TypedDoc(AiStateSchema, loroDoc)
-
-    // Log the raw CRDT value
-    console.log("Raw CRDT value:", JSON.stringify(loroDoc.toJSON(), null, 2))
+    const typedDoc = createTypedDoc(AiStateSchema, loroDoc)
 
     // This should not throw "placeholder required"
     // BUG: Currently throws because the nested MapRef has placeholder: undefined
     expect(() => {
-      const json = typedDoc.value.toJSON()
-      console.log("toJSON result:", JSON.stringify(json, null, 2))
+      typedDoc.toJSON()
     }).not.toThrow()
   })
 
@@ -80,7 +77,7 @@ describe("Record with Map entries - placeholder required bug", () => {
     const typedDoc = createTypedDoc(AiStateSchema)
 
     // Add an entry via the typed API
-    typedDoc.change(draft => {
+    change(typedDoc, draft => {
       draft.tomState.set("peer-123", {
         peerId: "peer-123",
         authorName: "Alice",
@@ -92,8 +89,7 @@ describe("Record with Map entries - placeholder required bug", () => {
 
     // This should work because all values were set
     expect(() => {
-      const json = typedDoc.value.toJSON()
-      console.log("toJSON result (via change):", JSON.stringify(json, null, 2))
+      typedDoc.toJSON()
     }).not.toThrow()
   })
 
@@ -111,18 +107,11 @@ describe("Record with Map entries - placeholder required bug", () => {
     // Only set peerId - other fields are missing
     studentMap.set("peerId", "peer-456")
 
-    const typedDoc = new TypedDoc(AiStateSchema, loroDoc)
-
-    // Log what we have
-    console.log(
-      "Raw CRDT (partial):",
-      JSON.stringify(loroDoc.toJSON(), null, 2),
-    )
+    const typedDoc = createTypedDoc(AiStateSchema, loroDoc)
 
     // This should not throw - missing fields should use placeholder defaults
     expect(() => {
-      const json = typedDoc.value.toJSON()
-      console.log("toJSON (partial):", JSON.stringify(json, null, 2))
+      typedDoc.toJSON()
     }).not.toThrow()
   })
 })

package/src/discriminated-union.test.ts

@@ -1,24 +1,25 @@
 import { describe, expect, it } from "vitest"
+import { change } from "./functional-helpers.js"
 import { mergeValue } from "./overlay.js"
 import { Shape } from "./shape.js"
-import { TypedDoc } from "./typed-doc.js"
+import { createTypedDoc } from "./typed-doc.js"
 import { validateValue } from "./validation.js"
 
 describe("discriminatedUnion", () => {
   // Define variant shapes
-  const ClientPresenceShape = Shape.plain.object({
+  const ClientPresenceShape = Shape.plain.struct({
     type: Shape.plain.string("client"),
     name: Shape.plain.string(),
-    input: Shape.plain.object({
+    input: Shape.plain.struct({
       force: Shape.plain.number(),
       angle: Shape.plain.number(),
     }),
   })
 
-  const ServerPresenceShape = Shape.plain.object({
+  const ServerPresenceShape = Shape.plain.struct({
     type: Shape.plain.string("server"),
     cars: Shape.plain.record(
-      Shape.plain.object({
+      Shape.plain.struct({
         x: Shape.plain.number(),
         y: Shape.plain.number(),
       }),
@@ -215,14 +216,14 @@ describe("discriminatedUnion", () => {
     describe("TypedDoc integration", () => {
       it("should allow setting a discriminated union property in a MapDraftNode", () => {
         const DocSchema = Shape.doc({
-          state: Shape.map({
+          state: Shape.struct({
             presence: GamePresenceSchema.placeholder(EmptyClientPresence),
           }),
         })
 
-        const doc = new TypedDoc(DocSchema)
+        const doc = createTypedDoc(DocSchema)
 
-        doc.change(draft => {
+        change(doc, draft => {
           // This should work now that MapDraftNode recognizes discriminatedUnion as a value shape
           draft.state.presence = {
             type: "server",

package/src/equality.test.ts

@@ -7,13 +7,21 @@ describe("Equality Check", () => {
     counter: Shape.counter().placeholder(1),
   })
 
-  it("should compare equal to plain object", () => {
+  it("should compare CounterRef.value to plain number", () => {
     const doc = createTypedDoc(schema)
-    expect(doc.value.counter).toEqual(1)
+    // doc.counter returns a CounterRef, use .value to get the number
+    expect(doc.counter.value).toEqual(1)
   })
 
   it("should compare equal using toJSON", () => {
     const doc = createTypedDoc(schema)
     expect(doc.toJSON()).toEqual({ counter: 1 })
   })
+
+  it("should support valueOf for loose comparisons", () => {
+    const doc = createTypedDoc(schema)
+    // CounterRef has valueOf() so it can be used in arithmetic
+    expect(doc.counter.valueOf()).toBe(1)
+    expect(+doc.counter).toBe(1)
+  })
 })

package/src/functional-helpers.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it } from "vitest"
+import { change, getLoroDoc } from "./functional-helpers.js"
+import { Shape } from "./shape.js"
+import { createTypedDoc } from "./typed-doc.js"
+
+const schema = Shape.doc({
+  title: Shape.text(),
+  count: Shape.counter(),
+  users: Shape.record(
+    Shape.plain.struct({
+      name: Shape.plain.string(),
+    }),
+  ),
+})
+
+describe("functional helpers", () => {
+  describe("change()", () => {
+    it("should batch multiple mutations into a single transaction", () => {
+      const doc = createTypedDoc(schema)
+
+      change(doc, draft => {
+        draft.title.insert(0, "Hello")
+        draft.count.increment(5)
+        draft.users.set("alice", { name: "Alice" })
+      })
+
+      expect(doc.toJSON().title).toBe("Hello")
+      expect(doc.toJSON().count).toBe(5)
+      expect(doc.toJSON().users.alice).toEqual({ name: "Alice" })
+    })
+
+    it("should return the doc for chaining", () => {
+      const doc = createTypedDoc(schema)
+
+      const result = change(doc, draft => {
+        draft.title.insert(0, "Test")
+        draft.count.increment(10)
+      })
+
+      // change() returns the doc for chaining
+      expect(result).toBe(doc)
+      expect(result.toJSON().title).toBe("Test")
+      expect(result.toJSON().count).toBe(10)
+    })
+
+    it("should support chaining mutations", () => {
+      const doc = createTypedDoc(schema)
+
+      // Chain mutations after batch
+      change(doc, draft => {
+        draft.count.increment(5)
+      }).count.increment(3)
+
+      expect(doc.toJSON().count).toBe(8)
+    })
+
+    it("should support fluent API with toJSON at the end", () => {
+      const doc = createTypedDoc(schema)
+
+      // Fluent API: change -> mutate -> toJSON
+      const json = change(doc, draft => {
+        draft.title.insert(0, "Hello")
+      }).toJSON()
+
+      expect(json.title).toBe("Hello")
+    })
+
+    it("should commit all changes as one transaction", () => {
+      const doc = createTypedDoc(schema)
+      const loroDoc = getLoroDoc(doc)
+
+      const versionBefore = loroDoc.version()
+
+      change(doc, draft => {
+        draft.count.increment(1)
+        draft.count.increment(2)
+        draft.count.increment(3)
+      })
+
+      const versionAfter = loroDoc.version()
+
+      // Version should have changed (one commit)
+      expect(versionAfter).not.toEqual(versionBefore)
+      expect(doc.toJSON().count).toBe(6)
+    })
+  })
+
+  describe("getLoroDoc()", () => {
+    it("should return the underlying LoroDoc", () => {
+      const doc = createTypedDoc(schema)
+      const loroDoc = getLoroDoc(doc)
+
+      expect(loroDoc).toBeDefined()
+      expect(typeof loroDoc.version).toBe("function")
+      expect(typeof loroDoc.subscribe).toBe("function")
+    })
+
+    it("should return the same LoroDoc as doc.$.loroDoc", () => {
+      const doc = createTypedDoc(schema)
+
+      expect(getLoroDoc(doc)).toBe(doc.$.loroDoc)
+    })
+  })
+
+  describe("doc.toJSON()", () => {
+    it("should work directly on the doc", () => {
+      const doc = createTypedDoc(schema)
+
+      doc.title.insert(0, "Hello")
+      doc.count.increment(5)
+
+      const json = doc.toJSON()
+
+      expect(json.title).toBe("Hello")
+      expect(json.count).toBe(5)
+    })
+
+    it("should work on refs", () => {
+      const doc = createTypedDoc(schema)
+
+      doc.users.set("alice", { name: "Alice" })
+      doc.users.set("bob", { name: "Bob" })
+
+      // toJSON on the record ref
+      const usersJson = doc.users.toJSON()
+      expect(usersJson).toEqual({
+        alice: { name: "Alice" },
+        bob: { name: "Bob" },
+      })
+
+      // toJSON on counter ref
+      doc.count.increment(10)
+      expect(doc.count.toJSON()).toBe(10)
+
+      // toJSON on text ref
+      doc.title.insert(0, "Test")
+      expect(doc.title.toJSON()).toBe("Test")
+    })
+
+    it("should be equivalent to doc.toJSON()", () => {
+      const doc = createTypedDoc(schema)
+
+      doc.title.insert(0, "Hello")
+      doc.count.increment(5)
+
+      expect(doc.toJSON()).toEqual(doc.toJSON())
+    })
+  })
+})