@voidhash/mimic 0.0.1-alpha.5 → 0.0.1-alpha.7

package/src/primitives/TreeNode.ts

@@ -1,10 +1,4 @@
-import { Effect, 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 { AnyPrimitive, InferState } from "../Primitive";
+import type { InferState } from "../Primitive";
 import { StructPrimitive } from "./Struct";
 
 /**
@@ -12,6 +6,15 @@ import { StructPrimitive } from "./Struct";
  */
 const TreeNodeSelfSymbol = Symbol.for("TreeNode.Self");
 
+/**
+ * Branded type for TreeNodeSelf - distinguishable at compile time
+ */
+declare const SelfBrand: unique symbol;
+export interface TreeNodeSelfType {
+  readonly _tag: "TreeNodeSelf";
+  readonly _brand: typeof SelfBrand;
+}
+
 /**
  * Special placeholder for self-referential tree nodes.
  * Use this in the children array when a node type can contain itself.
@@ -20,11 +23,11 @@ const TreeNodeSelfSymbol = Symbol.for("TreeNode.Self");
  * ```typescript
  * const FolderNode = TreeNode("folder", {
  *   data: Struct({ name: String() }),
- *   children: [Self], // Folder can contain other folders
+ *   children: [TreeNodeSelf], // Folder can contain other folders
  * });
  * ```
  */
-export const TreeNodeSelf = { _tag: "TreeNodeSelf", _symbol: TreeNodeSelfSymbol } as unknown as AnyTreeNodePrimitive;
+export const TreeNodeSelf: TreeNodeSelfType = { _tag: "TreeNodeSelf", _symbol: TreeNodeSelfSymbol } as unknown as TreeNodeSelfType;
 
 /**
  * Check if a value is the Self placeholder
@@ -33,41 +36,57 @@ const isSelf = (value: unknown): boolean => {
   return typeof value === "object" && value !== null && "_symbol" in value && (value as any)._symbol === TreeNodeSelfSymbol;
 };
 
+/**
+ * Type utility to resolve Self placeholders to the actual node type
+ */
+type ResolveSelf<T, TSelf extends AnyTreeNodePrimitive> = 
+  T extends TreeNodeSelfType ? TSelf : T;
+
+/**
+ * Type utility to resolve all children in a tuple, replacing Self with the node type
+ */
+type ResolveChildrenUnion<TChildren, TSelf extends AnyTreeNodePrimitive> = 
+  TChildren extends readonly (infer U)[] 
+    ? ResolveSelf<U, TSelf> 
+    : never;
+
 /**
  * The type for children - either a direct array or a lazy function (for self-referential nodes).
- * Using `Function` type allows self-references without explicit type annotations.
  */
-// eslint-disable-next-line @typescript-eslint/ban-types
-export type TreeNodeChildren = readonly AnyTreeNodePrimitive[] | Function;
+export type TreeNodeChildrenInput = readonly (AnyTreeNodePrimitive | TreeNodeSelfType)[] | (() => readonly (AnyTreeNodePrimitive | TreeNodeSelfType)[]);
 
 /**
  * Any TreeNodePrimitive type - used for generic constraints.
  */
-export type AnyTreeNodePrimitive = TreeNodePrimitive<string, StructPrimitive<any>>;
+export type AnyTreeNodePrimitive = TreeNodePrimitive<string, StructPrimitive<any>, any>;
 
 /**
  * Infer the data state type from a TreeNodePrimitive
  */
 export type InferTreeNodeDataState<T extends AnyTreeNodePrimitive> = 
-  T extends TreeNodePrimitive<any, infer TData> ? InferState<TData> : never;
+  T extends TreeNodePrimitive<any, infer TData, any> ? InferState<TData> : never;
 
 /**
  * Infer the type literal from a TreeNodePrimitive
  */
 export type InferTreeNodeType<T extends AnyTreeNodePrimitive> =
-  T extends TreeNodePrimitive<infer TType, any> ? TType : never;
+  T extends TreeNodePrimitive<infer TType, any, any> ? TType : never;
 
 /**
- * Infer the allowed children from a TreeNodePrimitive (resolved at runtime)
+ * Infer the allowed children from a TreeNodePrimitive
  */
-export type InferTreeNodeChildren<_T extends AnyTreeNodePrimitive> = AnyTreeNodePrimitive;
+export type InferTreeNodeChildren<T> = 
+  T extends TreeNodePrimitive<any, any, infer TChildren> ? TChildren : never;
 
 /**
  * Configuration for a TreeNode primitive
  */
-export interface TreeNodeConfig<TData extends StructPrimitive<any>> {
+export interface TreeNodeConfig<
+  TData extends StructPrimitive<any>,
+  TChildren extends readonly (AnyTreeNodePrimitive | TreeNodeSelfType)[]
+> {
   readonly data: TData;
-  readonly children: TreeNodeChildren;
+  readonly children: TChildren | (() => TChildren);
 }
 
 /**
@@ -75,18 +94,20 @@ export interface TreeNodeConfig<TData extends StructPrimitive<any>> {
  */
 export class TreeNodePrimitive<
   TType extends string,
-  TData extends StructPrimitive<any>
+  TData extends StructPrimitive<any>,
+  TChildren extends AnyTreeNodePrimitive = AnyTreeNodePrimitive
 > {
   readonly _tag = "TreeNodePrimitive" as const;
   readonly _Type!: TType;
   readonly _Data!: TData;
+  readonly _Children!: TChildren;
 
   private readonly _type: TType;
   private readonly _data: TData;
-  private readonly _children: TreeNodeChildren;
+  private readonly _children: TreeNodeChildrenInput;
   private _resolvedChildren: readonly AnyTreeNodePrimitive[] | undefined;
 
-  constructor(type: TType, config: TreeNodeConfig<TData>) {
+  constructor(type: TType, config: TreeNodeConfig<TData, readonly (AnyTreeNodePrimitive | TreeNodeSelfType)[]>) {
     this._type = type;
     this._data = config.data;
     this._children = config.children;
@@ -109,7 +130,7 @@ export class TreeNodePrimitive<
         ? (this._children as () => readonly AnyTreeNodePrimitive[])()
         : this._children;
       // Replace Self placeholders with this node
-      this._resolvedChildren = resolved.map(child => isSelf(child) ? this : child);
+      this._resolvedChildren = resolved.map(child => isSelf(child) ? this : child) as readonly AnyTreeNodePrimitive[];
     }
     return this._resolvedChildren;
   }
@@ -123,10 +144,11 @@ export class TreeNodePrimitive<
 /** Creates a new TreeNodePrimitive with the given type and config */
 export const TreeNode = <
   TType extends string,
-  TData extends StructPrimitive<any>
+  TData extends StructPrimitive<any>,
+  const TChildren extends readonly (AnyTreeNodePrimitive | TreeNodeSelfType)[]
 >(
   type: TType,
-  config: TreeNodeConfig<TData>
-): TreeNodePrimitive<TType, TData> =>
-  new TreeNodePrimitive(type, config);
+  config: TreeNodeConfig<TData, TChildren>
+): TreeNodePrimitive<TType, TData, ResolveChildrenUnion<TChildren, TreeNodePrimitive<TType, TData, any>>> =>
+  new TreeNodePrimitive(type, config) as TreeNodePrimitive<TType, TData, ResolveChildrenUnion<TChildren, TreeNodePrimitive<TType, TData, any>>>;
 

package/src/primitives/Union.ts

@@ -7,14 +7,14 @@ import * as Transform from "../Transform";
 import type { Primitive, PrimitiveInternal, MaybeUndefined, AnyPrimitive, InferState, InferProxy, InferSnapshot } 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, StructSetInput } 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,25 @@ export type InferUnionSnapshot<TVariants extends UnionVariants> = {
   [K in keyof TVariants]: InferSnapshot<TVariants[K]>;
 }[keyof TVariants];
 
+/**
+ * Compute the input type for union.set() operations.
+ * For each variant, uses StructSetInput to make fields with defaults optional.
+ */
+export type UnionSetInput<TVariants extends UnionVariants> = {
+  [K in keyof TVariants]: TVariants[K] extends StructPrimitive<infer TFields, any, any>
+    ? StructSetInput<TFields>
+    : InferState<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, TDefined extends boolean = false> {
   /** Gets the current union value */
   get(): MaybeUndefined<InferUnionState<TVariants>, TDefined>;
   
-  /** 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]>;
@@ -59,12 +69,14 @@ 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", TDefined extends boolean = false, THasDefault extends boolean = false>
+  implements Primitive<InferUnionState<TVariants>, UnionProxy<TVariants, TDiscriminator, TDefined>, TDefined, THasDefault>
 {
   readonly _tag = "UnionPrimitive" as const;
   readonly _State!: InferUnionState<TVariants>;
   readonly _Proxy!: UnionProxy<TVariants, TDiscriminator, TDefined>;
+  readonly _TDefined!: TDefined;
+  readonly _THasDefault!: THasDefault;
 
   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,6 +142,17 @@ export class UnionPrimitive<TVariants extends UnionVariants, TDiscriminator exte
     return undefined;
   }
 
+  /** 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, TDefined>> = {
     createProxy: (
       env: ProxyEnvironment.ProxyEnvironment,
@@ -141,9 +166,11 @@ export class UnionPrimitive<TVariants extends UnionVariants, TDiscriminator exte
           const state = env.getState(operationPath) as InferUnionState<TVariants> | undefined;
           return (state ?? defaultValue) as MaybeUndefined<InferUnionState<TVariants>, TDefined>;
         },
-        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]> => {
@@ -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,11 +11,18 @@ 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, TDefined extends boolean = false, THasDefault extends boolean = false> {
     readonly _tag: string;
     readonly _State: TState;
     readonly _Proxy: TProxy;
+    readonly _TDefined: TDefined;
+    readonly _THasDefault: THasDefault;
     readonly _internal: PrimitiveInternal<TState, TProxy>;
   }
   
@@ -46,17 +53,17 @@ 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;
   
   /**
    * Helper type to conditionally add undefined based on TDefined.
@@ -69,9 +76,48 @@ export interface Primitive<TState, TProxy> {
    * 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;
+
+  /**
+   * Determines if a field is required for set() operations.
+   * A field is required if: TDefined is true AND THasDefault is false
+   */
+  export type IsRequiredForSet<T> = T extends Primitive<any, any, true, false> ? true : false;
+
+  /**
+   * Extract keys of fields that are required for set() (required without default).
+   */
+  export type RequiredSetKeys<TFields extends Record<string, AnyPrimitive>> = {
+    [K in keyof TFields]: IsRequiredForSet<TFields[K]> extends true ? K : never;
+  }[keyof TFields];
+
+  /**
+   * Extract keys of fields that are optional for set() (has default OR not required).
+   */
+  export type OptionalSetKeys<TFields extends Record<string, AnyPrimitive>> = {
+    [K in keyof TFields]: IsRequiredForSet<TFields[K]> extends true ? never : K;
+  }[keyof TFields];
+
+  /**
+   * Compute the input type for set() operations on a struct.
+   * Required fields (required without default) must be provided.
+   * Optional fields (has default or not required) can be omitted.
+   */
+  export type StructSetInput<TFields extends Record<string, AnyPrimitive>> = 
+    { readonly [K in RequiredSetKeys<TFields>]: InferState<TFields[K]> } &
+    { readonly [K in OptionalSetKeys<TFields>]?: InferState<TFields[K]> };
   
   // =============================================================================
   // Validation Errors
@@ -120,3 +166,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/src/server/errors.ts

@@ -19,7 +19,7 @@ export class MimicServerError extends Error {
  * Error thrown when a transaction fails validation.
  */
 export class ValidationError extends MimicServerError {
-  readonly _tag = "ValidationError";
+  override readonly _tag = "ValidationError";
   readonly transactionId: string;
 
   constructor(transactionId: string, message: string) {
@@ -33,7 +33,7 @@ export class ValidationError extends MimicServerError {
  * Error thrown when an operation is invalid for the current schema.
  */
 export class InvalidOperationError extends MimicServerError {
-  readonly _tag = "InvalidOperationError";
+  override readonly _tag = "InvalidOperationError";
   readonly operationKind: string;
   readonly path: string;
 
@@ -49,9 +49,9 @@ export class InvalidOperationError extends MimicServerError {
  * Error thrown when an operation cannot be applied to the current state.
  */
 export class StateValidationError extends MimicServerError {
-  readonly _tag = "StateValidationError";
+  override readonly _tag = "StateValidationError";
   readonly transactionId: string;
-  readonly cause?: Error;
+  override readonly cause?: Error;
 
   constructor(transactionId: string, message: string, cause?: Error) {
     super(`Transaction ${transactionId} cannot be applied to current state: ${message}`);
@@ -65,7 +65,7 @@ export class StateValidationError extends MimicServerError {
  * Error thrown when attempting to apply an empty transaction.
  */
 export class EmptyTransactionError extends MimicServerError {
-  readonly _tag = "EmptyTransactionError";
+  override readonly _tag = "EmptyTransactionError";
   readonly transactionId: string;
 
   constructor(transactionId: string) {
@@ -79,7 +79,7 @@ export class EmptyTransactionError extends MimicServerError {
  * Error thrown when a duplicate transaction is submitted.
  */
 export class DuplicateTransactionError extends MimicServerError {
-  readonly _tag = "DuplicateTransactionError";
+  override readonly _tag = "DuplicateTransactionError";
   readonly transactionId: string;
 
   constructor(transactionId: string) {