@zod-utils/core 0.2.0 → 0.5.0

package/README.md

@@ -2,6 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@zod-utils/core.svg)](https://www.npmjs.com/package/@zod-utils/core)
 [![npm downloads](https://img.shields.io/npm/dm/@zod-utils/core.svg)](https://www.npmjs.com/package/@zod-utils/core)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@zod-utils/core)](https://bundlephobia.com/package/@zod-utils/core)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
 [![CI](https://github.com/thu-san/zod-utils/workflows/CI/badge.svg)](https://github.com/thu-san/zod-utils/actions)
@@ -15,10 +16,15 @@ Pure TypeScript utilities for Zod schema manipulation and default extraction. No
 npm install @zod-utils/core zod
 ```
 
+## Related Packages
+
+- **[@zod-utils/react-hook-form](https://www.npmjs.com/package/@zod-utils/react-hook-form)** - React Hook Form integration with automatic type transformation. Uses this package internally and re-exports all utilities for convenience.
+
 ## Features
 
 - 🎯 **Extract defaults** - Get default values from Zod schemas
-- ✅ **Check required fields** - Determine if fields are required
+- ✅ **Check validation requirements** - Determine if fields will error on empty input
+- 🔍 **Extract validation checks** - Get all validation constraints (min/max, formats, patterns, etc.)
 - 🔧 **Schema utilities** - Unwrap and manipulate schema types
 - 📦 **Zero dependencies** - Only requires Zod as a peer dependency
 - 🌐 **Universal** - Works in Node.js, browsers, and any TypeScript project
@@ -67,48 +73,64 @@ const defaults = getSchemaDefaults(schema);
 
 ---
 
-### `checkIfFieldIsRequired(field)`
+### `requiresValidInput(field)`
 
-Check if a Zod field is required. Returns `false` if the field accepts any of:
+Determines if a field will show validation errors when the user submits empty or invalid input. Useful for form UIs to show which fields need valid user input (asterisks, validation indicators).
 
-- `undefined` (via `.optional()` or `.default()`)
-- `null` (via `.nullable()`)
-- Empty string (plain `z.string()` without `.min(1)` or `.nonempty()`)
-- Empty array (plain `z.array()` without `.min(1)` or `.nonempty()`)
+**Key insight:** Defaults are just initial values - they don't prevent validation errors if the user clears the field.
+
+**Real-world example:**
 
 ```typescript
-import { checkIfFieldIsRequired } from "@zod-utils/core";
-import { z } from "zod";
+// Marital status with default but validation rules
+const maritalStatus = z.string().min(1).default('single');
+
+// What happens in the form:
+// 1. Initial: field shows "single" (from default)
+// 2. User deletes the value → empty string
+// 3. User submits form → validation fails (.min(1) rejects empty)
+// 4. requiresValidInput(maritalStatus) → true (show *, show error)
+```
+
+**How it works:**
+
+1. Removes `.default()` wrappers (defaults ≠ validation rules)
+2. Tests if underlying schema accepts empty/invalid input:
+   - `undefined` (via `.optional()`)
+   - `null` (via `.nullable()`)
+   - Empty string (plain `z.string()`)
+   - Empty array (plain `z.array()`)
+3. Returns `true` if validation will fail on empty input
 
-// Required fields - return true
-const requiredString = z.string().min(1);
-const nonemptyString = z.string().nonempty();
-const requiredArray = z.array(z.string()).min(1);
-const nonemptyArray = z.array(z.string()).nonempty();
+**Examples:**
 
-checkIfFieldIsRequired(requiredString); // true
-checkIfFieldIsRequired(nonemptyString); // true
-checkIfFieldIsRequired(requiredArray); // true
-checkIfFieldIsRequired(nonemptyArray); // true
+```typescript
+import { requiresValidInput } from "@zod-utils/core";
+import { z } from "zod";
 
-// Fields accepting undefined - return false
-const optionalField = z.string().optional();
-const fieldWithDefault = z.string().default("hello");
+// User name - required, no default
+const userName = z.string().min(1);
+requiresValidInput(userName); // true - will error if empty
 
-checkIfFieldIsRequired(optionalField); // false
-checkIfFieldIsRequired(fieldWithDefault); // false
+// Marital status - required WITH default
+const maritalStatus = z.string().min(1).default('single');
+requiresValidInput(maritalStatus); // true - will error if user clears it
 
-// Fields accepting empty values - return false
-const emptyStringAllowed = z.string();
-const emptyArrayAllowed = z.array(z.string());
+// Age with default - requires valid input
+const age = z.number().default(0);
+requiresValidInput(age); // true - numbers reject empty strings
 
-checkIfFieldIsRequired(emptyStringAllowed); // false
-checkIfFieldIsRequired(emptyArrayAllowed); // false
+// Optional bio - doesn't require input
+const bio = z.string().optional();
+requiresValidInput(bio); // false - user can leave empty
 
-// Fields accepting null - return false
-const nullableField = z.string().nullable();
+// Notes with default but NO validation
+const notes = z.string().default('N/A');
+requiresValidInput(notes); // false - plain z.string() accepts empty
 
-checkIfFieldIsRequired(nullableField); // false
+// Nullable middle name
+const middleName = z.string().nullable();
+requiresValidInput(middleName); // false - user can leave null
 ```
 
 ---
@@ -152,17 +174,100 @@ withoutDefault.parse(undefined); // throws error
 
 ### `extractDefault(field)`
 
-Extract the default value from a Zod field (recursively unwraps optional/nullable).
+Extract the default value from a Zod field (recursively unwraps optional/nullable/union 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).
 
 ```typescript
 import { extractDefault } from "@zod-utils/core";
 import { z } from "zod";
 
+// Basic usage
 const field = z.string().optional().default("hello");
 extractDefault(field); // 'hello'
 
 const noDefault = z.string();
 extractDefault(noDefault); // undefined
+
+// Union with default in first option
+const unionField = z.union([z.string().default('hello'), z.number()]);
+extractDefault(unionField); // 'hello'
+
+// Union with default in second option (only checks first)
+const unionField2 = z.union([z.string(), z.number().default(42)]);
+extractDefault(unionField2); // undefined
+
+// Union wrapped in optional
+const wrappedUnion = z.union([z.string().default('test'), z.number()]).optional();
+extractDefault(wrappedUnion); // 'test'
+```
+
+---
+
+### `getFieldChecks(field)`
+
+Extract all validation check definitions from a Zod schema field. Returns Zod's raw check definition objects directly, including all properties like `check`, `minimum`, `maximum`, `value`, `inclusive`, `format`, `pattern`, etc.
+
+**Automatically unwraps:** optional, nullable, and default layers. For unions, checks only the first option.
+
+**Supported check types:** Returns any of 21 check types:
+- **Length checks**: `min_length`, `max_length`, `length_equals` (strings, arrays)
+- **Size checks**: `min_size`, `max_size`, `size_equals` (files, sets, maps)
+- **Numeric checks**: `greater_than`, `less_than`, `multiple_of`
+- **Format checks**: `number_format`, `bigint_format`, `string_format` (email, url, uuid, etc.)
+- **String pattern checks**: `regex`, `lowercase`, `uppercase`, `includes`, `starts_with`, `ends_with`
+- **Other checks**: `property`, `mime_type`, `overwrite`
+
+```typescript
+import { getFieldChecks } from "@zod-utils/core";
+import { z } from "zod";
+
+// String with length constraints
+const username = z.string().min(3).max(20);
+const checks = getFieldChecks(username);
+// [
+//   { check: 'min_length', minimum: 3, when: [Function], ... },
+//   { check: 'max_length', maximum: 20, when: [Function], ... }
+// ]
+
+// Number with range constraints
+const age = z.number().min(18).max(120);
+const checks = getFieldChecks(age);
+// [
+//   { check: 'greater_than', value: 18, inclusive: true, ... },
+//   { check: 'less_than', value: 120, inclusive: true, ... }
+// ]
+
+// Array with item count constraints
+const tags = z.array(z.string()).min(1).max(5);
+const checks = getFieldChecks(tags);
+// [
+//   { check: 'min_length', minimum: 1, ... },
+//   { check: 'max_length', maximum: 5, ... }
+// ]
+
+// String with format validation
+const email = z.string().email();
+const checks = getFieldChecks(email);
+// [{ check: 'string_format', format: 'email', ... }]
+
+// Unwrapping optional/nullable/default layers
+const bio = z.string().min(10).max(500).optional();
+const checks = getFieldChecks(bio);
+// [
+//   { check: 'min_length', minimum: 10, ... },
+//   { check: 'max_length', maximum: 500, ... }
+// ]
+
+// No checks
+const plainString = z.string();
+getFieldChecks(plainString); // []
+```
+
+**Type:** The return type is `ZodUnionCheck[]`, a union of all 21 Zod check definition types. You can also import the `ZodUnionCheck` type:
+
+```typescript
+import { getFieldChecks, type ZodUnionCheck } from "@zod-utils/core";
 ```
 
 ---

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 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';
 
 /**
  * Simplifies complex TypeScript types for better IDE hover tooltips and error messages.
@@ -45,11 +46,14 @@ type Simplify<T> = {
 } & {};
 
 /**
- * Extracts the default value from a Zod field, recursively unwrapping optional and nullable layers.
+ * Extracts the default value from a Zod field, recursively unwrapping optional, nullable, and union layers.
  *
- * This function traverses through wrapper types (like `ZodOptional`, `ZodNullable`) to find
+ * This function traverses through wrapper types (like `ZodOptional`, `ZodNullable`, `ZodUnion`) to find
  * the underlying `ZodDefault` and returns its default value. If no default is found, returns `undefined`.
  *
+ * **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).
+ *
  * @template T - The Zod type to extract default from
  * @param field - The Zod field to extract default from
  * @returns The default value if present, undefined otherwise
@@ -71,6 +75,22 @@ type Simplify<T> = {
  * ```
  *
  * @example
+ * Union with default in first option
+ * ```typescript
+ * const field = z.union([z.string().default('hello'), z.number()]);
+ * const defaultValue = extractDefault(field);
+ * // Result: 'hello' (extracts from first union option)
+ * ```
+ *
+ * @example
+ * Union with default in second option
+ * ```typescript
+ * const field = z.union([z.string(), z.number().default(42)]);
+ * const defaultValue = extractDefault(field);
+ * // Result: undefined (only checks first option)
+ * ```
+ *
+ * @example
  * Field without default
  * ```typescript
  * const field = z.string().optional();
@@ -169,6 +189,78 @@ type Unwrappable = {
  * @since 0.1.0
  */
 declare function canUnwrap(field: z.ZodTypeAny): field is z.ZodTypeAny & Unwrappable;
+/**
+ * Unwraps a ZodUnion type and returns the first field and all union options.
+ *
+ * This function extracts the individual type options from a union type.
+ * By default, it filters out `ZodNull` and `ZodUndefined` types, returning only
+ * the meaningful type options. You can disable this filtering to get all options.
+ *
+ * @template T - The Zod type to unwrap
+ * @param field - The Zod field (union or single type)
+ * @param options - Configuration options
+ * @param options.filterNullish - Whether to filter out null and undefined types (default: true)
+ * @returns Object with `field` (first option) and `union` (all options array)
+ *
+ * @example
+ * Basic union unwrapping
+ * ```typescript
+ * const field = z.union([z.string(), z.number()]);
+ * const result = unwrapUnion(field);
+ * // Result: { field: z.string(), union: [z.string(), z.number()] }
+ * ```
+ *
+ * @example
+ * Union with null (filtered by default)
+ * ```typescript
+ * const field = z.union([z.string(), z.null()]);
+ * const result = unwrapUnion(field);
+ * // Result: { field: z.string(), union: [z.string()] }
+ * ```
+ *
+ * @example
+ * Union with null (keep all options)
+ * ```typescript
+ * const field = z.union([z.string(), z.null()]);
+ * const result = unwrapUnion(field, { filterNullish: false });
+ * // Result: { field: z.string(), union: [z.string(), z.null()] }
+ * ```
+ *
+ * @example
+ * Non-union type (returns single field)
+ * ```typescript
+ * const field = z.string();
+ * const result = unwrapUnion(field);
+ * // Result: { field: z.string(), union: [z.string()] }
+ * ```
+ *
+ * @example
+ * Nullable as union
+ * ```typescript
+ * const field = z.string().nullable(); // This is z.union([z.string(), z.null()])
+ * const result = unwrapUnion(field);
+ * // Result: { field: z.string(), union: [z.string()] } (null filtered out)
+ * ```
+ *
+ * @example
+ * Using the first field for type checking
+ * ```typescript
+ * const field = z.union([z.string(), z.number()]);
+ * const { field: firstField, union } = unwrapUnion(field);
+ * if (firstField instanceof z.ZodString) {
+ *   console.log('First type is string');
+ * }
+ * ```
+ *
+ * @see {@link getPrimitiveType} for unwrapping wrapper types
+ * @since 0.1.0
+ */
+declare function unwrapUnion<T extends z.ZodTypeAny>(field: T, options?: {
+    filterNullish?: boolean;
+}): {
+    field: z.ZodTypeAny;
+    union: z.ZodTypeAny[];
+};
 /**
  * Gets the underlying primitive type of a Zod field by recursively unwrapping wrapper types.
  *
@@ -206,7 +298,7 @@ declare function canUnwrap(field: z.ZodTypeAny): field is z.ZodTypeAny & Unwrapp
  * @see {@link canUnwrap} for checking if a field can be unwrapped
  * @since 0.1.0
  */
-declare const getPrimitiveType: <T extends z.ZodTypeAny>(field: T) => z.ZodTypeAny;
+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;
 /**
  * Removes default values from a Zod field while preserving other wrapper types.
@@ -243,72 +335,177 @@ type StripZodDefault<T> = T extends z.ZodDefault<infer Inner> ? StripZodDefault<
  * // Result: z.string().nullable()
  * ```
  *
- * @see {@link checkIfFieldIsRequired} for usage with requirement checking
+ * @see {@link requiresValidInput} for usage with requirement checking
  * @since 0.1.0
  */
 declare function removeDefault<T extends z.ZodType>(field: T): StripZodDefault<T>;
 /**
- * Checks if a Zod field is truly required by testing multiple acceptance criteria.
+ * Determines if a field will show validation errors when the user submits empty or invalid input.
+ *
+ * This is useful for form UIs to indicate which fields require valid user input (e.g., showing
+ * asterisks, validation states). The key insight: **defaults are just initial values** - they
+ * don't prevent validation errors if the user clears the field.
  *
- * A field is considered **not required** if it accepts any of the following:
- * - `undefined` (via `.optional()` or `.default()`)
- * - `null` (via `.nullable()`)
- * - Empty string (plain `z.string()` without `.min(1)` or `.nonempty()`)
- * - Empty array (plain `z.array()` without `.min(1)` or `.nonempty()`)
+ * **Real-world example:**
+ * ```typescript
+ * // Marital status field with default but validation rules
+ * const maritalStatus = z.string().min(1).default('single');
+ *
+ * // Initial: field shows "single" (from default)
+ * // User deletes the value → field is now empty string
+ * // User submits form → validation fails because .min(1) rejects empty strings
+ * // requiresValidInput(maritalStatus) → true (shows * indicator, validation error)
+ * ```
  *
- * **Note:** Fields with `.default()` are considered not required since they'll have a value
- * even if the user doesn't provide one.
+ * **How it works:**
+ * 1. Removes `.default()` wrappers (defaults are initial values, not validation rules)
+ * 2. Tests if the underlying schema accepts empty/invalid input:
+ *    - `undefined` (via `.optional()`)
+ *    - `null` (via `.nullable()`)
+ *    - Empty string (plain `z.string()` without `.min(1)` or `.nonempty()`)
+ *    - Empty array (plain `z.array()` without `.min(1)` or `.nonempty()`)
+ * 3. Returns `true` if validation will fail, `false` if empty input is accepted
  *
  * @template T - The Zod type to check
- * @param field - The Zod field to check for required status
- * @returns True if the field is required, false otherwise
+ * @param field - The Zod field to check
+ * @returns True if the field will show validation errors on empty/invalid input, false otherwise
  *
  * @example
- * Required field
+ * User name field - required, no default
  * ```typescript
- * const field = z.string().min(1);
- * console.log(checkIfFieldIsRequired(field)); // true
+ * const userName = z.string().min(1);
+ * requiresValidInput(userName); // true - will error if user submits empty
  * ```
  *
  * @example
- * Optional field (not required)
+ * Marital status - required WITH default
  * ```typescript
- * const field = z.string().optional();
- * console.log(checkIfFieldIsRequired(field)); // false
+ * const maritalStatus = z.string().min(1).default('single');
+ * requiresValidInput(maritalStatus); // true - will error if user clears and submits
  * ```
  *
  * @example
- * Field with default (not required)
+ * Age with default - requires valid input
  * ```typescript
- * const field = z.string().default('hello');
- * console.log(checkIfFieldIsRequired(field)); // false
+ * const age = z.number().default(0);
+ * requiresValidInput(age); // true - numbers reject empty strings
  * ```
  *
  * @example
- * String without min length (not required - accepts empty string)
+ * Optional bio field - doesn't require input
  * ```typescript
- * const field = z.string();
- * console.log(checkIfFieldIsRequired(field)); // false
+ * const bio = z.string().optional();
+ * requiresValidInput(bio); // false - user can leave empty
  * ```
  *
  * @example
- * String with nonempty (required)
+ * String with default but NO validation - doesn't require input
  * ```typescript
- * const field = z.string().nonempty();
- * console.log(checkIfFieldIsRequired(field)); // true
+ * const notes = z.string().default('N/A');
+ * requiresValidInput(notes); // false - plain z.string() accepts empty strings
  * ```
  *
  * @example
- * Nullable field (not required)
+ * Nullable field - doesn't require input
  * ```typescript
- * const field = z.number().nullable();
- * console.log(checkIfFieldIsRequired(field)); // false
+ * const middleName = z.string().nullable();
+ * requiresValidInput(middleName); // false - user can leave null
  * ```
  *
  * @see {@link removeDefault} for understanding how defaults are handled
  * @see {@link getPrimitiveType} for understanding type unwrapping
  * @since 0.1.0
  */
-declare const checkIfFieldIsRequired: <T extends z.ZodType>(field: T) => boolean;
+declare const requiresValidInput: <T extends z.ZodType>(field: T) => boolean;
+/**
+ * Union type of all Zod check definition types.
+ *
+ * Includes all validation check types supported by Zod v4:
+ * - **Length checks**: `min_length`, `max_length`, `length_equals` (strings, arrays)
+ * - **Size checks**: `min_size`, `max_size`, `size_equals` (files, sets, maps)
+ * - **Numeric checks**: `greater_than`, `less_than`, `multiple_of`
+ * - **Format checks**: `number_format` (int32, float64, etc.), `bigint_format`, `string_format` (email, url, uuid, etc.)
+ * - **String pattern checks**: `regex`, `lowercase`, `uppercase`, `includes`, `starts_with`, `ends_with`
+ * - **Other checks**: `property`, `mime_type`, `overwrite`
+ *
+ * @since 0.4.0
+ */
+type ZodUnionCheck = $ZodCheckLessThanDef | $ZodCheckGreaterThanDef | $ZodCheckMultipleOfDef | $ZodCheckNumberFormatDef | $ZodCheckBigIntFormatDef | $ZodCheckMaxSizeDef | $ZodCheckMinSizeDef | $ZodCheckSizeEqualsDef | $ZodCheckMaxLengthDef | $ZodCheckMinLengthDef | $ZodCheckLengthEqualsDef | $ZodCheckStringFormatDef | $ZodCheckRegexDef | $ZodCheckLowerCaseDef | $ZodCheckUpperCaseDef | $ZodCheckIncludesDef | $ZodCheckStartsWithDef | $ZodCheckEndsWithDef | $ZodCheckPropertyDef | $ZodCheckMimeTypeDef | $ZodCheckOverwriteDef;
+/**
+ * Extracts all validation check definitions from a Zod schema field.
+ *
+ * This function analyzes a Zod field and returns all check definitions as defined
+ * by Zod's internal structure. Returns Zod's raw check definition objects directly,
+ * including all properties like `check`, `minimum`, `maximum`, `value`, `inclusive`,
+ * `format`, `pattern`, etc.
+ *
+ * **Unwrapping behavior:** Automatically unwraps optional, nullable, and default layers.
+ * For unions, checks only the first option (same as other schema utilities).
+ *
+ * **Supported check types:** Returns any of the 21 check types defined in {@link ZodUnionCheck},
+ * including length, size, numeric range, format validation, string patterns, and more.
+ *
+ * @template T - The Zod type to extract checks from
+ * @param field - The Zod field to analyze
+ * @returns Array of Zod check definition objects (see {@link ZodUnionCheck})
+ *
+ * @example
+ * String with length constraints
+ * ```typescript
+ * const username = z.string().min(3).max(20);
+ * const checks = getFieldChecks(username);
+ * // [
+ * //   { check: 'min_length', minimum: 3, when: [Function], ... },
+ * //   { check: 'max_length', maximum: 20, when: [Function], ... }
+ * // ]
+ * ```
+ *
+ * @example
+ * Number with range constraints
+ * ```typescript
+ * const age = z.number().min(18).max(120);
+ * const checks = getFieldChecks(age);
+ * // [
+ * //   { check: 'greater_than', value: 18, inclusive: true, when: [Function], ... },
+ * //   { check: 'less_than', value: 120, inclusive: true, when: [Function], ... }
+ * // ]
+ * ```
+ *
+ * @example
+ * Array with item count constraints
+ * ```typescript
+ * const tags = z.array(z.string()).min(1).max(5);
+ * const checks = getFieldChecks(tags);
+ * // [
+ * //   { check: 'min_length', minimum: 1, ... },
+ * //   { check: 'max_length', maximum: 5, ... }
+ * // ]
+ * ```
+ *
+ * @example
+ * String with format validation
+ * ```typescript
+ * const email = z.string().email();
+ * const checks = getFieldChecks(email);
+ * // [
+ * //   { check: 'string_format', format: 'email', ... }
+ * // ]
+ * ```
+ *
+ * @example
+ * Unwrapping optional/nullable/default layers
+ * ```typescript
+ * const bio = z.string().min(10).max(500).optional();
+ * const checks = getFieldChecks(bio);
+ * // [
+ * //   { check: 'min_length', minimum: 10, ... },
+ * //   { check: 'max_length', maximum: 500, ... }
+ * // ]
+ * ```
+ *
+ * @see {@link ZodUnionCheck} for all supported check types
+ * @since 0.4.0
+ */
+declare function getFieldChecks<T extends z.ZodTypeAny>(field: T): Array<ZodUnionCheck>;
 
-export { type Simplify, canUnwrap, checkIfFieldIsRequired, extractDefault, getPrimitiveType, getSchemaDefaults, removeDefault };
+export { type Simplify, type ZodUnionCheck, canUnwrap, extractDefault, getFieldChecks, getPrimitiveType, getSchemaDefaults, removeDefault, requiresValidInput, unwrapUnion };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 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';
 
 /**
  * Simplifies complex TypeScript types for better IDE hover tooltips and error messages.
@@ -45,11 +46,14 @@ type Simplify<T> = {
 } & {};
 
 /**
- * Extracts the default value from a Zod field, recursively unwrapping optional and nullable layers.
+ * Extracts the default value from a Zod field, recursively unwrapping optional, nullable, and union layers.
  *
- * This function traverses through wrapper types (like `ZodOptional`, `ZodNullable`) to find
+ * This function traverses through wrapper types (like `ZodOptional`, `ZodNullable`, `ZodUnion`) to find
  * the underlying `ZodDefault` and returns its default value. If no default is found, returns `undefined`.
  *
+ * **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).
+ *
  * @template T - The Zod type to extract default from
  * @param field - The Zod field to extract default from
  * @returns The default value if present, undefined otherwise
@@ -71,6 +75,22 @@ type Simplify<T> = {
  * ```
  *
  * @example
+ * Union with default in first option
+ * ```typescript
+ * const field = z.union([z.string().default('hello'), z.number()]);
+ * const defaultValue = extractDefault(field);
+ * // Result: 'hello' (extracts from first union option)
+ * ```
+ *
+ * @example
+ * Union with default in second option
+ * ```typescript
+ * const field = z.union([z.string(), z.number().default(42)]);
+ * const defaultValue = extractDefault(field);
+ * // Result: undefined (only checks first option)
+ * ```
+ *
+ * @example
  * Field without default
  * ```typescript
  * const field = z.string().optional();
@@ -169,6 +189,78 @@ type Unwrappable = {
  * @since 0.1.0
  */
 declare function canUnwrap(field: z.ZodTypeAny): field is z.ZodTypeAny & Unwrappable;
+/**
+ * Unwraps a ZodUnion type and returns the first field and all union options.
+ *
+ * This function extracts the individual type options from a union type.
+ * By default, it filters out `ZodNull` and `ZodUndefined` types, returning only
+ * the meaningful type options. You can disable this filtering to get all options.
+ *
+ * @template T - The Zod type to unwrap
+ * @param field - The Zod field (union or single type)
+ * @param options - Configuration options
+ * @param options.filterNullish - Whether to filter out null and undefined types (default: true)
+ * @returns Object with `field` (first option) and `union` (all options array)
+ *
+ * @example
+ * Basic union unwrapping
+ * ```typescript
+ * const field = z.union([z.string(), z.number()]);
+ * const result = unwrapUnion(field);
+ * // Result: { field: z.string(), union: [z.string(), z.number()] }
+ * ```
+ *
+ * @example
+ * Union with null (filtered by default)
+ * ```typescript
+ * const field = z.union([z.string(), z.null()]);
+ * const result = unwrapUnion(field);
+ * // Result: { field: z.string(), union: [z.string()] }
+ * ```
+ *
+ * @example
+ * Union with null (keep all options)
+ * ```typescript
+ * const field = z.union([z.string(), z.null()]);
+ * const result = unwrapUnion(field, { filterNullish: false });
+ * // Result: { field: z.string(), union: [z.string(), z.null()] }
+ * ```
+ *
+ * @example
+ * Non-union type (returns single field)
+ * ```typescript
+ * const field = z.string();
+ * const result = unwrapUnion(field);
+ * // Result: { field: z.string(), union: [z.string()] }
+ * ```
+ *
+ * @example
+ * Nullable as union
+ * ```typescript
+ * const field = z.string().nullable(); // This is z.union([z.string(), z.null()])
+ * const result = unwrapUnion(field);
+ * // Result: { field: z.string(), union: [z.string()] } (null filtered out)
+ * ```
+ *
+ * @example
+ * Using the first field for type checking
+ * ```typescript
+ * const field = z.union([z.string(), z.number()]);
+ * const { field: firstField, union } = unwrapUnion(field);
+ * if (firstField instanceof z.ZodString) {
+ *   console.log('First type is string');
+ * }
+ * ```
+ *
+ * @see {@link getPrimitiveType} for unwrapping wrapper types
+ * @since 0.1.0
+ */
+declare function unwrapUnion<T extends z.ZodTypeAny>(field: T, options?: {
+    filterNullish?: boolean;
+}): {
+    field: z.ZodTypeAny;
+    union: z.ZodTypeAny[];
+};
 /**
  * Gets the underlying primitive type of a Zod field by recursively unwrapping wrapper types.
  *
@@ -206,7 +298,7 @@ declare function canUnwrap(field: z.ZodTypeAny): field is z.ZodTypeAny & Unwrapp
  * @see {@link canUnwrap} for checking if a field can be unwrapped
  * @since 0.1.0
  */
-declare const getPrimitiveType: <T extends z.ZodTypeAny>(field: T) => z.ZodTypeAny;
+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;
 /**
  * Removes default values from a Zod field while preserving other wrapper types.
@@ -243,72 +335,177 @@ type StripZodDefault<T> = T extends z.ZodDefault<infer Inner> ? StripZodDefault<
  * // Result: z.string().nullable()
  * ```
  *
- * @see {@link checkIfFieldIsRequired} for usage with requirement checking
+ * @see {@link requiresValidInput} for usage with requirement checking
  * @since 0.1.0
  */
 declare function removeDefault<T extends z.ZodType>(field: T): StripZodDefault<T>;
 /**
- * Checks if a Zod field is truly required by testing multiple acceptance criteria.
+ * Determines if a field will show validation errors when the user submits empty or invalid input.
+ *
+ * This is useful for form UIs to indicate which fields require valid user input (e.g., showing
+ * asterisks, validation states). The key insight: **defaults are just initial values** - they
+ * don't prevent validation errors if the user clears the field.
  *
- * A field is considered **not required** if it accepts any of the following:
- * - `undefined` (via `.optional()` or `.default()`)
- * - `null` (via `.nullable()`)
- * - Empty string (plain `z.string()` without `.min(1)` or `.nonempty()`)
- * - Empty array (plain `z.array()` without `.min(1)` or `.nonempty()`)
+ * **Real-world example:**
+ * ```typescript
+ * // Marital status field with default but validation rules
+ * const maritalStatus = z.string().min(1).default('single');
+ *
+ * // Initial: field shows "single" (from default)
+ * // User deletes the value → field is now empty string
+ * // User submits form → validation fails because .min(1) rejects empty strings
+ * // requiresValidInput(maritalStatus) → true (shows * indicator, validation error)
+ * ```
  *
- * **Note:** Fields with `.default()` are considered not required since they'll have a value
- * even if the user doesn't provide one.
+ * **How it works:**
+ * 1. Removes `.default()` wrappers (defaults are initial values, not validation rules)
+ * 2. Tests if the underlying schema accepts empty/invalid input:
+ *    - `undefined` (via `.optional()`)
+ *    - `null` (via `.nullable()`)
+ *    - Empty string (plain `z.string()` without `.min(1)` or `.nonempty()`)
+ *    - Empty array (plain `z.array()` without `.min(1)` or `.nonempty()`)
+ * 3. Returns `true` if validation will fail, `false` if empty input is accepted
  *
  * @template T - The Zod type to check
- * @param field - The Zod field to check for required status
- * @returns True if the field is required, false otherwise
+ * @param field - The Zod field to check
+ * @returns True if the field will show validation errors on empty/invalid input, false otherwise
  *
  * @example
- * Required field
+ * User name field - required, no default
  * ```typescript
- * const field = z.string().min(1);
- * console.log(checkIfFieldIsRequired(field)); // true
+ * const userName = z.string().min(1);
+ * requiresValidInput(userName); // true - will error if user submits empty
  * ```
  *
  * @example
- * Optional field (not required)
+ * Marital status - required WITH default
  * ```typescript
- * const field = z.string().optional();
- * console.log(checkIfFieldIsRequired(field)); // false
+ * const maritalStatus = z.string().min(1).default('single');
+ * requiresValidInput(maritalStatus); // true - will error if user clears and submits
  * ```
  *
  * @example
- * Field with default (not required)
+ * Age with default - requires valid input
  * ```typescript
- * const field = z.string().default('hello');
- * console.log(checkIfFieldIsRequired(field)); // false
+ * const age = z.number().default(0);
+ * requiresValidInput(age); // true - numbers reject empty strings
  * ```
  *
  * @example
- * String without min length (not required - accepts empty string)
+ * Optional bio field - doesn't require input
  * ```typescript
- * const field = z.string();
- * console.log(checkIfFieldIsRequired(field)); // false
+ * const bio = z.string().optional();
+ * requiresValidInput(bio); // false - user can leave empty
  * ```
  *
  * @example
- * String with nonempty (required)
+ * String with default but NO validation - doesn't require input
  * ```typescript
- * const field = z.string().nonempty();
- * console.log(checkIfFieldIsRequired(field)); // true
+ * const notes = z.string().default('N/A');
+ * requiresValidInput(notes); // false - plain z.string() accepts empty strings
  * ```
  *
  * @example
- * Nullable field (not required)
+ * Nullable field - doesn't require input
  * ```typescript
- * const field = z.number().nullable();
- * console.log(checkIfFieldIsRequired(field)); // false
+ * const middleName = z.string().nullable();
+ * requiresValidInput(middleName); // false - user can leave null
  * ```
  *
  * @see {@link removeDefault} for understanding how defaults are handled
  * @see {@link getPrimitiveType} for understanding type unwrapping
  * @since 0.1.0
  */
-declare const checkIfFieldIsRequired: <T extends z.ZodType>(field: T) => boolean;
+declare const requiresValidInput: <T extends z.ZodType>(field: T) => boolean;
+/**
+ * Union type of all Zod check definition types.
+ *
+ * Includes all validation check types supported by Zod v4:
+ * - **Length checks**: `min_length`, `max_length`, `length_equals` (strings, arrays)
+ * - **Size checks**: `min_size`, `max_size`, `size_equals` (files, sets, maps)
+ * - **Numeric checks**: `greater_than`, `less_than`, `multiple_of`
+ * - **Format checks**: `number_format` (int32, float64, etc.), `bigint_format`, `string_format` (email, url, uuid, etc.)
+ * - **String pattern checks**: `regex`, `lowercase`, `uppercase`, `includes`, `starts_with`, `ends_with`
+ * - **Other checks**: `property`, `mime_type`, `overwrite`
+ *
+ * @since 0.4.0
+ */
+type ZodUnionCheck = $ZodCheckLessThanDef | $ZodCheckGreaterThanDef | $ZodCheckMultipleOfDef | $ZodCheckNumberFormatDef | $ZodCheckBigIntFormatDef | $ZodCheckMaxSizeDef | $ZodCheckMinSizeDef | $ZodCheckSizeEqualsDef | $ZodCheckMaxLengthDef | $ZodCheckMinLengthDef | $ZodCheckLengthEqualsDef | $ZodCheckStringFormatDef | $ZodCheckRegexDef | $ZodCheckLowerCaseDef | $ZodCheckUpperCaseDef | $ZodCheckIncludesDef | $ZodCheckStartsWithDef | $ZodCheckEndsWithDef | $ZodCheckPropertyDef | $ZodCheckMimeTypeDef | $ZodCheckOverwriteDef;
+/**
+ * Extracts all validation check definitions from a Zod schema field.
+ *
+ * This function analyzes a Zod field and returns all check definitions as defined
+ * by Zod's internal structure. Returns Zod's raw check definition objects directly,
+ * including all properties like `check`, `minimum`, `maximum`, `value`, `inclusive`,
+ * `format`, `pattern`, etc.
+ *
+ * **Unwrapping behavior:** Automatically unwraps optional, nullable, and default layers.
+ * For unions, checks only the first option (same as other schema utilities).
+ *
+ * **Supported check types:** Returns any of the 21 check types defined in {@link ZodUnionCheck},
+ * including length, size, numeric range, format validation, string patterns, and more.
+ *
+ * @template T - The Zod type to extract checks from
+ * @param field - The Zod field to analyze
+ * @returns Array of Zod check definition objects (see {@link ZodUnionCheck})
+ *
+ * @example
+ * String with length constraints
+ * ```typescript
+ * const username = z.string().min(3).max(20);
+ * const checks = getFieldChecks(username);
+ * // [
+ * //   { check: 'min_length', minimum: 3, when: [Function], ... },
+ * //   { check: 'max_length', maximum: 20, when: [Function], ... }
+ * // ]
+ * ```
+ *
+ * @example
+ * Number with range constraints
+ * ```typescript
+ * const age = z.number().min(18).max(120);
+ * const checks = getFieldChecks(age);
+ * // [
+ * //   { check: 'greater_than', value: 18, inclusive: true, when: [Function], ... },
+ * //   { check: 'less_than', value: 120, inclusive: true, when: [Function], ... }
+ * // ]
+ * ```
+ *
+ * @example
+ * Array with item count constraints
+ * ```typescript
+ * const tags = z.array(z.string()).min(1).max(5);
+ * const checks = getFieldChecks(tags);
+ * // [
+ * //   { check: 'min_length', minimum: 1, ... },
+ * //   { check: 'max_length', maximum: 5, ... }
+ * // ]
+ * ```
+ *
+ * @example
+ * String with format validation
+ * ```typescript
+ * const email = z.string().email();
+ * const checks = getFieldChecks(email);
+ * // [
+ * //   { check: 'string_format', format: 'email', ... }
+ * // ]
+ * ```
+ *
+ * @example
+ * Unwrapping optional/nullable/default layers
+ * ```typescript
+ * const bio = z.string().min(10).max(500).optional();
+ * const checks = getFieldChecks(bio);
+ * // [
+ * //   { check: 'min_length', minimum: 10, ... },
+ * //   { check: 'max_length', maximum: 500, ... }
+ * // ]
+ * ```
+ *
+ * @see {@link ZodUnionCheck} for all supported check types
+ * @since 0.4.0
+ */
+declare function getFieldChecks<T extends z.ZodTypeAny>(field: T): Array<ZodUnionCheck>;
 
-export { type Simplify, canUnwrap, checkIfFieldIsRequired, extractDefault, getPrimitiveType, getSchemaDefaults, removeDefault };
+export { type Simplify, type ZodUnionCheck, canUnwrap, extractDefault, getFieldChecks, getPrimitiveType, getSchemaDefaults, removeDefault, requiresValidInput, unwrapUnion };

package/dist/index.js

@@ -26,6 +26,23 @@ var z__namespace = /*#__PURE__*/_interopNamespace(z);
 function canUnwrap(field) {
   return "unwrap" in field && typeof field.unwrap === "function";
 }
+function unwrapUnion(field, options = {}) {
+  const { filterNullish = true } = options;
+  if (field instanceof z__namespace.ZodUnion) {
+    const unionOptions = [...field.def.options];
+    const filteredOptions = filterNullish ? unionOptions.filter(
+      (option) => !(option instanceof z__namespace.ZodNull) && !(option instanceof z__namespace.ZodUndefined)
+    ) : unionOptions;
+    return {
+      field: filteredOptions[0] || field,
+      union: filteredOptions
+    };
+  }
+  return {
+    field,
+    union: [field]
+  };
+}
 var getPrimitiveType = (field) => {
   if (field instanceof z__namespace.ZodArray) {
     return field;
@@ -33,6 +50,9 @@ var getPrimitiveType = (field) => {
   if (canUnwrap(field)) {
     return getPrimitiveType(field.unwrap());
   }
+  if (field instanceof z__namespace.ZodUnion) {
+    return getPrimitiveType(unwrapUnion(field).field);
+  }
   return field;
 };
 function removeDefault(field) {
@@ -50,21 +70,23 @@ function removeDefault(field) {
   }
   return field;
 }
-var checkIfFieldIsRequired = (field) => {
-  const undefinedResult = field.safeParse(void 0).success;
-  if (undefinedResult) {
-    return false;
-  }
+var requiresValidInput = (field) => {
   const defaultRemovedField = removeDefault(field);
   if (!(defaultRemovedField instanceof z__namespace.ZodType)) {
     return false;
   }
+  const undefinedResult = defaultRemovedField.safeParse(void 0).success;
   const nullResult = defaultRemovedField.safeParse(null).success;
   const primitiveType = getPrimitiveType(defaultRemovedField);
   const emptyStringResult = primitiveType.type === "string" && defaultRemovedField.safeParse("").success;
   const emptyArrayResult = primitiveType.type === "array" && defaultRemovedField.safeParse([]).success;
   return !undefinedResult && !nullResult && !emptyStringResult && !emptyArrayResult;
 };
+function getFieldChecks(field) {
+  var _a;
+  const primitiveType = getPrimitiveType(field);
+  return ((_a = primitiveType.def.checks) == null ? void 0 : _a.map((check) => check._zod.def)) || [];
+}
 
 // src/defaults.ts
 function extractDefault(field) {
@@ -74,6 +96,9 @@ function extractDefault(field) {
   if (canUnwrap(field)) {
     return extractDefault(field.unwrap());
   }
+  if (field instanceof z__namespace.ZodUnion) {
+    return extractDefault(unwrapUnion(field).field);
+  }
   return void 0;
 }
 function getSchemaDefaults(schema) {
@@ -90,10 +115,12 @@ function getSchemaDefaults(schema) {
 }
 
 exports.canUnwrap = canUnwrap;
-exports.checkIfFieldIsRequired = checkIfFieldIsRequired;
 exports.extractDefault = extractDefault;
+exports.getFieldChecks = getFieldChecks;
 exports.getPrimitiveType = getPrimitiveType;
 exports.getSchemaDefaults = getSchemaDefaults;
 exports.removeDefault = removeDefault;
+exports.requiresValidInput = requiresValidInput;
+exports.unwrapUnion = unwrapUnion;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/schema.ts","../src/defaults.ts"],"names":["z","z2"],"mappings":"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","file":"index.js","sourcesContent":["import * as z from 'zod';\n\n/**\n * Type representing a Zod type that has an unwrap method\n */\ntype Unwrappable = { unwrap: () => z.ZodTypeAny };\n\n/**\n * Type guard to check if a Zod field can be unwrapped (has wrapper types like optional, nullable, default).\n *\n * This checks whether a Zod type has an `unwrap()` method, which is present on wrapper types\n * like `ZodOptional`, `ZodNullable`, `ZodDefault`, and others.\n *\n * @param field - The Zod field to check\n * @returns True if the field has an unwrap method, false otherwise\n *\n * @example\n * ```typescript\n * const optionalField = z.string().optional();\n * console.log(canUnwrap(optionalField)); // true\n *\n * const plainField = z.string();\n * console.log(canUnwrap(plainField)); // false\n * ```\n *\n * @since 0.1.0\n */\nexport function canUnwrap(\n  field: z.ZodTypeAny,\n): field is z.ZodTypeAny & Unwrappable {\n  return 'unwrap' in field && typeof field.unwrap === 'function';\n}\n\n/**\n * Gets the underlying primitive type of a Zod field by recursively unwrapping wrapper types.\n *\n * This function removes wrapper layers (optional, nullable, default) to reveal the base type.\n * **Important:** It stops at array types without unwrapping them, treating arrays as primitives.\n *\n * @template T - The Zod type to unwrap\n * @param field - The Zod field to unwrap\n * @returns The unwrapped primitive Zod type\n *\n * @example\n * Unwrapping to string primitive\n * ```typescript\n * const field = z.string().optional().nullable();\n * const primitive = getPrimitiveType(field);\n * // Result: z.string() (unwrapped all wrappers)\n * ```\n *\n * @example\n * Stopping at array type\n * ```typescript\n * const field = z.array(z.string()).optional();\n * const primitive = getPrimitiveType(field);\n * // Result: z.array(z.string()) (stops at array, doesn't unwrap it)\n * ```\n *\n * @example\n * Unwrapping defaults\n * ```typescript\n * const field = z.number().default(0).optional();\n * const primitive = getPrimitiveType(field);\n * // Result: z.number()\n * ```\n *\n * @see {@link canUnwrap} for checking if a field can be unwrapped\n * @since 0.1.0\n */\nexport const getPrimitiveType = <T extends z.ZodTypeAny>(\n  field: T,\n): z.ZodTypeAny => {\n  // Stop at arrays - don't unwrap them\n  if (field instanceof z.ZodArray) {\n    return field;\n  }\n\n  if (canUnwrap(field)) {\n    return getPrimitiveType(field.unwrap());\n  }\n\n  return field;\n};\n\ntype StripZodDefault<T> = T extends z.ZodDefault<infer Inner>\n  ? StripZodDefault<Inner>\n  : T extends z.ZodOptional<infer Inner>\n    ? z.ZodOptional<StripZodDefault<Inner>>\n    : T extends z.ZodNullable<infer Inner>\n      ? z.ZodNullable<StripZodDefault<Inner>>\n      : T;\n\n/**\n * Removes default values from a Zod field while preserving other wrapper types.\n *\n * This function recursively removes `ZodDefault` wrappers from a field, while maintaining\n * `optional()` and `nullable()` wrappers. Useful for scenarios where you want to check\n * field requirements without considering default values.\n *\n * @template T - The Zod type to process\n * @param field - The Zod field to remove defaults from\n * @returns The field without defaults but with optional/nullable preserved\n *\n * @example\n * Removing simple default\n * ```typescript\n * const field = z.string().default('hello');\n * const withoutDefault = removeDefault(field);\n * // Result: z.string()\n * ```\n *\n * @example\n * Preserving optional wrapper\n * ```typescript\n * const field = z.string().default('hello').optional();\n * const withoutDefault = removeDefault(field);\n * // Result: z.string().optional()\n * ```\n *\n * @example\n * Nested defaults\n * ```typescript\n * const field = z.string().default('inner').nullable().default('outer');\n * const withoutDefault = removeDefault(field);\n * // Result: z.string().nullable()\n * ```\n *\n * @see {@link checkIfFieldIsRequired} for usage with requirement checking\n * @since 0.1.0\n */\nexport function removeDefault<T extends z.ZodType>(\n  field: T,\n): StripZodDefault<T> {\n  if (field instanceof z.ZodDefault) {\n    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n    return field.unwrap() as StripZodDefault<T>;\n  }\n\n  if ('innerType' in field.def && field.def.innerType instanceof z.ZodType) {\n    const inner = removeDefault(field.def.innerType);\n    // Reconstruct the wrapper with the modified inner type\n    if (field instanceof z.ZodOptional) {\n      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n      return inner.optional() as unknown as StripZodDefault<T>;\n    }\n    if (field instanceof z.ZodNullable) {\n      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n      return inner.nullable() as unknown as StripZodDefault<T>;\n    }\n  }\n\n  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n  return field as StripZodDefault<T>;\n}\n\n/**\n * Checks if a Zod field is truly required by testing multiple acceptance criteria.\n *\n * A field is considered **not required** if it accepts any of the following:\n * - `undefined` (via `.optional()` or `.default()`)\n * - `null` (via `.nullable()`)\n * - Empty string (plain `z.string()` without `.min(1)` or `.nonempty()`)\n * - Empty array (plain `z.array()` without `.min(1)` or `.nonempty()`)\n *\n * **Note:** Fields with `.default()` are considered not required since they'll have a value\n * even if the user doesn't provide one.\n *\n * @template T - The Zod type to check\n * @param field - The Zod field to check for required status\n * @returns True if the field is required, false otherwise\n *\n * @example\n * Required field\n * ```typescript\n * const field = z.string().min(1);\n * console.log(checkIfFieldIsRequired(field)); // true\n * ```\n *\n * @example\n * Optional field (not required)\n * ```typescript\n * const field = z.string().optional();\n * console.log(checkIfFieldIsRequired(field)); // false\n * ```\n *\n * @example\n * Field with default (not required)\n * ```typescript\n * const field = z.string().default('hello');\n * console.log(checkIfFieldIsRequired(field)); // false\n * ```\n *\n * @example\n * String without min length (not required - accepts empty string)\n * ```typescript\n * const field = z.string();\n * console.log(checkIfFieldIsRequired(field)); // false\n * ```\n *\n * @example\n * String with nonempty (required)\n * ```typescript\n * const field = z.string().nonempty();\n * console.log(checkIfFieldIsRequired(field)); // true\n * ```\n *\n * @example\n * Nullable field (not required)\n * ```typescript\n * const field = z.number().nullable();\n * console.log(checkIfFieldIsRequired(field)); // false\n * ```\n *\n * @see {@link removeDefault} for understanding how defaults are handled\n * @see {@link getPrimitiveType} for understanding type unwrapping\n * @since 0.1.0\n */\nexport const checkIfFieldIsRequired = <T extends z.ZodType>(field: T) => {\n  // First check the original field for undefined - this catches fields with defaults\n  const undefinedResult = field.safeParse(undefined).success;\n  if (undefinedResult) {\n    return false;\n  }\n\n  const defaultRemovedField = removeDefault(field);\n\n  if (!(defaultRemovedField instanceof z.ZodType)) {\n    return false;\n  }\n\n  // Check if field accepts null (nullable)\n  const nullResult = defaultRemovedField.safeParse(null).success;\n\n  const primitiveType = getPrimitiveType(defaultRemovedField);\n\n  const emptyStringResult =\n    primitiveType.type === 'string' &&\n    defaultRemovedField.safeParse('').success;\n\n  const emptyArrayResult =\n    primitiveType.type === 'array' && defaultRemovedField.safeParse([]).success;\n\n  return (\n    !undefinedResult && !nullResult && !emptyStringResult && !emptyArrayResult\n  );\n};\n","import * as z from 'zod';\nimport { canUnwrap } from './schema';\nimport type { Simplify } from './types';\n\n/**\n * Extracts the default value from a Zod field, recursively unwrapping optional and nullable layers.\n *\n * This function traverses through wrapper types (like `ZodOptional`, `ZodNullable`) to find\n * the underlying `ZodDefault` and returns its default value. If no default is found, returns `undefined`.\n *\n * @template T - The Zod type to extract default from\n * @param field - The Zod field to extract default from\n * @returns The default value if present, undefined otherwise\n *\n * @example\n * Basic usage with default value\n * ```typescript\n * const field = z.string().default('hello');\n * const defaultValue = extractDefault(field);\n * // Result: 'hello'\n * ```\n *\n * @example\n * Unwrapping optional/nullable layers\n * ```typescript\n * const field = z.string().default('world').optional();\n * const defaultValue = extractDefault(field);\n * // Result: 'world' (unwraps optional to find default)\n * ```\n *\n * @example\n * Field without default\n * ```typescript\n * const field = z.string().optional();\n * const defaultValue = extractDefault(field);\n * // Result: undefined\n * ```\n *\n * @see {@link getSchemaDefaults} for extracting defaults from entire schemas\n * @since 0.1.0\n */\nexport function extractDefault<T extends z.ZodTypeAny>(\n  field: T,\n): z.infer<T> | undefined {\n  if (field instanceof z.ZodDefault) {\n    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n    return field.def.defaultValue as z.infer<T>;\n  }\n\n  if (canUnwrap(field)) {\n    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n    return extractDefault(field.unwrap()) as z.infer<T>;\n  }\n\n  return undefined;\n}\n\n/**\n * Extracts default values from a Zod object schema while skipping fields without defaults.\n *\n * This function recursively traverses the schema and collects all fields that have\n * explicit default values defined. Fields without defaults are excluded from the result.\n *\n * **Important:** Nested defaults are NOT extracted unless the parent object also has\n * an explicit `.default()`. This is by design to match Zod's default value behavior.\n *\n * @template T - The Zod object schema type\n * @param schema - The Zod object schema to extract defaults from\n * @returns A partial object containing only fields with default values\n *\n * @example\n * Basic usage\n * ```typescript\n * const schema = z.object({\n *   name: z.string().default('John'),\n *   age: z.number(), // no default - will be skipped\n *   email: z.string().email().optional(),\n * });\n *\n * const defaults = getSchemaDefaults(schema);\n * // Result: { name: 'John' }\n * ```\n *\n * @example\n * Nested objects with defaults\n * ```typescript\n * const schema = z.object({\n *   user: z.object({\n *     name: z.string().default('Guest')\n *   }).default({ name: 'Guest' }), // ✅ Extracted because parent has .default()\n *\n *   settings: z.object({\n *     theme: z.string().default('light')\n *   }), // ❌ NOT extracted - parent has no .default()\n * });\n *\n * const defaults = getSchemaDefaults(schema);\n * // Result: { user: { name: 'Guest' } }\n * ```\n *\n * @example\n * Unwrapping optional/nullable fields\n * ```typescript\n * const schema = z.object({\n *   title: z.string().default('Untitled').optional(),\n *   count: z.number().default(0).nullable(),\n * });\n *\n * const defaults = getSchemaDefaults(schema);\n * // Result: { title: 'Untitled', count: 0 }\n * ```\n *\n * @see {@link extractDefault} for extracting defaults from individual fields\n * @since 0.1.0\n */\nexport function getSchemaDefaults<T extends z.ZodObject>(\n  schema: T,\n): Simplify<Partial<z.infer<T>>> {\n  const defaults: Record<string, unknown> = {};\n\n  for (const key in schema.shape) {\n    const field = schema.shape[key];\n    if (!field) continue;\n\n    // Check if this field has an explicit default value\n    const defaultValue = extractDefault(field);\n    if (defaultValue !== undefined) {\n      defaults[key] = defaultValue;\n    }\n  }\n\n  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n  return defaults as Partial<z.infer<T>>;\n}\n"]}
+{"version":3,"sources":["../src/schema.ts","../src/defaults.ts"],"names":["z","z2"],"mappings":"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","file":"index.js","sourcesContent":["import * as z from 'zod';\nimport type {\n  $ZodCheckBigIntFormatDef,\n  $ZodCheckEndsWithDef,\n  $ZodCheckGreaterThanDef,\n  $ZodCheckIncludesDef,\n  $ZodCheckLengthEqualsDef,\n  $ZodCheckLessThanDef,\n  $ZodCheckLowerCaseDef,\n  $ZodCheckMaxLengthDef,\n  $ZodCheckMaxSizeDef,\n  $ZodCheckMimeTypeDef,\n  $ZodCheckMinLengthDef,\n  $ZodCheckMinSizeDef,\n  $ZodCheckMultipleOfDef,\n  $ZodCheckNumberFormatDef,\n  $ZodCheckOverwriteDef,\n  $ZodCheckPropertyDef,\n  $ZodCheckRegexDef,\n  $ZodCheckSizeEqualsDef,\n  $ZodCheckStartsWithDef,\n  $ZodCheckStringFormatDef,\n  $ZodCheckUpperCaseDef,\n} from 'zod/v4/core';\n\n/**\n * Type representing a Zod type that has an unwrap method\n */\ntype Unwrappable = { unwrap: () => z.ZodTypeAny };\n\n/**\n * Type guard to check if a Zod field can be unwrapped (has wrapper types like optional, nullable, default).\n *\n * This checks whether a Zod type has an `unwrap()` method, which is present on wrapper types\n * like `ZodOptional`, `ZodNullable`, `ZodDefault`, and others.\n *\n * @param field - The Zod field to check\n * @returns True if the field has an unwrap method, false otherwise\n *\n * @example\n * ```typescript\n * const optionalField = z.string().optional();\n * console.log(canUnwrap(optionalField)); // true\n *\n * const plainField = z.string();\n * console.log(canUnwrap(plainField)); // false\n * ```\n *\n * @since 0.1.0\n */\nexport function canUnwrap(\n  field: z.ZodTypeAny,\n): field is z.ZodTypeAny & Unwrappable {\n  return 'unwrap' in field && typeof field.unwrap === 'function';\n}\n\n/**\n * Unwraps a ZodUnion type and returns the first field and all union options.\n *\n * This function extracts the individual type options from a union type.\n * By default, it filters out `ZodNull` and `ZodUndefined` types, returning only\n * the meaningful type options. You can disable this filtering to get all options.\n *\n * @template T - The Zod type to unwrap\n * @param field - The Zod field (union or single type)\n * @param options - Configuration options\n * @param options.filterNullish - Whether to filter out null and undefined types (default: true)\n * @returns Object with `field` (first option) and `union` (all options array)\n *\n * @example\n * Basic union unwrapping\n * ```typescript\n * const field = z.union([z.string(), z.number()]);\n * const result = unwrapUnion(field);\n * // Result: { field: z.string(), union: [z.string(), z.number()] }\n * ```\n *\n * @example\n * Union with null (filtered by default)\n * ```typescript\n * const field = z.union([z.string(), z.null()]);\n * const result = unwrapUnion(field);\n * // Result: { field: z.string(), union: [z.string()] }\n * ```\n *\n * @example\n * Union with null (keep all options)\n * ```typescript\n * const field = z.union([z.string(), z.null()]);\n * const result = unwrapUnion(field, { filterNullish: false });\n * // Result: { field: z.string(), union: [z.string(), z.null()] }\n * ```\n *\n * @example\n * Non-union type (returns single field)\n * ```typescript\n * const field = z.string();\n * const result = unwrapUnion(field);\n * // Result: { field: z.string(), union: [z.string()] }\n * ```\n *\n * @example\n * Nullable as union\n * ```typescript\n * const field = z.string().nullable(); // This is z.union([z.string(), z.null()])\n * const result = unwrapUnion(field);\n * // Result: { field: z.string(), union: [z.string()] } (null filtered out)\n * ```\n *\n * @example\n * Using the first field for type checking\n * ```typescript\n * const field = z.union([z.string(), z.number()]);\n * const { field: firstField, union } = unwrapUnion(field);\n * if (firstField instanceof z.ZodString) {\n *   console.log('First type is string');\n * }\n * ```\n *\n * @see {@link getPrimitiveType} for unwrapping wrapper types\n * @since 0.1.0\n */\nexport function unwrapUnion<T extends z.ZodTypeAny>(\n  field: T,\n  options: { filterNullish?: boolean } = {},\n): { field: z.ZodTypeAny; union: z.ZodTypeAny[] } {\n  const { filterNullish = true } = options;\n\n  if (field instanceof z.ZodUnion) {\n    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n    const unionOptions = [...field.def.options] as z.ZodTypeAny[];\n\n    const filteredOptions = filterNullish\n      ? unionOptions.filter(\n          (option) =>\n            !(option instanceof z.ZodNull) &&\n            !(option instanceof z.ZodUndefined),\n        )\n      : unionOptions;\n\n    return {\n      field: filteredOptions[0] || field,\n      union: filteredOptions,\n    };\n  }\n\n  // If it's not a union, return the field itself\n  return {\n    field,\n    union: [field],\n  };\n}\n\n/**\n * Gets the underlying primitive type of a Zod field by recursively unwrapping wrapper types.\n *\n * This function removes wrapper layers (optional, nullable, default) to reveal the base type.\n * **Important:** It stops at array types without unwrapping them, treating arrays as primitives.\n *\n * @template T - The Zod type to unwrap\n * @param field - The Zod field to unwrap\n * @returns The unwrapped primitive Zod type\n *\n * @example\n * Unwrapping to string primitive\n * ```typescript\n * const field = z.string().optional().nullable();\n * const primitive = getPrimitiveType(field);\n * // Result: z.string() (unwrapped all wrappers)\n * ```\n *\n * @example\n * Stopping at array type\n * ```typescript\n * const field = z.array(z.string()).optional();\n * const primitive = getPrimitiveType(field);\n * // Result: z.array(z.string()) (stops at array, doesn't unwrap it)\n * ```\n *\n * @example\n * Unwrapping defaults\n * ```typescript\n * const field = z.number().default(0).optional();\n * const primitive = getPrimitiveType(field);\n * // Result: z.number()\n * ```\n *\n * @see {@link canUnwrap} for checking if a field can be unwrapped\n * @since 0.1.0\n */\nexport const getPrimitiveType = <T extends z.ZodType>(\n  field: T,\n): z.ZodTypeAny => {\n  // Stop at arrays - don't unwrap them\n  if (field instanceof z.ZodArray) {\n    return field;\n  }\n\n  if (canUnwrap(field)) {\n    return getPrimitiveType(field.unwrap());\n  }\n\n  if (field instanceof z.ZodUnion) {\n    return getPrimitiveType(unwrapUnion(field).field);\n  }\n\n  return field;\n};\n\ntype StripZodDefault<T> = T extends z.ZodDefault<infer Inner>\n  ? StripZodDefault<Inner>\n  : T extends z.ZodOptional<infer Inner>\n    ? z.ZodOptional<StripZodDefault<Inner>>\n    : T extends z.ZodNullable<infer Inner>\n      ? z.ZodNullable<StripZodDefault<Inner>>\n      : T;\n\n/**\n * Removes default values from a Zod field while preserving other wrapper types.\n *\n * This function recursively removes `ZodDefault` wrappers from a field, while maintaining\n * `optional()` and `nullable()` wrappers. Useful for scenarios where you want to check\n * field requirements without considering default values.\n *\n * @template T - The Zod type to process\n * @param field - The Zod field to remove defaults from\n * @returns The field without defaults but with optional/nullable preserved\n *\n * @example\n * Removing simple default\n * ```typescript\n * const field = z.string().default('hello');\n * const withoutDefault = removeDefault(field);\n * // Result: z.string()\n * ```\n *\n * @example\n * Preserving optional wrapper\n * ```typescript\n * const field = z.string().default('hello').optional();\n * const withoutDefault = removeDefault(field);\n * // Result: z.string().optional()\n * ```\n *\n * @example\n * Nested defaults\n * ```typescript\n * const field = z.string().default('inner').nullable().default('outer');\n * const withoutDefault = removeDefault(field);\n * // Result: z.string().nullable()\n * ```\n *\n * @see {@link requiresValidInput} for usage with requirement checking\n * @since 0.1.0\n */\nexport function removeDefault<T extends z.ZodType>(\n  field: T,\n): StripZodDefault<T> {\n  if (field instanceof z.ZodDefault) {\n    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n    return field.unwrap() as StripZodDefault<T>;\n  }\n\n  if ('innerType' in field.def && field.def.innerType instanceof z.ZodType) {\n    const inner = removeDefault(field.def.innerType);\n    // Reconstruct the wrapper with the modified inner type\n    if (field instanceof z.ZodOptional) {\n      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n      return inner.optional() as unknown as StripZodDefault<T>;\n    }\n    if (field instanceof z.ZodNullable) {\n      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n      return inner.nullable() as unknown as StripZodDefault<T>;\n    }\n  }\n\n  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n  return field as StripZodDefault<T>;\n}\n\n/**\n * Determines if a field will show validation errors when the user submits empty or invalid input.\n *\n * This is useful for form UIs to indicate which fields require valid user input (e.g., showing\n * asterisks, validation states). The key insight: **defaults are just initial values** - they\n * don't prevent validation errors if the user clears the field.\n *\n * **Real-world example:**\n * ```typescript\n * // Marital status field with default but validation rules\n * const maritalStatus = z.string().min(1).default('single');\n *\n * // Initial: field shows \"single\" (from default)\n * // User deletes the value → field is now empty string\n * // User submits form → validation fails because .min(1) rejects empty strings\n * // requiresValidInput(maritalStatus) → true (shows * indicator, validation error)\n * ```\n *\n * **How it works:**\n * 1. Removes `.default()` wrappers (defaults are initial values, not validation rules)\n * 2. Tests if the underlying schema accepts empty/invalid input:\n *    - `undefined` (via `.optional()`)\n *    - `null` (via `.nullable()`)\n *    - Empty string (plain `z.string()` without `.min(1)` or `.nonempty()`)\n *    - Empty array (plain `z.array()` without `.min(1)` or `.nonempty()`)\n * 3. Returns `true` if validation will fail, `false` if empty input is accepted\n *\n * @template T - The Zod type to check\n * @param field - The Zod field to check\n * @returns True if the field will show validation errors on empty/invalid input, false otherwise\n *\n * @example\n * User name field - required, no default\n * ```typescript\n * const userName = z.string().min(1);\n * requiresValidInput(userName); // true - will error if user submits empty\n * ```\n *\n * @example\n * Marital status - required WITH default\n * ```typescript\n * const maritalStatus = z.string().min(1).default('single');\n * requiresValidInput(maritalStatus); // true - will error if user clears and submits\n * ```\n *\n * @example\n * Age with default - requires valid input\n * ```typescript\n * const age = z.number().default(0);\n * requiresValidInput(age); // true - numbers reject empty strings\n * ```\n *\n * @example\n * Optional bio field - doesn't require input\n * ```typescript\n * const bio = z.string().optional();\n * requiresValidInput(bio); // false - user can leave empty\n * ```\n *\n * @example\n * String with default but NO validation - doesn't require input\n * ```typescript\n * const notes = z.string().default('N/A');\n * requiresValidInput(notes); // false - plain z.string() accepts empty strings\n * ```\n *\n * @example\n * Nullable field - doesn't require input\n * ```typescript\n * const middleName = z.string().nullable();\n * requiresValidInput(middleName); // false - user can leave null\n * ```\n *\n * @see {@link removeDefault} for understanding how defaults are handled\n * @see {@link getPrimitiveType} for understanding type unwrapping\n * @since 0.1.0\n */\nexport const requiresValidInput = <T extends z.ZodType>(field: T) => {\n  const defaultRemovedField = removeDefault(field);\n  if (!(defaultRemovedField instanceof z.ZodType)) {\n    return false;\n  }\n\n  const undefinedResult = defaultRemovedField.safeParse(undefined).success;\n\n  // Check if field accepts null (nullable)\n  const nullResult = defaultRemovedField.safeParse(null).success;\n\n  const primitiveType = getPrimitiveType(defaultRemovedField);\n\n  const emptyStringResult =\n    primitiveType.type === 'string' &&\n    defaultRemovedField.safeParse('').success;\n\n  const emptyArrayResult =\n    primitiveType.type === 'array' && defaultRemovedField.safeParse([]).success;\n\n  return (\n    !undefinedResult && !nullResult && !emptyStringResult && !emptyArrayResult\n  );\n};\n\n/**\n * Union type of all Zod check definition types.\n *\n * Includes all validation check types supported by Zod v4:\n * - **Length checks**: `min_length`, `max_length`, `length_equals` (strings, arrays)\n * - **Size checks**: `min_size`, `max_size`, `size_equals` (files, sets, maps)\n * - **Numeric checks**: `greater_than`, `less_than`, `multiple_of`\n * - **Format checks**: `number_format` (int32, float64, etc.), `bigint_format`, `string_format` (email, url, uuid, etc.)\n * - **String pattern checks**: `regex`, `lowercase`, `uppercase`, `includes`, `starts_with`, `ends_with`\n * - **Other checks**: `property`, `mime_type`, `overwrite`\n *\n * @since 0.4.0\n */\nexport type ZodUnionCheck =\n  | $ZodCheckLessThanDef\n  | $ZodCheckGreaterThanDef\n  | $ZodCheckMultipleOfDef\n  | $ZodCheckNumberFormatDef\n  | $ZodCheckBigIntFormatDef\n  | $ZodCheckMaxSizeDef\n  | $ZodCheckMinSizeDef\n  | $ZodCheckSizeEqualsDef\n  | $ZodCheckMaxLengthDef\n  | $ZodCheckMinLengthDef\n  | $ZodCheckLengthEqualsDef\n  | $ZodCheckStringFormatDef\n  | $ZodCheckRegexDef\n  | $ZodCheckLowerCaseDef\n  | $ZodCheckUpperCaseDef\n  | $ZodCheckIncludesDef\n  | $ZodCheckStartsWithDef\n  | $ZodCheckEndsWithDef\n  | $ZodCheckPropertyDef\n  | $ZodCheckMimeTypeDef\n  | $ZodCheckOverwriteDef;\n\n/**\n * Extracts all validation check definitions from a Zod schema field.\n *\n * This function analyzes a Zod field and returns all check definitions as defined\n * by Zod's internal structure. Returns Zod's raw check definition objects directly,\n * including all properties like `check`, `minimum`, `maximum`, `value`, `inclusive`,\n * `format`, `pattern`, etc.\n *\n * **Unwrapping behavior:** Automatically unwraps optional, nullable, and default layers.\n * For unions, checks only the first option (same as other schema utilities).\n *\n * **Supported check types:** Returns any of the 21 check types defined in {@link ZodUnionCheck},\n * including length, size, numeric range, format validation, string patterns, and more.\n *\n * @template T - The Zod type to extract checks from\n * @param field - The Zod field to analyze\n * @returns Array of Zod check definition objects (see {@link ZodUnionCheck})\n *\n * @example\n * String with length constraints\n * ```typescript\n * const username = z.string().min(3).max(20);\n * const checks = getFieldChecks(username);\n * // [\n * //   { check: 'min_length', minimum: 3, when: [Function], ... },\n * //   { check: 'max_length', maximum: 20, when: [Function], ... }\n * // ]\n * ```\n *\n * @example\n * Number with range constraints\n * ```typescript\n * const age = z.number().min(18).max(120);\n * const checks = getFieldChecks(age);\n * // [\n * //   { check: 'greater_than', value: 18, inclusive: true, when: [Function], ... },\n * //   { check: 'less_than', value: 120, inclusive: true, when: [Function], ... }\n * // ]\n * ```\n *\n * @example\n * Array with item count constraints\n * ```typescript\n * const tags = z.array(z.string()).min(1).max(5);\n * const checks = getFieldChecks(tags);\n * // [\n * //   { check: 'min_length', minimum: 1, ... },\n * //   { check: 'max_length', maximum: 5, ... }\n * // ]\n * ```\n *\n * @example\n * String with format validation\n * ```typescript\n * const email = z.string().email();\n * const checks = getFieldChecks(email);\n * // [\n * //   { check: 'string_format', format: 'email', ... }\n * // ]\n * ```\n *\n * @example\n * Unwrapping optional/nullable/default layers\n * ```typescript\n * const bio = z.string().min(10).max(500).optional();\n * const checks = getFieldChecks(bio);\n * // [\n * //   { check: 'min_length', minimum: 10, ... },\n * //   { check: 'max_length', maximum: 500, ... }\n * // ]\n * ```\n *\n * @see {@link ZodUnionCheck} for all supported check types\n * @since 0.4.0\n */\nexport function getFieldChecks<T extends z.ZodTypeAny>(\n  field: T,\n): Array<ZodUnionCheck> {\n  const primitiveType = getPrimitiveType(field);\n  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n  return (primitiveType.def.checks?.map((check) => check._zod.def) ||\n    []) as Array<ZodUnionCheck>;\n}\n","import * as z from 'zod';\nimport { canUnwrap, unwrapUnion } from './schema';\nimport type { Simplify } from './types';\n\n/**\n * Extracts the default value from a Zod field, recursively unwrapping optional, nullable, and union layers.\n *\n * This function traverses through wrapper types (like `ZodOptional`, `ZodNullable`, `ZodUnion`) to find\n * the underlying `ZodDefault` and returns its default value. If no default is found, returns `undefined`.\n *\n * **Union handling:** For union types, extracts the default from the first option. If the first option\n * has no default, returns `undefined` (defaults in other union options are not checked).\n *\n * @template T - The Zod type to extract default from\n * @param field - The Zod field to extract default from\n * @returns The default value if present, undefined otherwise\n *\n * @example\n * Basic usage with default value\n * ```typescript\n * const field = z.string().default('hello');\n * const defaultValue = extractDefault(field);\n * // Result: 'hello'\n * ```\n *\n * @example\n * Unwrapping optional/nullable layers\n * ```typescript\n * const field = z.string().default('world').optional();\n * const defaultValue = extractDefault(field);\n * // Result: 'world' (unwraps optional to find default)\n * ```\n *\n * @example\n * Union with default in first option\n * ```typescript\n * const field = z.union([z.string().default('hello'), z.number()]);\n * const defaultValue = extractDefault(field);\n * // Result: 'hello' (extracts from first union option)\n * ```\n *\n * @example\n * Union with default in second option\n * ```typescript\n * const field = z.union([z.string(), z.number().default(42)]);\n * const defaultValue = extractDefault(field);\n * // Result: undefined (only checks first option)\n * ```\n *\n * @example\n * Field without default\n * ```typescript\n * const field = z.string().optional();\n * const defaultValue = extractDefault(field);\n * // Result: undefined\n * ```\n *\n * @see {@link getSchemaDefaults} for extracting defaults from entire schemas\n * @since 0.1.0\n */\nexport function extractDefault<T extends z.ZodTypeAny>(\n  field: T,\n): z.infer<T> | undefined {\n  if (field instanceof z.ZodDefault) {\n    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n    return field.def.defaultValue as z.infer<T>;\n  }\n\n  if (canUnwrap(field)) {\n    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n    return extractDefault(field.unwrap()) as z.infer<T>;\n  }\n\n  if (field instanceof z.ZodUnion) {\n    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n    return extractDefault(unwrapUnion(field).field) as z.infer<T>;\n  }\n\n  return undefined;\n}\n\n/**\n * Extracts default values from a Zod object schema while skipping fields without defaults.\n *\n * This function recursively traverses the schema and collects all fields that have\n * explicit default values defined. Fields without defaults are excluded from the result.\n *\n * **Important:** Nested defaults are NOT extracted unless the parent object also has\n * an explicit `.default()`. This is by design to match Zod's default value behavior.\n *\n * @template T - The Zod object schema type\n * @param schema - The Zod object schema to extract defaults from\n * @returns A partial object containing only fields with default values\n *\n * @example\n * Basic usage\n * ```typescript\n * const schema = z.object({\n *   name: z.string().default('John'),\n *   age: z.number(), // no default - will be skipped\n *   email: z.string().email().optional(),\n * });\n *\n * const defaults = getSchemaDefaults(schema);\n * // Result: { name: 'John' }\n * ```\n *\n * @example\n * Nested objects with defaults\n * ```typescript\n * const schema = z.object({\n *   user: z.object({\n *     name: z.string().default('Guest')\n *   }).default({ name: 'Guest' }), // ✅ Extracted because parent has .default()\n *\n *   settings: z.object({\n *     theme: z.string().default('light')\n *   }), // ❌ NOT extracted - parent has no .default()\n * });\n *\n * const defaults = getSchemaDefaults(schema);\n * // Result: { user: { name: 'Guest' } }\n * ```\n *\n * @example\n * Unwrapping optional/nullable fields\n * ```typescript\n * const schema = z.object({\n *   title: z.string().default('Untitled').optional(),\n *   count: z.number().default(0).nullable(),\n * });\n *\n * const defaults = getSchemaDefaults(schema);\n * // Result: { title: 'Untitled', count: 0 }\n * ```\n *\n * @see {@link extractDefault} for extracting defaults from individual fields\n * @since 0.1.0\n */\nexport function getSchemaDefaults<T extends z.ZodObject>(\n  schema: T,\n): Simplify<Partial<z.infer<T>>> {\n  const defaults: Record<string, unknown> = {};\n\n  for (const key in schema.shape) {\n    const field = schema.shape[key];\n    if (!field) continue;\n\n    // Check if this field has an explicit default value\n    const defaultValue = extractDefault(field);\n    if (defaultValue !== undefined) {\n      defaults[key] = defaultValue;\n    }\n  }\n\n  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n  return defaults as Partial<z.infer<T>>;\n}\n"]}

package/dist/index.mjs

@@ -4,6 +4,23 @@ import * as z from 'zod';
 function canUnwrap(field) {
   return "unwrap" in field && typeof field.unwrap === "function";
 }
+function unwrapUnion(field, options = {}) {
+  const { filterNullish = true } = options;
+  if (field instanceof z.ZodUnion) {
+    const unionOptions = [...field.def.options];
+    const filteredOptions = filterNullish ? unionOptions.filter(
+      (option) => !(option instanceof z.ZodNull) && !(option instanceof z.ZodUndefined)
+    ) : unionOptions;
+    return {
+      field: filteredOptions[0] || field,
+      union: filteredOptions
+    };
+  }
+  return {
+    field,
+    union: [field]
+  };
+}
 var getPrimitiveType = (field) => {
   if (field instanceof z.ZodArray) {
     return field;
@@ -11,6 +28,9 @@ var getPrimitiveType = (field) => {
   if (canUnwrap(field)) {
     return getPrimitiveType(field.unwrap());
   }
+  if (field instanceof z.ZodUnion) {
+    return getPrimitiveType(unwrapUnion(field).field);
+  }
   return field;
 };
 function removeDefault(field) {
@@ -28,21 +48,23 @@ function removeDefault(field) {
   }
   return field;
 }
-var checkIfFieldIsRequired = (field) => {
-  const undefinedResult = field.safeParse(void 0).success;
-  if (undefinedResult) {
-    return false;
-  }
+var requiresValidInput = (field) => {
   const defaultRemovedField = removeDefault(field);
   if (!(defaultRemovedField instanceof z.ZodType)) {
     return false;
   }
+  const undefinedResult = defaultRemovedField.safeParse(void 0).success;
   const nullResult = defaultRemovedField.safeParse(null).success;
   const primitiveType = getPrimitiveType(defaultRemovedField);
   const emptyStringResult = primitiveType.type === "string" && defaultRemovedField.safeParse("").success;
   const emptyArrayResult = primitiveType.type === "array" && defaultRemovedField.safeParse([]).success;
   return !undefinedResult && !nullResult && !emptyStringResult && !emptyArrayResult;
 };
+function getFieldChecks(field) {
+  var _a;
+  const primitiveType = getPrimitiveType(field);
+  return ((_a = primitiveType.def.checks) == null ? void 0 : _a.map((check) => check._zod.def)) || [];
+}
 
 // src/defaults.ts
 function extractDefault(field) {
@@ -52,6 +74,9 @@ function extractDefault(field) {
   if (canUnwrap(field)) {
     return extractDefault(field.unwrap());
   }
+  if (field instanceof z.ZodUnion) {
+    return extractDefault(unwrapUnion(field).field);
+  }
   return void 0;
 }
 function getSchemaDefaults(schema) {
@@ -67,6 +92,6 @@ function getSchemaDefaults(schema) {
   return defaults;
 }
 
-export { canUnwrap, checkIfFieldIsRequired, extractDefault, getPrimitiveType, getSchemaDefaults, removeDefault };
+export { canUnwrap, extractDefault, getFieldChecks, getPrimitiveType, getSchemaDefaults, removeDefault, requiresValidInput, unwrapUnion };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/schema.ts","../src/defaults.ts"],"names":["z2"],"mappings":";;;AA2BO,SAAS,UACd,KAAA,EACqC;AACrC,EAAA,OAAO,QAAA,IAAY,KAAA,IAAS,OAAO,KAAA,CAAM,MAAA,KAAW,UAAA;AACtD;AAuCO,IAAM,gBAAA,GAAmB,CAC9B,KAAA,KACiB;AAEjB,EAAA,IAAI,iBAAmB,CAAA,CAAA,QAAA,EAAU;AAC/B,IAAA,OAAO,KAAA;AAAA,EACT;AAEA,EAAA,IAAI,SAAA,CAAU,KAAK,CAAA,EAAG;AACpB,IAAA,OAAO,gBAAA,CAAiB,KAAA,CAAM,MAAA,EAAQ,CAAA;AAAA,EACxC;AAEA,EAAA,OAAO,KAAA;AACT;AAgDO,SAAS,cACd,KAAA,EACoB;AACpB,EAAA,IAAI,iBAAmB,CAAA,CAAA,UAAA,EAAY;AAEjC,IAAA,OAAO,MAAM,MAAA,EAAO;AAAA,EACtB;AAEA,EAAA,IAAI,eAAe,KAAA,CAAM,GAAA,IAAO,KAAA,CAAM,GAAA,CAAI,qBAAuB,CAAA,CAAA,OAAA,EAAS;AACxE,IAAA,MAAM,KAAA,GAAQ,aAAA,CAAc,KAAA,CAAM,GAAA,CAAI,SAAS,CAAA;AAE/C,IAAA,IAAI,iBAAmB,CAAA,CAAA,WAAA,EAAa;AAElC,MAAA,OAAO,MAAM,QAAA,EAAS;AAAA,IACxB;AACA,IAAA,IAAI,iBAAmB,CAAA,CAAA,WAAA,EAAa;AAElC,MAAA,OAAO,MAAM,QAAA,EAAS;AAAA,IACxB;AAAA,EACF;AAGA,EAAA,OAAO,KAAA;AACT;AAgEO,IAAM,sBAAA,GAAyB,CAAsB,KAAA,KAAa;AAEvE,EAAA,MAAM,eAAA,GAAkB,KAAA,CAAM,SAAA,CAAU,MAAS,CAAA,CAAE,OAAA;AACnD,EAAA,IAAI,eAAA,EAAiB;AACnB,IAAA,OAAO,KAAA;AAAA,EACT;AAEA,EAAA,MAAM,mBAAA,GAAsB,cAAc,KAAK,CAAA;AAE/C,EAAA,IAAI,EAAE,+BAAiC,CAAA,CAAA,OAAA,CAAA,EAAU;AAC/C,IAAA,OAAO,KAAA;AAAA,EACT;AAGA,EAAA,MAAM,UAAA,GAAa,mBAAA,CAAoB,SAAA,CAAU,IAAI,CAAA,CAAE,OAAA;AAEvD,EAAA,MAAM,aAAA,GAAgB,iBAAiB,mBAAmB,CAAA;AAE1D,EAAA,MAAM,oBACJ,aAAA,CAAc,IAAA,KAAS,YACvB,mBAAA,CAAoB,SAAA,CAAU,EAAE,CAAA,CAAE,OAAA;AAEpC,EAAA,MAAM,gBAAA,GACJ,cAAc,IAAA,KAAS,OAAA,IAAW,oBAAoB,SAAA,CAAU,EAAE,CAAA,CAAE,OAAA;AAEtE,EAAA,OACE,CAAC,eAAA,IAAmB,CAAC,UAAA,IAAc,CAAC,qBAAqB,CAAC,gBAAA;AAE9D;;;AC7MO,SAAS,eACd,KAAA,EACwB;AACxB,EAAA,IAAI,iBAAmBA,CAAA,CAAA,UAAA,EAAY;AAEjC,IAAA,OAAO,MAAM,GAAA,CAAI,YAAA;AAAA,EACnB;AAEA,EAAA,IAAI,SAAA,CAAU,KAAK,CAAA,EAAG;AAEpB,IAAA,OAAO,cAAA,CAAe,KAAA,CAAM,MAAA,EAAQ,CAAA;AAAA,EACtC;AAEA,EAAA,OAAO,MAAA;AACT;AA4DO,SAAS,kBACd,MAAA,EAC+B;AAC/B,EAAA,MAAM,WAAoC,EAAC;AAE3C,EAAA,KAAA,MAAW,GAAA,IAAO,OAAO,KAAA,EAAO;AAC9B,IAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,KAAA,CAAM,GAAG,CAAA;AAC9B,IAAA,IAAI,CAAC,KAAA,EAAO;AAGZ,IAAA,MAAM,YAAA,GAAe,eAAe,KAAK,CAAA;AACzC,IAAA,IAAI,iBAAiB,MAAA,EAAW;AAC9B,MAAA,QAAA,CAAS,GAAG,CAAA,GAAI,YAAA;AAAA,IAClB;AAAA,EACF;AAGA,EAAA,OAAO,QAAA;AACT","file":"index.mjs","sourcesContent":["import * as z from 'zod';\n\n/**\n * Type representing a Zod type that has an unwrap method\n */\ntype Unwrappable = { unwrap: () => z.ZodTypeAny };\n\n/**\n * Type guard to check if a Zod field can be unwrapped (has wrapper types like optional, nullable, default).\n *\n * This checks whether a Zod type has an `unwrap()` method, which is present on wrapper types\n * like `ZodOptional`, `ZodNullable`, `ZodDefault`, and others.\n *\n * @param field - The Zod field to check\n * @returns True if the field has an unwrap method, false otherwise\n *\n * @example\n * ```typescript\n * const optionalField = z.string().optional();\n * console.log(canUnwrap(optionalField)); // true\n *\n * const plainField = z.string();\n * console.log(canUnwrap(plainField)); // false\n * ```\n *\n * @since 0.1.0\n */\nexport function canUnwrap(\n  field: z.ZodTypeAny,\n): field is z.ZodTypeAny & Unwrappable {\n  return 'unwrap' in field && typeof field.unwrap === 'function';\n}\n\n/**\n * Gets the underlying primitive type of a Zod field by recursively unwrapping wrapper types.\n *\n * This function removes wrapper layers (optional, nullable, default) to reveal the base type.\n * **Important:** It stops at array types without unwrapping them, treating arrays as primitives.\n *\n * @template T - The Zod type to unwrap\n * @param field - The Zod field to unwrap\n * @returns The unwrapped primitive Zod type\n *\n * @example\n * Unwrapping to string primitive\n * ```typescript\n * const field = z.string().optional().nullable();\n * const primitive = getPrimitiveType(field);\n * // Result: z.string() (unwrapped all wrappers)\n * ```\n *\n * @example\n * Stopping at array type\n * ```typescript\n * const field = z.array(z.string()).optional();\n * const primitive = getPrimitiveType(field);\n * // Result: z.array(z.string()) (stops at array, doesn't unwrap it)\n * ```\n *\n * @example\n * Unwrapping defaults\n * ```typescript\n * const field = z.number().default(0).optional();\n * const primitive = getPrimitiveType(field);\n * // Result: z.number()\n * ```\n *\n * @see {@link canUnwrap} for checking if a field can be unwrapped\n * @since 0.1.0\n */\nexport const getPrimitiveType = <T extends z.ZodTypeAny>(\n  field: T,\n): z.ZodTypeAny => {\n  // Stop at arrays - don't unwrap them\n  if (field instanceof z.ZodArray) {\n    return field;\n  }\n\n  if (canUnwrap(field)) {\n    return getPrimitiveType(field.unwrap());\n  }\n\n  return field;\n};\n\ntype StripZodDefault<T> = T extends z.ZodDefault<infer Inner>\n  ? StripZodDefault<Inner>\n  : T extends z.ZodOptional<infer Inner>\n    ? z.ZodOptional<StripZodDefault<Inner>>\n    : T extends z.ZodNullable<infer Inner>\n      ? z.ZodNullable<StripZodDefault<Inner>>\n      : T;\n\n/**\n * Removes default values from a Zod field while preserving other wrapper types.\n *\n * This function recursively removes `ZodDefault` wrappers from a field, while maintaining\n * `optional()` and `nullable()` wrappers. Useful for scenarios where you want to check\n * field requirements without considering default values.\n *\n * @template T - The Zod type to process\n * @param field - The Zod field to remove defaults from\n * @returns The field without defaults but with optional/nullable preserved\n *\n * @example\n * Removing simple default\n * ```typescript\n * const field = z.string().default('hello');\n * const withoutDefault = removeDefault(field);\n * // Result: z.string()\n * ```\n *\n * @example\n * Preserving optional wrapper\n * ```typescript\n * const field = z.string().default('hello').optional();\n * const withoutDefault = removeDefault(field);\n * // Result: z.string().optional()\n * ```\n *\n * @example\n * Nested defaults\n * ```typescript\n * const field = z.string().default('inner').nullable().default('outer');\n * const withoutDefault = removeDefault(field);\n * // Result: z.string().nullable()\n * ```\n *\n * @see {@link checkIfFieldIsRequired} for usage with requirement checking\n * @since 0.1.0\n */\nexport function removeDefault<T extends z.ZodType>(\n  field: T,\n): StripZodDefault<T> {\n  if (field instanceof z.ZodDefault) {\n    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n    return field.unwrap() as StripZodDefault<T>;\n  }\n\n  if ('innerType' in field.def && field.def.innerType instanceof z.ZodType) {\n    const inner = removeDefault(field.def.innerType);\n    // Reconstruct the wrapper with the modified inner type\n    if (field instanceof z.ZodOptional) {\n      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n      return inner.optional() as unknown as StripZodDefault<T>;\n    }\n    if (field instanceof z.ZodNullable) {\n      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n      return inner.nullable() as unknown as StripZodDefault<T>;\n    }\n  }\n\n  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n  return field as StripZodDefault<T>;\n}\n\n/**\n * Checks if a Zod field is truly required by testing multiple acceptance criteria.\n *\n * A field is considered **not required** if it accepts any of the following:\n * - `undefined` (via `.optional()` or `.default()`)\n * - `null` (via `.nullable()`)\n * - Empty string (plain `z.string()` without `.min(1)` or `.nonempty()`)\n * - Empty array (plain `z.array()` without `.min(1)` or `.nonempty()`)\n *\n * **Note:** Fields with `.default()` are considered not required since they'll have a value\n * even if the user doesn't provide one.\n *\n * @template T - The Zod type to check\n * @param field - The Zod field to check for required status\n * @returns True if the field is required, false otherwise\n *\n * @example\n * Required field\n * ```typescript\n * const field = z.string().min(1);\n * console.log(checkIfFieldIsRequired(field)); // true\n * ```\n *\n * @example\n * Optional field (not required)\n * ```typescript\n * const field = z.string().optional();\n * console.log(checkIfFieldIsRequired(field)); // false\n * ```\n *\n * @example\n * Field with default (not required)\n * ```typescript\n * const field = z.string().default('hello');\n * console.log(checkIfFieldIsRequired(field)); // false\n * ```\n *\n * @example\n * String without min length (not required - accepts empty string)\n * ```typescript\n * const field = z.string();\n * console.log(checkIfFieldIsRequired(field)); // false\n * ```\n *\n * @example\n * String with nonempty (required)\n * ```typescript\n * const field = z.string().nonempty();\n * console.log(checkIfFieldIsRequired(field)); // true\n * ```\n *\n * @example\n * Nullable field (not required)\n * ```typescript\n * const field = z.number().nullable();\n * console.log(checkIfFieldIsRequired(field)); // false\n * ```\n *\n * @see {@link removeDefault} for understanding how defaults are handled\n * @see {@link getPrimitiveType} for understanding type unwrapping\n * @since 0.1.0\n */\nexport const checkIfFieldIsRequired = <T extends z.ZodType>(field: T) => {\n  // First check the original field for undefined - this catches fields with defaults\n  const undefinedResult = field.safeParse(undefined).success;\n  if (undefinedResult) {\n    return false;\n  }\n\n  const defaultRemovedField = removeDefault(field);\n\n  if (!(defaultRemovedField instanceof z.ZodType)) {\n    return false;\n  }\n\n  // Check if field accepts null (nullable)\n  const nullResult = defaultRemovedField.safeParse(null).success;\n\n  const primitiveType = getPrimitiveType(defaultRemovedField);\n\n  const emptyStringResult =\n    primitiveType.type === 'string' &&\n    defaultRemovedField.safeParse('').success;\n\n  const emptyArrayResult =\n    primitiveType.type === 'array' && defaultRemovedField.safeParse([]).success;\n\n  return (\n    !undefinedResult && !nullResult && !emptyStringResult && !emptyArrayResult\n  );\n};\n","import * as z from 'zod';\nimport { canUnwrap } from './schema';\nimport type { Simplify } from './types';\n\n/**\n * Extracts the default value from a Zod field, recursively unwrapping optional and nullable layers.\n *\n * This function traverses through wrapper types (like `ZodOptional`, `ZodNullable`) to find\n * the underlying `ZodDefault` and returns its default value. If no default is found, returns `undefined`.\n *\n * @template T - The Zod type to extract default from\n * @param field - The Zod field to extract default from\n * @returns The default value if present, undefined otherwise\n *\n * @example\n * Basic usage with default value\n * ```typescript\n * const field = z.string().default('hello');\n * const defaultValue = extractDefault(field);\n * // Result: 'hello'\n * ```\n *\n * @example\n * Unwrapping optional/nullable layers\n * ```typescript\n * const field = z.string().default('world').optional();\n * const defaultValue = extractDefault(field);\n * // Result: 'world' (unwraps optional to find default)\n * ```\n *\n * @example\n * Field without default\n * ```typescript\n * const field = z.string().optional();\n * const defaultValue = extractDefault(field);\n * // Result: undefined\n * ```\n *\n * @see {@link getSchemaDefaults} for extracting defaults from entire schemas\n * @since 0.1.0\n */\nexport function extractDefault<T extends z.ZodTypeAny>(\n  field: T,\n): z.infer<T> | undefined {\n  if (field instanceof z.ZodDefault) {\n    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n    return field.def.defaultValue as z.infer<T>;\n  }\n\n  if (canUnwrap(field)) {\n    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n    return extractDefault(field.unwrap()) as z.infer<T>;\n  }\n\n  return undefined;\n}\n\n/**\n * Extracts default values from a Zod object schema while skipping fields without defaults.\n *\n * This function recursively traverses the schema and collects all fields that have\n * explicit default values defined. Fields without defaults are excluded from the result.\n *\n * **Important:** Nested defaults are NOT extracted unless the parent object also has\n * an explicit `.default()`. This is by design to match Zod's default value behavior.\n *\n * @template T - The Zod object schema type\n * @param schema - The Zod object schema to extract defaults from\n * @returns A partial object containing only fields with default values\n *\n * @example\n * Basic usage\n * ```typescript\n * const schema = z.object({\n *   name: z.string().default('John'),\n *   age: z.number(), // no default - will be skipped\n *   email: z.string().email().optional(),\n * });\n *\n * const defaults = getSchemaDefaults(schema);\n * // Result: { name: 'John' }\n * ```\n *\n * @example\n * Nested objects with defaults\n * ```typescript\n * const schema = z.object({\n *   user: z.object({\n *     name: z.string().default('Guest')\n *   }).default({ name: 'Guest' }), // ✅ Extracted because parent has .default()\n *\n *   settings: z.object({\n *     theme: z.string().default('light')\n *   }), // ❌ NOT extracted - parent has no .default()\n * });\n *\n * const defaults = getSchemaDefaults(schema);\n * // Result: { user: { name: 'Guest' } }\n * ```\n *\n * @example\n * Unwrapping optional/nullable fields\n * ```typescript\n * const schema = z.object({\n *   title: z.string().default('Untitled').optional(),\n *   count: z.number().default(0).nullable(),\n * });\n *\n * const defaults = getSchemaDefaults(schema);\n * // Result: { title: 'Untitled', count: 0 }\n * ```\n *\n * @see {@link extractDefault} for extracting defaults from individual fields\n * @since 0.1.0\n */\nexport function getSchemaDefaults<T extends z.ZodObject>(\n  schema: T,\n): Simplify<Partial<z.infer<T>>> {\n  const defaults: Record<string, unknown> = {};\n\n  for (const key in schema.shape) {\n    const field = schema.shape[key];\n    if (!field) continue;\n\n    // Check if this field has an explicit default value\n    const defaultValue = extractDefault(field);\n    if (defaultValue !== undefined) {\n      defaults[key] = defaultValue;\n    }\n  }\n\n  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n  return defaults as Partial<z.infer<T>>;\n}\n"]}
+{"version":3,"sources":["../src/schema.ts","../src/defaults.ts"],"names":["z2"],"mappings":"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","file":"index.mjs","sourcesContent":["import * as z from 'zod';\nimport type {\n  $ZodCheckBigIntFormatDef,\n  $ZodCheckEndsWithDef,\n  $ZodCheckGreaterThanDef,\n  $ZodCheckIncludesDef,\n  $ZodCheckLengthEqualsDef,\n  $ZodCheckLessThanDef,\n  $ZodCheckLowerCaseDef,\n  $ZodCheckMaxLengthDef,\n  $ZodCheckMaxSizeDef,\n  $ZodCheckMimeTypeDef,\n  $ZodCheckMinLengthDef,\n  $ZodCheckMinSizeDef,\n  $ZodCheckMultipleOfDef,\n  $ZodCheckNumberFormatDef,\n  $ZodCheckOverwriteDef,\n  $ZodCheckPropertyDef,\n  $ZodCheckRegexDef,\n  $ZodCheckSizeEqualsDef,\n  $ZodCheckStartsWithDef,\n  $ZodCheckStringFormatDef,\n  $ZodCheckUpperCaseDef,\n} from 'zod/v4/core';\n\n/**\n * Type representing a Zod type that has an unwrap method\n */\ntype Unwrappable = { unwrap: () => z.ZodTypeAny };\n\n/**\n * Type guard to check if a Zod field can be unwrapped (has wrapper types like optional, nullable, default).\n *\n * This checks whether a Zod type has an `unwrap()` method, which is present on wrapper types\n * like `ZodOptional`, `ZodNullable`, `ZodDefault`, and others.\n *\n * @param field - The Zod field to check\n * @returns True if the field has an unwrap method, false otherwise\n *\n * @example\n * ```typescript\n * const optionalField = z.string().optional();\n * console.log(canUnwrap(optionalField)); // true\n *\n * const plainField = z.string();\n * console.log(canUnwrap(plainField)); // false\n * ```\n *\n * @since 0.1.0\n */\nexport function canUnwrap(\n  field: z.ZodTypeAny,\n): field is z.ZodTypeAny & Unwrappable {\n  return 'unwrap' in field && typeof field.unwrap === 'function';\n}\n\n/**\n * Unwraps a ZodUnion type and returns the first field and all union options.\n *\n * This function extracts the individual type options from a union type.\n * By default, it filters out `ZodNull` and `ZodUndefined` types, returning only\n * the meaningful type options. You can disable this filtering to get all options.\n *\n * @template T - The Zod type to unwrap\n * @param field - The Zod field (union or single type)\n * @param options - Configuration options\n * @param options.filterNullish - Whether to filter out null and undefined types (default: true)\n * @returns Object with `field` (first option) and `union` (all options array)\n *\n * @example\n * Basic union unwrapping\n * ```typescript\n * const field = z.union([z.string(), z.number()]);\n * const result = unwrapUnion(field);\n * // Result: { field: z.string(), union: [z.string(), z.number()] }\n * ```\n *\n * @example\n * Union with null (filtered by default)\n * ```typescript\n * const field = z.union([z.string(), z.null()]);\n * const result = unwrapUnion(field);\n * // Result: { field: z.string(), union: [z.string()] }\n * ```\n *\n * @example\n * Union with null (keep all options)\n * ```typescript\n * const field = z.union([z.string(), z.null()]);\n * const result = unwrapUnion(field, { filterNullish: false });\n * // Result: { field: z.string(), union: [z.string(), z.null()] }\n * ```\n *\n * @example\n * Non-union type (returns single field)\n * ```typescript\n * const field = z.string();\n * const result = unwrapUnion(field);\n * // Result: { field: z.string(), union: [z.string()] }\n * ```\n *\n * @example\n * Nullable as union\n * ```typescript\n * const field = z.string().nullable(); // This is z.union([z.string(), z.null()])\n * const result = unwrapUnion(field);\n * // Result: { field: z.string(), union: [z.string()] } (null filtered out)\n * ```\n *\n * @example\n * Using the first field for type checking\n * ```typescript\n * const field = z.union([z.string(), z.number()]);\n * const { field: firstField, union } = unwrapUnion(field);\n * if (firstField instanceof z.ZodString) {\n *   console.log('First type is string');\n * }\n * ```\n *\n * @see {@link getPrimitiveType} for unwrapping wrapper types\n * @since 0.1.0\n */\nexport function unwrapUnion<T extends z.ZodTypeAny>(\n  field: T,\n  options: { filterNullish?: boolean } = {},\n): { field: z.ZodTypeAny; union: z.ZodTypeAny[] } {\n  const { filterNullish = true } = options;\n\n  if (field instanceof z.ZodUnion) {\n    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n    const unionOptions = [...field.def.options] as z.ZodTypeAny[];\n\n    const filteredOptions = filterNullish\n      ? unionOptions.filter(\n          (option) =>\n            !(option instanceof z.ZodNull) &&\n            !(option instanceof z.ZodUndefined),\n        )\n      : unionOptions;\n\n    return {\n      field: filteredOptions[0] || field,\n      union: filteredOptions,\n    };\n  }\n\n  // If it's not a union, return the field itself\n  return {\n    field,\n    union: [field],\n  };\n}\n\n/**\n * Gets the underlying primitive type of a Zod field by recursively unwrapping wrapper types.\n *\n * This function removes wrapper layers (optional, nullable, default) to reveal the base type.\n * **Important:** It stops at array types without unwrapping them, treating arrays as primitives.\n *\n * @template T - The Zod type to unwrap\n * @param field - The Zod field to unwrap\n * @returns The unwrapped primitive Zod type\n *\n * @example\n * Unwrapping to string primitive\n * ```typescript\n * const field = z.string().optional().nullable();\n * const primitive = getPrimitiveType(field);\n * // Result: z.string() (unwrapped all wrappers)\n * ```\n *\n * @example\n * Stopping at array type\n * ```typescript\n * const field = z.array(z.string()).optional();\n * const primitive = getPrimitiveType(field);\n * // Result: z.array(z.string()) (stops at array, doesn't unwrap it)\n * ```\n *\n * @example\n * Unwrapping defaults\n * ```typescript\n * const field = z.number().default(0).optional();\n * const primitive = getPrimitiveType(field);\n * // Result: z.number()\n * ```\n *\n * @see {@link canUnwrap} for checking if a field can be unwrapped\n * @since 0.1.0\n */\nexport const getPrimitiveType = <T extends z.ZodType>(\n  field: T,\n): z.ZodTypeAny => {\n  // Stop at arrays - don't unwrap them\n  if (field instanceof z.ZodArray) {\n    return field;\n  }\n\n  if (canUnwrap(field)) {\n    return getPrimitiveType(field.unwrap());\n  }\n\n  if (field instanceof z.ZodUnion) {\n    return getPrimitiveType(unwrapUnion(field).field);\n  }\n\n  return field;\n};\n\ntype StripZodDefault<T> = T extends z.ZodDefault<infer Inner>\n  ? StripZodDefault<Inner>\n  : T extends z.ZodOptional<infer Inner>\n    ? z.ZodOptional<StripZodDefault<Inner>>\n    : T extends z.ZodNullable<infer Inner>\n      ? z.ZodNullable<StripZodDefault<Inner>>\n      : T;\n\n/**\n * Removes default values from a Zod field while preserving other wrapper types.\n *\n * This function recursively removes `ZodDefault` wrappers from a field, while maintaining\n * `optional()` and `nullable()` wrappers. Useful for scenarios where you want to check\n * field requirements without considering default values.\n *\n * @template T - The Zod type to process\n * @param field - The Zod field to remove defaults from\n * @returns The field without defaults but with optional/nullable preserved\n *\n * @example\n * Removing simple default\n * ```typescript\n * const field = z.string().default('hello');\n * const withoutDefault = removeDefault(field);\n * // Result: z.string()\n * ```\n *\n * @example\n * Preserving optional wrapper\n * ```typescript\n * const field = z.string().default('hello').optional();\n * const withoutDefault = removeDefault(field);\n * // Result: z.string().optional()\n * ```\n *\n * @example\n * Nested defaults\n * ```typescript\n * const field = z.string().default('inner').nullable().default('outer');\n * const withoutDefault = removeDefault(field);\n * // Result: z.string().nullable()\n * ```\n *\n * @see {@link requiresValidInput} for usage with requirement checking\n * @since 0.1.0\n */\nexport function removeDefault<T extends z.ZodType>(\n  field: T,\n): StripZodDefault<T> {\n  if (field instanceof z.ZodDefault) {\n    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n    return field.unwrap() as StripZodDefault<T>;\n  }\n\n  if ('innerType' in field.def && field.def.innerType instanceof z.ZodType) {\n    const inner = removeDefault(field.def.innerType);\n    // Reconstruct the wrapper with the modified inner type\n    if (field instanceof z.ZodOptional) {\n      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n      return inner.optional() as unknown as StripZodDefault<T>;\n    }\n    if (field instanceof z.ZodNullable) {\n      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n      return inner.nullable() as unknown as StripZodDefault<T>;\n    }\n  }\n\n  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n  return field as StripZodDefault<T>;\n}\n\n/**\n * Determines if a field will show validation errors when the user submits empty or invalid input.\n *\n * This is useful for form UIs to indicate which fields require valid user input (e.g., showing\n * asterisks, validation states). The key insight: **defaults are just initial values** - they\n * don't prevent validation errors if the user clears the field.\n *\n * **Real-world example:**\n * ```typescript\n * // Marital status field with default but validation rules\n * const maritalStatus = z.string().min(1).default('single');\n *\n * // Initial: field shows \"single\" (from default)\n * // User deletes the value → field is now empty string\n * // User submits form → validation fails because .min(1) rejects empty strings\n * // requiresValidInput(maritalStatus) → true (shows * indicator, validation error)\n * ```\n *\n * **How it works:**\n * 1. Removes `.default()` wrappers (defaults are initial values, not validation rules)\n * 2. Tests if the underlying schema accepts empty/invalid input:\n *    - `undefined` (via `.optional()`)\n *    - `null` (via `.nullable()`)\n *    - Empty string (plain `z.string()` without `.min(1)` or `.nonempty()`)\n *    - Empty array (plain `z.array()` without `.min(1)` or `.nonempty()`)\n * 3. Returns `true` if validation will fail, `false` if empty input is accepted\n *\n * @template T - The Zod type to check\n * @param field - The Zod field to check\n * @returns True if the field will show validation errors on empty/invalid input, false otherwise\n *\n * @example\n * User name field - required, no default\n * ```typescript\n * const userName = z.string().min(1);\n * requiresValidInput(userName); // true - will error if user submits empty\n * ```\n *\n * @example\n * Marital status - required WITH default\n * ```typescript\n * const maritalStatus = z.string().min(1).default('single');\n * requiresValidInput(maritalStatus); // true - will error if user clears and submits\n * ```\n *\n * @example\n * Age with default - requires valid input\n * ```typescript\n * const age = z.number().default(0);\n * requiresValidInput(age); // true - numbers reject empty strings\n * ```\n *\n * @example\n * Optional bio field - doesn't require input\n * ```typescript\n * const bio = z.string().optional();\n * requiresValidInput(bio); // false - user can leave empty\n * ```\n *\n * @example\n * String with default but NO validation - doesn't require input\n * ```typescript\n * const notes = z.string().default('N/A');\n * requiresValidInput(notes); // false - plain z.string() accepts empty strings\n * ```\n *\n * @example\n * Nullable field - doesn't require input\n * ```typescript\n * const middleName = z.string().nullable();\n * requiresValidInput(middleName); // false - user can leave null\n * ```\n *\n * @see {@link removeDefault} for understanding how defaults are handled\n * @see {@link getPrimitiveType} for understanding type unwrapping\n * @since 0.1.0\n */\nexport const requiresValidInput = <T extends z.ZodType>(field: T) => {\n  const defaultRemovedField = removeDefault(field);\n  if (!(defaultRemovedField instanceof z.ZodType)) {\n    return false;\n  }\n\n  const undefinedResult = defaultRemovedField.safeParse(undefined).success;\n\n  // Check if field accepts null (nullable)\n  const nullResult = defaultRemovedField.safeParse(null).success;\n\n  const primitiveType = getPrimitiveType(defaultRemovedField);\n\n  const emptyStringResult =\n    primitiveType.type === 'string' &&\n    defaultRemovedField.safeParse('').success;\n\n  const emptyArrayResult =\n    primitiveType.type === 'array' && defaultRemovedField.safeParse([]).success;\n\n  return (\n    !undefinedResult && !nullResult && !emptyStringResult && !emptyArrayResult\n  );\n};\n\n/**\n * Union type of all Zod check definition types.\n *\n * Includes all validation check types supported by Zod v4:\n * - **Length checks**: `min_length`, `max_length`, `length_equals` (strings, arrays)\n * - **Size checks**: `min_size`, `max_size`, `size_equals` (files, sets, maps)\n * - **Numeric checks**: `greater_than`, `less_than`, `multiple_of`\n * - **Format checks**: `number_format` (int32, float64, etc.), `bigint_format`, `string_format` (email, url, uuid, etc.)\n * - **String pattern checks**: `regex`, `lowercase`, `uppercase`, `includes`, `starts_with`, `ends_with`\n * - **Other checks**: `property`, `mime_type`, `overwrite`\n *\n * @since 0.4.0\n */\nexport type ZodUnionCheck =\n  | $ZodCheckLessThanDef\n  | $ZodCheckGreaterThanDef\n  | $ZodCheckMultipleOfDef\n  | $ZodCheckNumberFormatDef\n  | $ZodCheckBigIntFormatDef\n  | $ZodCheckMaxSizeDef\n  | $ZodCheckMinSizeDef\n  | $ZodCheckSizeEqualsDef\n  | $ZodCheckMaxLengthDef\n  | $ZodCheckMinLengthDef\n  | $ZodCheckLengthEqualsDef\n  | $ZodCheckStringFormatDef\n  | $ZodCheckRegexDef\n  | $ZodCheckLowerCaseDef\n  | $ZodCheckUpperCaseDef\n  | $ZodCheckIncludesDef\n  | $ZodCheckStartsWithDef\n  | $ZodCheckEndsWithDef\n  | $ZodCheckPropertyDef\n  | $ZodCheckMimeTypeDef\n  | $ZodCheckOverwriteDef;\n\n/**\n * Extracts all validation check definitions from a Zod schema field.\n *\n * This function analyzes a Zod field and returns all check definitions as defined\n * by Zod's internal structure. Returns Zod's raw check definition objects directly,\n * including all properties like `check`, `minimum`, `maximum`, `value`, `inclusive`,\n * `format`, `pattern`, etc.\n *\n * **Unwrapping behavior:** Automatically unwraps optional, nullable, and default layers.\n * For unions, checks only the first option (same as other schema utilities).\n *\n * **Supported check types:** Returns any of the 21 check types defined in {@link ZodUnionCheck},\n * including length, size, numeric range, format validation, string patterns, and more.\n *\n * @template T - The Zod type to extract checks from\n * @param field - The Zod field to analyze\n * @returns Array of Zod check definition objects (see {@link ZodUnionCheck})\n *\n * @example\n * String with length constraints\n * ```typescript\n * const username = z.string().min(3).max(20);\n * const checks = getFieldChecks(username);\n * // [\n * //   { check: 'min_length', minimum: 3, when: [Function], ... },\n * //   { check: 'max_length', maximum: 20, when: [Function], ... }\n * // ]\n * ```\n *\n * @example\n * Number with range constraints\n * ```typescript\n * const age = z.number().min(18).max(120);\n * const checks = getFieldChecks(age);\n * // [\n * //   { check: 'greater_than', value: 18, inclusive: true, when: [Function], ... },\n * //   { check: 'less_than', value: 120, inclusive: true, when: [Function], ... }\n * // ]\n * ```\n *\n * @example\n * Array with item count constraints\n * ```typescript\n * const tags = z.array(z.string()).min(1).max(5);\n * const checks = getFieldChecks(tags);\n * // [\n * //   { check: 'min_length', minimum: 1, ... },\n * //   { check: 'max_length', maximum: 5, ... }\n * // ]\n * ```\n *\n * @example\n * String with format validation\n * ```typescript\n * const email = z.string().email();\n * const checks = getFieldChecks(email);\n * // [\n * //   { check: 'string_format', format: 'email', ... }\n * // ]\n * ```\n *\n * @example\n * Unwrapping optional/nullable/default layers\n * ```typescript\n * const bio = z.string().min(10).max(500).optional();\n * const checks = getFieldChecks(bio);\n * // [\n * //   { check: 'min_length', minimum: 10, ... },\n * //   { check: 'max_length', maximum: 500, ... }\n * // ]\n * ```\n *\n * @see {@link ZodUnionCheck} for all supported check types\n * @since 0.4.0\n */\nexport function getFieldChecks<T extends z.ZodTypeAny>(\n  field: T,\n): Array<ZodUnionCheck> {\n  const primitiveType = getPrimitiveType(field);\n  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n  return (primitiveType.def.checks?.map((check) => check._zod.def) ||\n    []) as Array<ZodUnionCheck>;\n}\n","import * as z from 'zod';\nimport { canUnwrap, unwrapUnion } from './schema';\nimport type { Simplify } from './types';\n\n/**\n * Extracts the default value from a Zod field, recursively unwrapping optional, nullable, and union layers.\n *\n * This function traverses through wrapper types (like `ZodOptional`, `ZodNullable`, `ZodUnion`) to find\n * the underlying `ZodDefault` and returns its default value. If no default is found, returns `undefined`.\n *\n * **Union handling:** For union types, extracts the default from the first option. If the first option\n * has no default, returns `undefined` (defaults in other union options are not checked).\n *\n * @template T - The Zod type to extract default from\n * @param field - The Zod field to extract default from\n * @returns The default value if present, undefined otherwise\n *\n * @example\n * Basic usage with default value\n * ```typescript\n * const field = z.string().default('hello');\n * const defaultValue = extractDefault(field);\n * // Result: 'hello'\n * ```\n *\n * @example\n * Unwrapping optional/nullable layers\n * ```typescript\n * const field = z.string().default('world').optional();\n * const defaultValue = extractDefault(field);\n * // Result: 'world' (unwraps optional to find default)\n * ```\n *\n * @example\n * Union with default in first option\n * ```typescript\n * const field = z.union([z.string().default('hello'), z.number()]);\n * const defaultValue = extractDefault(field);\n * // Result: 'hello' (extracts from first union option)\n * ```\n *\n * @example\n * Union with default in second option\n * ```typescript\n * const field = z.union([z.string(), z.number().default(42)]);\n * const defaultValue = extractDefault(field);\n * // Result: undefined (only checks first option)\n * ```\n *\n * @example\n * Field without default\n * ```typescript\n * const field = z.string().optional();\n * const defaultValue = extractDefault(field);\n * // Result: undefined\n * ```\n *\n * @see {@link getSchemaDefaults} for extracting defaults from entire schemas\n * @since 0.1.0\n */\nexport function extractDefault<T extends z.ZodTypeAny>(\n  field: T,\n): z.infer<T> | undefined {\n  if (field instanceof z.ZodDefault) {\n    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n    return field.def.defaultValue as z.infer<T>;\n  }\n\n  if (canUnwrap(field)) {\n    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n    return extractDefault(field.unwrap()) as z.infer<T>;\n  }\n\n  if (field instanceof z.ZodUnion) {\n    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n    return extractDefault(unwrapUnion(field).field) as z.infer<T>;\n  }\n\n  return undefined;\n}\n\n/**\n * Extracts default values from a Zod object schema while skipping fields without defaults.\n *\n * This function recursively traverses the schema and collects all fields that have\n * explicit default values defined. Fields without defaults are excluded from the result.\n *\n * **Important:** Nested defaults are NOT extracted unless the parent object also has\n * an explicit `.default()`. This is by design to match Zod's default value behavior.\n *\n * @template T - The Zod object schema type\n * @param schema - The Zod object schema to extract defaults from\n * @returns A partial object containing only fields with default values\n *\n * @example\n * Basic usage\n * ```typescript\n * const schema = z.object({\n *   name: z.string().default('John'),\n *   age: z.number(), // no default - will be skipped\n *   email: z.string().email().optional(),\n * });\n *\n * const defaults = getSchemaDefaults(schema);\n * // Result: { name: 'John' }\n * ```\n *\n * @example\n * Nested objects with defaults\n * ```typescript\n * const schema = z.object({\n *   user: z.object({\n *     name: z.string().default('Guest')\n *   }).default({ name: 'Guest' }), // ✅ Extracted because parent has .default()\n *\n *   settings: z.object({\n *     theme: z.string().default('light')\n *   }), // ❌ NOT extracted - parent has no .default()\n * });\n *\n * const defaults = getSchemaDefaults(schema);\n * // Result: { user: { name: 'Guest' } }\n * ```\n *\n * @example\n * Unwrapping optional/nullable fields\n * ```typescript\n * const schema = z.object({\n *   title: z.string().default('Untitled').optional(),\n *   count: z.number().default(0).nullable(),\n * });\n *\n * const defaults = getSchemaDefaults(schema);\n * // Result: { title: 'Untitled', count: 0 }\n * ```\n *\n * @see {@link extractDefault} for extracting defaults from individual fields\n * @since 0.1.0\n */\nexport function getSchemaDefaults<T extends z.ZodObject>(\n  schema: T,\n): Simplify<Partial<z.infer<T>>> {\n  const defaults: Record<string, unknown> = {};\n\n  for (const key in schema.shape) {\n    const field = schema.shape[key];\n    if (!field) continue;\n\n    // Check if this field has an explicit default value\n    const defaultValue = extractDefault(field);\n    if (defaultValue !== undefined) {\n      defaults[key] = defaultValue;\n    }\n  }\n\n  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n  return defaults as Partial<z.infer<T>>;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zod-utils/core",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "Pure TypeScript utilities for Zod schema manipulation and default extraction",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -28,6 +28,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
+    "bench": "vitest bench --run",
+    "bench:watch": "vitest bench",
     "prepublishOnly": "npm run build"
   },
   "keywords": [