@zod-utils/core 0.1.0 → 0.4.0

package/dist/index.d.mts

@@ -1,79 +1,401 @@
 import * as z from 'zod';
 
 /**
- * Get the primitive type of a Zod field by unwrapping optional/nullable wrappers
- * @param field - The Zod field to unwrap
- * @param options - Options for unwrapping
- * @param options.unwrapArrays - If true, continues unwrapping arrays. If false (default), stops at arrays
- * @returns The unwrapped primitive type
- */
-declare const getPrimitiveType: <T extends z.ZodTypeAny>(field: T, options?: {
-    unwrapArrays?: boolean;
-}) => z.ZodTypeAny;
-/**
- * Remove default values from a Zod field
- * @param field - The Zod field to remove defaults from
- * @returns The field without defaults
- */
-declare function removeDefault(field: z.ZodType): z.ZodType;
-/**
- * Check if a Zod field is required (not optional/nullable and doesn't accept empty values)
- * @param field - The Zod field to check
- * @returns True if the field is required
+ * Simplifies complex TypeScript types for better IDE hover tooltips and error messages.
+ *
+ * This utility type flattens intersections and complex type expressions into a single,
+ * readable object type. This is especially useful when working with mapped types,
+ * conditional types, or type intersections that produce hard-to-read IDE hints.
+ *
+ * @template T - The type to simplify
+ *
+ * @example
+ * Simplifying intersection types
+ * ```typescript
+ * type A = { name: string };
+ * type B = { age: number };
+ * type C = A & B; // Shows as "A & B" in IDE
+ * type D = Simplify<A & B>; // Shows as "{ name: string; age: number }" in IDE
+ * ```
+ *
+ * @example
+ * Simplifying Partial<> results
+ * ```typescript
+ * type User = { name: string; age: number; email: string };
+ * type PartialUser = Partial<User>; // Shows as "Partial<User>" in IDE
+ * type SimplifiedPartialUser = Simplify<Partial<User>>;
+ * // Shows as "{ name?: string; age?: number; email?: string }" in IDE
+ * ```
+ *
+ * @example
+ * Usage with zod schema inference
+ * ```typescript
+ * const schema = z.object({ id: z.string() })
+ *   .merge(z.object({ name: z.string() }));
+ *
+ * type InferredType = z.infer<typeof schema>; // May show complex type
+ * type SimplifiedType = Simplify<z.infer<typeof schema>>;
+ * // Shows clear: { id: string; name: string }
+ * ```
+ *
+ * @since 0.1.0
  */
-declare const checkIfFieldIsRequired: <T extends z.ZodTypeAny>(field: T) => boolean;
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
 
 /**
- * Extract the default value from a Zod field (recursively unwraps optional/nullable)
+ * Extracts the default value from a Zod field, recursively unwrapping optional and nullable layers.
+ *
+ * This function traverses through wrapper types (like `ZodOptional`, `ZodNullable`) to find
+ * the underlying `ZodDefault` and returns its default value. If no default is found, returns `undefined`.
+ *
+ * @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
+ *
+ * @example
+ * Basic usage with default value
+ * ```typescript
+ * const field = z.string().default('hello');
+ * const defaultValue = extractDefault(field);
+ * // Result: 'hello'
+ * ```
+ *
+ * @example
+ * Unwrapping optional/nullable layers
+ * ```typescript
+ * const field = z.string().default('world').optional();
+ * const defaultValue = extractDefault(field);
+ * // Result: 'world' (unwraps optional to find default)
+ * ```
+ *
+ * @example
+ * Field without default
+ * ```typescript
+ * const field = z.string().optional();
+ * const defaultValue = extractDefault(field);
+ * // Result: undefined
+ * ```
+ *
+ * @see {@link getSchemaDefaults} for extracting defaults from entire schemas
+ * @since 0.1.0
  */
-declare function extractDefault(field: z.ZodTypeAny): any;
-/**
- * Get the unwrapped type without going through defaults
- * Useful for detecting nested objects/arrays while preserving defaults
- * @param field - The Zod field to unwrap
- * @returns The unwrapped type
- */
-declare function getUnwrappedType(field: z.ZodTypeAny): z.ZodTypeAny;
+declare function extractDefault<T extends z.ZodTypeAny>(field: T): z.infer<T> | undefined;
 /**
- * Extract all default values from a Zod object schema
- * Recursively handles nested objects and only returns fields with defaults
+ * Extracts default values from a Zod object schema while skipping fields without defaults.
+ *
+ * This function recursively traverses the schema and collects all fields that have
+ * explicit default values defined. Fields without defaults are excluded from the result.
+ *
+ * **Important:** Nested defaults are NOT extracted unless the parent object also has
+ * an explicit `.default()`. This is by design to match Zod's default value behavior.
+ *
+ * @template T - The Zod object schema type
  * @param schema - The Zod object schema to extract defaults from
- * @returns Partial object with only fields that have defaults
+ * @returns A partial object containing only fields with default values
  *
  * @example
- * ```ts
+ * Basic usage
+ * ```typescript
  * const schema = z.object({
  *   name: z.string().default('John'),
- *   age: z.number(), // no default - skipped
+ *   age: z.number(), // no default - will be skipped
+ *   email: z.string().email().optional(),
+ * });
+ *
+ * const defaults = getSchemaDefaults(schema);
+ * // Result: { name: 'John' }
+ * ```
+ *
+ * @example
+ * Nested objects with defaults
+ * ```typescript
+ * const schema = z.object({
+ *   user: z.object({
+ *     name: z.string().default('Guest')
+ *   }).default({ name: 'Guest' }), // ✅ Extracted because parent has .default()
+ *
  *   settings: z.object({
  *     theme: z.string().default('light')
- *   })
+ *   }), // ❌ NOT extracted - parent has no .default()
  * });
  *
- * getSchemaDefaults(schema);
- * // Returns: { name: 'John', settings: { theme: 'light' } }
+ * const defaults = getSchemaDefaults(schema);
+ * // Result: { user: { name: 'Guest' } }
  * ```
+ *
+ * @example
+ * Unwrapping optional/nullable fields
+ * ```typescript
+ * const schema = z.object({
+ *   title: z.string().default('Untitled').optional(),
+ *   count: z.number().default(0).nullable(),
+ * });
+ *
+ * const defaults = getSchemaDefaults(schema);
+ * // Result: { title: 'Untitled', count: 0 }
+ * ```
+ *
+ * @see {@link extractDefault} for extracting defaults from individual fields
+ * @since 0.1.0
  */
-declare function getSchemaDefaults<T extends z.ZodObject<any>>(schema: T): Partial<z.infer<T>>;
+declare function getSchemaDefaults<T extends z.ZodObject>(schema: T): Simplify<Partial<z.infer<T>>>;
 
 /**
- * Extract the element type from an array or undefined
+ * Type representing a Zod type that has an unwrap method
  */
-type PickArrayObject<TArray extends unknown[] | undefined> = NonNullable<TArray>[number];
+type Unwrappable = {
+    unwrap: () => z.ZodTypeAny;
+};
 /**
- * Simplify complex types for better IDE hints
+ * Type guard to check if a Zod field can be unwrapped (has wrapper types like optional, nullable, default).
+ *
+ * This checks whether a Zod type has an `unwrap()` method, which is present on wrapper types
+ * like `ZodOptional`, `ZodNullable`, `ZodDefault`, and others.
+ *
+ * @param field - The Zod field to check
+ * @returns True if the field has an unwrap method, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const optionalField = z.string().optional();
+ * console.log(canUnwrap(optionalField)); // true
+ *
+ * const plainField = z.string();
+ * console.log(canUnwrap(plainField)); // false
+ * ```
+ *
+ * @since 0.1.0
  */
-type Simplify<T> = {
-    [K in keyof T]: T[K];
-} & {};
+declare function canUnwrap(field: z.ZodTypeAny): field is z.ZodTypeAny & Unwrappable;
 /**
- * Make all properties optional and nullable
- * Useful for form input types where fields can be empty
+ * 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
  */
-type MakeOptionalAndNullable<T> = {
-    [K in keyof T]?: T[K] | null;
+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.
+ *
+ * This function removes wrapper layers (optional, nullable, default) to reveal the base type.
+ * **Important:** It stops at array types without unwrapping them, treating arrays as primitives.
+ *
+ * @template T - The Zod type to unwrap
+ * @param field - The Zod field to unwrap
+ * @returns The unwrapped primitive Zod type
+ *
+ * @example
+ * Unwrapping to string primitive
+ * ```typescript
+ * const field = z.string().optional().nullable();
+ * const primitive = getPrimitiveType(field);
+ * // Result: z.string() (unwrapped all wrappers)
+ * ```
+ *
+ * @example
+ * Stopping at array type
+ * ```typescript
+ * const field = z.array(z.string()).optional();
+ * const primitive = getPrimitiveType(field);
+ * // Result: z.array(z.string()) (stops at array, doesn't unwrap it)
+ * ```
+ *
+ * @example
+ * Unwrapping defaults
+ * ```typescript
+ * const field = z.number().default(0).optional();
+ * const primitive = getPrimitiveType(field);
+ * // Result: z.number()
+ * ```
+ *
+ * @see {@link canUnwrap} for checking if a field can be unwrapped
+ * @since 0.1.0
+ */
+declare const getPrimitiveType: <T extends z.ZodType>(field: T) => z.ZodTypeAny;
+type StripZodDefault<T> = T extends z.ZodDefault<infer Inner> ? StripZodDefault<Inner> : T extends z.ZodOptional<infer Inner> ? z.ZodOptional<StripZodDefault<Inner>> : T extends z.ZodNullable<infer Inner> ? z.ZodNullable<StripZodDefault<Inner>> : T;
+/**
+ * Removes default values from a Zod field while preserving other wrapper types.
+ *
+ * This function recursively removes `ZodDefault` wrappers from a field, while maintaining
+ * `optional()` and `nullable()` wrappers. Useful for scenarios where you want to check
+ * field requirements without considering default values.
+ *
+ * @template T - The Zod type to process
+ * @param field - The Zod field to remove defaults from
+ * @returns The field without defaults but with optional/nullable preserved
+ *
+ * @example
+ * Removing simple default
+ * ```typescript
+ * const field = z.string().default('hello');
+ * const withoutDefault = removeDefault(field);
+ * // Result: z.string()
+ * ```
+ *
+ * @example
+ * Preserving optional wrapper
+ * ```typescript
+ * const field = z.string().default('hello').optional();
+ * const withoutDefault = removeDefault(field);
+ * // Result: z.string().optional()
+ * ```
+ *
+ * @example
+ * Nested defaults
+ * ```typescript
+ * const field = z.string().default('inner').nullable().default('outer');
+ * const withoutDefault = removeDefault(field);
+ * // Result: z.string().nullable()
+ * ```
+ *
+ * @see {@link requiresValidInput} for usage with requirement checking
+ * @since 0.1.0
+ */
+declare function removeDefault<T extends z.ZodType>(field: T): StripZodDefault<T>;
+/**
+ * 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.
+ *
+ * **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)
+ * ```
+ *
+ * **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
+ * @returns True if the field will show validation errors on empty/invalid input, false otherwise
+ *
+ * @example
+ * User name field - required, no default
+ * ```typescript
+ * const userName = z.string().min(1);
+ * requiresValidInput(userName); // true - will error if user submits empty
+ * ```
+ *
+ * @example
+ * Marital status - required WITH default
+ * ```typescript
+ * const maritalStatus = z.string().min(1).default('single');
+ * requiresValidInput(maritalStatus); // true - will error if user clears and submits
+ * ```
+ *
+ * @example
+ * Age with default - requires valid input
+ * ```typescript
+ * const age = z.number().default(0);
+ * requiresValidInput(age); // true - numbers reject empty strings
+ * ```
+ *
+ * @example
+ * Optional bio field - doesn't require input
+ * ```typescript
+ * const bio = z.string().optional();
+ * requiresValidInput(bio); // false - user can leave empty
+ * ```
+ *
+ * @example
+ * String with default but NO validation - doesn't require input
+ * ```typescript
+ * const notes = z.string().default('N/A');
+ * requiresValidInput(notes); // false - plain z.string() accepts empty strings
+ * ```
+ *
+ * @example
+ * Nullable field - doesn't require input
+ * ```typescript
+ * 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 requiresValidInput: <T extends z.ZodType>(field: T) => boolean;
 
-export { type MakeOptionalAndNullable, type PickArrayObject, type Simplify, checkIfFieldIsRequired, extractDefault, getPrimitiveType, getSchemaDefaults, getUnwrappedType, removeDefault };
+export { type Simplify, canUnwrap, extractDefault, getPrimitiveType, getSchemaDefaults, removeDefault, requiresValidInput, unwrapUnion };