@zod-utils/core 1.1.0 → 2.0.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as z from 'zod';
-import { util, z as z$1 } from 'zod';
+import { z as z$1, util } from 'zod';
 import { $InferUnionInput, $ZodCheckLessThanDef, $ZodCheckGreaterThanDef, $ZodCheckMultipleOfDef, $ZodCheckNumberFormatDef, $ZodCheckBigIntFormatDef, $ZodCheckMaxSizeDef, $ZodCheckMinSizeDef, $ZodCheckSizeEqualsDef, $ZodCheckMaxLengthDef, $ZodCheckMinLengthDef, $ZodCheckLengthEqualsDef, $ZodCheckStringFormatDef, $ZodCheckRegexDef, $ZodCheckLowerCaseDef, $ZodCheckUpperCaseDef, $ZodCheckIncludesDef, $ZodCheckStartsWithDef, $ZodCheckEndsWithDef, $ZodCheckPropertyDef, $ZodCheckMimeTypeDef, $ZodCheckOverwriteDef } from 'zod/v4/core';
 
 /**
@@ -45,6 +45,95 @@ import { $InferUnionInput, $ZodCheckLessThanDef, $ZodCheckGreaterThanDef, $ZodCh
 type Simplify<T> = {
     [K in keyof T]: T[K];
 } & {};
+/**
+ * Extracts all field keys from a Zod schema's input type.
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({ name: z.string(), age: z.number() });
+ * type Keys = DiscriminatorKey<typeof schema>;
+ * // "name" | "age"
+ * ```
+ */
+type DiscriminatorKey<TSchema extends z$1.ZodType> = keyof z$1.input<TSchema> & string;
+/**
+ * Extracts the value type for a discriminator field.
+ *
+ * @example
+ * ```typescript
+ * const schema = z.discriminatedUnion('mode', [
+ *   z.object({ mode: z.literal('create'), name: z.string() }),
+ *   z.object({ mode: z.literal('edit'), id: z.number() }),
+ * ]);
+ * type Mode = DiscriminatorValue<typeof schema, 'mode'>;
+ * // "create" | "edit"
+ * ```
+ */
+type DiscriminatorValue<TSchema extends z$1.ZodType, TDiscriminatorKey extends DiscriminatorKey<TSchema>> = TDiscriminatorKey extends string ? z$1.input<TSchema>[TDiscriminatorKey] & util.Literal : never;
+/**
+ * Discriminator configuration for discriminated union schemas.
+ */
+type Discriminator<TSchema extends z$1.ZodType, TDiscriminatorKey extends DiscriminatorKey<TSchema>, TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>> = {
+    key: TDiscriminatorKey;
+    value: TDiscriminatorValue;
+};
+type Primitive = string | number | boolean | null | undefined | symbol | bigint;
+type NonZeroDigit = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+type PathsHint<T, Prefix extends string = ''> = T extends Primitive ? never : T extends (infer E)[] ? (Prefix extends '' ? never : Prefix) | `${Prefix}.0` | PathsHint<E, `${Prefix}.0`> : T extends object ? {
+    [K in keyof T & string]: (Prefix extends '' ? K : `${Prefix}.${K}`) | PathsHint<T[K], Prefix extends '' ? K : `${Prefix}.${K}`>;
+}[keyof T & string] : never;
+type NonZeroIndex = `${NonZeroDigit}` | `${NonZeroDigit}${number}`;
+type PathsLoose<T, Prefix extends string = ''> = T extends Primitive ? never : T extends (infer E)[] ? (Prefix extends '' ? never : Prefix) | `${Prefix}.${NonZeroIndex}` | PathsLoose<E, `${Prefix}.${NonZeroIndex}`> : T extends object ? {
+    [K in keyof T & string]: (Prefix extends '' ? K : `${Prefix}.${K}`) | PathsLoose<T[K], Prefix extends '' ? K : `${Prefix}.${K}`>;
+}[keyof T & string] : never;
+/**
+ * Generates all valid dot-notation paths for a given type.
+ * Supports nested objects and arrays with numeric indices.
+ *
+ * @example
+ * ```typescript
+ * type User = { name: string; address: { city: string } };
+ * type UserPaths = Paths<User>;
+ * // "name" | "address" | "address.city"
+ * ```
+ */
+type Paths<T> = PathsHint<T> | PathsLoose<T>;
+/**
+ * Extracts fields common to all variants in a union type.
+ *
+ * Uses `Pick<T, keyof T>` to normalize union types by extracting only
+ * the keys that exist across all union members.
+ *
+ * @example
+ * ```typescript
+ * type A = { mode: 'create'; name: string };
+ * type B = { mode: 'edit'; id: number };
+ * type Common = CommonFields<A | B>;
+ * // { mode: 'create' | 'edit' }
+ * ```
+ */
+type CommonFields<T> = Pick<T, keyof T>;
+/**
+ * Generates valid dot-notation paths for fields in a discriminated union variant.
+ *
+ * Given a schema and discriminator value, extracts all possible field paths
+ * (including nested paths) for that specific variant.
+ *
+ * @example
+ * ```typescript
+ * const schema = z.discriminatedUnion('mode', [
+ *   z.object({ mode: z.literal('create'), name: z.string() }),
+ *   z.object({ mode: z.literal('edit'), id: z.number() }),
+ * ]);
+ *
+ * type CreatePaths = ValidPaths<typeof schema, 'mode', 'create'>;
+ * // "mode" | "name"
+ *
+ * type EditPaths = ValidPaths<typeof schema, 'mode', 'edit'>;
+ * // "mode" | "id"
+ * ```
+ */
+type ValidPaths<TSchema extends z$1.ZodType, TDiscriminatorKey extends DiscriminatorKey<TSchema>, TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>> = Paths<CommonFields<Extract<Required<z$1.input<TSchema>>, TDiscriminatorKey extends never ? z$1.input<TSchema> : TDiscriminatorValue extends never ? z$1.input<TSchema> : Simplify<Record<TDiscriminatorKey, TDiscriminatorValue>>>>>;
 
 /**
  * Extracts the default value from a Zod field, recursively unwrapping optional, nullable, and union layers.
@@ -177,27 +266,210 @@ declare function extractDefaultValue<T extends z.ZodType>(field: T): z.input<T>
  * @see {@link extractDefaultValue} for extracting defaults from individual fields
  * @since 0.1.0
  */
-declare function getSchemaDefaults<TSchema extends z.ZodType, TDiscriminatorKey extends keyof z.input<TSchema> & string, TDiscriminatorValue extends z.input<TSchema>[TDiscriminatorKey] & util.Literal>(schema: TSchema, options?: {
-    discriminator?: {
-        key: TDiscriminatorKey;
-        value: TDiscriminatorValue;
-    };
+declare function getSchemaDefaults<TSchema extends z.ZodType, TDiscriminatorKey extends DiscriminatorKey<TSchema>, TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>>(schema: TSchema, options?: {
+    discriminator?: Discriminator<TSchema, TDiscriminatorKey, TDiscriminatorValue>;
 }): Simplify<Partial<z.input<TSchema>>>;
 
-declare function extractFieldFromSchema<TSchema extends z$1.ZodType, TName extends keyof Extract<Required<z$1.input<TSchema>>, Record<TDiscriminatorKey, TDiscriminatorValue>>, TDiscriminatorKey extends keyof z$1.input<TSchema> & string, TDiscriminatorValue extends z$1.input<TSchema>[TDiscriminatorKey] & util.Literal>({ schema, fieldName, discriminator, }: {
+/**
+ * Recursively extracts the exact schema type from a discriminated union based on the discriminator value.
+ *
+ * This advanced TypeScript utility type walks through a union's options tuple at compile-time,
+ * checking each schema against the discriminator field and value, and returns the exact matching
+ * schema type (not a union of all options).
+ *
+ * **How it works:**
+ * 1. Extracts the options tuple from the union using `infer Options`
+ * 2. Destructure into head (`First`) and tail (`Rest`) using tuple pattern matching
+ * 3. Checks if `First` is a ZodObject with the matching discriminator field and value
+ * 4. If match found, returns `First` (the exact schema type)
+ * 5. If no match, recursively processes `Rest` until a match is found or list is exhausted
+ *
+ * **Type narrowing magic:**
+ * - Input: `z.discriminatedUnion('type', [SchemaA, SchemaB, SchemaC])`
+ * - Discriminator value: `'a'` (matches SchemaA)
+ * - Output: `SchemaA` (exact type, not `SchemaA | SchemaB | SchemaC`)
+ *
+ * @template TSchema - The ZodUnion or ZodDiscriminatedUnion type
+ * @template TDiscriminatorKey - The discriminator field name (e.g., "type", "mode")
+ * @template TDiscriminatorValue - The specific discriminator value (e.g., "create", "edit")
+ * @returns The exact matching schema type, or `never` if no match found
+ *
+ * @example
+ * ```typescript
+ * const schema = z.discriminatedUnion('mode', [
+ *   z.object({ mode: z.literal('create'), name: z.string() }),
+ *   z.object({ mode: z.literal('edit'), id: z.number() }),
+ * ]);
+ *
+ * // Exact type: z.object({ mode: z.literal('create'), name: z.string() })
+ * type CreateSchema = ExtractZodUnionMember<typeof schema, 'mode', 'create'>;
+ * ```
+ */
+type ExtractZodUnionMember<TSchema extends z$1.ZodUnion | z$1.ZodDiscriminatedUnion, TDiscriminatorKey extends DiscriminatorKey<TSchema>, TDiscriminatorValue extends z$1.input<TSchema>[TDiscriminatorKey] & util.Literal> = TSchema extends z$1.ZodUnion<infer Options> ? Options extends readonly [
+    infer First extends z$1.ZodTypeAny,
+    ...infer Rest extends z$1.ZodTypeAny[]
+] ? First extends z$1.ZodObject<infer Shape> ? TDiscriminatorKey extends keyof Shape ? Shape[TDiscriminatorKey] extends z$1.ZodLiteral<TDiscriminatorValue> | z$1.ZodDefault<z$1.ZodLiteral<TDiscriminatorValue>> ? First : Rest extends [] ? never : TDiscriminatorValue extends $InferUnionInput<Rest[number]>[TDiscriminatorKey] ? ExtractZodUnionMember<z$1.ZodUnion<Rest>, TDiscriminatorKey, TDiscriminatorValue> : never : Rest extends [] ? never : TDiscriminatorValue extends $InferUnionInput<Rest[number]>[TDiscriminatorKey] ? ExtractZodUnionMember<z$1.ZodUnion<Rest>, TDiscriminatorKey, TDiscriminatorValue> : never : never : never : never;
+/**
+ * Extracts a specific schema option from a discriminated union based on the discriminator field value.
+ *
+ * This function finds and returns the **exact matching schema** from a `ZodDiscriminatedUnion` by
+ * comparing the discriminator field value. It's used internally by {@link getSchemaDefaults} to
+ * extract defaults from the correct schema variant in a discriminated union.
+ *
+ * **Key feature:** Returns the **exact schema type**, not a union of all options, thanks to the
+ * {@link ExtractZodUnionMember} recursive type utility. This enables precise type narrowing at
+ * compile-time based on the discriminator value.
+ *
+ * **How it works:**
+ * 1. Iterates through all options in the discriminated union at runtime
+ * 2. For each option, validates it's a ZodObject and checks if the discriminator field matches
+ * 3. Returns the first matching schema with its exact type narrowed at compile-time
+ * 4. Returns `undefined` if no match found or if option is not a ZodObject
+ *
+ * @template TSchema - The ZodUnion or ZodDiscriminatedUnion schema type
+ * @template TDiscriminatorKey - The discriminator field name (string key of the inferred union type)
+ * @template TDiscriminatorValue - The specific discriminator value to match (literal type)
+ * @param params - Parameters object
+ * @param params.schema - The discriminated union schema to search
+ * @param params.discriminatorKey - The discriminator field name (e.g., "mode", "type")
+ * @param params.discriminatorValue - The discriminator value to match (e.g., "create", "edit")
+ * @returns The exact matching schema option (with precise type), or `undefined` if not found
+ *
+ * @example
+ * Basic discriminated union - create/edit mode
+ * ```typescript
+ * const userSchema = z.discriminatedUnion('mode', [
+ *   z.object({
+ *     mode: z.literal('create'),
+ *     name: z.string(),
+ *     age: z.number().optional(),
+ *   }),
+ *   z.object({
+ *     mode: z.literal('edit'),
+ *     id: z.number(),
+ *     name: z.string().optional(),
+ *   }),
+ * ]);
+ *
+ * // Extract the "create" schema
+ * const createSchema = extractDiscriminatedSchema({
+ *   schema: userSchema,
+ *   discriminatorKey: 'mode',
+ *   discriminatorValue: 'create',
+ * });
+ * // Result: z.object({ mode: z.literal('create'), name: z.string(), age: z.number().optional() })
+ *
+ * // Extract the "edit" schema
+ * const editSchema = extractDiscriminatedSchema({
+ *   schema: userSchema,
+ *   discriminatorKey: 'mode',
+ *   discriminatorValue: 'edit',
+ * });
+ * // Result: z.object({ mode: z.literal('edit'), id: z.number(), name: z.string().optional() })
+ * ```
+ *
+ * @example
+ * Type-based discrimination
+ * ```typescript
+ * const eventSchema = z.discriminatedUnion('type', [
+ *   z.object({ type: z.literal('click'), x: z.number(), y: z.number() }),
+ *   z.object({ type: z.literal('keypress'), key: z.string() }),
+ * ]);
+ *
+ * const clickSchema = extractDiscriminatedSchema({
+ *   schema: eventSchema,
+ *   discriminatorKey: 'type',
+ *   discriminatorValue: 'click',
+ * });
+ * // Result: z.object({ type: z.literal('click'), x: z.number(), y: z.number() })
+ * ```
+ *
+ * @example
+ * Invalid discriminator value
+ * ```typescript
+ * const schema = z.discriminatedUnion('mode', [
+ *   z.object({ mode: z.literal('create'), name: z.string() }),
+ * ]);
+ *
+ * const result = extractDiscriminatedSchema({
+ *   schema,
+ *   discriminatorKey: 'mode',
+ *   discriminatorValue: 'invalid', // doesn't match any option
+ * });
+ * // Result: undefined
+ * ```
+ *
+ * @example
+ * Type narrowing demonstration
+ * ```typescript
+ * const schema = z.discriminatedUnion('mode', [
+ *   z.object({ mode: z.literal('create'), name: z.string(), age: z.number() }),
+ *   z.object({ mode: z.literal('edit'), id: z.number(), bio: z.string() }),
+ * ]);
+ *
+ * const createSchema = extractDiscriminatedSchema({
+ *   schema,
+ *   discriminatorKey: 'mode',
+ *   discriminatorValue: 'create',
+ * });
+ *
+ * // Type is EXACTLY: z.object({ mode: z.literal('create'), name: z.string(), age: z.number() })
+ * // NOT: z.object({ mode: ..., ... }) | z.object({ mode: ..., ... }) | undefined
+ *
+ * if (createSchema) {
+ *   createSchema.shape.age;  // ✅ TypeScript knows 'age' exists
+ *   createSchema.shape.name; // ✅ TypeScript knows 'name' exists
+ *   // createSchema.shape.id;   // ❌ TypeScript error: 'id' doesn't exist on 'create' schema
+ * }
+ * ```
+ *
+ * @see {@link getSchemaDefaults} for usage with discriminated unions
+ * @see {@link ExtractZodUnionMember} for the type-level extraction logic
+ * @since 0.6.0
+ */
+declare const extractDiscriminatedSchema: <TSchema extends z$1.ZodType, TDiscriminatorKey extends DiscriminatorKey<TSchema>, TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>, ReturnType extends TSchema extends z$1.ZodDiscriminatedUnion ? ExtractZodUnionMember<TSchema, TDiscriminatorKey, TDiscriminatorValue> : never>({ schema, key, value, }: {
+    schema: TSchema;
+} & Discriminator<TSchema, TDiscriminatorKey, TDiscriminatorValue>) => ReturnType;
+
+type Split<S extends string> = S extends `${infer Head}.${infer Tail}` ? [Head, ...Split<Tail>] : [S];
+type IsNumeric<S extends string> = S extends `${number}` ? true : false;
+type Unwrap<T> = T extends z$1.ZodOptional<infer U> ? Unwrap<U> : T extends z$1.ZodNullable<infer U> ? Unwrap<U> : T extends z$1.ZodDefault<infer U> ? Unwrap<U> : T;
+type NavigateZod<T, Path extends string[]> = Path extends [
+    infer First extends string,
+    ...infer Rest extends string[]
+] ? Unwrap<T> extends z$1.ZodObject<infer Shape> ? First extends keyof Shape ? Rest extends [] ? Shape[First] : NavigateZod<Shape[First], Rest> : never : Unwrap<T> extends z$1.ZodArray<infer Element> ? IsNumeric<First> extends true ? Rest extends [] ? Element : NavigateZod<Element, Rest> : never : never : T;
+type ExtractZodByPath<Schema, Path extends string> = NavigateZod<Schema, Split<Path>>;
+declare function extractFieldFromSchema<TSchema extends z$1.ZodType, TPath extends ValidPaths<TSchema, TDiscriminatorKey, TDiscriminatorValue>, TDiscriminatorKey extends DiscriminatorKey<TSchema>, TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>>({ schema, name, discriminator, }: {
     schema: TSchema;
-    fieldName: TName;
-    discriminator?: {
-        key: TDiscriminatorKey;
-        value: TDiscriminatorValue;
-    };
-}): z$1.ZodType<unknown, unknown, z$1.core.$ZodTypeInternals<unknown, unknown>> | undefined;
+    name: TPath;
+    discriminator?: Discriminator<TSchema, TDiscriminatorKey, TDiscriminatorValue>;
+}): (ExtractZodByPath<TSchema, TPath> & z$1.ZodType) | undefined;
+/**
+ * Extends a Zod field with a transformation while preserving its metadata.
+ *
+ * This is useful when you want to add validations or transformations to a field
+ * but keep the original metadata (like translationKey) intact.
+ *
+ * @param field - The original Zod field
+ * @param transform - A function that transforms the field
+ * @returns The transformed field with preserved metadata
+ *
+ * @example
+ * ```typescript
+ * const baseField = z.string().meta({ translationKey: 'user.field.name' });
+ *
+ * // Add min/max validation while keeping the translationKey
+ * const extendedField = extendWithMeta(baseField, (f) => f.min(3).max(100));
+ * extendedField.meta(); // { translationKey: 'user.field.name' }
+ * ```
+ */
+declare function extendWithMeta<T extends z$1.ZodType, R extends z$1.ZodType>(field: T, transform: (f: T) => R): R;
 
 /**
  * Type representing a Zod type that has an unwrap method
  */
 type Unwrappable = {
-    unwrap: () => z.ZodTypeAny;
+    unwrap: () => z$1.ZodTypeAny;
 };
 /**
  * Type guard to check if a Zod field can be unwrapped (has wrapper types like optional, nullable, default).
@@ -219,7 +491,7 @@ type Unwrappable = {
  *
  * @since 0.1.0
  */
-declare function canUnwrap(field: z.ZodTypeAny): field is z.ZodTypeAny & Unwrappable;
+declare function canUnwrap(field: z$1.ZodTypeAny): field is z$1.ZodTypeAny & Unwrappable;
 /**
  * Attempts to strip nullish types from a union and return the single remaining type.
  *
@@ -257,7 +529,7 @@ declare function canUnwrap(field: z.ZodTypeAny): field is z.ZodTypeAny & Unwrapp
  * @see {@link getPrimitiveType} for unwrapping wrapper types
  * @since 0.5.0
  */
-declare function tryStripNullishOnly(field: z.ZodTypeAny): z.ZodType | false;
+declare function tryStripNullishOnly(field: z$1.ZodTypeAny): z$1.ZodType | false;
 /**
  * Gets the underlying primitive type of a Zod field by recursively unwrapping wrapper types.
  *
@@ -316,8 +588,8 @@ declare function tryStripNullishOnly(field: z.ZodTypeAny): z.ZodType | false;
  * @see {@link tryStripNullishOnly} for union nullish stripping logic
  * @since 0.1.0
  */
-declare const getPrimitiveType: <T extends z.ZodType>(field: T) => z.ZodTypeAny;
-type StripZodDefault<T> = T extends z.ZodDefault<infer Inner> ? StripZodDefault<Inner> : T extends z.ZodOptional<infer Inner> ? z.ZodOptional<StripZodDefault<Inner>> : T extends z.ZodNullable<infer Inner> ? z.ZodNullable<StripZodDefault<Inner>> : T;
+declare const getPrimitiveType: <T extends z$1.ZodType>(field: T) => z$1.ZodTypeAny;
+type StripZodDefault<T> = T extends z$1.ZodDefault<infer Inner> ? StripZodDefault<Inner> : T extends z$1.ZodOptional<infer Inner> ? z$1.ZodOptional<StripZodDefault<Inner>> : T extends z$1.ZodNullable<infer Inner> ? z$1.ZodNullable<StripZodDefault<Inner>> : T;
 /**
  * Removes default values from a Zod field while preserving other wrapper types.
  *
@@ -356,7 +628,7 @@ type StripZodDefault<T> = T extends z.ZodDefault<infer Inner> ? StripZodDefault<
  * @see {@link requiresValidInput} for usage with requirement checking
  * @since 0.1.0
  */
-declare function removeDefault<T extends z.ZodType>(field: T): StripZodDefault<T>;
+declare function removeDefault<T extends z$1.ZodType>(field: T): StripZodDefault<T>;
 /**
  * Determines if a field will show validation errors when the user submits empty or invalid input.
  *
@@ -434,7 +706,7 @@ declare function removeDefault<T extends z.ZodType>(field: T): StripZodDefault<T
  * @see {@link getPrimitiveType} for understanding type unwrapping
  * @since 0.1.0
  */
-declare const requiresValidInput: <T extends z.ZodType>(field: T) => boolean;
+declare const requiresValidInput: <T extends z$1.ZodType>(field: T) => boolean;
 /**
  * Union type of all Zod check definition types.
  *
@@ -524,168 +796,6 @@ type ZodUnionCheck = $ZodCheckLessThanDef | $ZodCheckGreaterThanDef | $ZodCheckM
  * @see {@link ZodUnionCheck} for all supported check types
  * @since 0.4.0
  */
-declare function getFieldChecks<T extends z.ZodTypeAny>(field: T): Array<ZodUnionCheck>;
-/**
- * Recursively extracts the exact schema type from a discriminated union based on the discriminator value.
- *
- * This advanced TypeScript utility type walks through a union's options tuple at compile-time,
- * checking each schema against the discriminator field and value, and returns the exact matching
- * schema type (not a union of all options).
- *
- * **How it works:**
- * 1. Extracts the options tuple from the union using `infer Options`
- * 2. Destructure into head (`First`) and tail (`Rest`) using tuple pattern matching
- * 3. Checks if `First` is a ZodObject with the matching discriminator field and value
- * 4. If match found, returns `First` (the exact schema type)
- * 5. If no match, recursively processes `Rest` until a match is found or list is exhausted
- *
- * **Type narrowing magic:**
- * - Input: `z.discriminatedUnion('type', [SchemaA, SchemaB, SchemaC])`
- * - Discriminator value: `'a'` (matches SchemaA)
- * - Output: `SchemaA` (exact type, not `SchemaA | SchemaB | SchemaC`)
- *
- * @template TSchema - The ZodUnion or ZodDiscriminatedUnion type
- * @template TDiscriminatorKey - The discriminator field name (e.g., "type", "mode")
- * @template TDiscriminatorValue - The specific discriminator value (e.g., "create", "edit")
- * @returns The exact matching schema type, or `never` if no match found
- *
- * @example
- * ```typescript
- * const schema = z.discriminatedUnion('mode', [
- *   z.object({ mode: z.literal('create'), name: z.string() }),
- *   z.object({ mode: z.literal('edit'), id: z.number() }),
- * ]);
- *
- * // Exact type: z.object({ mode: z.literal('create'), name: z.string() })
- * type CreateSchema = ExtractZodUnionMember<typeof schema, 'mode', 'create'>;
- * ```
- */
-type ExtractZodUnionMember<TSchema extends z.ZodUnion | z.ZodDiscriminatedUnion, TDiscriminatorKey extends keyof z.input<TSchema> & string, TDiscriminatorValue extends z.input<TSchema>[TDiscriminatorKey] & util.Literal> = TSchema extends z.ZodUnion<infer Options> ? Options extends readonly [
-    infer First extends z.ZodTypeAny,
-    ...infer Rest extends z.ZodTypeAny[]
-] ? First extends z.ZodObject<infer Shape> ? TDiscriminatorKey extends keyof Shape ? Shape[TDiscriminatorKey] extends z.ZodLiteral<TDiscriminatorValue> ? First : Rest extends [] ? never : TDiscriminatorValue extends $InferUnionInput<Rest[number]>[TDiscriminatorKey] ? ExtractZodUnionMember<z.ZodUnion<Rest>, TDiscriminatorKey, TDiscriminatorValue> : never : Rest extends [] ? never : TDiscriminatorValue extends $InferUnionInput<Rest[number]>[TDiscriminatorKey] ? ExtractZodUnionMember<z.ZodUnion<Rest>, TDiscriminatorKey, TDiscriminatorValue> : never : never : never : never;
-/**
- * Extracts a specific schema option from a discriminated union based on the discriminator field value.
- *
- * This function finds and returns the **exact matching schema** from a `ZodDiscriminatedUnion` by
- * comparing the discriminator field value. It's used internally by {@link getSchemaDefaults} to
- * extract defaults from the correct schema variant in a discriminated union.
- *
- * **Key feature:** Returns the **exact schema type**, not a union of all options, thanks to the
- * {@link ExtractZodUnionMember} recursive type utility. This enables precise type narrowing at
- * compile-time based on the discriminator value.
- *
- * **How it works:**
- * 1. Iterates through all options in the discriminated union at runtime
- * 2. For each option, validates it's a ZodObject and checks if the discriminator field matches
- * 3. Returns the first matching schema with its exact type narrowed at compile-time
- * 4. Returns `undefined` if no match found or if option is not a ZodObject
- *
- * @template TSchema - The ZodUnion or ZodDiscriminatedUnion schema type
- * @template TDiscriminatorKey - The discriminator field name (string key of the inferred union type)
- * @template TDiscriminatorValue - The specific discriminator value to match (literal type)
- * @param params - Parameters object
- * @param params.schema - The discriminated union schema to search
- * @param params.discriminatorKey - The discriminator field name (e.g., "mode", "type")
- * @param params.discriminatorValue - The discriminator value to match (e.g., "create", "edit")
- * @returns The exact matching schema option (with precise type), or `undefined` if not found
- *
- * @example
- * Basic discriminated union - create/edit mode
- * ```typescript
- * const userSchema = z.discriminatedUnion('mode', [
- *   z.object({
- *     mode: z.literal('create'),
- *     name: z.string(),
- *     age: z.number().optional(),
- *   }),
- *   z.object({
- *     mode: z.literal('edit'),
- *     id: z.number(),
- *     name: z.string().optional(),
- *   }),
- * ]);
- *
- * // Extract the "create" schema
- * const createSchema = extractDiscriminatedSchema({
- *   schema: userSchema,
- *   discriminatorKey: 'mode',
- *   discriminatorValue: 'create',
- * });
- * // Result: z.object({ mode: z.literal('create'), name: z.string(), age: z.number().optional() })
- *
- * // Extract the "edit" schema
- * const editSchema = extractDiscriminatedSchema({
- *   schema: userSchema,
- *   discriminatorKey: 'mode',
- *   discriminatorValue: 'edit',
- * });
- * // Result: z.object({ mode: z.literal('edit'), id: z.number(), name: z.string().optional() })
- * ```
- *
- * @example
- * Type-based discrimination
- * ```typescript
- * const eventSchema = z.discriminatedUnion('type', [
- *   z.object({ type: z.literal('click'), x: z.number(), y: z.number() }),
- *   z.object({ type: z.literal('keypress'), key: z.string() }),
- * ]);
- *
- * const clickSchema = extractDiscriminatedSchema({
- *   schema: eventSchema,
- *   discriminatorKey: 'type',
- *   discriminatorValue: 'click',
- * });
- * // Result: z.object({ type: z.literal('click'), x: z.number(), y: z.number() })
- * ```
- *
- * @example
- * Invalid discriminator value
- * ```typescript
- * const schema = z.discriminatedUnion('mode', [
- *   z.object({ mode: z.literal('create'), name: z.string() }),
- * ]);
- *
- * const result = extractDiscriminatedSchema({
- *   schema,
- *   discriminatorKey: 'mode',
- *   discriminatorValue: 'invalid', // doesn't match any option
- * });
- * // Result: undefined
- * ```
- *
- * @example
- * Type narrowing demonstration
- * ```typescript
- * const schema = z.discriminatedUnion('mode', [
- *   z.object({ mode: z.literal('create'), name: z.string(), age: z.number() }),
- *   z.object({ mode: z.literal('edit'), id: z.number(), bio: z.string() }),
- * ]);
- *
- * const createSchema = extractDiscriminatedSchema({
- *   schema,
- *   discriminatorKey: 'mode',
- *   discriminatorValue: 'create',
- * });
- *
- * // Type is EXACTLY: z.object({ mode: z.literal('create'), name: z.string(), age: z.number() })
- * // NOT: z.object({ mode: ..., ... }) | z.object({ mode: ..., ... }) | undefined
- *
- * if (createSchema) {
- *   createSchema.shape.age;  // ✅ TypeScript knows 'age' exists
- *   createSchema.shape.name; // ✅ TypeScript knows 'name' exists
- *   // createSchema.shape.id;   // ❌ TypeScript error: 'id' doesn't exist on 'create' schema
- * }
- * ```
- *
- * @see {@link getSchemaDefaults} for usage with discriminated unions
- * @see {@link ExtractZodUnionMember} for the type-level extraction logic
- * @since 0.6.0
- */
-declare const extractDiscriminatedSchema: <TSchema extends z.ZodUnion | z.ZodDiscriminatedUnion, TDiscriminatorKey extends keyof z.input<TSchema> & string, TDiscriminatorValue extends z.input<TSchema>[TDiscriminatorKey] & util.Literal>({ schema, key, value, }: {
-    schema: TSchema;
-    key: TDiscriminatorKey;
-    value: TDiscriminatorValue;
-}) => ExtractZodUnionMember<TSchema, TDiscriminatorKey, TDiscriminatorValue> | undefined;
+declare function getFieldChecks<T extends z$1.ZodTypeAny>(field: T): Array<ZodUnionCheck>;
 
-export { type Simplify, type ZodUnionCheck, canUnwrap, extractDefaultValue, extractDiscriminatedSchema, extractFieldFromSchema, getFieldChecks, getPrimitiveType, getSchemaDefaults, removeDefault, requiresValidInput, tryStripNullishOnly };
+export { type CommonFields, type Discriminator, type DiscriminatorKey, type DiscriminatorValue, type ExtractZodByPath, type Paths, type Simplify, type ValidPaths, type ZodUnionCheck, canUnwrap, extendWithMeta, extractDefaultValue, extractDiscriminatedSchema, extractFieldFromSchema, getFieldChecks, getPrimitiveType, getSchemaDefaults, removeDefault, requiresValidInput, tryStripNullishOnly };