@voidhash/mimic 0.0.1-alpha.1 → 0.0.1-alpha.111

package/src/primitives/Array.ts

@@ -5,9 +5,10 @@ import * as OperationPath from "../OperationPath";
 import * as ProxyEnvironment from "../ProxyEnvironment";
 import * as Transform from "../Transform";
 import * as FractionalIndex from "../FractionalIndex";
-import type { Primitive, PrimitiveInternal, MaybeUndefined, AnyPrimitive, Validator, InferState, InferProxy, InferSnapshot } from "../Primitive";
+import type { Primitive, PrimitiveInternal, MaybeUndefined, AnyPrimitive, Validator, InferState, InferProxy, InferSnapshot, InferSetInput } from "../Primitive";
 import { ValidationError } from "../Primitive";
-import { runValidators } from "./shared";
+import { runValidators, applyDefaults } from "./shared";
+import { StructPrimitive, StructSetInput } from "./Struct";
 
 
 /**
@@ -46,15 +47,28 @@ export interface ArrayEntrySnapshot<TElement extends AnyPrimitive> {
  */
 export type ArraySnapshot<TElement extends AnyPrimitive> = readonly ArrayEntrySnapshot<TElement>[];
 
+/**
+ * Compute the input type for array element values.
+ * Uses StructSetInput directly for struct elements so that:
+ * - Fields that are required AND have no default must be provided
+ * - Fields that are optional OR have defaults can be omitted
+ * 
+ * For non-struct elements, falls back to InferSetInput.
+ */
+export type ArrayElementSetInput<TElement extends AnyPrimitive> = 
+  TElement extends StructPrimitive<infer TFields, any, any>
+    ? StructSetInput<TFields>
+    : InferSetInput<TElement>;
+
 export interface ArrayProxy<TElement extends AnyPrimitive> {
   /** Gets the current array entries (sorted by position) */
   get(): ArrayState<TElement>;
-  /** Replaces the entire array with new values (generates new IDs and positions) */
-  set(values: readonly InferState<TElement>[]): void;
-  /** Appends a value to the end of the array */
-  push(value: InferState<TElement>): void;
-  /** Inserts a value at the specified visual index */
-  insertAt(index: number, value: InferState<TElement>): void;
+  /** Replaces the entire array with new values (generates new IDs and positions, applies defaults) */
+  set(values: readonly ArrayElementSetInput<TElement>[]): void;
+  /** Appends a value to the end of the array (applies defaults for struct elements) */
+  push(value: ArrayElementSetInput<TElement>): void;
+  /** Inserts a value at the specified visual index (applies defaults for struct elements) */
+  insertAt(index: number, value: ArrayElementSetInput<TElement>): void;
   /** Removes the element with the specified ID */
   remove(id: string): void;
   /** Moves an element to a new visual index */
@@ -77,12 +91,22 @@ interface ArrayPrimitiveSchema<TElement extends AnyPrimitive> {
   readonly validators: readonly Validator<ArrayState<TElement>>[];
 }
 
-export class ArrayPrimitive<TElement extends AnyPrimitive>
-  implements Primitive<ArrayState<TElement>, ArrayProxy<TElement>>
+/** Input type for array set() - an array of element set inputs */
+export type ArraySetInput<TElement extends AnyPrimitive> = readonly ArrayElementSetInput<TElement>[];
+
+/** Input type for array update() - same as set() for arrays */
+export type ArrayUpdateInput<TElement extends AnyPrimitive> = readonly ArrayElementSetInput<TElement>[];
+
+export class ArrayPrimitive<TElement extends AnyPrimitive, TRequired extends boolean = false, THasDefault extends boolean = false>
+  implements Primitive<ArrayState<TElement>, ArrayProxy<TElement>, TRequired, THasDefault, ArraySetInput<TElement>, ArrayUpdateInput<TElement>>
 {
   readonly _tag = "ArrayPrimitive" as const;
   readonly _State!: ArrayState<TElement>;
   readonly _Proxy!: ArrayProxy<TElement>;
+  readonly _TRequired!: TRequired;
+  readonly _THasDefault!: THasDefault;
+  readonly TSetInput!: ArraySetInput<TElement>;
+  readonly TUpdateInput!: ArrayUpdateInput<TElement>;
 
   private readonly _schema: ArrayPrimitiveSchema<TElement>;
 
@@ -118,7 +142,7 @@ export class ArrayPrimitive<TElement extends AnyPrimitive>
   }
 
   /** Mark this array as required */
-  required(): ArrayPrimitive<TElement> {
+  required(): ArrayPrimitive<TElement, true, THasDefault> {
     return new ArrayPrimitive({
       ...this._schema,
       required: true,
@@ -126,7 +150,7 @@ export class ArrayPrimitive<TElement extends AnyPrimitive>
   }
 
   /** Set a default value for this array */
-  default(defaultValue: ArrayState<TElement>): ArrayPrimitive<TElement> {
+  default(defaultValue: ArrayState<TElement>): ArrayPrimitive<TElement, TRequired, true> {
     return new ArrayPrimitive({
       ...this._schema,
       defaultValue,
@@ -139,7 +163,7 @@ export class ArrayPrimitive<TElement extends AnyPrimitive>
   }
 
   /** Add a custom validation rule */
-  refine(fn: (value: ArrayState<TElement>) => boolean, message: string): ArrayPrimitive<TElement> {
+  refine(fn: (value: ArrayState<TElement>) => boolean, message: string): ArrayPrimitive<TElement, TRequired, THasDefault> {
     return new ArrayPrimitive({
       ...this._schema,
       validators: [...this._schema.validators, { validate: fn, message }],
@@ -147,7 +171,7 @@ export class ArrayPrimitive<TElement extends AnyPrimitive>
   }
 
   /** Minimum array length */
-  minLength(length: number): ArrayPrimitive<TElement> {
+  minLength(length: number): ArrayPrimitive<TElement, TRequired, THasDefault> {
     return this.refine(
       (v) => v.length >= length,
       `Array must have at least ${length} elements`
@@ -155,7 +179,7 @@ export class ArrayPrimitive<TElement extends AnyPrimitive>
   }
 
   /** Maximum array length */
-  maxLength(length: number): ArrayPrimitive<TElement> {
+  maxLength(length: number): ArrayPrimitive<TElement, TRequired, THasDefault> {
     return this.refine(
       (v) => v.length <= length,
       `Array must have at most ${length} elements`
@@ -173,12 +197,17 @@ export class ArrayPrimitive<TElement extends AnyPrimitive>
         return sortByPos(state);
       };
 
+      // Helper to apply defaults for element values
+      const applyElementDefaults = (value: ArrayElementSetInput<TElement>): InferState<TElement> => {
+        return applyDefaults(elementPrimitive, value as Partial<InferState<TElement>>) as InferState<TElement>;
+      };
+
       return {
         get: (): ArrayState<TElement> => {
           return getCurrentState();
         },
 
-        set: (values: readonly InferState<TElement>[]) => {
+        set: (values: readonly ArrayElementSetInput<TElement>[]) => {
           // Generate entries with new IDs and sequential positions
           const entries: ArrayEntry<InferState<TElement>>[] = [];
           let prevPos: string | null = null;
@@ -186,7 +215,9 @@ export class ArrayPrimitive<TElement extends AnyPrimitive>
           for (const value of values) {
             const id = env.generateId();
             const pos = generatePosBetween(prevPos, null);
-            entries.push({ id, pos, value });
+            // Apply defaults to element value
+            const mergedValue = applyElementDefaults(value);
+            entries.push({ id, pos, value: mergedValue });
             prevPos = pos;
           }
           
@@ -195,27 +226,31 @@ export class ArrayPrimitive<TElement extends AnyPrimitive>
           );
         },
 
-        push: (value: InferState<TElement>) => {
+        push: (value: ArrayElementSetInput<TElement>) => {
           const sorted = getCurrentState();
           const lastPos = sorted.length > 0 ? sorted[sorted.length - 1]!.pos : null;
           const id = env.generateId();
           const pos = generatePosBetween(lastPos, null);
+          // Apply defaults to element value
+          const mergedValue = applyElementDefaults(value);
           
           env.addOperation(
-            Operation.fromDefinition(operationPath, this._opDefinitions.insert, { id, pos, value })
+            Operation.fromDefinition(operationPath, this._opDefinitions.insert, { id, pos, value: mergedValue })
           );
         },
 
-        insertAt: (index: number, value: InferState<TElement>) => {
+        insertAt: (index: number, value: ArrayElementSetInput<TElement>) => {
           const sorted = getCurrentState();
           const leftPos = index > 0 && sorted[index - 1] ? sorted[index - 1]!.pos : null;
           const rightPos = index < sorted.length && sorted[index] ? sorted[index]!.pos : null;
           
           const id = env.generateId();
           const pos = generatePosBetween(leftPos, rightPos);
+          // Apply defaults to element value
+          const mergedValue = applyElementDefaults(value);
           
           env.addOperation(
-            Operation.fromDefinition(operationPath, this._opDefinitions.insert, { id, pos, value })
+            Operation.fromDefinition(operationPath, this._opDefinitions.insert, { id, pos, value: mergedValue })
           );
         },
 
@@ -452,6 +487,6 @@ export class ArrayPrimitive<TElement extends AnyPrimitive>
 }
 
 /** Creates a new ArrayPrimitive with the given element type */
-export const Array = <TElement extends AnyPrimitive>(element: TElement): ArrayPrimitive<TElement> =>
+export const Array = <TElement extends AnyPrimitive>(element: TElement): ArrayPrimitive<TElement, false, false> =>
   new ArrayPrimitive({ required: false, defaultValue: undefined, element, validators: [] });
 

package/src/primitives/Boolean.ts

@@ -4,17 +4,22 @@ import * as Operation from "../Operation";
 import * as OperationPath from "../OperationPath";
 import * as ProxyEnvironment from "../ProxyEnvironment";
 import * as Transform from "../Transform";
-import type { Primitive, PrimitiveInternal, MaybeUndefined, Validator } from "./shared";
+import type { Primitive, PrimitiveInternal, MaybeUndefined, Validator, NeedsValue } from "./shared";
 import { runValidators, isCompatibleOperation, ValidationError } from "./shared";
 
 
-export interface BooleanProxy<TDefined extends boolean = false> {
+type InferSetInput<TRequired extends boolean = false, THasDefault extends boolean = false> = NeedsValue<boolean, TRequired, THasDefault>
+type InferUpdateInput<TRequired extends boolean = false, THasDefault extends boolean = false> = NeedsValue<boolean, TRequired, THasDefault>
+
+export interface BooleanProxy<TRequired extends boolean = false, THasDefault extends boolean = false> {
   /** Gets the current boolean value */
-  get(): MaybeUndefined<boolean, TDefined>;
+  get(): MaybeUndefined<boolean, TRequired, THasDefault>;
   /** Sets the boolean value, generating a boolean.set operation */
-  set(value: boolean): void;
+  set(value: InferSetInput<TRequired, THasDefault>): void;
+  /** This is the same as set. Updates the boolean value, generating a boolean.set operation */
+  update(value: InferUpdateInput<TRequired, THasDefault>): void;
   /** Returns a readonly snapshot of the boolean value for rendering */
-  toSnapshot(): MaybeUndefined<boolean, TDefined>;
+  toSnapshot(): MaybeUndefined<boolean, TRequired, THasDefault>;
 }
 
 interface BooleanPrimitiveSchema {
@@ -23,10 +28,14 @@ interface BooleanPrimitiveSchema {
   readonly validators: readonly Validator<boolean>[];
 }
 
-export class BooleanPrimitive<TDefined extends boolean = false> implements Primitive<boolean, BooleanProxy<TDefined>> {
+export class BooleanPrimitive<TRequired extends boolean = false, THasDefault extends boolean = false> implements Primitive<boolean, BooleanProxy<TRequired, THasDefault>, TRequired, THasDefault, InferSetInput<TRequired, THasDefault>, InferUpdateInput<TRequired, THasDefault>> {
   readonly _tag = "BooleanPrimitive" as const;
   readonly _State!: boolean;
-  readonly _Proxy!: BooleanProxy<TDefined>;
+  readonly _Proxy!: BooleanProxy<TRequired, THasDefault>;
+  readonly _TRequired!: TRequired;
+  readonly _THasDefault!: THasDefault;
+  readonly TUpdateInput!: InferUpdateInput<TRequired, THasDefault>;
+  readonly TSetInput!: InferSetInput<TRequired, THasDefault>;
 
   private readonly _schema: BooleanPrimitiveSchema;
 
@@ -44,7 +53,7 @@ export class BooleanPrimitive<TDefined extends boolean = false> implements Primi
   }
 
   /** Mark this boolean as required */
-  required(): BooleanPrimitive<true> {
+  required(): BooleanPrimitive<true, THasDefault> {
     return new BooleanPrimitive({
       ...this._schema,
       required: true,
@@ -52,7 +61,7 @@ export class BooleanPrimitive<TDefined extends boolean = false> implements Primi
   }
 
   /** Set a default value for this boolean */
-  default(defaultValue: boolean): BooleanPrimitive<true> {
+  default(defaultValue: boolean): BooleanPrimitive<TRequired, true> {
     return new BooleanPrimitive({
       ...this._schema,
       defaultValue,
@@ -60,34 +69,39 @@ export class BooleanPrimitive<TDefined extends boolean = false> implements Primi
   }
 
   /** Add a custom validation rule */
-  refine(fn: (value: boolean) => boolean, message: string): BooleanPrimitive<TDefined> {
+  refine(fn: (value: boolean) => boolean, message: string): BooleanPrimitive<TRequired, THasDefault> {
     return new BooleanPrimitive({
       ...this._schema,
       validators: [...this._schema.validators, { validate: fn, message }],
     });
   }
 
-  readonly _internal: PrimitiveInternal<boolean, BooleanProxy<TDefined>> = {
-    createProxy: (env: ProxyEnvironment.ProxyEnvironment, operationPath: OperationPath.OperationPath): BooleanProxy<TDefined> => {
+  readonly _internal: PrimitiveInternal<boolean, BooleanProxy<TRequired, THasDefault>> = {
+    createProxy: (env: ProxyEnvironment.ProxyEnvironment, operationPath: OperationPath.OperationPath): BooleanProxy<TRequired, THasDefault> => {
       const defaultValue = this._schema.defaultValue;
       return {
-        get: (): MaybeUndefined<boolean, TDefined> => {
+        get: (): MaybeUndefined<boolean, TRequired, THasDefault> => {
           const state = env.getState(operationPath) as boolean | undefined;
-          return (state ?? defaultValue) as MaybeUndefined<boolean, TDefined>;
+          return (state ?? defaultValue) as MaybeUndefined<boolean, TRequired, THasDefault>;
+        },
+        set: (value: InferSetInput<TRequired, THasDefault>) => {
+          env.addOperation(
+            Operation.fromDefinition(operationPath, this._opDefinitions.set, value)
+          );
         },
-        set: (value: boolean) => {
+        update: (value: InferUpdateInput<TRequired, THasDefault>) => {
           env.addOperation(
             Operation.fromDefinition(operationPath, this._opDefinitions.set, value)
           );
         },
-        toSnapshot: (): MaybeUndefined<boolean, TDefined> => {
+        toSnapshot: (): MaybeUndefined<boolean, TRequired, THasDefault> => {
           const state = env.getState(operationPath) as boolean | undefined;
-          return (state ?? defaultValue) as MaybeUndefined<boolean, TDefined>;
+          return (state ?? defaultValue) as MaybeUndefined<boolean, TRequired, THasDefault>;
         },
       };
     },
 
-    applyOperation: (state: boolean | undefined, operation: Operation.Operation<any, any, any>): boolean => {
+    applyOperation: (_state: boolean | undefined, operation: Operation.Operation<any, any, any>): boolean => {
       if (operation.kind !== "boolean.set") {
         throw new ValidationError(`BooleanPrimitive cannot apply operation of kind: ${operation.kind}`);
       }
@@ -123,6 +137,6 @@ export class BooleanPrimitive<TDefined extends boolean = false> implements Primi
 }
 
 /** Creates a new BooleanPrimitive */
-export const Boolean = (): BooleanPrimitive<false> =>
+export const Boolean = (): BooleanPrimitive<false, false> =>
   new BooleanPrimitive({ required: false, defaultValue: undefined, validators: [] });
 

package/src/primitives/Either.ts

@@ -0,0 +1,379 @@
+import { Schema } from "effect";
+import * as OperationDefinition from "../OperationDefinition";
+import * as Operation from "../Operation";
+import * as OperationPath from "../OperationPath";
+import * as ProxyEnvironment from "../ProxyEnvironment";
+import * as Transform from "../Transform";
+import type { Primitive, PrimitiveInternal, MaybeUndefined, InferState, NeedsValue } from "./shared";
+import { ValidationError } from "./shared";
+import { StringPrimitive } from "./String";
+import { NumberPrimitive } from "./Number";
+import { BooleanPrimitive } from "./Boolean";
+import { LiteralPrimitive, LiteralValue } from "./Literal";
+
+// =============================================================================
+// Either Primitive - Simple Type Union
+// =============================================================================
+
+type InferSetInput<TVariants extends readonly ScalarPrimitive[], TRequired extends boolean = false, THasDefault extends boolean = false> = NeedsValue<InferEitherState<TVariants>, TRequired, THasDefault>
+type InferUpdateInput<TVariants extends readonly ScalarPrimitive[], TRequired extends boolean = false, THasDefault extends boolean = false> = NeedsValue<InferEitherState<TVariants>, TRequired, THasDefault>
+
+/**
+ * Scalar primitives that can be used as variants in Either
+ */
+export type ScalarPrimitive =
+  | StringPrimitive<any, any>
+  | NumberPrimitive<any, any>
+  | BooleanPrimitive<any, any>
+  | LiteralPrimitive<any, any, any>;
+
+/**
+ * Infer the union state type from a tuple of scalar primitives
+ */
+export type InferEitherState<TVariants extends readonly ScalarPrimitive[]> =
+  InferState<TVariants[number]>;
+
+/**
+ * Infer the union snapshot type from a tuple of scalar primitives
+ */
+export type InferEitherSnapshot<TVariants extends readonly ScalarPrimitive[]> =
+  InferState<TVariants[number]>;
+
+/**
+ * Match handlers for Either - optional handlers for each scalar type
+ */
+export interface EitherMatchHandlers<R> {
+  string?: (value: string) => R;
+  number?: (value: number) => R;
+  boolean?: (value: boolean) => R;
+  literal?: (value: LiteralValue) => R;
+}
+
+/**
+ * Proxy for accessing Either values
+ */
+export interface EitherProxy<TVariants extends readonly ScalarPrimitive[], TRequired extends boolean = false, THasDefault extends boolean = false> {
+  /** Gets the current value */
+  get(): MaybeUndefined<InferEitherState<TVariants>, TRequired, THasDefault>;
+
+  /** Sets the value to any of the allowed variant types */
+  set(value: InferSetInput<TVariants, TRequired, THasDefault>): void;
+
+  /** This is the same as set. Updates the value, generating an either.set operation */
+  update(value: InferUpdateInput<TVariants, TRequired, THasDefault>): void;
+
+  /** Pattern match on the value type */
+  match<R>(handlers: EitherMatchHandlers<R>): R | undefined;
+
+  /** Returns a readonly snapshot of the value for rendering */
+  toSnapshot(): MaybeUndefined<InferEitherSnapshot<TVariants>, TRequired, THasDefault>;
+}
+
+interface EitherPrimitiveSchema<TVariants extends readonly ScalarPrimitive[]> {
+  readonly required: boolean;
+  readonly defaultValue: InferEitherState<TVariants> | undefined;
+  readonly variants: TVariants;
+}
+
+export class EitherPrimitive<TVariants extends readonly ScalarPrimitive[], TRequired extends boolean = false, THasDefault extends boolean = false>
+  implements Primitive<InferEitherState<TVariants>, EitherProxy<TVariants, TRequired, THasDefault>, TRequired, THasDefault, InferSetInput<TVariants, TRequired, THasDefault>, InferUpdateInput<TVariants, TRequired, THasDefault>>
+{
+  readonly _tag = "EitherPrimitive" as const;
+  readonly _State!: InferEitherState<TVariants>;
+  readonly _Proxy!: EitherProxy<TVariants, TRequired, THasDefault>;
+  readonly _TRequired!: TRequired;
+  readonly _THasDefault!: THasDefault;
+  readonly TUpdateInput!: InferUpdateInput<TVariants, TRequired, THasDefault>;
+  readonly TSetInput!: InferSetInput<TVariants, TRequired, THasDefault>;
+
+  private readonly _schema: EitherPrimitiveSchema<TVariants>;
+
+  private readonly _opDefinitions = {
+    set: OperationDefinition.make({
+      kind: "either.set" as const,
+      payload: Schema.Unknown,
+      target: Schema.Unknown,
+      apply: (payload) => payload,
+    }),
+  };
+
+  constructor(schema: EitherPrimitiveSchema<TVariants>) {
+    this._schema = schema;
+  }
+
+  /** Mark this either as required */
+  required(): EitherPrimitive<TVariants, true, THasDefault> {
+    return new EitherPrimitive({
+      ...this._schema,
+      required: true,
+    });
+  }
+
+  /** Set a default value for this either */
+  default(defaultValue: InferEitherState<TVariants>): EitherPrimitive<TVariants, TRequired, true> {
+    return new EitherPrimitive({
+      ...this._schema,
+      defaultValue,
+    });
+  }
+
+  /** Get the variants */
+  get variants(): TVariants {
+    return this._schema.variants;
+  }
+
+  /**
+   * Determine the type category of a value based on the variants
+   */
+  private _getValueType(value: unknown): "string" | "number" | "boolean" | "literal" | undefined {
+    const valueType = typeof value;
+
+    // Check for literal matches first (they take priority)
+    for (const variant of this._schema.variants) {
+      if (variant._tag === "LiteralPrimitive") {
+        const literalVariant = variant as LiteralPrimitive<any, any, any>;
+        if (value === literalVariant.literal) {
+          return "literal";
+        }
+      }
+    }
+
+    // Check for type matches
+    if (valueType === "string") {
+      for (const variant of this._schema.variants) {
+        if (variant._tag === "StringPrimitive") {
+          return "string";
+        }
+      }
+    }
+
+    if (valueType === "number") {
+      for (const variant of this._schema.variants) {
+        if (variant._tag === "NumberPrimitive") {
+          return "number";
+        }
+      }
+    }
+
+    if (valueType === "boolean") {
+      for (const variant of this._schema.variants) {
+        if (variant._tag === "BooleanPrimitive") {
+          return "boolean";
+        }
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Find the matching variant for a value.
+   * For literals, matches exact value. For other types, matches by typeof.
+   */
+  private _findMatchingVariant(value: unknown): ScalarPrimitive | undefined {
+    const valueType = typeof value;
+
+    // Check for literal matches first (they take priority)
+    for (const variant of this._schema.variants) {
+      if (variant._tag === "LiteralPrimitive") {
+        const literalVariant = variant as LiteralPrimitive<any, any, any>;
+        if (value === literalVariant.literal) {
+          return variant;
+        }
+      }
+    }
+
+    // Check for type matches
+    if (valueType === "string") {
+      for (const variant of this._schema.variants) {
+        if (variant._tag === "StringPrimitive") {
+          return variant;
+        }
+      }
+    }
+
+    if (valueType === "number") {
+      for (const variant of this._schema.variants) {
+        if (variant._tag === "NumberPrimitive") {
+          return variant;
+        }
+      }
+    }
+
+    if (valueType === "boolean") {
+      for (const variant of this._schema.variants) {
+        if (variant._tag === "BooleanPrimitive") {
+          return variant;
+        }
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Get the operation kind for a variant
+   */
+  private _getVariantOperationKind(variant: ScalarPrimitive): string {
+    switch (variant._tag) {
+      case "StringPrimitive":
+        return "string.set";
+      case "NumberPrimitive":
+        return "number.set";
+      case "BooleanPrimitive":
+        return "boolean.set";
+      case "LiteralPrimitive":
+        return "literal.set";
+      default:
+        return "unknown.set";
+    }
+  }
+
+  /**
+   * Validate a value against the matching variant, including running its validators.
+   * Throws ValidationError if the value doesn't match any variant or fails validation.
+   */
+  private _validateAndApplyToVariant(value: unknown, path: OperationPath.OperationPath): void {
+    const matchingVariant = this._findMatchingVariant(value);
+    
+    if (!matchingVariant) {
+      const allowedTypes = this._schema.variants.map((v) => v._tag).join(", ");
+      throw new ValidationError(
+        `EitherPrimitive.set requires a value matching one of: ${allowedTypes}, got: ${typeof value}`
+      );
+    }
+
+    // Create a synthetic operation for the variant's applyOperation
+    const variantOpKind = this._getVariantOperationKind(matchingVariant);
+    const syntheticOp: Operation.Operation<any, any, any> = {
+      kind: variantOpKind,
+      path: path,
+      payload: value,
+    };
+
+    // Delegate to the variant's applyOperation which runs its validators
+    // This will throw ValidationError if validation fails
+    matchingVariant._internal.applyOperation(undefined, syntheticOp);
+  }
+
+  readonly _internal: PrimitiveInternal<InferEitherState<TVariants>, EitherProxy<TVariants, TRequired, THasDefault>> = {
+    createProxy: (
+      env: ProxyEnvironment.ProxyEnvironment,
+      operationPath: OperationPath.OperationPath
+    ): EitherProxy<TVariants, TRequired, THasDefault> => {
+      const defaultValue = this._schema.defaultValue;
+
+      return {
+        get: (): MaybeUndefined<InferEitherState<TVariants>, TRequired, THasDefault> => {
+          const state = env.getState(operationPath) as InferEitherState<TVariants> | undefined;
+          return (state ?? defaultValue) as MaybeUndefined<InferEitherState<TVariants>, TRequired, THasDefault>;
+        },
+        set: (value: InferSetInput<TVariants, TRequired, THasDefault>) => {
+          env.addOperation(
+            Operation.fromDefinition(operationPath, this._opDefinitions.set, value)
+          );
+        },
+        update: (value: InferUpdateInput<TVariants, TRequired, THasDefault>) => {
+          env.addOperation(
+            Operation.fromDefinition(operationPath, this._opDefinitions.set, value)
+          );
+        },
+        match: <R,>(handlers: EitherMatchHandlers<R>): R | undefined => {
+          const currentState = env.getState(operationPath) as InferEitherState<TVariants> | undefined;
+          const effectiveState = currentState ?? defaultValue;
+          if (effectiveState === undefined) return undefined;
+
+          const valueType = this._getValueType(effectiveState);
+          if (!valueType) return undefined;
+
+          switch (valueType) {
+            case "string":
+              return handlers.string?.(effectiveState as string);
+            case "number":
+              return handlers.number?.(effectiveState as number);
+            case "boolean":
+              return handlers.boolean?.(effectiveState as boolean);
+            case "literal":
+              return handlers.literal?.(effectiveState as LiteralValue);
+            default:
+              return undefined;
+          }
+        },
+        toSnapshot: (): MaybeUndefined<InferEitherSnapshot<TVariants>, TRequired, THasDefault> => {
+          const state = env.getState(operationPath) as InferEitherState<TVariants> | undefined;
+          return (state ?? defaultValue) as MaybeUndefined<InferEitherSnapshot<TVariants>, TRequired, THasDefault>;
+        },
+      };
+    },
+
+    applyOperation: (
+      _state: InferEitherState<TVariants> | undefined,
+      operation: Operation.Operation<any, any, any>
+    ): InferEitherState<TVariants> => {
+      if (operation.kind !== "either.set") {
+        throw new ValidationError(`EitherPrimitive cannot apply operation of kind: ${operation.kind}`);
+      }
+
+      const payload = operation.payload;
+
+      // Validate that the payload matches one of the variant types and passes its validators
+      this._validateAndApplyToVariant(payload, operation.path);
+
+      return payload as InferEitherState<TVariants>;
+    },
+
+    getInitialState: (): InferEitherState<TVariants> | undefined => {
+      return this._schema.defaultValue;
+    },
+
+    transformOperation: (
+      clientOp: Operation.Operation<any, any, any>,
+      serverOp: Operation.Operation<any, any, any>
+    ): Transform.TransformResult => {
+      // If paths don't overlap, no transformation needed
+      if (!OperationPath.pathsOverlap(clientOp.path, serverOp.path)) {
+        return { type: "transformed", operation: clientOp };
+      }
+
+      // For same path, client wins (last-write-wins)
+      return { type: "transformed", operation: clientOp };
+    },
+  };
+}
+
+/**
+ * Creates a new EitherPrimitive with the given scalar variant types.
+ * Validators defined on the variants are applied when validating values.
+ *
+ * @example
+ * ```typescript
+ * // String or number
+ * const value = Either(String(), Number());
+ *
+ * // String, number, or boolean
+ * const status = Either(String(), Number(), Boolean()).default("pending");
+ *
+ * // With literal types
+ * const mode = Either(Literal("auto"), Literal("manual"), Number());
+ *
+ * // With validators - validates string length and number range
+ * const constrained = Either(
+ *   String().min(2).max(50),
+ *   Number().max(255)
+ * );
+ * ```
+ */
+export function Either<TVariants extends readonly ScalarPrimitive[]>(
+  ...variants: TVariants
+): EitherPrimitive<TVariants, false, false> {
+  if (variants.length === 0) {
+    throw new ValidationError("Either requires at least one variant");
+  }
+
+  return new EitherPrimitive({
+    required: false,
+    defaultValue: undefined,
+    variants,
+  });
+}
+