@loro-extended/change 0.5.0 → 0.7.0

package/src/change.test.ts

@@ -801,7 +801,7 @@ describe("TypedLoroDoc", () => {
       const emptyState = {
         title: "Default Title",
         count: 0,
-        items: ["default"],
+        items: [],
       }
 
       const typedDoc = createTypedDoc(schema, emptyState)
@@ -809,7 +809,7 @@ describe("TypedLoroDoc", () => {
       expect(typedDoc.value).toEqual({
         title: "Default Title",
         count: 0,
-        items: ["default"],
+        items: [],
       })
     })
 
@@ -823,7 +823,7 @@ describe("TypedLoroDoc", () => {
       const emptyState = {
         title: "Default Title",
         count: 0,
-        items: ["default"],
+        items: [],
       }
 
       const typedDoc = createTypedDoc(schema, emptyState)
@@ -835,7 +835,7 @@ describe("TypedLoroDoc", () => {
 
       expect(result.title).toBe("Hello World")
       expect(result.count).toBe(5)
-      expect(result.items).toEqual(["default"]) // Empty state preserved
+      expect(result.items).toEqual([]) // Empty state preserved
     })
 
     it("should handle nested empty state structures", () => {
@@ -855,7 +855,7 @@ describe("TypedLoroDoc", () => {
           title: "Default Title",
           metadata: {
             views: 0,
-            tags: ["default-tag"],
+            tags: [],
             author: "Anonymous",
           },
         },
@@ -873,7 +873,7 @@ describe("TypedLoroDoc", () => {
 
       expect(result.article.title).toBe("New Title")
       expect(result.article.metadata.views).toBe(10)
-      expect(result.article.metadata.tags).toEqual(["default-tag"]) // Preserved
+      expect(result.article.metadata.tags).toEqual([]) // Preserved
       expect(result.article.metadata.author).toBe("John Doe")
     })
 
@@ -973,6 +973,38 @@ describe("TypedLoroDoc", () => {
         createTypedDoc(schema, invalidEmptyState as any)
       }).toThrow()
     })
+    it("should handle null values in empty state correctly", () => {
+      const schema = Shape.doc({
+        interjection: Shape.map({
+          currentPrediction: Shape.plain.union([
+            Shape.plain.string(),
+            Shape.plain.null(),
+          ]),
+        }),
+      })
+
+      const emptyState = {
+        interjection: {
+          currentPrediction: null,
+        },
+      }
+
+      const typedDoc = createTypedDoc(schema, emptyState)
+
+      // This should not throw "empty state required"
+      expect(() => {
+        typedDoc.change(draft => {
+          // Accessing the property triggers getOrCreateNode
+          const current = draft.interjection.currentPrediction
+          expect(current).toBeNull()
+
+          // Verify we can update it
+          draft.interjection.currentPrediction = "new value"
+        })
+      }).not.toThrow()
+
+      expect(typedDoc.value.interjection.currentPrediction).toBe("new value")
+    })
   })
 
   describe("Multiple Changes", () => {

package/src/change.ts

@@ -10,14 +10,23 @@ import {
 } from "./json-patch.js"
 import { overlayEmptyState } from "./overlay.js"
 import type { DocShape } from "./shape.js"
-import type { Draft, InferPlainType } from "./types.js"
+import type { Draft, InferEmptyStateType, InferPlainType } from "./types.js"
 import { validateEmptyState } from "./validation.js"
 
 // Core TypedDoc abstraction around LoroDoc
 export class TypedDoc<Shape extends DocShape> {
+  /**
+   * Creates a new TypedDoc with the given schema and empty state.
+   *
+   * @param shape - The document schema
+   * @param emptyState - Default values for the document. For dynamic containers
+   *   (list, record, etc.), only empty values ([] or {}) are allowed. Use
+   *   `.change()` to add initial data after construction.
+   * @param doc - Optional existing LoroDoc to wrap
+   */
   constructor(
     private shape: Shape,
-    private emptyState: InferPlainType<Shape>,
+    private emptyState: InferEmptyStateType<Shape>,
     private doc: LoroDoc = new LoroDoc(),
   ) {
     validateEmptyState(emptyState, shape)
@@ -28,7 +37,7 @@ export class TypedDoc<Shape extends DocShape> {
     return overlayEmptyState(
       this.shape,
       crdtValue,
-      this.emptyState,
+      this.emptyState as any,
     ) as InferPlainType<Shape>
   }
 
@@ -36,7 +45,7 @@ export class TypedDoc<Shape extends DocShape> {
     // Reuse existing DocumentDraft system with empty state integration
     const draft = new DraftDoc({
       shape: this.shape,
-      emptyState: this.emptyState,
+      emptyState: this.emptyState as any,
       doc: this.doc,
     })
     fn(draft as unknown as Draft<Shape>)
@@ -98,7 +107,7 @@ export class TypedDoc<Shape extends DocShape> {
 // Factory function for TypedLoroDoc
 export function createTypedDoc<Shape extends DocShape>(
   shape: Shape,
-  emptyState: InferPlainType<Shape>,
+  emptyState: InferEmptyStateType<Shape>,
   existingDoc?: LoroDoc,
 ): TypedDoc<Shape> {
   return new TypedDoc<Shape>(shape, emptyState, existingDoc || new LoroDoc())

package/src/discriminated-union.test.ts

@@ -0,0 +1,246 @@
+import { describe, expect, it } from "vitest"
+import { TypedDoc } from "./change.js"
+import { mergeValue } from "./overlay.js"
+import { Shape } from "./shape.js"
+import { validateValue } from "./validation.js"
+
+describe("discriminatedUnion", () => {
+  // Define variant shapes
+  const ClientPresenceShape = Shape.plain.object({
+    type: Shape.plain.string("client"),
+    name: Shape.plain.string(),
+    input: Shape.plain.object({
+      force: Shape.plain.number(),
+      angle: Shape.plain.number(),
+    }),
+  })
+
+  const ServerPresenceShape = Shape.plain.object({
+    type: Shape.plain.string("server"),
+    cars: Shape.plain.record(
+      Shape.plain.object({
+        x: Shape.plain.number(),
+        y: Shape.plain.number(),
+      }),
+    ),
+    tick: Shape.plain.number(),
+  })
+
+  const GamePresenceSchema = Shape.plain.discriminatedUnion("type", {
+    client: ClientPresenceShape,
+    server: ServerPresenceShape,
+  })
+
+  const EmptyClientPresence = {
+    type: "client" as const,
+    name: "",
+    input: { force: 0, angle: 0 },
+  }
+
+  const EmptyServerPresence = {
+    type: "server" as const,
+    cars: {},
+    tick: 0,
+  }
+
+  it("should create a discriminated union shape", () => {
+    expect(GamePresenceSchema._type).toBe("value")
+    expect(GamePresenceSchema.valueType).toBe("discriminatedUnion")
+    expect(GamePresenceSchema.discriminantKey).toBe("type")
+    expect(GamePresenceSchema.variants).toHaveProperty("client")
+    expect(GamePresenceSchema.variants).toHaveProperty("server")
+  })
+
+  it("should merge client variant with defaults", () => {
+    const crdtValue = {
+      type: "client",
+      name: "Alice",
+      // input is missing - should use defaults
+    }
+
+    const result = mergeValue(
+      GamePresenceSchema,
+      crdtValue,
+      EmptyClientPresence,
+    )
+
+    expect(result).toEqual({
+      type: "client",
+      name: "Alice",
+      input: { force: 0, angle: 0 },
+    })
+  })
+
+  it("should merge server variant with defaults", () => {
+    const crdtValue = {
+      type: "server",
+      cars: {
+        "peer-1": { x: 100, y: 200 },
+      },
+      // tick is missing - should use defaults
+    }
+
+    const result = mergeValue(
+      GamePresenceSchema,
+      crdtValue,
+      EmptyServerPresence,
+    )
+
+    expect(result).toEqual({
+      type: "server",
+      cars: {
+        "peer-1": { x: 100, y: 200 },
+      },
+      tick: 0,
+    })
+  })
+
+  it("should use empty state discriminant when CRDT has no discriminant", () => {
+    const crdtValue = {
+      // No type field
+      name: "Bob",
+    }
+
+    const result = mergeValue(
+      GamePresenceSchema,
+      crdtValue,
+      EmptyClientPresence,
+    )
+
+    // Should use client variant based on emptyState's type
+    expect(result).toEqual({
+      type: "client",
+      name: "Bob",
+      input: { force: 0, angle: 0 },
+    })
+  })
+
+  it("should return empty state when no discriminant is available", () => {
+    const crdtValue = undefined
+    const emptyValue = EmptyClientPresence
+
+    const result = mergeValue(GamePresenceSchema, crdtValue, emptyValue)
+
+    expect(result).toEqual(EmptyClientPresence)
+  })
+
+  it("should handle nested object merging within variants", () => {
+    const crdtValue = {
+      type: "client",
+      name: "Charlie",
+      input: {
+        force: 0.5,
+        // angle is missing
+      },
+    }
+
+    const result = mergeValue(
+      GamePresenceSchema,
+      crdtValue,
+      EmptyClientPresence,
+    )
+
+    expect(result).toEqual({
+      type: "client",
+      name: "Charlie",
+      input: {
+        force: 0.5,
+        angle: 0, // Default from empty state
+      },
+    })
+  })
+
+  it("should preserve full CRDT values when all fields are present", () => {
+    const crdtValue = {
+      type: "server",
+      cars: {
+        "peer-1": { x: 50, y: 75 },
+        "peer-2": { x: 200, y: 300 },
+      },
+      tick: 42,
+    }
+
+    const result = mergeValue(
+      GamePresenceSchema,
+      crdtValue,
+      EmptyServerPresence,
+    )
+
+    expect(result).toEqual(crdtValue)
+  })
+  describe("validation", () => {
+    it("should validate a correct value for client variant", () => {
+      const value = {
+        type: "client",
+        name: "Alice",
+        input: { force: 1, angle: 90 },
+      }
+      expect(validateValue(value, GamePresenceSchema)).toEqual(value)
+    })
+
+    it("should validate a correct value for server variant", () => {
+      const value = {
+        type: "server",
+        cars: { p1: { x: 10, y: 20 } },
+        tick: 100,
+      }
+      expect(validateValue(value, GamePresenceSchema)).toEqual(value)
+    })
+
+    it("should throw an error for an invalid discriminant value", () => {
+      const value = { type: "unknown", name: "Bob" }
+      expect(() => validateValue(value, GamePresenceSchema)).toThrow(
+        'Invalid discriminant value "unknown" at path root. Expected one of: client, server',
+      )
+    })
+
+    it("should throw an error for a missing discriminant key", () => {
+      const value = { name: "Bob" }
+      expect(() => validateValue(value, GamePresenceSchema)).toThrow(
+        'Expected string for discriminant key "type" at path root, got undefined',
+      )
+    })
+
+    it("should throw an error if the value does not match the variant schema", () => {
+      const value = {
+        type: "client",
+        name: "Alice",
+        input: { force: "invalid", angle: 90 }, // force should be number
+      }
+      expect(() => validateValue(value, GamePresenceSchema)).toThrow(
+        "Expected number at path root.input.force, got string",
+      )
+    })
+
+    describe("TypedDoc integration", () => {
+      it("should allow setting a discriminated union property in a MapDraftNode", () => {
+        const DocSchema = Shape.doc({
+          state: Shape.map({
+            presence: GamePresenceSchema,
+          }),
+        })
+
+        const doc = new TypedDoc(DocSchema, {
+          state: {
+            presence: EmptyClientPresence,
+          },
+        })
+
+        doc.change(draft => {
+          // This should work now that MapDraftNode recognizes discriminatedUnion as a value shape
+          draft.state.presence = {
+            type: "server",
+            cars: { p1: { x: 10, y: 20 } },
+            tick: 100,
+          }
+        })
+
+        expect(doc.value.state.presence).toEqual({
+          type: "server",
+          cars: { p1: { x: 10, y: 20 } },
+          tick: 100,
+        })
+      })
+    })
+  })
+})

package/src/draft-nodes/map.ts

@@ -92,13 +92,13 @@ export class MapDraftNode<
         } else {
           // Only fall back to empty state if the container doesn't have the value
           const emptyState = (this.emptyState as any)?.[key]
-          if (!emptyState) {
+          if (emptyState === undefined) {
             throw new Error("empty state required")
           }
           node = emptyState as Value
         }
       }
-      if (!node) throw new Error("no container made")
+      if (node === undefined) throw new Error("no container made")
       this.propertyCache.set(key, node)
     }
 
@@ -114,6 +114,7 @@ export class MapDraftNode<
           ? value => {
               // console.log("set value", value)
               this.container.set(key, value)
+              this.propertyCache.set(key, value)
             }
           : undefined,
       })

package/src/index.ts

@@ -8,15 +8,19 @@ export type {
   ContainerType as RootContainerType,
   // Container shapes
   CounterContainerShape,
+  // Discriminated union for tagged unions
+  DiscriminatedUnionValueShape,
   // Schema node types
   DocShape,
   ListContainerShape,
   MapContainerShape,
   MovableListContainerShape,
+  ObjectValueShape,
   RecordContainerShape,
   RecordValueShape,
   TextContainerShape,
   TreeContainerShape,
+  UnionValueShape,
   // Value shapes
   ValueShape,
   // ...
@@ -25,8 +29,10 @@ export type {
 export { Shape } from "./shape.js"
 export type {
   Draft,
+  // Type inference - Infer<T> is the recommended unified helper
+  Infer,
   InferDraftType,
-  // Type inference
+  InferEmptyStateType,
   InferPlainType,
 } from "./types.js"
 // Utility exports

package/src/overlay.ts

@@ -1,5 +1,10 @@
 import type { Value } from "loro-crdt"
-import type { ContainerShape, DocShape, ValueShape } from "./shape.js"
+import type {
+  ContainerShape,
+  DiscriminatedUnionValueShape,
+  DocShape,
+  ValueShape,
+} from "./shape.js"
 import { isObjectValue } from "./utils/type-guards.js"
 
 /**
@@ -101,6 +106,55 @@ export function mergeValue<Shape extends ContainerShape | ValueShape>(
         }
         return result
       }
+
+      // Handle discriminated unions
+      if (shape._type === "value" && shape.valueType === "discriminatedUnion") {
+        return mergeDiscriminatedUnion(
+          shape as DiscriminatedUnionValueShape,
+          crdtValue,
+          emptyValue,
+        )
+      }
+
       return crdtValue ?? emptyValue
   }
 }
+
+/**
+ * Merges a discriminated union value by determining the variant from the discriminant key.
+ * Uses the emptyValue's discriminant to determine the default variant when the discriminant is missing.
+ */
+function mergeDiscriminatedUnion(
+  shape: DiscriminatedUnionValueShape,
+  crdtValue: Value,
+  emptyValue: Value,
+): Value {
+  const crdtObj = (crdtValue as Record<string, Value>) ?? {}
+  const emptyObj = (emptyValue as Record<string, Value>) ?? {}
+
+  // Get the discriminant value from CRDT, falling back to empty state
+  const discriminantValue =
+    crdtObj[shape.discriminantKey] ?? emptyObj[shape.discriminantKey]
+
+  if (typeof discriminantValue !== "string") {
+    // If no valid discriminant, return the empty state
+    return emptyValue
+  }
+
+  // Find the variant shape for this discriminant value
+  const variantShape = shape.variants[discriminantValue]
+
+  if (!variantShape) {
+    // Unknown variant - return CRDT value or empty
+    return crdtValue ?? emptyValue
+  }
+
+  // Merge using the variant's object shape
+  // If the empty state's discriminant doesn't match the current discriminant,
+  // we shouldn't use the empty state for merging as it belongs to a different variant.
+  const emptyDiscriminant = emptyObj[shape.discriminantKey]
+  const effectiveEmptyValue =
+    emptyDiscriminant === discriminantValue ? emptyValue : undefined
+
+  return mergeValue(variantShape, crdtValue, effectiveEmptyValue as Value)
+}

package/src/record.test.ts

@@ -108,7 +108,8 @@ describe("Record Types", () => {
         }),
       })
 
-      const doc = new TypedDoc(schema, { wrapper: { stats: { visits: 0 } } })
+      // Empty state must use empty record - add initial data via change()
+      const doc = new TypedDoc(schema, { wrapper: { stats: {} } })
 
       doc.change(draft => {
         draft.wrapper.stats.visits = 100