@zod-utils/core 0.9.0 → 1.1.0

package/README.md

@@ -35,6 +35,8 @@ npm install @zod-utils/core zod
 
 Extract all default values from a Zod object schema. Only extracts fields that explicitly have `.default()` on them.
 
+**Transform support:** Works with schemas that have `.transform()` - extracts defaults from the input type.
+
 ```typescript
 import { getSchemaDefaults } from "@zod-utils/core";
 import { z } from "zod";
@@ -137,9 +139,11 @@ requiresValidInput(middleName); // false - user can leave null
 
 ### `getPrimitiveType(field)`
 
-Get the primitive type of a Zod field by unwrapping optional/nullable wrappers.
+Get the primitive type of a Zod field by unwrapping optional/nullable/transform wrappers.
 Stops at arrays without unwrapping them.
 
+**Transform support:** Automatically unwraps `.transform()` to get the underlying input type.
+
 ```typescript
 import { getPrimitiveType } from "@zod-utils/core";
 import { z } from "zod";
@@ -151,6 +155,11 @@ const primitive = getPrimitiveType(field);
 const arrayField = z.array(z.string()).optional();
 const arrayPrimitive = getPrimitiveType(arrayField);
 // Returns the ZodArray (stops at arrays)
+
+// Transform support
+const transformed = z.string().transform((val) => val.toUpperCase());
+const primitiveFromTransform = getPrimitiveType(transformed);
+// Returns the underlying ZodString (unwraps the transform)
 ```
 
 ---
@@ -172,34 +181,40 @@ withoutDefault.parse(undefined); // throws error
 
 ---
 
-### `extractDefault(field)`
+### `extractDefaultValue(field)`
 
-Extract the default value from a Zod field (recursively unwraps optional/nullable/union layers).
+Extract the default value from a Zod field (recursively unwraps optional/nullable/union/transform layers).
 
 **Union handling:** For union types, extracts the default from the first option. If the first option has no default, returns `undefined` (defaults in other union options are not checked).
 
+**Transform support:** Automatically unwraps `.transform()` to get the input type's default value.
+
 ```typescript
-import { extractDefault } from "@zod-utils/core";
+import { extractDefaultValue } from "@zod-utils/core";
 import { z } from "zod";
 
 // Basic usage
 const field = z.string().optional().default("hello");
-extractDefault(field); // 'hello'
+extractDefaultValue(field); // 'hello'
 
 const noDefault = z.string();
-extractDefault(noDefault); // undefined
+extractDefaultValue(noDefault); // undefined
 
 // Union with default in first option
 const unionField = z.union([z.string().default('hello'), z.number()]);
-extractDefault(unionField); // 'hello'
+extractDefaultValue(unionField); // 'hello'
 
 // Union with default in second option (only checks first)
 const unionField2 = z.union([z.string(), z.number().default(42)]);
-extractDefault(unionField2); // undefined
+extractDefaultValue(unionField2); // undefined
 
 // Union wrapped in optional
 const wrappedUnion = z.union([z.string().default('test'), z.number()]).optional();
-extractDefault(wrappedUnion); // 'test'
+extractDefaultValue(wrappedUnion); // 'test'
+
+// Transform support - extracts input default, not output
+const transformed = z.string().default('hello').transform((val) => val.toUpperCase());
+extractDefaultValue(transformed); // 'hello' (not 'HELLO')
 ```
 
 ---
@@ -272,6 +287,173 @@ import { getFieldChecks, type ZodUnionCheck } from "@zod-utils/core";
 
 ---
 
+### `extractDiscriminatedSchema(schema, key, value)`
+
+Extract a specific variant from a discriminated union schema based on the discriminator field and value.
+
+```typescript
+import { extractDiscriminatedSchema } from "@zod-utils/core";
+import { z } from "zod";
+
+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(),
+    bio: z.string().optional(),
+  }),
+]);
+
+// Extract the 'create' variant
+const createSchema = extractDiscriminatedSchema({
+  schema: userSchema,
+  key: 'mode',
+  value: 'create',
+});
+// Returns: z.ZodObject with { mode, name, age }
+
+// Extract the 'edit' variant
+const editSchema = extractDiscriminatedSchema({
+  schema: userSchema,
+  key: 'mode',
+  value: 'edit',
+});
+// Returns: z.ZodObject with { mode, id, name, bio }
+```
+
+**Use with discriminated unions:** This is essential when working with `z.discriminatedUnion()` schemas, as it extracts the correct variant schema based on the discriminator value.
+
+---
+
+### `extractFieldFromSchema(schema, fieldName, discriminator?)`
+
+Extract a single field from a Zod object or discriminated union schema.
+
+**Transform support:** Works with schemas that have `.transform()` - extracts fields from the input type.
+
+```typescript
+import { extractFieldFromSchema } from "@zod-utils/core";
+import { z } from "zod";
+
+// Simple object schema
+const userSchema = z.object({
+  name: z.string(),
+  age: z.number(),
+  email: z.string().email(),
+});
+
+const nameField = extractFieldFromSchema({
+  schema: userSchema,
+  fieldName: 'name',
+});
+// Returns: ZodString
+
+// Discriminated union schema
+const formSchema = 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 field from specific variant
+const idField = extractFieldFromSchema({
+  schema: formSchema,
+  fieldName: 'id',
+  discriminator: {
+    key: 'mode',
+    value: 'edit',
+  },
+});
+// Returns: ZodNumber
+
+// Without discriminator on discriminated union, returns undefined
+const fieldWithoutDiscriminator = extractFieldFromSchema({
+  schema: formSchema,
+  fieldName: 'name',
+});
+// Returns: undefined (need discriminator to know which variant)
+
+// Works with transforms - extracts from input type
+const transformedSchema = z
+  .object({
+    name: z.string(),
+    age: z.number(),
+  })
+  .transform((data) => ({ ...data, computed: true }));
+
+const nameFromTransformed = extractFieldFromSchema({
+  schema: transformedSchema,
+  fieldName: 'name',
+});
+// Returns: ZodString (from the input type, not affected by transform)
+```
+
+**Discriminated union support:** When extracting fields from discriminated unions, you must provide the `discriminator` option with `key` and `value` to specify which variant to use.
+
+---
+
+### `getSchemaDefaults(schema, discriminator?)`
+
+**Updated:** Now supports discriminated union schemas with the `discriminator` option.
+
+```typescript
+import { getSchemaDefaults } from "@zod-utils/core";
+import { z } from "zod";
+
+// Discriminated union with defaults
+const formSchema = z.discriminatedUnion('mode', [
+  z.object({
+    mode: z.literal('create'),
+    name: z.string(),
+    age: z.number().default(18),
+  }),
+  z.object({
+    mode: z.literal('edit'),
+    id: z.number().default(1),
+    name: z.string().optional(),
+    bio: z.string().default('bio goes here'),
+  }),
+]);
+
+// Get defaults for 'create' mode
+const createDefaults = getSchemaDefaults(formSchema, {
+  discriminator: {
+    key: 'mode',
+    value: 'create',
+  },
+});
+// Returns: { age: 18 }
+
+// Get defaults for 'edit' mode
+const editDefaults = getSchemaDefaults(formSchema, {
+  discriminator: {
+    key: 'mode',
+    value: 'edit',
+  },
+});
+// Returns: { id: 1, bio: 'bio goes here' }
+
+// Without discriminator, returns empty object
+const noDefaults = getSchemaDefaults(formSchema);
+// Returns: {}
+```
+
+**Discriminator types:** The discriminator `value` can be a string, number, or boolean literal that matches the discriminator field type.
+
+---
+
 ## Type Utilities
 
 ### `Simplify<T>`

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import * as z from 'zod';
-import { $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';
+import { util, z as z$1 } 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';
 
 /**
  * Simplifies complex TypeScript types for better IDE hover tooltips and error messages.
@@ -34,8 +35,8 @@ import { $ZodCheckLessThanDef, $ZodCheckGreaterThanDef, $ZodCheckMultipleOfDef,
  * const schema = z.object({ id: z.string() })
  *   .merge(z.object({ name: z.string() }));
  *
- * type InferredType = z.infer<typeof schema>; // May show complex type
- * type SimplifiedType = Simplify<z.infer<typeof schema>>;
+ * type InferredType = z.input<typeof schema>; // May show complex type
+ * type SimplifiedType = Simplify<z.input<typeof schema>>;
  * // Shows clear: { id: string; name: string }
  * ```
  *
@@ -63,7 +64,7 @@ type Simplify<T> = {
  * Basic usage with default value
  * ```typescript
  * const field = z.string().default('hello');
- * const defaultValue = extractDefault(field);
+ * const defaultValue = extractDefaultValue(field);
  * // Result: 'hello'
  * ```
  *
@@ -71,7 +72,7 @@ type Simplify<T> = {
  * Unwrapping optional/nullable layers
  * ```typescript
  * const field = z.string().default('world').optional();
- * const defaultValue = extractDefault(field);
+ * const defaultValue = extractDefaultValue(field);
  * // Result: 'world' (unwraps optional to find default)
  * ```
  *
@@ -79,7 +80,7 @@ type Simplify<T> = {
  * Union with only nullish types stripped to single type
  * ```typescript
  * const field = z.union([z.string().default('hello'), z.null()]);
- * const defaultValue = extractDefault(field);
+ * const defaultValue = extractDefaultValue(field);
  * // Result: 'hello' (null stripped, leaving only string)
  * ```
  *
@@ -87,7 +88,7 @@ type Simplify<T> = {
  * Union with multiple non-nullish types
  * ```typescript
  * const field = z.union([z.string().default('hello'), z.number()]);
- * const defaultValue = extractDefault(field);
+ * const defaultValue = extractDefaultValue(field);
  * // Result: undefined (multiple non-nullish types - no default extracted)
  * ```
  *
@@ -95,7 +96,7 @@ type Simplify<T> = {
  * Field without default
  * ```typescript
  * const field = z.string().optional();
- * const defaultValue = extractDefault(field);
+ * const defaultValue = extractDefaultValue(field);
  * // Result: undefined
  * ```
  *
@@ -103,7 +104,7 @@ type Simplify<T> = {
  * @see {@link tryStripNullishOnly} for union nullish stripping logic
  * @since 0.1.0
  */
-declare function extractDefault<T extends z.ZodTypeAny>(field: T): z.infer<T> | undefined;
+declare function extractDefaultValue<T extends z.ZodType>(field: T): z.input<T> | undefined;
 /**
  * Extracts default values from a Zod object schema, returning only fields with explicit `.default()`.
  *
@@ -173,15 +174,24 @@ declare function extractDefault<T extends z.ZodTypeAny>(field: T): z.infer<T> |
  * <Input type="number" value={field.value ?? ''} />
  * ```
  *
- * @see {@link extractDefault} for extracting defaults from individual fields
+ * @see {@link extractDefaultValue} for extracting defaults from individual fields
  * @since 0.1.0
  */
-declare function getSchemaDefaults<TSchema extends z.ZodObject | z.ZodDiscriminatedUnion<Array<z.ZodObject>>, TObj extends z.infer<TSchema>, TDiscriminatorField extends keyof TObj = keyof TObj>(schema: TSchema, options?: {
+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?: {
-        field: TDiscriminatorField;
-        value: TObj[TDiscriminatorField];
+        key: TDiscriminatorKey;
+        value: TDiscriminatorValue;
     };
-}): Simplify<Partial<z.infer<TSchema>>>;
+}): 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, }: {
+    schema: TSchema;
+    fieldName: TName;
+    discriminator?: {
+        key: TDiscriminatorKey;
+        value: TDiscriminatorValue;
+    };
+}): z$1.ZodType<unknown, unknown, z$1.core.$ZodTypeInternals<unknown, unknown>> | undefined;
 
 /**
  * Type representing a Zod type that has an unwrap method
@@ -515,26 +525,70 @@ type ZodUnionCheck = $ZodCheckLessThanDef | $ZodCheckGreaterThanDef | $ZodCheckM
  * @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 matching schema option from a `ZodDiscriminatedUnion` by
+ * 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.
  *
- * **How it works:**
- * 1. Iterates through all options in the discriminated union
- * 2. For each option, checks if the discriminator field matches the provided value
- * 3. Returns the first matching schema option, or `undefined` if no match found
+ * **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.
  *
- * @template TSchema - The discriminated union schema type
- * @template TObj - The inferred type of the schema
- * @template TDiscriminatorField - The discriminator field key type
+ * **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.discriminatorField - The discriminator field name (e.g., "mode", "type")
+ * @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 matching schema option, or `undefined` if not found
+ * @returns The exact matching schema option (with precise type), or `undefined` if not found
  *
  * @example
  * Basic discriminated union - create/edit mode
@@ -555,7 +609,7 @@ declare function getFieldChecks<T extends z.ZodTypeAny>(field: T): Array<ZodUnio
  * // Extract the "create" schema
  * const createSchema = extractDiscriminatedSchema({
  *   schema: userSchema,
- *   discriminatorField: 'mode',
+ *   discriminatorKey: 'mode',
  *   discriminatorValue: 'create',
  * });
  * // Result: z.object({ mode: z.literal('create'), name: z.string(), age: z.number().optional() })
@@ -563,7 +617,7 @@ declare function getFieldChecks<T extends z.ZodTypeAny>(field: T): Array<ZodUnio
  * // Extract the "edit" schema
  * const editSchema = extractDiscriminatedSchema({
  *   schema: userSchema,
- *   discriminatorField: 'mode',
+ *   discriminatorKey: 'mode',
  *   discriminatorValue: 'edit',
  * });
  * // Result: z.object({ mode: z.literal('edit'), id: z.number(), name: z.string().optional() })
@@ -579,7 +633,7 @@ declare function getFieldChecks<T extends z.ZodTypeAny>(field: T): Array<ZodUnio
  *
  * const clickSchema = extractDiscriminatedSchema({
  *   schema: eventSchema,
- *   discriminatorField: 'type',
+ *   discriminatorKey: 'type',
  *   discriminatorValue: 'click',
  * });
  * // Result: z.object({ type: z.literal('click'), x: z.number(), y: z.number() })
@@ -594,19 +648,44 @@ declare function getFieldChecks<T extends z.ZodTypeAny>(field: T): Array<ZodUnio
  *
  * const result = extractDiscriminatedSchema({
  *   schema,
- *   discriminatorField: 'mode',
+ *   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.ZodDiscriminatedUnion<Array<z.ZodObject>>, TObj extends z.infer<TSchema>, TDiscriminatorField extends keyof TObj = keyof TObj>({ schema, discriminatorField, discriminatorValue, }: {
+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;
-    discriminatorField: TDiscriminatorField;
-    discriminatorValue: TObj[TDiscriminatorField];
-}) => z.ZodObject<z.core.$ZodLooseShape, z.core.$strip> | undefined;
+    key: TDiscriminatorKey;
+    value: TDiscriminatorValue;
+}) => ExtractZodUnionMember<TSchema, TDiscriminatorKey, TDiscriminatorValue> | undefined;
 
-export { type Simplify, type ZodUnionCheck, canUnwrap, extractDefault, extractDiscriminatedSchema, getFieldChecks, getPrimitiveType, getSchemaDefaults, removeDefault, requiresValidInput, tryStripNullishOnly };
+export { type Simplify, type ZodUnionCheck, canUnwrap, extractDefaultValue, extractDiscriminatedSchema, extractFieldFromSchema, getFieldChecks, getPrimitiveType, getSchemaDefaults, removeDefault, requiresValidInput, tryStripNullishOnly };