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

package/dist/index.d.mts

@@ -141,11 +141,18 @@ type TransformResult = {
 /**
  * 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
  */
-interface Primitive<TState, TProxy> {
+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>;
 }
 /**
@@ -171,15 +178,15 @@ interface PrimitiveInternal<TState, TProxy> {
 /**
  * Any primitive type - used for generic constraints.
  */
-type AnyPrimitive = Primitive<any, any>;
+type AnyPrimitive = Primitive<any, any, any, any>;
 /**
  * Infer the state type from a primitive.
  */
-type InferState<T> = T extends Primitive<infer S, any> ? S : never;
+type InferState<T> = T extends Primitive<infer S, any, any, any> ? S : never;
 /**
  * Infer the proxy type from a primitive.
  */
-type InferProxy<T> = T extends Primitive<any, infer P> ? P : never;
+type InferProxy<T> = T extends Primitive<any, infer P, any, any> ? P : 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()).
@@ -190,9 +197,36 @@ type MaybeUndefined<T, TDefined extends boolean> = TDefined extends true ? T : T
  * Infer the snapshot type from a primitive.
  * The snapshot is a readonly, type-safe structure suitable for rendering.
  */
-type InferSnapshot<T> = T extends Primitive<any, infer P> ? P extends {
+type InferSnapshot<T> = T extends Primitive<any, infer P, any, any> ? P extends {
   toSnapshot(): infer S;
 } ? S : never : never;
+/**
+ * Extract THasDefault from a primitive.
+ */
+type HasDefault<T> = T extends Primitive<any, any, any, infer H> ? H : false;
+/**
+ * Extract TDefined from a primitive.
+ */
+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
+ */
+type IsRequiredForSet<T> = T extends Primitive<any, any, true, false> ? true : false;
+/**
+ * Extract keys of fields that are required for set() (required without default).
+ */
+type RequiredSetKeys<TFields$1 extends Record<string, AnyPrimitive>> = { [K in keyof TFields$1]: IsRequiredForSet<TFields$1[K]> extends true ? K : never }[keyof TFields$1];
+/**
+ * Extract keys of fields that are optional for set() (has default OR not required).
+ */
+type OptionalSetKeys<TFields$1 extends Record<string, AnyPrimitive>> = { [K in keyof TFields$1]: IsRequiredForSet<TFields$1[K]> extends true ? never : K }[keyof TFields$1];
+/**
+ * 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.
+ */
+type StructSetInput<TFields$1 extends Record<string, AnyPrimitive>> = { readonly [K in RequiredSetKeys<TFields$1>]: InferState<TFields$1[K]> } & { readonly [K in OptionalSetKeys<TFields$1>]?: InferState<TFields$1[K]> };
 declare class ValidationError extends Error {
   readonly _tag = "ValidationError";
   constructor(message: string);
@@ -218,6 +252,19 @@ declare function runValidators<T>(value: T, validators: readonly {
  * @returns True if the operation is compatible, false otherwise.
  */
 declare function isCompatibleOperation(operation: Operation<any, any, any>, operationDefinitions: Record<string, OperationDefinition<any, any, any>>): boolean;
+/**
+ * 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
+ */
+declare function applyDefaults<T extends AnyPrimitive>(primitive: T, value: Partial<InferState<T>>): InferState<T>;
 //#endregion
 //#region src/primitives/String.d.ts
 interface StringProxy<TDefined extends boolean = false> {
@@ -233,84 +280,95 @@ interface StringPrimitiveSchema {
   readonly defaultValue: string | undefined;
   readonly validators: readonly Validator<string>[];
 }
-declare class StringPrimitive<TDefined extends boolean = false> implements Primitive<string, StringProxy<TDefined>> {
+declare class StringPrimitive<TDefined extends boolean = false, THasDefault extends boolean = false> implements Primitive<string, StringProxy<TDefined>, TDefined, THasDefault> {
   readonly _tag: "StringPrimitive";
   readonly _State: string;
   readonly _Proxy: StringProxy<TDefined>;
+  readonly _TDefined: TDefined;
+  readonly _THasDefault: THasDefault;
   private readonly _schema;
   private readonly _opDefinitions;
   constructor(schema: StringPrimitiveSchema);
   /** Mark this string as required */
-  required(): StringPrimitive<true>;
+  required(): StringPrimitive<true, THasDefault>;
   /** Set a default value for this string */
-  default(defaultValue: string): StringPrimitive<true>;
+  default(defaultValue: string): StringPrimitive<true, true>;
   /** Add a custom validation rule */
-  refine(fn: (value: string) => boolean, message: string): StringPrimitive<TDefined>;
+  refine(fn: (value: string) => boolean, message: string): StringPrimitive<TDefined, THasDefault>;
   /** Minimum string length */
-  min(length: number): StringPrimitive<TDefined>;
+  min(length: number): StringPrimitive<TDefined, THasDefault>;
   /** Maximum string length */
-  max(length: number): StringPrimitive<TDefined>;
+  max(length: number): StringPrimitive<TDefined, THasDefault>;
   /** Exact string length */
-  length(exact: number): StringPrimitive<TDefined>;
+  length(exact: number): StringPrimitive<TDefined, THasDefault>;
   /** Match a regex pattern */
-  regex(pattern: RegExp, message?: string): StringPrimitive<TDefined>;
+  regex(pattern: RegExp, message?: string): StringPrimitive<TDefined, THasDefault>;
   /** Validate as email format */
-  email(): StringPrimitive<TDefined>;
+  email(): StringPrimitive<TDefined, THasDefault>;
   /** Validate as URL format */
-  url(): StringPrimitive<TDefined>;
+  url(): StringPrimitive<TDefined, THasDefault>;
   readonly _internal: PrimitiveInternal<string, StringProxy<TDefined>>;
 }
 /** Creates a new StringPrimitive */
-declare const String: () => StringPrimitive<false>;
+declare const String: () => StringPrimitive<false, false>;
 //#endregion
 //#region src/primitives/Struct.d.ts
 /**
  * Maps a schema definition to its state type.
  * { name: StringPrimitive, age: NumberPrimitive } -> { name: string, age: number }
  */
-type InferStructState<TFields extends Record<string, AnyPrimitive>> = { readonly [K in keyof TFields]: InferState<TFields[K]> };
+type InferStructState<TFields$1 extends Record<string, AnyPrimitive>> = { readonly [K in keyof TFields$1]: InferState<TFields$1[K]> };
 /**
  * Maps a schema definition to its snapshot type.
  * Each field's snapshot type is inferred from the field primitive.
  */
-type InferStructSnapshot<TFields extends Record<string, AnyPrimitive>> = { readonly [K in keyof TFields]: InferSnapshot<TFields[K]> };
+type InferStructSnapshot<TFields$1 extends Record<string, AnyPrimitive>> = { readonly [K in keyof TFields$1]: InferSnapshot<TFields$1[K]> };
+/**
+ * Maps a schema definition to a partial update type.
+ * For nested structs, allows recursive partial updates.
+ */
+type StructUpdateValue<TFields$1 extends Record<string, AnyPrimitive>> = { readonly [K in keyof TFields$1]?: TFields$1[K] extends StructPrimitive<infer F, any> ? StructUpdateValue<F> | InferState<TFields$1[K]> : InferState<TFields$1[K]> };
 /**
  * Maps a schema definition to its proxy type.
  * Provides nested field access + get()/set()/toSnapshot() methods for the whole struct.
  */
-type StructProxy<TFields extends Record<string, AnyPrimitive>, TDefined extends boolean = false> = { readonly [K in keyof TFields]: InferProxy<TFields[K]> } & {
+type StructProxy<TFields$1 extends Record<string, AnyPrimitive>, TDefined extends boolean = false> = { readonly [K in keyof TFields$1]: InferProxy<TFields$1[K]> } & {
   /** Gets the entire struct value */
-  get(): MaybeUndefined<InferStructState<TFields>, TDefined>;
-  /** Sets the entire struct value */
-  set(value: InferStructState<TFields>): void;
+  get(): MaybeUndefined<InferStructState<TFields$1>, TDefined>;
+  /** Sets the entire struct value (only fields that are required without defaults must be provided) */
+  set(value: StructSetInput<TFields$1>): void;
+  /** Updates only the specified fields (partial update, handles nested structs recursively) */
+  update(value: StructUpdateValue<TFields$1>): void;
   /** Returns a readonly snapshot of the struct for rendering */
-  toSnapshot(): MaybeUndefined<InferStructSnapshot<TFields>, TDefined>;
+  toSnapshot(): MaybeUndefined<InferStructSnapshot<TFields$1>, TDefined>;
 };
-interface StructPrimitiveSchema<TFields extends Record<string, AnyPrimitive>> {
+interface StructPrimitiveSchema<TFields$1 extends Record<string, AnyPrimitive>> {
   readonly required: boolean;
-  readonly defaultValue: InferStructState<TFields> | undefined;
-  readonly fields: TFields;
-  readonly validators: readonly Validator<InferStructState<TFields>>[];
+  readonly defaultValue: InferStructState<TFields$1> | undefined;
+  readonly fields: TFields$1;
+  readonly validators: readonly Validator<InferStructState<TFields$1>>[];
 }
-declare class StructPrimitive<TFields extends Record<string, AnyPrimitive>, TDefined extends boolean = false> implements Primitive<InferStructState<TFields>, StructProxy<TFields, TDefined>> {
+declare class StructPrimitive<TFields$1 extends Record<string, AnyPrimitive>, TDefined extends boolean = false, THasDefault extends boolean = false> implements Primitive<InferStructState<TFields$1>, StructProxy<TFields$1, TDefined>, TDefined, THasDefault> {
   readonly _tag: "StructPrimitive";
-  readonly _State: InferStructState<TFields>;
-  readonly _Proxy: StructProxy<TFields, TDefined>;
+  readonly _State: InferStructState<TFields$1>;
+  readonly _Proxy: StructProxy<TFields$1, TDefined>;
+  readonly _TDefined: TDefined;
+  readonly _THasDefault: THasDefault;
   private readonly _schema;
   private readonly _opDefinitions;
-  constructor(schema: StructPrimitiveSchema<TFields>);
+  constructor(schema: StructPrimitiveSchema<TFields$1>);
   /** Mark this struct as required */
-  required(): StructPrimitive<TFields, true>;
+  required(): StructPrimitive<TFields$1, true, THasDefault>;
   /** Set a default value for this struct */
-  default(defaultValue: InferStructState<TFields>): StructPrimitive<TFields, true>;
+  default(defaultValue: StructSetInput<TFields$1>): StructPrimitive<TFields$1, true, true>;
   /** Get the fields schema */
-  get fields(): TFields;
+  get fields(): TFields$1;
   /** Add a custom validation rule (useful for cross-field validation) */
-  refine(fn: (value: InferStructState<TFields>) => boolean, message: string): StructPrimitive<TFields, TDefined>;
-  readonly _internal: PrimitiveInternal<InferStructState<TFields>, StructProxy<TFields, TDefined>>;
+  refine(fn: (value: InferStructState<TFields$1>) => boolean, message: string): StructPrimitive<TFields$1, TDefined, THasDefault>;
+  readonly _internal: PrimitiveInternal<InferStructState<TFields$1>, StructProxy<TFields$1, TDefined>>;
 }
 /** Creates a new StructPrimitive with the given fields */
-declare const Struct: <TFields extends Record<string, AnyPrimitive>>(fields: TFields) => StructPrimitive<TFields, false>;
+declare const Struct: <TFields$1 extends Record<string, AnyPrimitive>>(fields: TFields$1) => StructPrimitive<TFields$1, false, false>;
 //#endregion
 //#region src/primitives/Boolean.d.ts
 interface BooleanProxy<TDefined extends boolean = false> {
@@ -326,23 +384,25 @@ interface BooleanPrimitiveSchema {
   readonly defaultValue: boolean | undefined;
   readonly validators: readonly Validator<boolean>[];
 }
-declare class BooleanPrimitive<TDefined extends boolean = false> implements Primitive<boolean, BooleanProxy<TDefined>> {
+declare class BooleanPrimitive<TDefined extends boolean = false, THasDefault extends boolean = false> implements Primitive<boolean, BooleanProxy<TDefined>, TDefined, THasDefault> {
   readonly _tag: "BooleanPrimitive";
   readonly _State: boolean;
   readonly _Proxy: BooleanProxy<TDefined>;
+  readonly _TDefined: TDefined;
+  readonly _THasDefault: THasDefault;
   private readonly _schema;
   private readonly _opDefinitions;
   constructor(schema: BooleanPrimitiveSchema);
   /** Mark this boolean as required */
-  required(): BooleanPrimitive<true>;
+  required(): BooleanPrimitive<true, THasDefault>;
   /** Set a default value for this boolean */
-  default(defaultValue: boolean): BooleanPrimitive<true>;
+  default(defaultValue: boolean): BooleanPrimitive<true, true>;
   /** Add a custom validation rule */
-  refine(fn: (value: boolean) => boolean, message: string): BooleanPrimitive<TDefined>;
+  refine(fn: (value: boolean) => boolean, message: string): BooleanPrimitive<TDefined, THasDefault>;
   readonly _internal: PrimitiveInternal<boolean, BooleanProxy<TDefined>>;
 }
 /** Creates a new BooleanPrimitive */
-declare const Boolean: () => BooleanPrimitive<false>;
+declare const Boolean: () => BooleanPrimitive<false, false>;
 //#endregion
 //#region src/primitives/Number.d.ts
 interface NumberProxy<TDefined extends boolean = false> {
@@ -358,33 +418,35 @@ interface NumberPrimitiveSchema {
   readonly defaultValue: number | undefined;
   readonly validators: readonly Validator<number>[];
 }
-declare class NumberPrimitive<TDefined extends boolean = false> implements Primitive<number, NumberProxy<TDefined>> {
+declare class NumberPrimitive<TDefined extends boolean = false, THasDefault extends boolean = false> implements Primitive<number, NumberProxy<TDefined>, TDefined, THasDefault> {
   readonly _tag: "NumberPrimitive";
   readonly _State: number;
   readonly _Proxy: NumberProxy<TDefined>;
+  readonly _TDefined: TDefined;
+  readonly _THasDefault: THasDefault;
   private readonly _schema;
   private readonly _opDefinitions;
   constructor(schema: NumberPrimitiveSchema);
   /** Mark this number as required */
-  required(): NumberPrimitive<true>;
+  required(): NumberPrimitive<true, THasDefault>;
   /** Set a default value for this number */
-  default(defaultValue: number): NumberPrimitive<true>;
+  default(defaultValue: number): NumberPrimitive<true, true>;
   /** Add a custom validation rule */
-  refine(fn: (value: number) => boolean, message: string): NumberPrimitive<TDefined>;
+  refine(fn: (value: number) => boolean, message: string): NumberPrimitive<TDefined, THasDefault>;
   /** Minimum value (inclusive) */
-  min(value: number): NumberPrimitive<TDefined>;
+  min(value: number): NumberPrimitive<TDefined, THasDefault>;
   /** Maximum value (inclusive) */
-  max(value: number): NumberPrimitive<TDefined>;
+  max(value: number): NumberPrimitive<TDefined, THasDefault>;
   /** Must be positive (> 0) */
-  positive(): NumberPrimitive<TDefined>;
+  positive(): NumberPrimitive<TDefined, THasDefault>;
   /** Must be negative (< 0) */
-  negative(): NumberPrimitive<TDefined>;
+  negative(): NumberPrimitive<TDefined, THasDefault>;
   /** Must be an integer */
-  int(): NumberPrimitive<TDefined>;
+  int(): NumberPrimitive<TDefined, THasDefault>;
   readonly _internal: PrimitiveInternal<number, NumberProxy<TDefined>>;
 }
 /** Creates a new NumberPrimitive */
-declare const Number: () => NumberPrimitive<false>;
+declare const Number: () => NumberPrimitive<false, false>;
 //#endregion
 //#region src/primitives/Literal.d.ts
 /** Valid literal types */
@@ -402,23 +464,25 @@ interface LiteralPrimitiveSchema<T extends LiteralValue> {
   readonly defaultValue: T | undefined;
   readonly literal: T;
 }
-declare class LiteralPrimitive<T extends LiteralValue, TDefined extends boolean = false> implements Primitive<T, LiteralProxy<T, TDefined>> {
+declare class LiteralPrimitive<T extends LiteralValue, TDefined extends boolean = false, THasDefault extends boolean = false> implements Primitive<T, LiteralProxy<T, TDefined>, TDefined, THasDefault> {
   readonly _tag: "LiteralPrimitive";
   readonly _State: T;
   readonly _Proxy: LiteralProxy<T, TDefined>;
+  readonly _TDefined: TDefined;
+  readonly _THasDefault: THasDefault;
   private readonly _schema;
   private readonly _opDefinitions;
   constructor(schema: LiteralPrimitiveSchema<T>);
   /** Mark this literal as required */
-  required(): LiteralPrimitive<T, true>;
+  required(): LiteralPrimitive<T, true, THasDefault>;
   /** Set a default value for this literal */
-  default(defaultValue: T): LiteralPrimitive<T, true>;
+  default(defaultValue: T): LiteralPrimitive<T, true, true>;
   /** Get the literal value this primitive represents */
   get literal(): T;
   readonly _internal: PrimitiveInternal<T, LiteralProxy<T, TDefined>>;
 }
 /** Creates a new LiteralPrimitive with the given literal value */
-declare const Literal: <T extends LiteralValue>(literal: T) => LiteralPrimitive<T, false>;
+declare const Literal: <T extends LiteralValue>(literal: T) => LiteralPrimitive<T, false, false>;
 //#endregion
 //#region src/primitives/Array.d.ts
 /**
@@ -440,15 +504,21 @@ interface ArrayEntrySnapshot<TElement extends AnyPrimitive> {
  * Snapshot type for arrays - always an array (never undefined)
  */
 type ArraySnapshot<TElement extends AnyPrimitive> = readonly ArrayEntrySnapshot<TElement>[];
+/**
+ * Compute the input type for array element values.
+ * If the element is a struct, uses StructSetInput (partial with defaults).
+ * Otherwise uses the full state type.
+ */
+type ArrayElementSetInput<TElement extends AnyPrimitive> = TElement extends StructPrimitive<infer TFields, any, any> ? StructSetInput<TFields> : InferState<TElement>;
 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 */
@@ -468,29 +538,31 @@ interface ArrayPrimitiveSchema<TElement extends AnyPrimitive> {
   readonly element: TElement;
   readonly validators: readonly Validator<ArrayState<TElement>>[];
 }
-declare class ArrayPrimitive<TElement extends AnyPrimitive> implements Primitive<ArrayState<TElement>, ArrayProxy<TElement>> {
+declare class ArrayPrimitive<TElement extends AnyPrimitive, TDefined extends boolean = false, THasDefault extends boolean = false> implements Primitive<ArrayState<TElement>, ArrayProxy<TElement>, TDefined, THasDefault> {
   readonly _tag: "ArrayPrimitive";
   readonly _State: ArrayState<TElement>;
   readonly _Proxy: ArrayProxy<TElement>;
+  readonly _TDefined: TDefined;
+  readonly _THasDefault: THasDefault;
   private readonly _schema;
   private readonly _opDefinitions;
   constructor(schema: ArrayPrimitiveSchema<TElement>);
   /** Mark this array as required */
-  required(): ArrayPrimitive<TElement>;
+  required(): ArrayPrimitive<TElement, true, THasDefault>;
   /** Set a default value for this array */
-  default(defaultValue: ArrayState<TElement>): ArrayPrimitive<TElement>;
+  default(defaultValue: ArrayState<TElement>): ArrayPrimitive<TElement, true, true>;
   /** Get the element primitive */
   get element(): TElement;
   /** 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, TDefined, THasDefault>;
   /** Minimum array length */
-  minLength(length: number): ArrayPrimitive<TElement>;
+  minLength(length: number): ArrayPrimitive<TElement, TDefined, THasDefault>;
   /** Maximum array length */
-  maxLength(length: number): ArrayPrimitive<TElement>;
+  maxLength(length: number): ArrayPrimitive<TElement, TDefined, THasDefault>;
   readonly _internal: PrimitiveInternal<ArrayState<TElement>, ArrayProxy<TElement>>;
 }
 /** Creates a new ArrayPrimitive with the given element type */
-declare const Array$1: <TElement extends AnyPrimitive>(element: TElement) => ArrayPrimitive<TElement>;
+declare const Array$1: <TElement extends AnyPrimitive>(element: TElement) => ArrayPrimitive<TElement, false, false>;
 //#endregion
 //#region src/primitives/Lazy.d.ts
 /**
@@ -525,7 +597,7 @@ declare const Lazy: <TThunk extends () => AnyPrimitive>(thunk: TThunk) => LazyPr
 /**
  * Type constraint for union variants - must be struct primitives
  */
-type UnionVariants = Record<string, StructPrimitive<any, any>>;
+type UnionVariants = Record<string, StructPrimitive<any, any, any>>;
 /**
  * Infer the union state type from variants
  */
@@ -534,14 +606,19 @@ type InferUnionState<TVariants extends UnionVariants> = { [K in keyof TVariants]
  * Infer the union snapshot type from variants
  */
 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.
+ */
+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
  */
-interface UnionProxy<TVariants extends UnionVariants, TDiscriminator extends string, TDefined extends boolean = false> {
+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$1 extends keyof TVariants>(variant: K$1): InferProxy<TVariants[K$1]>;
   /** Pattern match on the variant type */
@@ -555,23 +632,27 @@ interface UnionPrimitiveSchema<TVariants extends UnionVariants, TDiscriminator e
   readonly discriminator: TDiscriminator;
   readonly variants: TVariants;
 }
-declare class UnionPrimitive<TVariants extends UnionVariants, TDiscriminator extends string = "type", TDefined extends boolean = false> implements Primitive<InferUnionState<TVariants>, UnionProxy<TVariants, TDiscriminator, TDefined>> {
+declare 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";
   readonly _State: InferUnionState<TVariants>;
   readonly _Proxy: UnionProxy<TVariants, TDiscriminator, TDefined>;
+  readonly _TDefined: TDefined;
+  readonly _THasDefault: THasDefault;
   private readonly _schema;
   private readonly _opDefinitions;
   constructor(schema: UnionPrimitiveSchema<TVariants, TDiscriminator>);
   /** Mark this union as required */
-  required(): UnionPrimitive<TVariants, TDiscriminator, true>;
+  required(): UnionPrimitive<TVariants, TDiscriminator, true, THasDefault>;
   /** Set a default value for this union */
-  default(defaultValue: InferUnionState<TVariants>): UnionPrimitive<TVariants, TDiscriminator, true>;
+  default(defaultValue: UnionSetInput<TVariants>): UnionPrimitive<TVariants, TDiscriminator, true, true>;
   /** Get the discriminator field name */
   get discriminator(): TDiscriminator;
   /** Get the variants */
   get variants(): TVariants;
   /** Find the variant key from a state value */
   private _findVariantKey;
+  /** Apply defaults to a variant value based on the discriminator */
+  private _applyVariantDefaults;
   readonly _internal: PrimitiveInternal<InferUnionState<TVariants>, UnionProxy<TVariants, TDiscriminator, TDefined>>;
 }
 /** Options for creating a Union primitive */
@@ -582,14 +663,14 @@ interface UnionOptions<TVariants extends UnionVariants, TDiscriminator extends s
   readonly variants: TVariants;
 }
 /** Creates a new UnionPrimitive with the given variants */
-declare function Union<TVariants extends UnionVariants>(options: UnionOptions<TVariants, "type">): UnionPrimitive<TVariants, "type", false>;
-declare function Union<TVariants extends UnionVariants, TDiscriminator extends string>(options: UnionOptions<TVariants, TDiscriminator>): UnionPrimitive<TVariants, TDiscriminator, false>;
+declare function Union<TVariants extends UnionVariants>(options: UnionOptions<TVariants, "type">): UnionPrimitive<TVariants, "type", false, false>;
+declare function Union<TVariants extends UnionVariants, TDiscriminator extends string>(options: UnionOptions<TVariants, TDiscriminator>): UnionPrimitive<TVariants, TDiscriminator, false, false>;
 //#endregion
 //#region src/primitives/Either.d.ts
 /**
  * Scalar primitives that can be used as variants in Either
  */
-type ScalarPrimitive = StringPrimitive<any> | NumberPrimitive<any> | BooleanPrimitive<any> | LiteralPrimitive<any, any>;
+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
  */
@@ -625,17 +706,19 @@ interface EitherPrimitiveSchema<TVariants extends readonly ScalarPrimitive[]> {
   readonly defaultValue: InferEitherState<TVariants> | undefined;
   readonly variants: TVariants;
 }
-declare class EitherPrimitive<TVariants extends readonly ScalarPrimitive[], TDefined extends boolean = false> implements Primitive<InferEitherState<TVariants>, EitherProxy<TVariants, TDefined>> {
+declare class EitherPrimitive<TVariants extends readonly ScalarPrimitive[], TDefined extends boolean = false, THasDefault extends boolean = false> implements Primitive<InferEitherState<TVariants>, EitherProxy<TVariants, TDefined>, TDefined, THasDefault> {
   readonly _tag: "EitherPrimitive";
   readonly _State: InferEitherState<TVariants>;
   readonly _Proxy: EitherProxy<TVariants, TDefined>;
+  readonly _TDefined: TDefined;
+  readonly _THasDefault: THasDefault;
   private readonly _schema;
   private readonly _opDefinitions;
   constructor(schema: EitherPrimitiveSchema<TVariants>);
   /** Mark this either as required */
-  required(): EitherPrimitive<TVariants, true>;
+  required(): EitherPrimitive<TVariants, true, THasDefault>;
   /** Set a default value for this either */
-  default(defaultValue: InferEitherState<TVariants>): EitherPrimitive<TVariants, true>;
+  default(defaultValue: InferEitherState<TVariants>): EitherPrimitive<TVariants, true, true>;
   /** Get the variants */
   get variants(): TVariants;
   /**
@@ -680,9 +763,17 @@ declare class EitherPrimitive<TVariants extends readonly ScalarPrimitive[], TDef
  * );
  * ```
  */
-declare function Either<TVariants extends readonly ScalarPrimitive[]>(...variants: TVariants): EitherPrimitive<TVariants, false>;
+declare function Either<TVariants extends readonly ScalarPrimitive[]>(...variants: TVariants): EitherPrimitive<TVariants, false, false>;
 //#endregion
 //#region src/primitives/TreeNode.d.ts
+/**
+ * Branded type for TreeNodeSelf - distinguishable at compile time
+ */
+declare const SelfBrand: unique symbol;
+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.
@@ -691,51 +782,59 @@ declare function Either<TVariants extends readonly ScalarPrimitive[]>(...variant
  * ```typescript
  * const FolderNode = TreeNode("folder", {
  *   data: Struct({ name: String() }),
- *   children: [Self], // Folder can contain other folders
+ *   children: [TreeNodeSelf], // Folder can contain other folders
  * });
  * ```
  */
-declare const TreeNodeSelf: AnyTreeNodePrimitive;
+declare const TreeNodeSelf: TreeNodeSelfType;
+/**
+ * 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.
  */
-type TreeNodeChildren = readonly AnyTreeNodePrimitive[] | Function;
+type TreeNodeChildrenInput = readonly (AnyTreeNodePrimitive | TreeNodeSelfType)[] | (() => readonly (AnyTreeNodePrimitive | TreeNodeSelfType)[]);
 /**
  * Any TreeNodePrimitive type - used for generic constraints.
  */
-type AnyTreeNodePrimitive = TreeNodePrimitive<string, StructPrimitive<any>>;
+type AnyTreeNodePrimitive = TreeNodePrimitive<string, StructPrimitive<any>, any>;
 /**
  * Infer the data state type from a TreeNodePrimitive
  */
-type InferTreeNodeDataState<T extends AnyTreeNodePrimitive> = T extends TreeNodePrimitive<any, infer TData> ? InferState<TData> : never;
+type InferTreeNodeDataState<T extends AnyTreeNodePrimitive> = T extends TreeNodePrimitive<any, infer TData, any> ? InferState<TData> : never;
 /**
  * Infer the type literal from a TreeNodePrimitive
  */
-type InferTreeNodeType<T extends AnyTreeNodePrimitive> = T extends TreeNodePrimitive<infer TType, any> ? TType : never;
+type InferTreeNodeType<T extends AnyTreeNodePrimitive> = 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
  */
-type InferTreeNodeChildren<_T extends AnyTreeNodePrimitive> = AnyTreeNodePrimitive;
+type InferTreeNodeChildren<T> = T extends TreeNodePrimitive<any, any, infer TChildren> ? TChildren : never;
 /**
  * Configuration for a TreeNode primitive
  */
-interface TreeNodeConfig<TData$1 extends StructPrimitive<any>> {
+interface TreeNodeConfig<TData$1 extends StructPrimitive<any>, TChildren extends readonly (AnyTreeNodePrimitive | TreeNodeSelfType)[]> {
   readonly data: TData$1;
-  readonly children: TreeNodeChildren;
+  readonly children: TChildren | (() => TChildren);
 }
 /**
  * TreeNodePrimitive - defines a node type with its data schema and allowed children
  */
-declare class TreeNodePrimitive<TType extends string, TData$1 extends StructPrimitive<any>> {
+declare class TreeNodePrimitive<TType extends string, TData$1 extends StructPrimitive<any>, TChildren extends AnyTreeNodePrimitive = AnyTreeNodePrimitive> {
   readonly _tag: "TreeNodePrimitive";
   readonly _Type: TType;
   readonly _Data: TData$1;
+  readonly _Children: TChildren;
   private readonly _type;
   private readonly _data;
   private readonly _children;
   private _resolvedChildren;
-  constructor(type: TType, config: TreeNodeConfig<TData$1>);
+  constructor(type: TType, config: TreeNodeConfig<TData$1, readonly (AnyTreeNodePrimitive | TreeNodeSelfType)[]>);
   /** Get the node type identifier */
   get type(): TType;
   /** Get the data primitive */
@@ -746,7 +845,7 @@ declare class TreeNodePrimitive<TType extends string, TData$1 extends StructPrim
   isChildAllowed(childType: string): boolean;
 }
 /** Creates a new TreeNodePrimitive with the given type and config */
-declare const TreeNode: <TType extends string, TData$1 extends StructPrimitive<any>>(type: TType, config: TreeNodeConfig<TData$1>) => TreeNodePrimitive<TType, TData$1>;
+declare const TreeNode: <TType extends string, TData$1 extends StructPrimitive<any>, const TChildren extends readonly (AnyTreeNodePrimitive | TreeNodeSelfType)[]>(type: TType, config: TreeNodeConfig<TData$1, TChildren>) => TreeNodePrimitive<TType, TData$1, ResolveChildrenUnion<TChildren, TreeNodePrimitive<TType, TData$1, any>>>;
 //#endregion
 //#region src/primitives/Tree.d.ts
 /**
@@ -772,7 +871,7 @@ interface TypedTreeNodeState<TNode extends AnyTreeNodePrimitive> {
 /**
  * The state type for trees - a flat array of nodes
  */
-type TreeState<TRoot$1 extends AnyTreeNodePrimitive> = readonly TreeNodeState[];
+type TreeState<_TRoot extends AnyTreeNodePrimitive> = readonly TreeNodeState[];
 /**
  * Snapshot of a single node for UI rendering (data properties spread at node level)
  */
@@ -785,6 +884,15 @@ type TreeNodeSnapshot<TNode extends AnyTreeNodePrimitive> = {
  * Infer the snapshot type for a tree (recursive tree structure for UI)
  */
 type InferTreeSnapshot<T extends TreePrimitive<any>> = T extends TreePrimitive<infer TRoot> ? TreeNodeSnapshot<TRoot> : never;
+/**
+ * Helper type to infer the update value type from a TreeNode's data
+ */
+type TreeNodeUpdateValue<TNode extends AnyTreeNodePrimitive> = TNode["data"] extends StructPrimitive<infer TFields, any, any> ? StructUpdateValue<TFields> : never;
+/**
+ * Helper type to infer the input type for node data (with defaults applied).
+ * Uses StructSetInput for struct data, making fields with defaults optional.
+ */
+type TreeNodeDataSetInput<TNode extends AnyTreeNodePrimitive> = TNode["data"] extends StructPrimitive<infer TFields, any, any> ? StructSetInput<TFields> : InferTreeNodeDataState<TNode>;
 /**
  * Typed proxy for a specific node type - provides type-safe data access
  */
@@ -797,11 +905,13 @@ interface TypedNodeProxy<TNode extends AnyTreeNodePrimitive> {
   readonly data: InferProxy<TNode["data"]>;
   /** Get the raw node state */
   get(): TypedTreeNodeState<TNode>;
+  /** Updates only the specified data fields (partial update, handles nested structs recursively) */
+  update(value: TreeNodeUpdateValue<TNode>): void;
 }
 /**
  * Node proxy with type narrowing capabilities
  */
-interface TreeNodeProxyBase<TRoot$1 extends AnyTreeNodePrimitive> {
+interface TreeNodeProxyBase<_TRoot extends AnyTreeNodePrimitive> {
   /** The node ID */
   readonly id: string;
   /** The node type (string) */
@@ -827,16 +937,16 @@ interface TreeProxy<TRoot$1 extends AnyTreeNodePrimitive> {
   children(parentId: string | null): TreeNodeState[];
   /** Gets a node proxy by ID with type narrowing capabilities */
   node(id: string): TreeNodeProxyBase<TRoot$1> | undefined;
-  /** Insert a new node as the first child */
-  insertFirst<TNode extends AnyTreeNodePrimitive>(parentId: string | null, nodeType: TNode, data: InferTreeNodeDataState<TNode>): string;
-  /** Insert a new node as the last child */
-  insertLast<TNode extends AnyTreeNodePrimitive>(parentId: string | null, nodeType: TNode, data: InferTreeNodeDataState<TNode>): string;
-  /** Insert a new node at a specific index among siblings */
-  insertAt<TNode extends AnyTreeNodePrimitive>(parentId: string | null, index: number, nodeType: TNode, data: InferTreeNodeDataState<TNode>): string;
-  /** Insert a new node after a sibling */
-  insertAfter<TNode extends AnyTreeNodePrimitive>(siblingId: string, nodeType: TNode, data: InferTreeNodeDataState<TNode>): string;
-  /** Insert a new node before a sibling */
-  insertBefore<TNode extends AnyTreeNodePrimitive>(siblingId: string, nodeType: TNode, data: InferTreeNodeDataState<TNode>): string;
+  /** Insert a new node as the first child (applies defaults for node data) */
+  insertFirst<TNode extends AnyTreeNodePrimitive>(parentId: string | null, nodeType: TNode, data: TreeNodeDataSetInput<TNode>): string;
+  /** Insert a new node as the last child (applies defaults for node data) */
+  insertLast<TNode extends AnyTreeNodePrimitive>(parentId: string | null, nodeType: TNode, data: TreeNodeDataSetInput<TNode>): string;
+  /** Insert a new node at a specific index among siblings (applies defaults for node data) */
+  insertAt<TNode extends AnyTreeNodePrimitive>(parentId: string | null, index: number, nodeType: TNode, data: TreeNodeDataSetInput<TNode>): string;
+  /** Insert a new node after a sibling (applies defaults for node data) */
+  insertAfter<TNode extends AnyTreeNodePrimitive>(siblingId: string, nodeType: TNode, data: TreeNodeDataSetInput<TNode>): string;
+  /** Insert a new node before a sibling (applies defaults for node data) */
+  insertBefore<TNode extends AnyTreeNodePrimitive>(siblingId: string, nodeType: TNode, data: TreeNodeDataSetInput<TNode>): string;
   /** Remove a node and all its descendants */
   remove(id: string): void;
   /** Move a node to a new parent at a specific index */
@@ -851,6 +961,8 @@ interface TreeProxy<TRoot$1 extends AnyTreeNodePrimitive> {
   moveToLast(nodeId: string, newParentId: string | null): void;
   /** Returns a typed proxy for a specific node's data */
   at<TNode extends AnyTreeNodePrimitive>(id: string, nodeType: TNode): InferProxy<TNode["data"]>;
+  /** Updates only the specified data fields of a node (partial update) */
+  updateAt<TNode extends AnyTreeNodePrimitive>(id: string, nodeType: TNode, value: TreeNodeUpdateValue<TNode>): void;
   /** Convert tree to a nested snapshot for UI rendering */
   toSnapshot(): TreeNodeSnapshot<TRoot$1> | undefined;
 }
@@ -860,22 +972,24 @@ interface TreePrimitiveSchema<TRoot$1 extends AnyTreeNodePrimitive> {
   readonly root: TRoot$1;
   readonly validators: readonly Validator<TreeState<TRoot$1>>[];
 }
-declare class TreePrimitive<TRoot$1 extends AnyTreeNodePrimitive> implements Primitive<TreeState<TRoot$1>, TreeProxy<TRoot$1>> {
+declare class TreePrimitive<TRoot$1 extends AnyTreeNodePrimitive, TDefined extends boolean = false, THasDefault extends boolean = false> implements Primitive<TreeState<TRoot$1>, TreeProxy<TRoot$1>, TDefined, THasDefault> {
   readonly _tag: "TreePrimitive";
   readonly _State: TreeState<TRoot$1>;
   readonly _Proxy: TreeProxy<TRoot$1>;
+  readonly _TDefined: TDefined;
+  readonly _THasDefault: THasDefault;
   private readonly _schema;
   private _nodeTypeRegistry;
   private readonly _opDefinitions;
   constructor(schema: TreePrimitiveSchema<TRoot$1>);
   /** Mark this tree as required */
-  required(): TreePrimitive<TRoot$1>;
+  required(): TreePrimitive<TRoot$1, true, THasDefault>;
   /** Set a default value for this tree */
-  default(defaultValue: TreeState<TRoot$1>): TreePrimitive<TRoot$1>;
+  default(defaultValue: TreeState<TRoot$1>): TreePrimitive<TRoot$1, true, true>;
   /** Get the root node type */
   get root(): TRoot$1;
   /** Add a custom validation rule */
-  refine(fn: (value: TreeState<TRoot$1>) => boolean, message: string): TreePrimitive<TRoot$1>;
+  refine(fn: (value: TreeState<TRoot$1>) => boolean, message: string): TreePrimitive<TRoot$1, TDefined, THasDefault>;
   /**
    * Build a registry of all node types reachable from root
    */
@@ -896,9 +1010,9 @@ interface TreeOptions<TRoot$1 extends AnyTreeNodePrimitive> {
   readonly root: TRoot$1;
 }
 /** Creates a new TreePrimitive with the given root node type */
-declare const Tree: <TRoot$1 extends AnyTreeNodePrimitive>(options: TreeOptions<TRoot$1>) => TreePrimitive<TRoot$1>;
+declare const Tree: <TRoot$1 extends AnyTreeNodePrimitive>(options: TreeOptions<TRoot$1>) => TreePrimitive<TRoot$1, false, false>;
 declare namespace Primitive_d_exports {
-  export { AnyPrimitive, AnyTreeNodePrimitive, Array$1 as Array, ArrayEntry, ArrayEntrySnapshot, ArrayPrimitive, ArrayProxy, ArraySnapshot, ArrayState, Boolean, BooleanPrimitive, BooleanProxy, Either, EitherMatchHandlers, EitherPrimitive, EitherProxy, InferEitherSnapshot, InferEitherState, InferLazyProxy, InferLazySnapshot, InferLazyState, InferProxy, InferSnapshot, InferState, InferStructSnapshot, InferStructState, InferTreeNodeChildren, InferTreeNodeDataState, InferTreeNodeType, InferTreeSnapshot, InferUnionSnapshot, InferUnionState, Lazy, LazyPrimitive, Literal, LiteralPrimitive, LiteralProxy, LiteralValue, MaybeUndefined, Number, NumberPrimitive, NumberProxy, Primitive, PrimitiveInternal, ScalarPrimitive, String, StringPrimitive, StringProxy, Struct, StructPrimitive, StructProxy, Tree, TreeNode, TreeNodeChildren, TreeNodeConfig, TreeNodePrimitive, TreeNodeProxyBase, TreeNodeSelf, TreeNodeSnapshot, TreeNodeState, TreeOptions, TreePrimitive, TreeProxy, TreeState, TypedNodeProxy, TypedTreeNodeState, Union, UnionOptions, UnionPrimitive, UnionProxy, UnionVariants, ValidationError, Validator, isCompatibleOperation, runValidators };
+  export { AnyPrimitive, AnyTreeNodePrimitive, Array$1 as Array, ArrayElementSetInput, ArrayEntry, ArrayEntrySnapshot, ArrayPrimitive, ArrayProxy, ArraySnapshot, ArrayState, Boolean, BooleanPrimitive, BooleanProxy, Either, EitherMatchHandlers, EitherPrimitive, EitherProxy, HasDefault, InferEitherSnapshot, InferEitherState, InferLazyProxy, InferLazySnapshot, InferLazyState, InferProxy, InferSnapshot, InferState, InferStructSnapshot, InferStructState, InferTreeNodeChildren, InferTreeNodeDataState, InferTreeNodeType, InferTreeSnapshot, InferUnionSnapshot, InferUnionState, IsDefined, IsRequiredForSet, Lazy, LazyPrimitive, Literal, LiteralPrimitive, LiteralProxy, LiteralValue, MaybeUndefined, Number, NumberPrimitive, NumberProxy, OptionalSetKeys, Primitive, PrimitiveInternal, RequiredSetKeys, ScalarPrimitive, String, StringPrimitive, StringProxy, Struct, StructPrimitive, StructProxy, StructSetInput, StructUpdateValue, Tree, TreeNode, TreeNodeChildrenInput, TreeNodeConfig, TreeNodeDataSetInput, TreeNodePrimitive, TreeNodeProxyBase, TreeNodeSelf, TreeNodeSelfType, TreeNodeSnapshot, TreeNodeState, TreeNodeUpdateValue, TreeOptions, TreePrimitive, TreeProxy, TreeState, TypedNodeProxy, TypedTreeNodeState, Union, UnionOptions, UnionPrimitive, UnionProxy, UnionSetInput, UnionVariants, ValidationError, Validator, applyDefaults, isCompatibleOperation, runValidators };
 }
 declare namespace Transaction_d_exports {
   export { EncodedTransaction, Transaction, decode, empty, encode, isEmpty, make$2 as make, merge };