@loro-extended/change 0.5.0 → 0.7.0

package/README.md

@@ -176,6 +176,76 @@ console.log(result); // Updated document state
 
 ## Advanced Usage
 
+### Discriminated Unions
+
+For type-safe tagged unions (like different message types or presence states), use `Shape.plain.discriminatedUnion()`:
+
+```typescript
+import { Shape, mergeValue } from "@loro-extended/change";
+
+// Define variant shapes - each must have the discriminant key
+const ClientPresenceShape = Shape.plain.object({
+  type: Shape.plain.string("client"), // Literal type for discrimination
+  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"), // Literal type for discrimination
+  cars: Shape.plain.record(
+    Shape.plain.object({
+      x: Shape.plain.number(),
+      y: Shape.plain.number(),
+    })
+  ),
+  tick: Shape.plain.number(),
+});
+
+// Create the discriminated union
+const GamePresenceSchema = Shape.plain.discriminatedUnion("type", {
+  client: ClientPresenceShape,
+  server: ServerPresenceShape,
+});
+
+// Empty states for each variant
+const EmptyClientPresence = {
+  type: "client" as const,
+  name: "",
+  input: { force: 0, angle: 0 },
+};
+
+const EmptyServerPresence = {
+  type: "server" as const,
+  cars: {},
+  tick: 0,
+};
+
+// Use with mergeValue for presence data
+const crdtValue = { type: "client", name: "Alice" };
+const result = mergeValue(GamePresenceSchema, crdtValue, EmptyClientPresence);
+// Result: { type: "client", name: "Alice", input: { force: 0, angle: 0 } }
+
+// Type-safe filtering
+function handlePresence(presence: typeof result) {
+  if (presence.type === "server") {
+    // TypeScript knows this is ServerPresence
+    console.log(presence.cars, presence.tick);
+  } else {
+    // TypeScript knows this is ClientPresence
+    console.log(presence.name, presence.input);
+  }
+}
+```
+
+**Key features:**
+- The discriminant key (e.g., `"type"`) determines which variant shape to use
+- Missing fields are filled from the empty state of the matching variant
+- Works seamlessly with `@loro-extended/react`'s `usePresence` hook
+- Full TypeScript support for discriminated union types
+
 ### Nested Structures
 
 Handle complex nested documents with ease:
@@ -335,6 +405,7 @@ const schema = Shape.doc({
 - `Shape.plain.record(valueShape)` - Object values with dynamic string keys
 - `Shape.plain.array(itemShape)` - Array values
 - `Shape.plain.union(shapes)` - Union of value types (e.g., `string | null`)
+- `Shape.plain.discriminatedUnion(key, variants)` - Tagged union types with a discriminant key
 
 ### TypedDoc Methods
 

package/dist/index.d.ts

@@ -1,7 +1,44 @@
 import { LoroList, LoroMovableList, Container, LoroMap, Value, LoroText, LoroCounter, LoroTree, LoroDoc } from 'loro-crdt';
 
-type InferPlainType<T> = T extends Shape<infer P, any> ? P : never;
-type InferDraftType<T> = T extends Shape<any, infer D> ? D : never;
+/**
+ * Infers the plain (JSON-serializable) type from any Shape.
+ *
+ * This is the recommended way to extract types from shapes.
+ * Works with DocShape, ContainerShape, and ValueShape.
+ *
+ * @example
+ * ```typescript
+ * const ChatSchema = Shape.doc({
+ *   messages: Shape.list(Shape.map({
+ *     id: Shape.plain.string(),
+ *     content: Shape.text(),
+ *   })),
+ * })
+ *
+ * // Extract the document type
+ * type ChatDoc = Infer<typeof ChatSchema>
+ * // Result: { messages: { id: string; content: string }[] }
+ *
+ * const PresenceSchema = Shape.plain.object({
+ *   name: Shape.plain.string(),
+ *   cursor: Shape.plain.object({ x: Shape.plain.number(), y: Shape.plain.number() }),
+ * })
+ *
+ * // Extract the presence type
+ * type Presence = Infer<typeof PresenceSchema>
+ * // Result: { name: string; cursor: { x: number; y: number } }
+ * ```
+ */
+type Infer<T> = T extends Shape<infer P, any, any> ? P : never;
+type InferPlainType<T> = T extends Shape<infer P, any, any> ? P : never;
+type InferDraftType<T> = T extends Shape<any, infer D, any> ? D : never;
+/**
+ * Extracts the valid empty state type from a shape.
+ *
+ * For dynamic containers (list, record, etc.), this will be constrained to
+ * empty values ([] or {}) to prevent users from expecting per-entry merging.
+ */
+type InferEmptyStateType<T> = T extends Shape<any, any, infer E> ? E : never;
 type Draft<T extends DocShape<Record<string, ContainerShape>>> = InferDraftType<T>;
 
 type DraftNodeParams<Shape extends DocShape | ContainerShape> = {
@@ -128,25 +165,27 @@ interface DocShape<NestedShapes extends Record<string, ContainerShape> = Record<
     [K in keyof NestedShapes]: NestedShapes[K]["_plain"];
 }, {
     [K in keyof NestedShapes]: NestedShapes[K]["_draft"];
+}, {
+    [K in keyof NestedShapes]: NestedShapes[K]["_emptyState"];
 }> {
     readonly _type: "doc";
     readonly shapes: NestedShapes;
 }
-interface TextContainerShape extends Shape<string, TextDraftNode> {
+interface TextContainerShape extends Shape<string, TextDraftNode, string> {
     readonly _type: "text";
 }
-interface CounterContainerShape extends Shape<number, CounterDraftNode> {
+interface CounterContainerShape extends Shape<number, CounterDraftNode, number> {
     readonly _type: "counter";
 }
-interface TreeContainerShape<NestedShape = ContainerOrValueShape> extends Shape<any, any> {
+interface TreeContainerShape<NestedShape = ContainerOrValueShape> extends Shape<any, any, never[]> {
     readonly _type: "tree";
     readonly shape: NestedShape;
 }
-interface ListContainerShape<NestedShape extends ContainerOrValueShape = ContainerOrValueShape> extends Shape<NestedShape["_plain"][], ListDraftNode<NestedShape>> {
+interface ListContainerShape<NestedShape extends ContainerOrValueShape = ContainerOrValueShape> extends Shape<NestedShape["_plain"][], ListDraftNode<NestedShape>, never[]> {
     readonly _type: "list";
     readonly shape: NestedShape;
 }
-interface MovableListContainerShape<NestedShape extends ContainerOrValueShape = ContainerOrValueShape> extends Shape<NestedShape["_plain"][], MovableListDraftNode<NestedShape>> {
+interface MovableListContainerShape<NestedShape extends ContainerOrValueShape = ContainerOrValueShape> extends Shape<NestedShape["_plain"][], MovableListDraftNode<NestedShape>, never[]> {
     readonly _type: "movableList";
     readonly shape: NestedShape;
 }
@@ -154,38 +193,40 @@ interface MapContainerShape<NestedShapes extends Record<string, ContainerOrValue
     [K in keyof NestedShapes]: NestedShapes[K]["_plain"];
 }, MapDraftNode<NestedShapes> & {
     [K in keyof NestedShapes]: NestedShapes[K]["_draft"];
+}, {
+    [K in keyof NestedShapes]: NestedShapes[K]["_emptyState"];
 }> {
     readonly _type: "map";
     readonly shapes: NestedShapes;
 }
-interface RecordContainerShape<NestedShape extends ContainerOrValueShape = ContainerOrValueShape> extends Shape<Record<string, NestedShape["_plain"]>, RecordDraftNode<NestedShape>> {
+interface RecordContainerShape<NestedShape extends ContainerOrValueShape = ContainerOrValueShape> extends Shape<Record<string, NestedShape["_plain"]>, RecordDraftNode<NestedShape>, Record<string, never>> {
     readonly _type: "record";
     readonly shape: NestedShape;
 }
 type ContainerShape = CounterContainerShape | ListContainerShape | MapContainerShape | MovableListContainerShape | RecordContainerShape | TextContainerShape | TreeContainerShape;
 type ContainerType = ContainerShape["_type"];
-interface StringValueShape<T extends string = string> extends Shape<T, T> {
+interface StringValueShape<T extends string = string> extends Shape<T, T, T> {
     readonly _type: "value";
     readonly valueType: "string";
     readonly options?: T[];
 }
-interface NumberValueShape extends Shape<number, number> {
+interface NumberValueShape extends Shape<number, number, number> {
     readonly _type: "value";
     readonly valueType: "number";
 }
-interface BooleanValueShape extends Shape<boolean, boolean> {
+interface BooleanValueShape extends Shape<boolean, boolean, boolean> {
     readonly _type: "value";
     readonly valueType: "boolean";
 }
-interface NullValueShape extends Shape<null, null> {
+interface NullValueShape extends Shape<null, null, null> {
     readonly _type: "value";
     readonly valueType: "null";
 }
-interface UndefinedValueShape extends Shape<undefined, undefined> {
+interface UndefinedValueShape extends Shape<undefined, undefined, undefined> {
     readonly _type: "value";
     readonly valueType: "undefined";
 }
-interface Uint8ArrayValueShape extends Shape<Uint8Array, Uint8Array> {
+interface Uint8ArrayValueShape extends Shape<Uint8Array, Uint8Array, Uint8Array> {
     readonly _type: "value";
     readonly valueType: "uint8array";
 }
@@ -193,32 +234,54 @@ interface ObjectValueShape<T extends Record<string, ValueShape> = Record<string,
     [K in keyof T]: T[K]["_plain"];
 }, {
     [K in keyof T]: T[K]["_draft"];
+}, {
+    [K in keyof T]: T[K]["_emptyState"];
 }> {
     readonly _type: "value";
     readonly valueType: "object";
     readonly shape: T;
 }
-interface RecordValueShape<T extends ValueShape = ValueShape> extends Shape<Record<string, T["_plain"]>, Record<string, T["_draft"]>> {
+interface RecordValueShape<T extends ValueShape = ValueShape> extends Shape<Record<string, T["_plain"]>, Record<string, T["_draft"]>, Record<string, never>> {
     readonly _type: "value";
     readonly valueType: "record";
     readonly shape: T;
 }
-interface ArrayValueShape<T extends ValueShape = ValueShape> extends Shape<T["_plain"][], T["_draft"][]> {
+interface ArrayValueShape<T extends ValueShape = ValueShape> extends Shape<T["_plain"][], T["_draft"][], never[]> {
     readonly _type: "value";
     readonly valueType: "array";
     readonly shape: T;
 }
-interface UnionValueShape<T extends ValueShape[] = ValueShape[]> extends Shape<T[number]["_plain"], T[number]["_draft"]> {
+interface UnionValueShape<T extends ValueShape[] = ValueShape[]> extends Shape<T[number]["_plain"], T[number]["_draft"], T[number]["_emptyState"]> {
     readonly _type: "value";
     readonly valueType: "union";
     readonly shapes: T;
 }
-type ValueShape = StringValueShape | NumberValueShape | BooleanValueShape | NullValueShape | UndefinedValueShape | Uint8ArrayValueShape | ObjectValueShape | RecordValueShape | ArrayValueShape | UnionValueShape;
+/**
+ * A discriminated union shape that uses a discriminant key to determine which variant to use.
+ * This enables type-safe handling of tagged unions like:
+ *
+ * ```typescript
+ * type GamePresence =
+ *   | { type: "client"; name: string; input: { force: number; angle: number } }
+ *   | { type: "server"; cars: Record<string, CarState>; tick: number }
+ * ```
+ *
+ * @typeParam K - The discriminant key (e.g., "type")
+ * @typeParam T - A record mapping discriminant values to their object shapes
+ */
+interface DiscriminatedUnionValueShape<K extends string = string, T extends Record<string, ObjectValueShape> = Record<string, ObjectValueShape>> extends Shape<T[keyof T]["_plain"], T[keyof T]["_draft"], T[keyof T]["_emptyState"]> {
+    readonly _type: "value";
+    readonly valueType: "discriminatedUnion";
+    readonly discriminantKey: K;
+    readonly variants: T;
+}
+type ValueShape = StringValueShape | NumberValueShape | BooleanValueShape | NullValueShape | UndefinedValueShape | Uint8ArrayValueShape | ObjectValueShape | RecordValueShape | ArrayValueShape | UnionValueShape | DiscriminatedUnionValueShape<any, any>;
 type ContainerOrValueShape = ContainerShape | ValueShape;
-interface Shape<Plain, Draft> {
+interface Shape<Plain, Draft, EmptyState = Plain> {
     readonly _type: string;
     readonly _plain: Plain;
     readonly _draft: Draft;
+    readonly _emptyState: EmptyState;
 }
 /**
  * The LoroShape factory object
@@ -247,6 +310,33 @@ declare const Shape: {
         record: <T extends ValueShape>(shape: T) => RecordValueShape<T>;
         array: <T extends ValueShape>(shape: T) => ArrayValueShape<T>;
         union: <T extends ValueShape[]>(shapes: T) => UnionValueShape<T>;
+        /**
+         * Creates a discriminated union shape for type-safe tagged unions.
+         *
+         * @example
+         * ```typescript
+         * 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,
+         * })
+         * ```
+         *
+         * @param discriminantKey - The key used to discriminate between variants (e.g., "type")
+         * @param variants - A record mapping discriminant values to their object shapes
+         */
+        discriminatedUnion: <K extends string, T extends Record<string, ObjectValueShape>>(discriminantKey: K, variants: T) => DiscriminatedUnionValueShape<K, T>;
     };
 };
 type ShapeToContainer<T extends DocShape | ContainerShape> = T extends TextContainerShape ? LoroText : T extends CounterContainerShape ? LoroCounter : T extends ListContainerShape ? LoroList : T extends MovableListContainerShape ? LoroMovableList : T extends MapContainerShape | RecordContainerShape ? LoroMap : T extends TreeContainerShape ? LoroTree : never;
@@ -291,7 +381,16 @@ declare class TypedDoc<Shape extends DocShape> {
     private shape;
     private emptyState;
     private doc;
-    constructor(shape: Shape, emptyState: InferPlainType<Shape>, doc?: LoroDoc);
+    /**
+     * 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(shape: Shape, emptyState: InferEmptyStateType<Shape>, doc?: LoroDoc);
     get value(): InferPlainType<Shape>;
     change(fn: (draft: Draft<Shape>) => void): InferPlainType<Shape>;
     /**
@@ -314,7 +413,7 @@ declare class TypedDoc<Shape extends DocShape> {
     get docShape(): Shape;
     get rawValue(): any;
 }
-declare function createTypedDoc<Shape extends DocShape>(shape: Shape, emptyState: InferPlainType<Shape>, existingDoc?: LoroDoc): TypedDoc<Shape>;
+declare function createTypedDoc<Shape extends DocShape>(shape: Shape, emptyState: InferEmptyStateType<Shape>, existingDoc?: LoroDoc): TypedDoc<Shape>;
 
 /**
  * Overlays CRDT state with empty state defaults
@@ -337,4 +436,4 @@ declare function mergeValue<Shape extends ContainerShape | ValueShape>(shape: Sh
  */
 declare function validateEmptyState<T extends DocShape>(emptyState: unknown, schema: T): InferPlainType<T>;
 
-export { type ArrayValueShape, type ContainerOrValueShape, type ContainerShape, type CounterContainerShape, type DocShape, type Draft, type InferDraftType, type InferPlainType, type ListContainerShape, type MapContainerShape, type MovableListContainerShape, type RecordContainerShape, type RecordValueShape, type ContainerType as RootContainerType, Shape, type TextContainerShape, type TreeContainerShape, TypedDoc, type ValueShape, createTypedDoc, mergeValue, overlayEmptyState, validateEmptyState };
+export { type ArrayValueShape, type ContainerOrValueShape, type ContainerShape, type CounterContainerShape, type DiscriminatedUnionValueShape, type DocShape, type Draft, type Infer, type InferDraftType, type InferEmptyStateType, type InferPlainType, type ListContainerShape, type MapContainerShape, type MovableListContainerShape, type ObjectValueShape, type RecordContainerShape, type RecordValueShape, type ContainerType as RootContainerType, Shape, type TextContainerShape, type TreeContainerShape, TypedDoc, type UnionValueShape, type ValueShape, createTypedDoc, mergeValue, overlayEmptyState, validateEmptyState };

package/dist/index.js

@@ -63,7 +63,8 @@ function isValueShape(schema) {
     "object",
     "record",
     "array",
-    "union"
+    "union",
+    "discriminatedUnion"
   ].includes(schema.valueType);
 }
 function isObjectValue(value) {
@@ -487,13 +488,13 @@ var MapDraftNode = class extends DraftNode {
           node = containerValue;
         } else {
           const emptyState = this.emptyState?.[key];
-          if (!emptyState) {
+          if (emptyState === void 0) {
             throw new Error("empty state required");
           }
           node = emptyState;
         }
       }
-      if (!node) throw new Error("no container made");
+      if (node === void 0) throw new Error("no container made");
       this.propertyCache.set(key, node);
     }
     return node;
@@ -505,6 +506,7 @@ var MapDraftNode = class extends DraftNode {
         get: () => this.getOrCreateNode(key, shape),
         set: isValueShape(shape) ? (value) => {
           this.container.set(key, value);
+          this.propertyCache.set(key, value);
         } : void 0
       });
     }
@@ -1105,9 +1107,31 @@ function mergeValue(shape, crdtValue, emptyValue) {
         }
         return result;
       }
+      if (shape._type === "value" && shape.valueType === "discriminatedUnion") {
+        return mergeDiscriminatedUnion(
+          shape,
+          crdtValue,
+          emptyValue
+        );
+      }
       return crdtValue ?? emptyValue;
   }
 }
+function mergeDiscriminatedUnion(shape, crdtValue, emptyValue) {
+  const crdtObj = crdtValue ?? {};
+  const emptyObj = emptyValue ?? {};
+  const discriminantValue = crdtObj[shape.discriminantKey] ?? emptyObj[shape.discriminantKey];
+  if (typeof discriminantValue !== "string") {
+    return emptyValue;
+  }
+  const variantShape = shape.variants[discriminantValue];
+  if (!variantShape) {
+    return crdtValue ?? emptyValue;
+  }
+  const emptyDiscriminant = emptyObj[shape.discriminantKey];
+  const effectiveEmptyValue = emptyDiscriminant === discriminantValue ? emptyValue : void 0;
+  return mergeValue(variantShape, crdtValue, effectiveEmptyValue);
+}
 
 // src/validation.ts
 function validateValue(value, schema, path = "") {
@@ -1289,6 +1313,30 @@ function validateValue(value, schema, path = "") {
           `Value at path ${currentPath} does not match any union type: ${lastError?.message}`
         );
       }
+      case "discriminatedUnion": {
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+          throw new Error(
+            `Expected object at path ${currentPath}, got ${typeof value}`
+          );
+        }
+        const unionSchema = valueSchema;
+        const discriminantKey = unionSchema.discriminantKey;
+        const discriminantValue = value[discriminantKey];
+        if (typeof discriminantValue !== "string") {
+          throw new Error(
+            `Expected string for discriminant key "${discriminantKey}" at path ${currentPath}, got ${typeof discriminantValue}`
+          );
+        }
+        const variantSchema = unionSchema.variants[discriminantValue];
+        if (!variantSchema) {
+          throw new Error(
+            `Invalid discriminant value "${discriminantValue}" at path ${currentPath}. Expected one of: ${Object.keys(
+              unionSchema.variants
+            ).join(", ")}`
+          );
+        }
+        return validateValue(value, variantSchema, currentPath);
+      }
       default:
         throw new Error(`Unknown value type: ${valueSchema.valueType}`);
     }
@@ -1309,6 +1357,15 @@ function validateEmptyState(emptyState, schema) {
 
 // src/change.ts
 var TypedDoc = class {
+  /**
+   * 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(shape, emptyState, doc = new LoroDoc()) {
     this.shape = shape;
     this.emptyState = emptyState;
@@ -1382,49 +1439,57 @@ var Shape = {
     _type: "doc",
     shapes: shape,
     _plain: {},
-    _draft: {}
+    _draft: {},
+    _emptyState: {}
   }),
   // CRDTs are represented by Loro Containers--they converge on state using Loro's
   // various CRDT algorithms
   counter: () => ({
     _type: "counter",
     _plain: 0,
-    _draft: {}
+    _draft: {},
+    _emptyState: 0
   }),
   list: (shape) => ({
     _type: "list",
     shape,
     _plain: [],
-    _draft: {}
+    _draft: {},
+    _emptyState: []
   }),
   map: (shape) => ({
     _type: "map",
     shapes: shape,
     _plain: {},
-    _draft: {}
+    _draft: {},
+    _emptyState: {}
   }),
   record: (shape) => ({
     _type: "record",
     shape,
     _plain: {},
-    _draft: {}
+    _draft: {},
+    _emptyState: {}
   }),
   movableList: (shape) => ({
     _type: "movableList",
     shape,
     _plain: [],
-    _draft: {}
+    _draft: {},
+    _emptyState: []
   }),
   text: () => ({
     _type: "text",
     _plain: "",
-    _draft: {}
+    _draft: {},
+    _emptyState: ""
   }),
   tree: (shape) => ({
     _type: "tree",
     shape,
     _plain: {},
-    _draft: {}
+    _draft: {},
+    _emptyState: []
   }),
   // Values are represented as plain JS objects, with the limitation that they MUST be
   // representable as a Loro "Value"--basically JSON. The behavior of a Value is basically
@@ -1436,58 +1501,67 @@ var Shape = {
       valueType: "string",
       _plain: options[0] ?? "",
       _draft: options[0] ?? "",
+      _emptyState: options[0] ?? "",
       options: options.length > 0 ? options : void 0
     }),
     number: () => ({
       _type: "value",
       valueType: "number",
       _plain: 0,
-      _draft: 0
+      _draft: 0,
+      _emptyState: 0
     }),
     boolean: () => ({
       _type: "value",
       valueType: "boolean",
       _plain: false,
-      _draft: false
+      _draft: false,
+      _emptyState: false
     }),
     null: () => ({
       _type: "value",
       valueType: "null",
       _plain: null,
-      _draft: null
+      _draft: null,
+      _emptyState: null
     }),
     undefined: () => ({
       _type: "value",
       valueType: "undefined",
       _plain: void 0,
-      _draft: void 0
+      _draft: void 0,
+      _emptyState: void 0
     }),
     uint8Array: () => ({
       _type: "value",
       valueType: "uint8array",
       _plain: new Uint8Array(),
-      _draft: new Uint8Array()
+      _draft: new Uint8Array(),
+      _emptyState: new Uint8Array()
     }),
     object: (shape) => ({
       _type: "value",
       valueType: "object",
       shape,
       _plain: {},
-      _draft: {}
+      _draft: {},
+      _emptyState: {}
     }),
     record: (shape) => ({
       _type: "value",
       valueType: "record",
       shape,
       _plain: {},
-      _draft: {}
+      _draft: {},
+      _emptyState: {}
     }),
     array: (shape) => ({
       _type: "value",
       valueType: "array",
       shape,
       _plain: [],
-      _draft: []
+      _draft: [],
+      _emptyState: []
     }),
     // Special value type that helps make things like `string | null` representable
     // TODO(duane): should this be a more general type for containers too?
@@ -1496,7 +1570,43 @@ var Shape = {
       valueType: "union",
       shapes,
       _plain: {},
-      _draft: {}
+      _draft: {},
+      _emptyState: {}
+    }),
+    /**
+     * Creates a discriminated union shape for type-safe tagged unions.
+     *
+     * @example
+     * ```typescript
+     * 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,
+     * })
+     * ```
+     *
+     * @param discriminantKey - The key used to discriminate between variants (e.g., "type")
+     * @param variants - A record mapping discriminant values to their object shapes
+     */
+    discriminatedUnion: (discriminantKey, variants) => ({
+      _type: "value",
+      valueType: "discriminatedUnion",
+      discriminantKey,
+      variants,
+      _plain: {},
+      _draft: {},
+      _emptyState: {}
     })
   }
 };