@zod-utils/react-hook-form 0.2.0 → 0.4.0

package/README.md

@@ -2,6 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@zod-utils/react-hook-form.svg)](https://www.npmjs.com/package/@zod-utils/react-hook-form)
 [![npm downloads](https://img.shields.io/npm/dm/@zod-utils/react-hook-form.svg)](https://www.npmjs.com/package/@zod-utils/react-hook-form)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@zod-utils/react-hook-form)](https://bundlephobia.com/package/@zod-utils/react-hook-form)
 [![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)
@@ -11,7 +12,7 @@ React Hook Form integration and utilities for Zod schemas.
 
 ## 💡 Why Use This?
 
-**The whole point:** Automatically transforms your Zod schema types so form inputs and default values accept `null | undefined` during editing, while the validated output remains exactly as your Zod schema defines.
+**The whole point:** Automatically transforms your Zod schema types so form inputs accept `undefined` (and `null` for objects only) during editing, while the validated output remains exactly as your Zod schema defines.
 
 No more type wrestling with React Hook Form - just pass your schema and it works.
 
@@ -19,27 +20,33 @@ No more type wrestling with React Hook Form - just pass your schema and it works
 import { useZodForm } from "@zod-utils/react-hook-form";
 import { z } from "zod";
 
-// Your schema requires string - NOT optional
+// Your schema with primitives, arrays, and objects - NOT optional
 const schema = z.object({
   username: z.string().min(3),
-  email: z.string().email(),
+  age: z.number().min(18),
+  tags: z.array(z.string()),
+  profile: z.object({ bio: z.string() }),
 });
 
 const form = useZodForm({ schema });
 
-// ✅ Works! defaultValues accepts null/undefined during editing
-form.reset({ username: null, email: undefined });
+// ✅ Works! Primitives and arrays accept undefined during editing
+form.setValue("username", undefined);
+form.setValue("age", undefined);
+form.setValue("tags", undefined);
 
-// ✅ Works! setValue accepts null/undefined during editing
-form.setValue("username", null);
-form.setValue("email", undefined);
+// ✅ Works! Objects accept both null and undefined
+form.setValue("profile", null);
+form.setValue("profile", undefined);
 
 // ✅ Validated output type is exactly z.infer<typeof schema>
 const onSubmit = form.handleSubmit((data) => {
-  // Type: { username: string; email: string }
-  // NOT { username: string | null | undefined; email: string | null | undefined }
+  // Type: { username: string; age: number; tags: string[]; profile: { bio: string } }
+  // NOT { username: string | null | undefined; ... }
   console.log(data.username); // Type: string
-  console.log(data.email); // Type: string
+  console.log(data.age); // Type: number
+  console.log(data.tags); // Type: string[]
+  console.log(data.profile); // Type: { bio: string }
 });
 ```
 
@@ -49,6 +56,10 @@ const onSubmit = form.handleSubmit((data) => {
 npm install @zod-utils/react-hook-form zod react react-hook-form @hookform/resolvers
 ```
 
+## Related Packages
+
+- **[@zod-utils/core](https://www.npmjs.com/package/@zod-utils/core)** - Pure TypeScript utilities for Zod schema manipulation (no React dependencies). All utilities are re-exported from this package for convenience.
+
 ## Features
 
 - 🎣 **useZodForm** - Automatic type transformation for form inputs (nullable/undefined) while preserving Zod schema validation
@@ -117,11 +128,55 @@ const form = useZodForm({
 
 **What it does:**
 
-- **Input transformation**: Form field values can be `null` or `undefined` during editing
+- **Input transformation** (by default):
+  - **Primitive fields** (string, number, boolean) accept `undefined` only
+  - **Array fields** accept `undefined` only
+  - **Object fields** accept both `null` and `undefined`
+  - You can override this by specifying a custom input type (see examples below)
 - **Output validation**: Validated data matches your Zod schema exactly
 - **Type inference**: No manual type annotations needed - everything is inferred from the schema
 - **Zod integration**: Automatically sets up `zodResolver` for validation
 
+#### Custom Input Types
+
+You can override the default input type transformation if needed:
+
+```typescript
+import {
+  useZodForm,
+  PartialWithAllNullables,
+} from "@zod-utils/react-hook-form";
+import { z } from "zod";
+
+const schema = z.object({
+  username: z.string().min(3),
+  email: z.string().email(),
+  age: z.number(),
+});
+
+// Option 1: Use PartialWithAllNullables to make ALL fields accept null
+const form = useZodForm<
+  z.infer<typeof schema>,
+  PartialWithAllNullables<z.infer<typeof schema>>
+>({
+  schema,
+  defaultValues: { username: null, email: null, age: null },
+});
+
+// Option 2: Specify exact input types per field
+const form2 = useZodForm<
+  z.infer<typeof schema>,
+  {
+    username?: string | null; // Can be set to null
+    email?: string; // Can only be undefined
+    age?: number | null; // Can be set to null
+  }
+>({
+  schema,
+  defaultValues: { username: null, email: undefined, age: null },
+});
+```
+
 ---
 
 ## Core Utilities (Re-exported)
@@ -132,14 +187,15 @@ All utilities from `@zod-utils/core` are re-exported for convenience:
 import {
   // Schema utilities (from @zod-utils/core)
   getSchemaDefaults,
-  checkIfFieldIsRequired,
+  requiresValidInput,
   getPrimitiveType,
   removeDefault,
   extractDefault,
   type Simplify,
 
   // Type utilities (react-hook-form specific)
-  type MakeOptionalAndNullable,
+  type PartialWithNullableObjects,
+  type PartialWithAllNullables,
 } from "@zod-utils/react-hook-form";
 ```
 
@@ -147,23 +203,63 @@ See [@zod-utils/core documentation](../core/README.md) for details on schema uti
 
 ### Type Utilities
 
-#### `MakeOptionalAndNullable<T>`
+#### `PartialWithNullableObjects<T>`
+
+Transforms properties based on their type. Primitive and array fields become optional-only (not nullable), while object fields become optional and nullable.
+
+**Transformation rules:**
+
+- **Primitives** (string, number, boolean): optional → `type | undefined`
+- **Arrays**: optional → `type[] | undefined`
+- **Objects**: optional and nullable → `type | null | undefined`
+
+```typescript
+import type { PartialWithNullableObjects } from "@zod-utils/react-hook-form";
+
+type User = {
+  name: string;
+  age: number;
+  tags: string[];
+  profile: { bio: string };
+};
+
+type FormInput = PartialWithNullableObjects<User>;
+// {
+//   name?: string;                  // Primitive: optional, not nullable
+//   age?: number;                   // Primitive: optional, not nullable
+//   tags?: string[];                // Array: optional, not nullable
+//   profile?: { bio: string } | null; // Object: optional AND nullable
+// }
+```
+
+This type is used internally by `useZodForm` to allow form fields to accept undefined (and null for objects only) during editing while maintaining proper validation types.
+
+#### `PartialWithAllNullables<T>`
+
+Makes all fields optional and nullable, regardless of type.
+
+**Transformation rules:**
 
-Make all properties optional and nullable. Useful for React Hook Form input types where fields can be empty during editing.
+- **All fields**: optional and nullable → `type | null | undefined`
 
 ```typescript
-import type { MakeOptionalAndNullable } from "@zod-utils/react-hook-form";
+import type { PartialWithAllNullables } from "@zod-utils/react-hook-form";
 
 type User = {
   name: string;
   age: number;
+  tags: string[];
 };
 
-type FormInput = MakeOptionalAndNullable<User>;
-// { name?: string | null; age?: number | null; }
+type FormInput = PartialWithAllNullables<User>;
+// {
+//   name?: string | null;       // All fields: optional AND nullable
+//   age?: number | null;        // All fields: optional AND nullable
+//   tags?: string[] | null;     // All fields: optional AND nullable
+// }
 ```
 
-This type is used internally by `useZodForm` to allow form fields to be null/undefined during editing while maintaining proper validation types.
+Use this when all fields need to accept `null`, not just objects/arrays.
 
 ---
 

package/dist/index.d.mts

@@ -5,75 +5,40 @@ import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
 
 /**
- * Transforms all properties in a type to be optional and nullable.
- *
- * This type utility is the secret sauce behind `useZodForm`'s type transformation.
- * It makes form inputs accept `null | undefined` during editing, while validated
- * output remains exactly as the schema defines.
- *
- * **Why this matters:**
- * - React Hook Form fields often contain `null` or `undefined` during user input
- * - Zod schemas define strict output types without these nullable/optional wrappers
- * - This type bridges the gap, eliminating "Type 'null' is not assignable to..." errors
+ * Helper type that adds `null` to object-type fields only (excludes arrays).
+ * @internal
+ */
+type AddNullToObjects<T> = {
+    [K in keyof T]: T[K] extends readonly unknown[] ? T[K] : T[K] extends object ? T[K] | null : T[K];
+};
+/**
+ * Transforms Zod schema types for form inputs.
  *
- * @template T - The object type to transform
+ * - **Primitives** (string, number, boolean): optional → `type | undefined`
+ * - **Arrays**: optional → `type[] | undefined`
+ * - **Objects**: optional and nullable → `type | null | undefined`
  *
  * @example
- * Basic transformation
  * ```typescript
- * type User = {
- *   name: string;
- *   age: number;
- * };
- *
- * type FormUser = MakeOptionalAndNullable<User>;
- * // Result: {
- * //   name?: string | null;
- * //   age?: number | null;
- * // }
+ * type User = { name: string; tags: string[]; profile: { bio: string } };
+ * type FormInput = PartialWithNullableObjects<User>;
+ * // { name?: string; tags?: string[]; profile?: { bio: string } | null; }
  * ```
+ */
+type PartialWithNullableObjects<T> = Partial<AddNullToObjects<T>>;
+/**
+ * Makes all fields optional and nullable.
  *
- * @example
- * Usage with useZodForm
- * ```typescript
- * const schema = z.object({
- *   title: z.string(),
- *   count: z.number(),
- * });
- *
- * const form = useZodForm({ schema });
- *
- * // ✅ These work without type errors:
- * form.setValue('title', null); // Accepts null during editing
- * form.setValue('title', undefined); // Accepts undefined
- * form.reset({ title: null, count: null }); // Reset with null values
- *
- * // But validated output is still:
- * // { title: string, count: number }
- * ```
+ * - **All fields**: optional and nullable → `type | null | undefined`
  *
  * @example
- * Comparison with original type
  * ```typescript
- * type Schema = {
- *   email: string;
- *   isActive: boolean;
- * };
- *
- * // Original: { email: string; isActive: boolean }
- * // Transformed: { email?: string | null; isActive?: boolean | null }
- *
- * const original: Schema = { email: '', isActive: true }; // OK
- * const original2: Schema = { email: null }; // ❌ Error
- *
- * const transformed: MakeOptionalAndNullable<Schema> = {}; // OK
- * const transformed2: MakeOptionalAndNullable<Schema> = { email: null }; // OK
+ * type User = { name: string; age: number; tags: string[] };
+ * type FormInput = PartialWithAllNullables<User>;
+ * // { name?: string | null; age?: number | null; tags?: string[] | null; }
  * ```
- *
- * @see {@link useZodForm} for how this type is used in practice
- * @since 0.1.0
  */
-type MakeOptionalAndNullable<T> = {
+type PartialWithAllNullables<T> = {
     [K in keyof T]?: T[K] | null;
 };
 
@@ -82,7 +47,7 @@ type MakeOptionalAndNullable<T> = {
  *
  * This hook eliminates the TypeScript friction between React Hook Form's nullable field values
  * and Zod's strict output types. It uses a two-type schema pattern where:
- * - **Input type** (`MakeOptionalAndNullable<T>`): Form fields accept `null | undefined` during editing
+ * - **Input type** (`PartialWithNullableObjects<T>`): Form fields accept `null | undefined` during editing
  * - **Output type** (`T`): Validated data matches exact schema type (no `null | undefined`)
  *
  * **Key Benefits:**
@@ -94,7 +59,7 @@ type MakeOptionalAndNullable<T> = {
  * @template T - The Zod schema output type (extends FieldValues)
  *
  * @param options - Configuration object
- * @param options.schema - Zod schema with two-type signature `z.ZodType<T, MakeOptionalAndNullable<T>>`
+ * @param options.schema - Zod schema with two-type signature `z.ZodType<T, PartialWithNullableObjects<T>>`
  * @param options.defaultValues - Default form values (accepts nullable/undefined values)
  * @param options.zodResolverOptions - Optional zodResolver configuration
  * @param options....formOptions - All other react-hook-form useForm options
@@ -215,15 +180,15 @@ type MakeOptionalAndNullable<T> = {
  * }
  * ```
  *
- * @see {@link MakeOptionalAndNullable} for the type transformation utility
+ * @see {@link PartialWithNullableObjects} for the type transformation utility
  * @see https://react-hook-form.com/docs/useform for React Hook Form documentation
  * @see https://zod.dev for Zod schema documentation
  * @since 0.1.0
  */
-declare const useZodForm: <T extends FieldValues>({ schema, zodResolverOptions, ...formOptions }: {
-    schema: z.ZodType<T, MakeOptionalAndNullable<T>>;
-    defaultValues?: DefaultValues<MakeOptionalAndNullable<T>>;
+declare const useZodForm: <T extends FieldValues, I extends PartialWithAllNullables<T> = PartialWithNullableObjects<T>>({ schema, zodResolverOptions, ...formOptions }: {
+    schema: z.ZodType<T, I>;
+    defaultValues?: DefaultValues<I>;
     zodResolverOptions?: Parameters<typeof zodResolver>[1];
-} & Omit<UseFormProps<MakeOptionalAndNullable<T>, unknown, T>, "resolver" | "defaultValues">) => react_hook_form.UseFormReturn<MakeOptionalAndNullable<T>, unknown, T>;
+} & Omit<UseFormProps<I, unknown, T>, "resolver" | "defaultValues">) => react_hook_form.UseFormReturn<I, unknown, T>;
 
-export { type MakeOptionalAndNullable, useZodForm };
+export { type PartialWithAllNullables, type PartialWithNullableObjects, useZodForm };

package/dist/index.d.ts

@@ -5,75 +5,40 @@ import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
 
 /**
- * Transforms all properties in a type to be optional and nullable.
- *
- * This type utility is the secret sauce behind `useZodForm`'s type transformation.
- * It makes form inputs accept `null | undefined` during editing, while validated
- * output remains exactly as the schema defines.
- *
- * **Why this matters:**
- * - React Hook Form fields often contain `null` or `undefined` during user input
- * - Zod schemas define strict output types without these nullable/optional wrappers
- * - This type bridges the gap, eliminating "Type 'null' is not assignable to..." errors
+ * Helper type that adds `null` to object-type fields only (excludes arrays).
+ * @internal
+ */
+type AddNullToObjects<T> = {
+    [K in keyof T]: T[K] extends readonly unknown[] ? T[K] : T[K] extends object ? T[K] | null : T[K];
+};
+/**
+ * Transforms Zod schema types for form inputs.
  *
- * @template T - The object type to transform
+ * - **Primitives** (string, number, boolean): optional → `type | undefined`
+ * - **Arrays**: optional → `type[] | undefined`
+ * - **Objects**: optional and nullable → `type | null | undefined`
  *
  * @example
- * Basic transformation
  * ```typescript
- * type User = {
- *   name: string;
- *   age: number;
- * };
- *
- * type FormUser = MakeOptionalAndNullable<User>;
- * // Result: {
- * //   name?: string | null;
- * //   age?: number | null;
- * // }
+ * type User = { name: string; tags: string[]; profile: { bio: string } };
+ * type FormInput = PartialWithNullableObjects<User>;
+ * // { name?: string; tags?: string[]; profile?: { bio: string } | null; }
  * ```
+ */
+type PartialWithNullableObjects<T> = Partial<AddNullToObjects<T>>;
+/**
+ * Makes all fields optional and nullable.
  *
- * @example
- * Usage with useZodForm
- * ```typescript
- * const schema = z.object({
- *   title: z.string(),
- *   count: z.number(),
- * });
- *
- * const form = useZodForm({ schema });
- *
- * // ✅ These work without type errors:
- * form.setValue('title', null); // Accepts null during editing
- * form.setValue('title', undefined); // Accepts undefined
- * form.reset({ title: null, count: null }); // Reset with null values
- *
- * // But validated output is still:
- * // { title: string, count: number }
- * ```
+ * - **All fields**: optional and nullable → `type | null | undefined`
  *
  * @example
- * Comparison with original type
  * ```typescript
- * type Schema = {
- *   email: string;
- *   isActive: boolean;
- * };
- *
- * // Original: { email: string; isActive: boolean }
- * // Transformed: { email?: string | null; isActive?: boolean | null }
- *
- * const original: Schema = { email: '', isActive: true }; // OK
- * const original2: Schema = { email: null }; // ❌ Error
- *
- * const transformed: MakeOptionalAndNullable<Schema> = {}; // OK
- * const transformed2: MakeOptionalAndNullable<Schema> = { email: null }; // OK
+ * type User = { name: string; age: number; tags: string[] };
+ * type FormInput = PartialWithAllNullables<User>;
+ * // { name?: string | null; age?: number | null; tags?: string[] | null; }
  * ```
- *
- * @see {@link useZodForm} for how this type is used in practice
- * @since 0.1.0
  */
-type MakeOptionalAndNullable<T> = {
+type PartialWithAllNullables<T> = {
     [K in keyof T]?: T[K] | null;
 };
 
@@ -82,7 +47,7 @@ type MakeOptionalAndNullable<T> = {
  *
  * This hook eliminates the TypeScript friction between React Hook Form's nullable field values
  * and Zod's strict output types. It uses a two-type schema pattern where:
- * - **Input type** (`MakeOptionalAndNullable<T>`): Form fields accept `null | undefined` during editing
+ * - **Input type** (`PartialWithNullableObjects<T>`): Form fields accept `null | undefined` during editing
  * - **Output type** (`T`): Validated data matches exact schema type (no `null | undefined`)
  *
  * **Key Benefits:**
@@ -94,7 +59,7 @@ type MakeOptionalAndNullable<T> = {
  * @template T - The Zod schema output type (extends FieldValues)
  *
  * @param options - Configuration object
- * @param options.schema - Zod schema with two-type signature `z.ZodType<T, MakeOptionalAndNullable<T>>`
+ * @param options.schema - Zod schema with two-type signature `z.ZodType<T, PartialWithNullableObjects<T>>`
  * @param options.defaultValues - Default form values (accepts nullable/undefined values)
  * @param options.zodResolverOptions - Optional zodResolver configuration
  * @param options....formOptions - All other react-hook-form useForm options
@@ -215,15 +180,15 @@ type MakeOptionalAndNullable<T> = {
  * }
  * ```
  *
- * @see {@link MakeOptionalAndNullable} for the type transformation utility
+ * @see {@link PartialWithNullableObjects} for the type transformation utility
  * @see https://react-hook-form.com/docs/useform for React Hook Form documentation
  * @see https://zod.dev for Zod schema documentation
  * @since 0.1.0
  */
-declare const useZodForm: <T extends FieldValues>({ schema, zodResolverOptions, ...formOptions }: {
-    schema: z.ZodType<T, MakeOptionalAndNullable<T>>;
-    defaultValues?: DefaultValues<MakeOptionalAndNullable<T>>;
+declare const useZodForm: <T extends FieldValues, I extends PartialWithAllNullables<T> = PartialWithNullableObjects<T>>({ schema, zodResolverOptions, ...formOptions }: {
+    schema: z.ZodType<T, I>;
+    defaultValues?: DefaultValues<I>;
     zodResolverOptions?: Parameters<typeof zodResolver>[1];
-} & Omit<UseFormProps<MakeOptionalAndNullable<T>, unknown, T>, "resolver" | "defaultValues">) => react_hook_form.UseFormReturn<MakeOptionalAndNullable<T>, unknown, T>;
+} & Omit<UseFormProps<I, unknown, T>, "resolver" | "defaultValues">) => react_hook_form.UseFormReturn<I, unknown, T>;
 
-export { type MakeOptionalAndNullable, useZodForm };
+export { type PartialWithAllNullables, type PartialWithNullableObjects, useZodForm };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/use-zod-form.ts"],"names":["zodResolver","useForm"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyJO,IAAM,UAAA,GAAa,CAAwB,EAAA,KAW5C;AAX4C,EAAA,IAAA,EAAA,GAAA,EAAA,EAChD;AAAA,IAAA,MAAA;AAAA,IACA;AAAA,GA3JF,GAyJkD,EAAA,EAG7C,WAAA,GAAA,SAAA,CAH6C,EAAA,EAG7C;AAAA,IAFH,QAAA;AAAA,IACA;AAAA,GAAA,CAAA;AAUA,EAAA,MAAM,QAAA,GAAWA,eAAA,CAAY,MAAA,EAAQ,kBAAkB,CAAA;AAEvD,EAAA,OAAOC,qBAAA,CAAQ,cAAA,CAAA;AAAA,IACb;AAAA,GAAA,EACG,WAAA,CACJ,CAAA;AACH","file":"index.js","sourcesContent":["import { zodResolver } from '@hookform/resolvers/zod';\nimport {\n  type DefaultValues,\n  type FieldValues,\n  type UseFormProps,\n  useForm,\n} from 'react-hook-form';\nimport type { z } from 'zod';\nimport type { MakeOptionalAndNullable } from './types';\n\n/**\n * Type-safe React Hook Form wrapper with automatic Zod v4 schema validation and type transformation.\n *\n * This hook eliminates the TypeScript friction between React Hook Form's nullable field values\n * and Zod's strict output types. It uses a two-type schema pattern where:\n * - **Input type** (`MakeOptionalAndNullable<T>`): Form fields accept `null | undefined` during editing\n * - **Output type** (`T`): Validated data matches exact schema type (no `null | undefined`)\n *\n * **Key Benefits:**\n * - ✅ No more \"Type 'null' is not assignable to...\" TypeScript errors\n * - ✅ Use `form.setValue()` and `form.reset()` with `null` values freely\n * - ✅ Validated output is still type-safe with exact Zod schema types\n * - ✅ Automatic zodResolver setup - no manual configuration needed\n *\n * @template T - The Zod schema output type (extends FieldValues)\n *\n * @param options - Configuration object\n * @param options.schema - Zod schema with two-type signature `z.ZodType<T, MakeOptionalAndNullable<T>>`\n * @param options.defaultValues - Default form values (accepts nullable/undefined values)\n * @param options.zodResolverOptions - Optional zodResolver configuration\n * @param options....formOptions - All other react-hook-form useForm options\n *\n * @returns React Hook Form instance with type-safe methods\n *\n * @example\n * Basic usage with required fields\n * ```typescript\n * import { useZodForm } from '@zod-utils/react-hook-form';\n * import { z } from 'zod';\n *\n * const schema = z.object({\n *   name: z.string().min(1), // Required field\n *   age: z.number().min(0),\n * }) satisfies z.ZodType<{ name: string; age: number }, any>;\n *\n * function MyForm() {\n *   const form = useZodForm({ schema });\n *\n *   // ✅ These work without type errors:\n *   form.setValue('name', null); // Accepts null during editing\n *   form.reset({ name: null, age: null }); // Reset with null\n *\n *   const onSubmit = (data: { name: string; age: number }) => {\n *     // ✅ data is exact type - no null | undefined\n *     console.log(data.name.toUpperCase()); // Safe to use string methods\n *   };\n *\n *   return <form onSubmit={form.handleSubmit(onSubmit)}>...</form>;\n * }\n * ```\n *\n * @example\n * With default values\n * ```typescript\n * const schema = z.object({\n *   username: z.string(),\n *   email: z.string().email(),\n *   notifications: z.boolean().default(true),\n * }) satisfies z.ZodType<{\n *   username: string;\n *   email: string;\n *   notifications: boolean;\n * }, any>;\n *\n * const form = useZodForm({\n *   schema,\n *   defaultValues: {\n *     username: '',\n *     email: '',\n *     // notifications gets default from schema\n *   },\n * });\n * ```\n *\n * @example\n * With optional and nullable fields\n * ```typescript\n * const schema = z.object({\n *   title: z.string(),\n *   description: z.string().optional(), // Optional in output\n *   tags: z.array(z.string()).nullable(), // Nullable in output\n * }) satisfies z.ZodType<{\n *   title: string;\n *   description?: string;\n *   tags: string[] | null;\n * }, any>;\n *\n * const form = useZodForm({ schema });\n *\n * // All fields accept null/undefined during editing\n * form.setValue('title', null);\n * form.setValue('description', undefined);\n * form.setValue('tags', null);\n * ```\n *\n * @example\n * With zodResolver options\n * ```typescript\n * const form = useZodForm({\n *   schema,\n *   zodResolverOptions: {\n *     async: true, // Enable async validation\n *     errorMap: customErrorMap, // Custom error messages\n *   },\n * });\n * ```\n *\n * @example\n * Complete form example\n * ```typescript\n * const userSchema = z.object({\n *   name: z.string().min(1, 'Name is required'),\n *   email: z.string().email('Invalid email'),\n *   age: z.number().min(18, 'Must be 18+'),\n * }) satisfies z.ZodType<{ name: string; email: string; age: number }, any>;\n *\n * function UserForm() {\n *   const form = useZodForm({\n *     schema: userSchema,\n *     defaultValues: { name: '', email: '', age: null },\n *   });\n *\n *   const onSubmit = (data: { name: string; email: string; age: number }) => {\n *     // Type-safe: data has exact types, no null/undefined\n *     console.log(`${data.name} is ${data.age} years old`);\n *   };\n *\n *   return (\n *     <form onSubmit={form.handleSubmit(onSubmit)}>\n *       <input {...form.register('name')} />\n *       <input {...form.register('email')} type=\"email\" />\n *       <input {...form.register('age', { valueAsNumber: true })} type=\"number\" />\n *       <button type=\"submit\">Submit</button>\n *     </form>\n *   );\n * }\n * ```\n *\n * @see {@link MakeOptionalAndNullable} for the type transformation utility\n * @see https://react-hook-form.com/docs/useform for React Hook Form documentation\n * @see https://zod.dev for Zod schema documentation\n * @since 0.1.0\n */\nexport const useZodForm = <T extends FieldValues>({\n  schema,\n  zodResolverOptions,\n  ...formOptions\n}: {\n  schema: z.ZodType<T, MakeOptionalAndNullable<T>>;\n  defaultValues?: DefaultValues<MakeOptionalAndNullable<T>>;\n  zodResolverOptions?: Parameters<typeof zodResolver>[1];\n} & Omit<\n  UseFormProps<MakeOptionalAndNullable<T>, unknown, T>,\n  'resolver' | 'defaultValues'\n>) => {\n  const resolver = zodResolver(schema, zodResolverOptions);\n\n  return useForm({\n    resolver,\n    ...formOptions,\n  });\n};\n"]}
+{"version":3,"sources":["../src/use-zod-form.ts"],"names":["zodResolver","useForm"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4JO,IAAM,UAAA,GAAa,CAGxB,EAAA,KAQsE;AARtE,EAAA,IAAA,EAAA,GAAA,EAAA,EACA;AAAA,IAAA,MAAA;AAAA,IACA;AAAA,GAjKF,GA+JE,EAAA,EAGG,WAAA,GAAA,SAAA,CAHH,EAAA,EAGG;AAAA,IAFH,QAAA;AAAA,IACA;AAAA,GAAA,CAAA;AAOA,EAAA,MAAM,QAAA,GAAWA,eAAA,CAAY,MAAA,EAAQ,kBAAkB,CAAA;AAEvD,EAAA,OAAOC,qBAAA,CAAQ,cAAA,CAAA;AAAA,IACb;AAAA,GAAA,EACG,WAAA,CACJ,CAAA;AACH","file":"index.js","sourcesContent":["import { zodResolver } from '@hookform/resolvers/zod';\nimport {\n  type DefaultValues,\n  type FieldValues,\n  type UseFormProps,\n  useForm,\n} from 'react-hook-form';\nimport type { z } from 'zod';\nimport type {\n  PartialWithAllNullables,\n  PartialWithNullableObjects,\n} from './types';\n\n/**\n * Type-safe React Hook Form wrapper with automatic Zod v4 schema validation and type transformation.\n *\n * This hook eliminates the TypeScript friction between React Hook Form's nullable field values\n * and Zod's strict output types. It uses a two-type schema pattern where:\n * - **Input type** (`PartialWithNullableObjects<T>`): Form fields accept `null | undefined` during editing\n * - **Output type** (`T`): Validated data matches exact schema type (no `null | undefined`)\n *\n * **Key Benefits:**\n * - ✅ No more \"Type 'null' is not assignable to...\" TypeScript errors\n * - ✅ Use `form.setValue()` and `form.reset()` with `null` values freely\n * - ✅ Validated output is still type-safe with exact Zod schema types\n * - ✅ Automatic zodResolver setup - no manual configuration needed\n *\n * @template T - The Zod schema output type (extends FieldValues)\n *\n * @param options - Configuration object\n * @param options.schema - Zod schema with two-type signature `z.ZodType<T, PartialWithNullableObjects<T>>`\n * @param options.defaultValues - Default form values (accepts nullable/undefined values)\n * @param options.zodResolverOptions - Optional zodResolver configuration\n * @param options....formOptions - All other react-hook-form useForm options\n *\n * @returns React Hook Form instance with type-safe methods\n *\n * @example\n * Basic usage with required fields\n * ```typescript\n * import { useZodForm } from '@zod-utils/react-hook-form';\n * import { z } from 'zod';\n *\n * const schema = z.object({\n *   name: z.string().min(1), // Required field\n *   age: z.number().min(0),\n * }) satisfies z.ZodType<{ name: string; age: number }, any>;\n *\n * function MyForm() {\n *   const form = useZodForm({ schema });\n *\n *   // ✅ These work without type errors:\n *   form.setValue('name', null); // Accepts null during editing\n *   form.reset({ name: null, age: null }); // Reset with null\n *\n *   const onSubmit = (data: { name: string; age: number }) => {\n *     // ✅ data is exact type - no null | undefined\n *     console.log(data.name.toUpperCase()); // Safe to use string methods\n *   };\n *\n *   return <form onSubmit={form.handleSubmit(onSubmit)}>...</form>;\n * }\n * ```\n *\n * @example\n * With default values\n * ```typescript\n * const schema = z.object({\n *   username: z.string(),\n *   email: z.string().email(),\n *   notifications: z.boolean().default(true),\n * }) satisfies z.ZodType<{\n *   username: string;\n *   email: string;\n *   notifications: boolean;\n * }, any>;\n *\n * const form = useZodForm({\n *   schema,\n *   defaultValues: {\n *     username: '',\n *     email: '',\n *     // notifications gets default from schema\n *   },\n * });\n * ```\n *\n * @example\n * With optional and nullable fields\n * ```typescript\n * const schema = z.object({\n *   title: z.string(),\n *   description: z.string().optional(), // Optional in output\n *   tags: z.array(z.string()).nullable(), // Nullable in output\n * }) satisfies z.ZodType<{\n *   title: string;\n *   description?: string;\n *   tags: string[] | null;\n * }, any>;\n *\n * const form = useZodForm({ schema });\n *\n * // All fields accept null/undefined during editing\n * form.setValue('title', null);\n * form.setValue('description', undefined);\n * form.setValue('tags', null);\n * ```\n *\n * @example\n * With zodResolver options\n * ```typescript\n * const form = useZodForm({\n *   schema,\n *   zodResolverOptions: {\n *     async: true, // Enable async validation\n *     errorMap: customErrorMap, // Custom error messages\n *   },\n * });\n * ```\n *\n * @example\n * Complete form example\n * ```typescript\n * const userSchema = z.object({\n *   name: z.string().min(1, 'Name is required'),\n *   email: z.string().email('Invalid email'),\n *   age: z.number().min(18, 'Must be 18+'),\n * }) satisfies z.ZodType<{ name: string; email: string; age: number }, any>;\n *\n * function UserForm() {\n *   const form = useZodForm({\n *     schema: userSchema,\n *     defaultValues: { name: '', email: '', age: null },\n *   });\n *\n *   const onSubmit = (data: { name: string; email: string; age: number }) => {\n *     // Type-safe: data has exact types, no null/undefined\n *     console.log(`${data.name} is ${data.age} years old`);\n *   };\n *\n *   return (\n *     <form onSubmit={form.handleSubmit(onSubmit)}>\n *       <input {...form.register('name')} />\n *       <input {...form.register('email')} type=\"email\" />\n *       <input {...form.register('age', { valueAsNumber: true })} type=\"number\" />\n *       <button type=\"submit\">Submit</button>\n *     </form>\n *   );\n * }\n * ```\n *\n * @see {@link PartialWithNullableObjects} for the type transformation utility\n * @see https://react-hook-form.com/docs/useform for React Hook Form documentation\n * @see https://zod.dev for Zod schema documentation\n * @since 0.1.0\n */\nexport const useZodForm = <\n  T extends FieldValues,\n  I extends PartialWithAllNullables<T> = PartialWithNullableObjects<T>,\n>({\n  schema,\n  zodResolverOptions,\n  ...formOptions\n}: {\n  schema: z.ZodType<T, I>;\n  defaultValues?: DefaultValues<I>;\n  zodResolverOptions?: Parameters<typeof zodResolver>[1];\n} & Omit<UseFormProps<I, unknown, T>, 'resolver' | 'defaultValues'>) => {\n  const resolver = zodResolver(schema, zodResolverOptions);\n\n  return useForm({\n    resolver,\n    ...formOptions,\n  });\n};\n"]}

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/use-zod-form.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyJO,IAAM,UAAA,GAAa,CAAwB,EAAA,KAW5C;AAX4C,EAAA,IAAA,EAAA,GAAA,EAAA,EAChD;AAAA,IAAA,MAAA;AAAA,IACA;AAAA,GA3JF,GAyJkD,EAAA,EAG7C,WAAA,GAAA,SAAA,CAH6C,EAAA,EAG7C;AAAA,IAFH,QAAA;AAAA,IACA;AAAA,GAAA,CAAA;AAUA,EAAA,MAAM,QAAA,GAAW,WAAA,CAAY,MAAA,EAAQ,kBAAkB,CAAA;AAEvD,EAAA,OAAO,OAAA,CAAQ,cAAA,CAAA;AAAA,IACb;AAAA,GAAA,EACG,WAAA,CACJ,CAAA;AACH","file":"index.mjs","sourcesContent":["import { zodResolver } from '@hookform/resolvers/zod';\nimport {\n  type DefaultValues,\n  type FieldValues,\n  type UseFormProps,\n  useForm,\n} from 'react-hook-form';\nimport type { z } from 'zod';\nimport type { MakeOptionalAndNullable } from './types';\n\n/**\n * Type-safe React Hook Form wrapper with automatic Zod v4 schema validation and type transformation.\n *\n * This hook eliminates the TypeScript friction between React Hook Form's nullable field values\n * and Zod's strict output types. It uses a two-type schema pattern where:\n * - **Input type** (`MakeOptionalAndNullable<T>`): Form fields accept `null | undefined` during editing\n * - **Output type** (`T`): Validated data matches exact schema type (no `null | undefined`)\n *\n * **Key Benefits:**\n * - ✅ No more \"Type 'null' is not assignable to...\" TypeScript errors\n * - ✅ Use `form.setValue()` and `form.reset()` with `null` values freely\n * - ✅ Validated output is still type-safe with exact Zod schema types\n * - ✅ Automatic zodResolver setup - no manual configuration needed\n *\n * @template T - The Zod schema output type (extends FieldValues)\n *\n * @param options - Configuration object\n * @param options.schema - Zod schema with two-type signature `z.ZodType<T, MakeOptionalAndNullable<T>>`\n * @param options.defaultValues - Default form values (accepts nullable/undefined values)\n * @param options.zodResolverOptions - Optional zodResolver configuration\n * @param options....formOptions - All other react-hook-form useForm options\n *\n * @returns React Hook Form instance with type-safe methods\n *\n * @example\n * Basic usage with required fields\n * ```typescript\n * import { useZodForm } from '@zod-utils/react-hook-form';\n * import { z } from 'zod';\n *\n * const schema = z.object({\n *   name: z.string().min(1), // Required field\n *   age: z.number().min(0),\n * }) satisfies z.ZodType<{ name: string; age: number }, any>;\n *\n * function MyForm() {\n *   const form = useZodForm({ schema });\n *\n *   // ✅ These work without type errors:\n *   form.setValue('name', null); // Accepts null during editing\n *   form.reset({ name: null, age: null }); // Reset with null\n *\n *   const onSubmit = (data: { name: string; age: number }) => {\n *     // ✅ data is exact type - no null | undefined\n *     console.log(data.name.toUpperCase()); // Safe to use string methods\n *   };\n *\n *   return <form onSubmit={form.handleSubmit(onSubmit)}>...</form>;\n * }\n * ```\n *\n * @example\n * With default values\n * ```typescript\n * const schema = z.object({\n *   username: z.string(),\n *   email: z.string().email(),\n *   notifications: z.boolean().default(true),\n * }) satisfies z.ZodType<{\n *   username: string;\n *   email: string;\n *   notifications: boolean;\n * }, any>;\n *\n * const form = useZodForm({\n *   schema,\n *   defaultValues: {\n *     username: '',\n *     email: '',\n *     // notifications gets default from schema\n *   },\n * });\n * ```\n *\n * @example\n * With optional and nullable fields\n * ```typescript\n * const schema = z.object({\n *   title: z.string(),\n *   description: z.string().optional(), // Optional in output\n *   tags: z.array(z.string()).nullable(), // Nullable in output\n * }) satisfies z.ZodType<{\n *   title: string;\n *   description?: string;\n *   tags: string[] | null;\n * }, any>;\n *\n * const form = useZodForm({ schema });\n *\n * // All fields accept null/undefined during editing\n * form.setValue('title', null);\n * form.setValue('description', undefined);\n * form.setValue('tags', null);\n * ```\n *\n * @example\n * With zodResolver options\n * ```typescript\n * const form = useZodForm({\n *   schema,\n *   zodResolverOptions: {\n *     async: true, // Enable async validation\n *     errorMap: customErrorMap, // Custom error messages\n *   },\n * });\n * ```\n *\n * @example\n * Complete form example\n * ```typescript\n * const userSchema = z.object({\n *   name: z.string().min(1, 'Name is required'),\n *   email: z.string().email('Invalid email'),\n *   age: z.number().min(18, 'Must be 18+'),\n * }) satisfies z.ZodType<{ name: string; email: string; age: number }, any>;\n *\n * function UserForm() {\n *   const form = useZodForm({\n *     schema: userSchema,\n *     defaultValues: { name: '', email: '', age: null },\n *   });\n *\n *   const onSubmit = (data: { name: string; email: string; age: number }) => {\n *     // Type-safe: data has exact types, no null/undefined\n *     console.log(`${data.name} is ${data.age} years old`);\n *   };\n *\n *   return (\n *     <form onSubmit={form.handleSubmit(onSubmit)}>\n *       <input {...form.register('name')} />\n *       <input {...form.register('email')} type=\"email\" />\n *       <input {...form.register('age', { valueAsNumber: true })} type=\"number\" />\n *       <button type=\"submit\">Submit</button>\n *     </form>\n *   );\n * }\n * ```\n *\n * @see {@link MakeOptionalAndNullable} for the type transformation utility\n * @see https://react-hook-form.com/docs/useform for React Hook Form documentation\n * @see https://zod.dev for Zod schema documentation\n * @since 0.1.0\n */\nexport const useZodForm = <T extends FieldValues>({\n  schema,\n  zodResolverOptions,\n  ...formOptions\n}: {\n  schema: z.ZodType<T, MakeOptionalAndNullable<T>>;\n  defaultValues?: DefaultValues<MakeOptionalAndNullable<T>>;\n  zodResolverOptions?: Parameters<typeof zodResolver>[1];\n} & Omit<\n  UseFormProps<MakeOptionalAndNullable<T>, unknown, T>,\n  'resolver' | 'defaultValues'\n>) => {\n  const resolver = zodResolver(schema, zodResolverOptions);\n\n  return useForm({\n    resolver,\n    ...formOptions,\n  });\n};\n"]}
+{"version":3,"sources":["../src/use-zod-form.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4JO,IAAM,UAAA,GAAa,CAGxB,EAAA,KAQsE;AARtE,EAAA,IAAA,EAAA,GAAA,EAAA,EACA;AAAA,IAAA,MAAA;AAAA,IACA;AAAA,GAjKF,GA+JE,EAAA,EAGG,WAAA,GAAA,SAAA,CAHH,EAAA,EAGG;AAAA,IAFH,QAAA;AAAA,IACA;AAAA,GAAA,CAAA;AAOA,EAAA,MAAM,QAAA,GAAW,WAAA,CAAY,MAAA,EAAQ,kBAAkB,CAAA;AAEvD,EAAA,OAAO,OAAA,CAAQ,cAAA,CAAA;AAAA,IACb;AAAA,GAAA,EACG,WAAA,CACJ,CAAA;AACH","file":"index.mjs","sourcesContent":["import { zodResolver } from '@hookform/resolvers/zod';\nimport {\n  type DefaultValues,\n  type FieldValues,\n  type UseFormProps,\n  useForm,\n} from 'react-hook-form';\nimport type { z } from 'zod';\nimport type {\n  PartialWithAllNullables,\n  PartialWithNullableObjects,\n} from './types';\n\n/**\n * Type-safe React Hook Form wrapper with automatic Zod v4 schema validation and type transformation.\n *\n * This hook eliminates the TypeScript friction between React Hook Form's nullable field values\n * and Zod's strict output types. It uses a two-type schema pattern where:\n * - **Input type** (`PartialWithNullableObjects<T>`): Form fields accept `null | undefined` during editing\n * - **Output type** (`T`): Validated data matches exact schema type (no `null | undefined`)\n *\n * **Key Benefits:**\n * - ✅ No more \"Type 'null' is not assignable to...\" TypeScript errors\n * - ✅ Use `form.setValue()` and `form.reset()` with `null` values freely\n * - ✅ Validated output is still type-safe with exact Zod schema types\n * - ✅ Automatic zodResolver setup - no manual configuration needed\n *\n * @template T - The Zod schema output type (extends FieldValues)\n *\n * @param options - Configuration object\n * @param options.schema - Zod schema with two-type signature `z.ZodType<T, PartialWithNullableObjects<T>>`\n * @param options.defaultValues - Default form values (accepts nullable/undefined values)\n * @param options.zodResolverOptions - Optional zodResolver configuration\n * @param options....formOptions - All other react-hook-form useForm options\n *\n * @returns React Hook Form instance with type-safe methods\n *\n * @example\n * Basic usage with required fields\n * ```typescript\n * import { useZodForm } from '@zod-utils/react-hook-form';\n * import { z } from 'zod';\n *\n * const schema = z.object({\n *   name: z.string().min(1), // Required field\n *   age: z.number().min(0),\n * }) satisfies z.ZodType<{ name: string; age: number }, any>;\n *\n * function MyForm() {\n *   const form = useZodForm({ schema });\n *\n *   // ✅ These work without type errors:\n *   form.setValue('name', null); // Accepts null during editing\n *   form.reset({ name: null, age: null }); // Reset with null\n *\n *   const onSubmit = (data: { name: string; age: number }) => {\n *     // ✅ data is exact type - no null | undefined\n *     console.log(data.name.toUpperCase()); // Safe to use string methods\n *   };\n *\n *   return <form onSubmit={form.handleSubmit(onSubmit)}>...</form>;\n * }\n * ```\n *\n * @example\n * With default values\n * ```typescript\n * const schema = z.object({\n *   username: z.string(),\n *   email: z.string().email(),\n *   notifications: z.boolean().default(true),\n * }) satisfies z.ZodType<{\n *   username: string;\n *   email: string;\n *   notifications: boolean;\n * }, any>;\n *\n * const form = useZodForm({\n *   schema,\n *   defaultValues: {\n *     username: '',\n *     email: '',\n *     // notifications gets default from schema\n *   },\n * });\n * ```\n *\n * @example\n * With optional and nullable fields\n * ```typescript\n * const schema = z.object({\n *   title: z.string(),\n *   description: z.string().optional(), // Optional in output\n *   tags: z.array(z.string()).nullable(), // Nullable in output\n * }) satisfies z.ZodType<{\n *   title: string;\n *   description?: string;\n *   tags: string[] | null;\n * }, any>;\n *\n * const form = useZodForm({ schema });\n *\n * // All fields accept null/undefined during editing\n * form.setValue('title', null);\n * form.setValue('description', undefined);\n * form.setValue('tags', null);\n * ```\n *\n * @example\n * With zodResolver options\n * ```typescript\n * const form = useZodForm({\n *   schema,\n *   zodResolverOptions: {\n *     async: true, // Enable async validation\n *     errorMap: customErrorMap, // Custom error messages\n *   },\n * });\n * ```\n *\n * @example\n * Complete form example\n * ```typescript\n * const userSchema = z.object({\n *   name: z.string().min(1, 'Name is required'),\n *   email: z.string().email('Invalid email'),\n *   age: z.number().min(18, 'Must be 18+'),\n * }) satisfies z.ZodType<{ name: string; email: string; age: number }, any>;\n *\n * function UserForm() {\n *   const form = useZodForm({\n *     schema: userSchema,\n *     defaultValues: { name: '', email: '', age: null },\n *   });\n *\n *   const onSubmit = (data: { name: string; email: string; age: number }) => {\n *     // Type-safe: data has exact types, no null/undefined\n *     console.log(`${data.name} is ${data.age} years old`);\n *   };\n *\n *   return (\n *     <form onSubmit={form.handleSubmit(onSubmit)}>\n *       <input {...form.register('name')} />\n *       <input {...form.register('email')} type=\"email\" />\n *       <input {...form.register('age', { valueAsNumber: true })} type=\"number\" />\n *       <button type=\"submit\">Submit</button>\n *     </form>\n *   );\n * }\n * ```\n *\n * @see {@link PartialWithNullableObjects} for the type transformation utility\n * @see https://react-hook-form.com/docs/useform for React Hook Form documentation\n * @see https://zod.dev for Zod schema documentation\n * @since 0.1.0\n */\nexport const useZodForm = <\n  T extends FieldValues,\n  I extends PartialWithAllNullables<T> = PartialWithNullableObjects<T>,\n>({\n  schema,\n  zodResolverOptions,\n  ...formOptions\n}: {\n  schema: z.ZodType<T, I>;\n  defaultValues?: DefaultValues<I>;\n  zodResolverOptions?: Parameters<typeof zodResolver>[1];\n} & Omit<UseFormProps<I, unknown, T>, 'resolver' | 'defaultValues'>) => {\n  const resolver = zodResolver(schema, zodResolverOptions);\n\n  return useForm({\n    resolver,\n    ...formOptions,\n  });\n};\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zod-utils/react-hook-form",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "React Hook Form integration and utilities for Zod schemas",
   "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": [