@zod-utils/core 0.1.0 → 0.4.0

package/README.md

@@ -2,9 +2,11 @@
 
 [![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)
+[![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.
 
@@ -14,10 +16,14 @@ 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
 - 🔧 **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
@@ -26,20 +32,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 +55,101 @@ 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)`
+### `requiresValidInput(field)`
+
+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).
 
-Check if a Zod field is required (not optional/nullable and doesn't accept empty values).
+**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:**
 
-const requiredField = z.string();
-const optionalField = z.string().optional();
-const emptyStringAllowed = z.string().min(0);
+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
 
-checkIfFieldIsRequired(requiredField);     // true
-checkIfFieldIsRequired(optionalField);     // false
-checkIfFieldIsRequired(emptyStringAllowed); // false
+**Examples:**
+
+```typescript
+import { requiresValidInput } from "@zod-utils/core";
+import { z } from "zod";
+
+// User name - required, no default
+const userName = z.string().min(1);
+requiresValidInput(userName); // true - will error if empty
+
+// Marital status - required WITH default
+const maritalStatus = z.string().min(1).default('single');
+requiresValidInput(maritalStatus); // true - will error if user clears it
+
+// Age with default - requires valid input
+const age = z.number().default(0);
+requiresValidInput(age); // true - numbers reject empty strings
+
+// Optional bio - doesn't require input
+const bio = z.string().optional();
+requiresValidInput(bio); // false - user can leave empty
+
+// Notes with default but NO validation
+const notes = z.string().default('N/A');
+requiresValidInput(notes); // false - plain z.string() accepts empty
+
+// Nullable middle name
+const middleName = z.string().nullable();
+requiresValidInput(middleName); // false - user can leave null
 ```
 
 ---
 
-### `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 +159,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 +176,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 +188,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