@loro-extended/change 0.9.0 → 1.0.0

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,
@@ -59,7 +59,7 @@ function convertListInput(
   const list = new LoroList()
 
   for (const item of value) {
-    const convertedItem = convertInputToNode(item, shape.shape)
+    const convertedItem = convertInputToRef(item, shape.shape)
     if (isContainer(convertedItem)) {
       list.pushContainer(convertedItem)
     } else {
@@ -85,7 +85,7 @@ function convertMovableListInput(
   const list = new LoroMovableList()
 
   for (const item of value) {
-    const convertedItem = convertInputToNode(item, shape.shape)
+    const convertedItem = convertInputToRef(item, shape.shape)
     if (isContainer(convertedItem)) {
       list.pushContainer(convertedItem)
     } else {
@@ -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
@@ -111,7 +111,7 @@ function convertMapInput(
   for (const [k, v] of Object.entries(value)) {
     const nestedSchema = shape.shapes[k]
     if (nestedSchema) {
-      const convertedValue = convertInputToNode(v, nestedSchema)
+      const convertedValue = convertInputToRef(v, nestedSchema)
       if (isContainer(convertedValue)) {
         map.setContainer(k, convertedValue)
       } else {
@@ -138,7 +138,7 @@ function convertRecordInput(
 
   const map = new LoroMap()
   for (const [k, v] of Object.entries(value)) {
-    const convertedValue = convertInputToNode(v, shape.shape)
+    const convertedValue = convertInputToRef(v, shape.shape)
     if (isContainer(convertedValue)) {
       map.setContainer(k, convertedValue)
     } else {
@@ -153,7 +153,7 @@ function convertRecordInput(
  * Main conversion function that transforms input values to appropriate CRDT containers
  * based on schema definitions
  */
-export function convertInputToNode<Shape extends ContainerOrValueShape>(
+export function convertInputToRef<Shape extends ContainerOrValueShape>(
   value: Value,
   shape: Shape,
 ): Container | Value {
@@ -186,12 +186,12 @@ export function convertInputToNode<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())
+    })
+  })
+})

package/src/functional-helpers.ts

@@ -0,0 +1,61 @@
+import type { LoroDoc } from "loro-crdt"
+import type { DocShape } from "./shape.js"
+import type { TypedDoc } from "./typed-doc.js"
+import type { Mutable } from "./types.js"
+
+/**
+ * The primary method of mutating typed documents.
+ * Batches multiple mutations into a single transaction.
+ * All changes commit together at the end.
+ *
+ * Use this for:
+ * - Find-and-mutate operations (required due to JS limitations)
+ * - Performance (fewer commits)
+ * - Atomic undo (all changes = one undo step)
+ *
+ * Returns the doc for chaining.
+ *
+ * @param doc - The TypedDoc to mutate
+ * @param fn - Function that performs mutations on the draft
+ * @returns The same TypedDoc for chaining
+ *
+ * @example
+ * ```typescript
+ * import { change } from "@loro-extended/change"
+ *
+ * // Chainable API
+ * change(doc, draft => {
+ *   draft.count.increment(10)
+ *   draft.title.update("Hello")
+ * })
+ *   .count.increment(5)  // Optional: continue mutating
+ *   .toJSON()            // Optional: get last item snapshot when needed
+ * ```
+ */
+export function change<Shape extends DocShape>(
+  doc: TypedDoc<Shape>,
+  fn: (draft: Mutable<Shape>) => void,
+): TypedDoc<Shape> {
+  return doc.$.change(fn)
+}
+
+/**
+ * Access the underlying LoroDoc for advanced operations.
+ *
+ * @param doc - The TypedDoc to unwrap
+ * @returns The underlying LoroDoc instance
+ *
+ * @example
+ * ```typescript
+ * import { getLoroDoc } from "@loro-extended/change"
+ *
+ * const loroDoc = getLoroDoc(doc)
+ * const version = loroDoc.version()
+ * loroDoc.subscribe(() => console.log("changed"))
+ * ```
+ */
+export function getLoroDoc<Shape extends DocShape>(
+  doc: TypedDoc<Shape>,
+): LoroDoc {
+  return doc.$.loroDoc
+}