@zod-utils/core 0.1.0 → 0.2.0

package/README.md

@@ -5,6 +5,7 @@
 [![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)
+[![codecov](https://codecov.io/gh/thu-san/zod-utils/branch/main/graph/badge.svg?flag=core)](https://codecov.io/gh/thu-san/zod-utils)
 
 Pure TypeScript utilities for Zod schema manipulation and default extraction. No React dependencies.
 
@@ -26,20 +27,22 @@ npm install @zod-utils/core zod
 
 ### `getSchemaDefaults(schema)`
 
-Extract all default values from a Zod object schema. Recursively handles nested objects.
+Extract all default values from a Zod object schema. Only extracts fields that explicitly have `.default()` on them.
 
 ```typescript
-import { getSchemaDefaults } from '@zod-utils/core';
-import { z } from 'zod';
+import { getSchemaDefaults } from "@zod-utils/core";
+import { z } from "zod";
 
 const schema = z.object({
-  name: z.string().default('John Doe'),
+  name: z.string().default("John Doe"),
   age: z.number().default(25),
   email: z.string().email(), // no default - skipped
-  settings: z.object({
-    theme: z.string().default('light'),
-    notifications: z.boolean().default(true),
-  }),
+  settings: z
+    .object({
+      theme: z.string().default("light"),
+      notifications: z.boolean().default(true),
+    })
+    .default({}), // must have explicit .default() to be extracted
   tags: z.array(z.string()).default([]),
 });
 
@@ -47,53 +50,85 @@ const defaults = getSchemaDefaults(schema);
 // {
 //   name: 'John Doe',
 //   age: 25,
-//   settings: { theme: 'light', notifications: true },
+//   settings: {},
 //   tags: []
 // }
 ```
 
+**Important:** Only fields with explicit `.default()` are extracted. Nested object fields without an explicit default on the parent field are not extracted, even if they contain defaults internally.
+
 **Handles:**
-- Nested objects at any depth
+
 - Optional fields with defaults: `.optional().default(value)`
+- Nullable fields with defaults: `.nullable().default(value)`
 - Arrays with defaults: `.array().default([])`
-- Skips fields without defaults
+- Objects with defaults: `.object({...}).default({})`
+- Skips fields without explicit defaults
 
 ---
 
 ### `checkIfFieldIsRequired(field)`
 
-Check if a Zod field is required (not optional/nullable and doesn't accept empty values).
+Check if a Zod field is required. Returns `false` if the field accepts any of:
+
+- `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()`)
 
 ```typescript
-import { checkIfFieldIsRequired } from '@zod-utils/core';
-import { z } from 'zod';
+import { checkIfFieldIsRequired } from "@zod-utils/core";
+import { z } from "zod";
+
+// 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();
 
-const requiredField = z.string();
+checkIfFieldIsRequired(requiredString); // true
+checkIfFieldIsRequired(nonemptyString); // true
+checkIfFieldIsRequired(requiredArray); // true
+checkIfFieldIsRequired(nonemptyArray); // true
+
+// Fields accepting undefined - return false
 const optionalField = z.string().optional();
-const emptyStringAllowed = z.string().min(0);
+const fieldWithDefault = z.string().default("hello");
+
+checkIfFieldIsRequired(optionalField); // false
+checkIfFieldIsRequired(fieldWithDefault); // false
+
+// Fields accepting empty values - return false
+const emptyStringAllowed = z.string();
+const emptyArrayAllowed = z.array(z.string());
 
-checkIfFieldIsRequired(requiredField);     // true
-checkIfFieldIsRequired(optionalField);     // false
 checkIfFieldIsRequired(emptyStringAllowed); // false
+checkIfFieldIsRequired(emptyArrayAllowed); // false
+
+// Fields accepting null - return false
+const nullableField = z.string().nullable();
+
+checkIfFieldIsRequired(nullableField); // false
 ```
 
 ---
 
-### `getPrimitiveType(field, options?)`
+### `getPrimitiveType(field)`
 
 Get the primitive type of a Zod field by unwrapping optional/nullable wrappers.
+Stops at arrays without unwrapping them.
 
 ```typescript
-import { getPrimitiveType } from '@zod-utils/core';
-import { z } from 'zod';
+import { getPrimitiveType } from "@zod-utils/core";
+import { z } from "zod";
 
 const field = z.string().optional().nullable();
 const primitive = getPrimitiveType(field);
 // Returns the underlying string schema
 
-// Options
-getPrimitiveType(z.array(z.string()), { unwrapArrays: false }); // Stops at array
-getPrimitiveType(z.array(z.string()), { unwrapArrays: true });  // Continues unwrapping
+const arrayField = z.array(z.string()).optional();
+const arrayPrimitive = getPrimitiveType(arrayField);
+// Returns the ZodArray (stops at arrays)
 ```
 
 ---
@@ -103,14 +138,14 @@ getPrimitiveType(z.array(z.string()), { unwrapArrays: true });  // Continues unw
 Remove default values from a Zod field.
 
 ```typescript
-import { removeDefault } from '@zod-utils/core';
-import { z } from 'zod';
+import { removeDefault } from "@zod-utils/core";
+import { z } from "zod";
 
-const withDefault = z.string().default('hello');
+const withDefault = z.string().default("hello");
 const withoutDefault = removeDefault(withDefault);
 
-withDefault.parse(undefined);     // 'hello'
-withoutDefault.parse(undefined);  // throws error
+withDefault.parse(undefined); // 'hello'
+withoutDefault.parse(undefined); // throws error
 ```
 
 ---
@@ -120,10 +155,10 @@ withoutDefault.parse(undefined);  // throws error
 Extract the default value from a Zod field (recursively unwraps optional/nullable).
 
 ```typescript
-import { extractDefault } from '@zod-utils/core';
-import { z } from 'zod';
+import { extractDefault } from "@zod-utils/core";
+import { z } from "zod";
 
-const field = z.string().optional().default('hello');
+const field = z.string().optional().default("hello");
 extractDefault(field); // 'hello'
 
 const noDefault = z.string();
@@ -132,63 +167,20 @@ extractDefault(noDefault); // undefined
 
 ---
 
-### `getUnwrappedType(field)`
-
-Get the unwrapped type without going through defaults. Useful for detecting nested objects/arrays.
-
-```typescript
-import { getUnwrappedType } from '@zod-utils/core';
-import { z } from 'zod';
-
-const field = z.object({ name: z.string() }).optional().default({});
-const unwrapped = getUnwrappedType(field);
-// Returns the ZodObject (preserves the default wrapper)
-```
-
----
-
 ## Type Utilities
 
-### `MakeOptionalAndNullable<T>`
-
-Make all properties optional and nullable. Useful for form input types.
-
-```typescript
-import type { MakeOptionalAndNullable } from '@zod-utils/core';
-
-type User = {
-  name: string;
-  age: number;
-};
-
-type FormInput = MakeOptionalAndNullable<User>;
-// { name?: string | null; age?: number | null; }
-```
-
 ### `Simplify<T>`
 
 Simplify complex types for better IDE hints.
 
 ```typescript
-import type { Simplify } from '@zod-utils/core';
+import type { Simplify } from "@zod-utils/core";
 
 type Complex = { a: string } & { b: number };
 type Simple = Simplify<Complex>;
 // { a: string; b: number }
 ```
 
-### `PickArrayObject<T>`
-
-Extract the element type from an array.
-
-```typescript
-import type { PickArrayObject } from '@zod-utils/core';
-
-type Users = Array<{ name: string }>;
-type User = PickArrayObject<Users>;
-// { name: string }
-```
-
 ---
 
 ## License

package/dist/index.d.mts

@@ -1,79 +1,314 @@
 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 Unwrappable = {
+    unwrap: () => z.ZodTypeAny;
+};
+/**
+ * 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
+ */
+declare function canUnwrap(field: z.ZodTypeAny): field is z.ZodTypeAny & Unwrappable;
+/**
+ * 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
  */
-type PickArrayObject<TArray extends unknown[] | undefined> = NonNullable<TArray>[number];
+declare const getPrimitiveType: <T extends z.ZodTypeAny>(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;
 /**
- * Simplify complex types for better IDE hints
+ * 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 checkIfFieldIsRequired} for usage with requirement checking
+ * @since 0.1.0
  */
-type Simplify<T> = {
-    [K in keyof T]: T[K];
-} & {};
+declare function removeDefault<T extends z.ZodType>(field: T): StripZodDefault<T>;
 /**
- * Make all properties optional and nullable
- * Useful for form input types where fields can be empty
+ * Checks if a Zod field is truly required by testing multiple acceptance criteria.
+ *
+ * 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()`)
+ *
+ * **Note:** Fields with `.default()` are considered not required since they'll have a value
+ * even if the user doesn't provide one.
+ *
+ * @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
+ *
+ * @example
+ * Required field
+ * ```typescript
+ * const field = z.string().min(1);
+ * console.log(checkIfFieldIsRequired(field)); // true
+ * ```
+ *
+ * @example
+ * Optional field (not required)
+ * ```typescript
+ * const field = z.string().optional();
+ * console.log(checkIfFieldIsRequired(field)); // false
+ * ```
+ *
+ * @example
+ * Field with default (not required)
+ * ```typescript
+ * const field = z.string().default('hello');
+ * console.log(checkIfFieldIsRequired(field)); // false
+ * ```
+ *
+ * @example
+ * String without min length (not required - accepts empty string)
+ * ```typescript
+ * const field = z.string();
+ * console.log(checkIfFieldIsRequired(field)); // false
+ * ```
+ *
+ * @example
+ * String with nonempty (required)
+ * ```typescript
+ * const field = z.string().nonempty();
+ * console.log(checkIfFieldIsRequired(field)); // true
+ * ```
+ *
+ * @example
+ * Nullable field (not required)
+ * ```typescript
+ * const field = z.number().nullable();
+ * console.log(checkIfFieldIsRequired(field)); // false
+ * ```
+ *
+ * @see {@link removeDefault} for understanding how defaults are handled
+ * @see {@link getPrimitiveType} for understanding type unwrapping
+ * @since 0.1.0
  */
-type MakeOptionalAndNullable<T> = {
-    [K in keyof T]?: T[K] | null;
-};
+declare const checkIfFieldIsRequired: <T extends z.ZodType>(field: T) => boolean;
 
-export { type MakeOptionalAndNullable, type PickArrayObject, type Simplify, checkIfFieldIsRequired, extractDefault, getPrimitiveType, getSchemaDefaults, getUnwrappedType, removeDefault };
+export { type Simplify, canUnwrap, checkIfFieldIsRequired, extractDefault, getPrimitiveType, getSchemaDefaults, removeDefault };