@voidhash/mimic 0.0.1-alpha.6 → 0.0.1-alpha.8

package/src/primitives/Union.ts

@@ -4,17 +4,17 @@ 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, AnyPrimitive, InferState, InferProxy, InferSnapshot } from "../Primitive";
+import type { Primitive, PrimitiveInternal, MaybeUndefined, AnyPrimitive, InferState, InferProxy, InferSnapshot, InferSetInput } from "../Primitive";
 import { ValidationError } from "../Primitive";
 import { LiteralPrimitive } from "./Literal";
-import { StructPrimitive } from "./Struct";
-import { runValidators } from "./shared";
+import { StructPrimitive, InferStructState } from "./Struct";
+import { runValidators, applyDefaults } from "./shared";
 
 
 /**
  * Type constraint for union variants - must be struct primitives
  */
-export type UnionVariants = Record<string, StructPrimitive<any, any>>;
+export type UnionVariants = Record<string, StructPrimitive<any, any, any>>;
 
 /**
  * Infer the union state type from variants
@@ -30,15 +30,23 @@ export type InferUnionSnapshot<TVariants extends UnionVariants> = {
   [K in keyof TVariants]: InferSnapshot<TVariants[K]>;
 }[keyof TVariants];
 
+/**
+ * Compute the input type for union.set() operations.
+ * Uses each variant's TSetInput type.
+ */
+export type UnionSetInput<TVariants extends UnionVariants> = {
+  [K in keyof TVariants]: InferSetInput<TVariants[K]>;
+}[keyof TVariants];
+
 /**
  * Proxy for accessing union variants
  */
-export interface UnionProxy<TVariants extends UnionVariants, _TDiscriminator extends string, TDefined extends boolean = false> {
+export interface UnionProxy<TVariants extends UnionVariants, _TDiscriminator extends string, TRequired extends boolean = false, THasDefault extends boolean = false> {
   /** Gets the current union value */
-  get(): MaybeUndefined<InferUnionState<TVariants>, TDefined>;
+  get(): MaybeUndefined<InferUnionState<TVariants>, TRequired, THasDefault>;
   
-  /** Sets the entire union value */
-  set(value: InferUnionState<TVariants>): void;
+  /** Sets the entire union value (applies defaults for variant fields) */
+  set(value: UnionSetInput<TVariants>): void;
   
   /** Access a specific variant's proxy (assumes the variant is active) */
   as<K extends keyof TVariants>(variant: K): InferProxy<TVariants[K]>;
@@ -49,7 +57,7 @@ export interface UnionProxy<TVariants extends UnionVariants, _TDiscriminator ext
   }): R | undefined;
   
   /** Returns a readonly snapshot of the union for rendering */
-  toSnapshot(): MaybeUndefined<InferUnionSnapshot<TVariants>, TDefined>;
+  toSnapshot(): MaybeUndefined<InferUnionSnapshot<TVariants>, TRequired, THasDefault>;
 }
 
 interface UnionPrimitiveSchema<TVariants extends UnionVariants, TDiscriminator extends string> {
@@ -59,12 +67,16 @@ interface UnionPrimitiveSchema<TVariants extends UnionVariants, TDiscriminator e
   readonly variants: TVariants;
 }
 
-export class UnionPrimitive<TVariants extends UnionVariants, TDiscriminator extends string = "type", TDefined extends boolean = false>
-  implements Primitive<InferUnionState<TVariants>, UnionProxy<TVariants, TDiscriminator, TDefined>>
+export class UnionPrimitive<TVariants extends UnionVariants, TDiscriminator extends string = "type", TRequired extends boolean = false, THasDefault extends boolean = false>
+  implements Primitive<InferUnionState<TVariants>, UnionProxy<TVariants, TDiscriminator, TRequired, THasDefault>, TRequired, THasDefault, UnionSetInput<TVariants>, UnionSetInput<TVariants>>
 {
   readonly _tag = "UnionPrimitive" as const;
   readonly _State!: InferUnionState<TVariants>;
-  readonly _Proxy!: UnionProxy<TVariants, TDiscriminator, TDefined>;
+  readonly _Proxy!: UnionProxy<TVariants, TDiscriminator, TRequired, THasDefault>;
+  readonly _TRequired!: TRequired;
+  readonly _THasDefault!: THasDefault;
+  readonly TSetInput!: UnionSetInput<TVariants>;
+  readonly TUpdateInput!: UnionSetInput<TVariants>;
 
   private readonly _schema: UnionPrimitiveSchema<TVariants, TDiscriminator>;
 
@@ -82,7 +94,7 @@ export class UnionPrimitive<TVariants extends UnionVariants, TDiscriminator exte
   }
 
   /** Mark this union as required */
-  required(): UnionPrimitive<TVariants, TDiscriminator, true> {
+  required(): UnionPrimitive<TVariants, TDiscriminator, true, THasDefault> {
     return new UnionPrimitive({
       ...this._schema,
       required: true,
@@ -90,10 +102,12 @@ export class UnionPrimitive<TVariants extends UnionVariants, TDiscriminator exte
   }
 
   /** Set a default value for this union */
-  default(defaultValue: InferUnionState<TVariants>): UnionPrimitive<TVariants, TDiscriminator, true> {
+  default(defaultValue: UnionSetInput<TVariants>): UnionPrimitive<TVariants, TDiscriminator, true, true> {
+    // Apply defaults to the variant
+    const merged = this._applyVariantDefaults(defaultValue as Partial<InferUnionState<TVariants>>);
     return new UnionPrimitive({
       ...this._schema,
-      defaultValue,
+      defaultValue: merged,
     });
   }
 
@@ -119,7 +133,7 @@ export class UnionPrimitive<TVariants extends UnionVariants, TDiscriminator exte
       const variant = this._schema.variants[key]!;
       const discriminatorField = variant.fields[this._schema.discriminator];
       if (discriminatorField && discriminatorField._tag === "LiteralPrimitive") {
-        const literalPrimitive = discriminatorField as LiteralPrimitive<any, any>;
+        const literalPrimitive = discriminatorField as LiteralPrimitive<any, any, any>;
         if (literalPrimitive.literal === discriminatorValue) {
           return key;
         }
@@ -128,22 +142,35 @@ export class UnionPrimitive<TVariants extends UnionVariants, TDiscriminator exte
     return undefined;
   }
 
-  readonly _internal: PrimitiveInternal<InferUnionState<TVariants>, UnionProxy<TVariants, TDiscriminator, TDefined>> = {
+  /** Apply defaults to a variant value based on the discriminator */
+  private _applyVariantDefaults(value: Partial<InferUnionState<TVariants>>): InferUnionState<TVariants> {
+    const variantKey = this._findVariantKey(value as InferUnionState<TVariants>);
+    if (!variantKey) {
+      return value as InferUnionState<TVariants>;
+    }
+    
+    const variantPrimitive = this._schema.variants[variantKey]!;
+    return applyDefaults(variantPrimitive as AnyPrimitive, value) as InferUnionState<TVariants>;
+  }
+
+  readonly _internal: PrimitiveInternal<InferUnionState<TVariants>, UnionProxy<TVariants, TDiscriminator, TRequired, THasDefault>> = {
     createProxy: (
       env: ProxyEnvironment.ProxyEnvironment,
       operationPath: OperationPath.OperationPath
-    ): UnionProxy<TVariants, TDiscriminator, TDefined> => {
+    ): UnionProxy<TVariants, TDiscriminator, TRequired, THasDefault> => {
       const variants = this._schema.variants;
       const defaultValue = this._schema.defaultValue;
 
       return {
-        get: (): MaybeUndefined<InferUnionState<TVariants>, TDefined> => {
+        get: (): MaybeUndefined<InferUnionState<TVariants>, TRequired, THasDefault> => {
           const state = env.getState(operationPath) as InferUnionState<TVariants> | undefined;
-          return (state ?? defaultValue) as MaybeUndefined<InferUnionState<TVariants>, TDefined>;
+          return (state ?? defaultValue) as MaybeUndefined<InferUnionState<TVariants>, TRequired, THasDefault>;
         },
-        set: (value: InferUnionState<TVariants>) => {
+        set: (value: UnionSetInput<TVariants>) => {
+          // Apply defaults for the variant
+          const merged = this._applyVariantDefaults(value as Partial<InferUnionState<TVariants>>);
           env.addOperation(
-            Operation.fromDefinition(operationPath, this._opDefinitions.set, value)
+            Operation.fromDefinition(operationPath, this._opDefinitions.set, merged)
           );
         },
         as: <K extends keyof TVariants>(variant: K): InferProxy<TVariants[K]> => {
@@ -166,21 +193,21 @@ export class UnionPrimitive<TVariants extends UnionVariants, TDiscriminator exte
           const variantProxy = variants[variantKey]!._internal.createProxy(env, operationPath) as InferProxy<TVariants[typeof variantKey]>;
           return handler(variantProxy);
         },
-        toSnapshot: (): MaybeUndefined<InferUnionSnapshot<TVariants>, TDefined> => {
+        toSnapshot: (): MaybeUndefined<InferUnionSnapshot<TVariants>, TRequired, THasDefault> => {
           const state = env.getState(operationPath) as InferUnionState<TVariants> | undefined;
           const effectiveState = state ?? defaultValue;
           if (!effectiveState) {
-            return undefined as MaybeUndefined<InferUnionSnapshot<TVariants>, TDefined>;
+            return undefined as MaybeUndefined<InferUnionSnapshot<TVariants>, TRequired, THasDefault>;
           }
           
           const variantKey = this._findVariantKey(effectiveState);
           if (!variantKey) {
-            return undefined as MaybeUndefined<InferUnionSnapshot<TVariants>, TDefined>;
+            return undefined as MaybeUndefined<InferUnionSnapshot<TVariants>, TRequired, THasDefault>;
           }
           
           const variantPrimitive = variants[variantKey]!;
           const variantProxy = variantPrimitive._internal.createProxy(env, operationPath);
-          return (variantProxy as unknown as { toSnapshot(): InferUnionSnapshot<TVariants> }).toSnapshot() as MaybeUndefined<InferUnionSnapshot<TVariants>, TDefined>;
+          return (variantProxy as unknown as { toSnapshot(): InferUnionSnapshot<TVariants> }).toSnapshot() as MaybeUndefined<InferUnionSnapshot<TVariants>, TRequired, THasDefault>;
         },
       };
     },
@@ -311,13 +338,13 @@ export interface UnionOptions<TVariants extends UnionVariants, TDiscriminator ex
 /** Creates a new UnionPrimitive with the given variants */
 export function Union<TVariants extends UnionVariants>(
   options: UnionOptions<TVariants, "type">
-): UnionPrimitive<TVariants, "type", false>;
+): UnionPrimitive<TVariants, "type", false, false>;
 export function Union<TVariants extends UnionVariants, TDiscriminator extends string>(
   options: UnionOptions<TVariants, TDiscriminator>
-): UnionPrimitive<TVariants, TDiscriminator, false>;
+): UnionPrimitive<TVariants, TDiscriminator, false, false>;
 export function Union<TVariants extends UnionVariants, TDiscriminator extends string = "type">(
   options: UnionOptions<TVariants, TDiscriminator>
-): UnionPrimitive<TVariants, TDiscriminator, false> {
+): UnionPrimitive<TVariants, TDiscriminator, false, false> {
   const discriminator = (options.discriminator ?? "type") as TDiscriminator;
   return new UnionPrimitive({
     required: false,

package/src/primitives/shared.ts

@@ -11,12 +11,21 @@ import * as Transform from "../Transform";
 /**
  * Base interface that all primitives must implement.
  * Provides type inference helpers and internal operations.
+ * 
+ * @typeParam TState - The state type this primitive holds
+ * @typeParam TProxy - The proxy type for interacting with this primitive
+ * @typeParam TDefined - Whether the value is guaranteed to be defined (via required() or default())
+ * @typeParam THasDefault - Whether this primitive has a default value
  */
-export interface Primitive<TState, TProxy> {
+export interface Primitive<TState, TProxy, TRequired extends boolean = false, THasDefault extends boolean = false, TSetInput = unknown, TUpdateInput = unknown> {
     readonly _tag: string;
     readonly _State: TState;
     readonly _Proxy: TProxy;
+    readonly _TRequired: TRequired;
+    readonly _THasDefault: THasDefault;
     readonly _internal: PrimitiveInternal<TState, TProxy>;
+    readonly TSetInput: TSetInput;
+    readonly TUpdateInput: TUpdateInput;
   }
   
   /**
@@ -46,32 +55,62 @@ export interface Primitive<TState, TProxy> {
   /**
    * Any primitive type - used for generic constraints.
    */
-  export type AnyPrimitive = Primitive<any, any>;
+  export type AnyPrimitive = Primitive<any, any, any, any>;
   
   /**
    * Infer the state type from a primitive.
    */
-  export type InferState<T> = T extends Primitive<infer S, any> ? S : never;
+  export type InferState<T> = T extends Primitive<infer S, any, any, any> ? S : never;
   
   /**
    * Infer the proxy type from a primitive.
    */
-  export type InferProxy<T> = T extends Primitive<any, infer P> ? P : never;
+  export type InferProxy<T> = T extends Primitive<any, infer P, any, any> ? P : never;
+
+  /**
+   * Infer the SetInput type from a primitive.
+   */
+  export type InferSetInput<T> = T extends Primitive<any, any, any, any, infer S, any> ? S : never;
+
+  /**
+   * Infer the UpdateInput type from a primitive.
+   */
+  export type InferUpdateInput<T> = T extends Primitive<any, any, any, any, any, infer U> ? U : never;
   
   /**
-   * Helper type to conditionally add undefined based on TDefined.
-   * When TDefined is true, the value is guaranteed to be defined (via required() or default()).
-   * When TDefined is false, the value may be undefined.
+   * Helper type to conditionally add undefined based on TRequired and THasDefault.
+   * When TRequired is false and THasDefault is false, the value may be undefined.
+   * Otherwise, the value is guaranteed to be defined.
+   */
+  export type MaybeUndefined<T, TRequired extends boolean, THasDefault extends boolean> = TRequired extends false ? THasDefault extends false ? Optional<T> : T : T;
+
+  export type Optional<T> = T | undefined;
+
+  /**
+   * Helper type to conditionally add undefined based on TRequired and THasDefault.
+   * When TRequired is true and THasDefault is false, the value must be provided.
+   * Otherwise, the value may be undefined.
    */
-  export type MaybeUndefined<T, TDefined extends boolean> = TDefined extends true ? T : T | undefined;
+  export type NeedsValue<T, TRequired extends boolean, THasDefault extends boolean> = TRequired extends true ? THasDefault extends false ? T : Optional<T> : Optional<T>;
   
   /**
    * Infer the snapshot type from a primitive.
    * The snapshot is a readonly, type-safe structure suitable for rendering.
    */
-  export type InferSnapshot<T> = T extends Primitive<any, infer P>
+  export type InferSnapshot<T> = T extends Primitive<any, infer P, any, any>
     ? P extends { toSnapshot(): infer S } ? S : never
     : never;
+
+  /**
+   * Extract THasDefault from a primitive.
+   */
+  export type HasDefault<T> = T extends Primitive<any, any, any, infer H> ? H : false;
+
+  /**
+   * Extract TDefined from a primitive.
+   */
+  export type IsDefined<T> = T extends Primitive<any, any, infer D, any> ? D : false;
+
   
   // =============================================================================
   // Validation Errors
@@ -120,3 +159,58 @@ export function isCompatibleOperation(operation: Operation.Operation<any, any, a
   return values.some(value => value.kind === operation.kind);
 }
 
+// =============================================================================
+// Default Value Utilities
+// =============================================================================
+
+/**
+ * Applies default values to a partial input, recursively handling nested structs.
+ * 
+ * Uses a two-layer approach:
+ * 1. First, get the struct's initial state (which includes struct-level defaults)
+ * 2. Then, layer the provided values on top
+ * 3. Finally, ensure nested structs are recursively processed
+ * 
+ * @param primitive - The primitive definition containing field information
+ * @param value - The partial value provided by the user
+ * @returns The value with defaults applied for missing fields
+ */
+export function applyDefaults<T extends AnyPrimitive>(
+  primitive: T,
+  value: Partial<InferState<T>>
+): InferState<T> {
+  // Only structs need default merging
+  if (primitive._tag === "StructPrimitive") {
+    const structPrimitive = primitive as unknown as { 
+      fields: Record<string, AnyPrimitive>;
+      _internal: { getInitialState: () => Record<string, unknown> | undefined };
+    };
+    
+    // Start with the struct's initial state (struct-level default or field defaults)
+    const structInitialState = structPrimitive._internal.getInitialState() ?? {};
+    
+    // Layer the provided values on top of initial state
+    const result: Record<string, unknown> = { ...structInitialState, ...value };
+    
+    for (const key in structPrimitive.fields) {
+      const fieldPrimitive = structPrimitive.fields[key]!;
+      
+      if (result[key] === undefined) {
+        // Field still not provided after merging - try individual field default
+        const fieldDefault = fieldPrimitive._internal.getInitialState();
+        if (fieldDefault !== undefined) {
+          result[key] = fieldDefault;
+        }
+      } else if (fieldPrimitive._tag === "StructPrimitive" && typeof result[key] === "object" && result[key] !== null) {
+        // Recursively apply defaults to nested structs
+        result[key] = applyDefaults(fieldPrimitive, result[key] as Partial<InferState<typeof fieldPrimitive>>);
+      }
+    }
+    
+    return result as InferState<T>;
+  }
+  
+  // For non-struct primitives, return the value as-is
+  return value as InferState<T>;
+}
+

package/tests/primitives/Array.test.ts

@@ -411,6 +411,114 @@ describe("ArrayPrimitive", () => {
       expect(positions[1]! < positions[2]!).toBe(true);
     });
   });
+  describe("struct elements with defaults", () => {
+    // Define a struct element with required and optional fields
+    const TaskStruct = Primitive.Struct({
+      title: Primitive.String().required(),       // Must provide
+      priority: Primitive.Number().default(0),     // Has default, optional
+      completed: Primitive.Boolean().default(false), // Has default, optional
+    });
+
+    const taskArray = Primitive.Array(TaskStruct);
+
+    // Helper to create environment for task array
+    const createTaskEnv = (
+      state: Primitive.ArrayEntry<{ title: string; priority: number; completed: boolean }>[] = []
+    ): { env: ReturnType<typeof ProxyEnvironment.make>; operations: Operation.Operation<any, any, any>[] } => {
+      const operations: Operation.Operation<any, any, any>[] = [];
+      let currentState = [...state];
+      let idCounter = 0;
+
+      const env = ProxyEnvironment.make({
+        onOperation: (op) => {
+          operations.push(op);
+          if (op.kind === "array.insert") {
+            currentState.push(op.payload);
+          } else if (op.kind === "array.set") {
+            currentState = op.payload;
+          }
+        },
+        getState: () => currentState,
+        generateId: () => `task-${++idCounter}`,
+      });
+
+      return { env, operations };
+    };
+
+    it("push() only requires fields without defaults", () => {
+      const { env, operations } = createTaskEnv();
+      const proxy = taskArray._internal.createProxy(env, OperationPath.make(""));
+
+      // Only provide required 'title', priority and completed should use defaults
+      proxy.push({ title: "New Task" });
+
+      expect(operations).toHaveLength(1);
+      expect(operations[0]!.kind).toBe("array.insert");
+
+      const payload = operations[0]!.payload as { value: { title: string; priority: number; completed: boolean } };
+      expect(payload.value.title).toBe("New Task");
+      expect(payload.value.priority).toBe(0); // Default value
+      expect(payload.value.completed).toBe(false); // Default value
+    });
+
+    it("push() allows overriding defaults", () => {
+      const { env, operations } = createTaskEnv();
+      const proxy = taskArray._internal.createProxy(env, OperationPath.make(""));
+
+      // Provide title and override priority, let completed use default
+      proxy.push({ title: "Important Task", priority: 10 });
+
+      const payload = operations[0]!.payload as { value: { title: string; priority: number; completed: boolean } };
+      expect(payload.value.title).toBe("Important Task");
+      expect(payload.value.priority).toBe(10); // Overridden
+      expect(payload.value.completed).toBe(false); // Default value
+    });
+
+    it("insertAt() applies defaults for omitted fields", () => {
+      const existingEntry = {
+        id: "existing",
+        pos: "a0",
+        value: { title: "Existing", priority: 5, completed: true },
+      };
+      const { env, operations } = createTaskEnv([existingEntry]);
+      const proxy = taskArray._internal.createProxy(env, OperationPath.make(""));
+
+      // Insert with only required field
+      proxy.insertAt(0, { title: "First Task" });
+
+      const payload = operations[0]!.payload as { value: { title: string; priority: number; completed: boolean } };
+      expect(payload.value.title).toBe("First Task");
+      expect(payload.value.priority).toBe(0); // Default
+      expect(payload.value.completed).toBe(false); // Default
+    });
+
+    it("set() applies defaults to each element", () => {
+      const { env, operations } = createTaskEnv();
+      const proxy = taskArray._internal.createProxy(env, OperationPath.make(""));
+
+      // Set array with items that only have required fields
+      proxy.set([
+        { title: "Task 1" },
+        { title: "Task 2", priority: 5 },
+        { title: "Task 3", completed: true },
+      ]);
+
+      expect(operations).toHaveLength(1);
+      expect(operations[0]!.kind).toBe("array.set");
+
+      const entries = operations[0]!.payload as { value: { title: string; priority: number; completed: boolean } }[];
+      expect(entries).toHaveLength(3);
+
+      // First item: only title, defaults for others
+      expect(entries[0]!.value).toEqual({ title: "Task 1", priority: 0, completed: false });
+
+      // Second item: title and priority, default for completed
+      expect(entries[1]!.value).toEqual({ title: "Task 2", priority: 5, completed: false });
+
+      // Third item: title and completed, default for priority
+      expect(entries[2]!.value).toEqual({ title: "Task 3", priority: 0, completed: true });
+    });
+  });
 });
 
 // =============================================================================