@zod-utils/react-hook-form 0.6.0 → 0.8.0

package/README.md

@@ -137,6 +137,99 @@ const form = useZodForm({
 - **Type inference**: No manual type annotations needed - everything is inferred from the schema
 - **Zod integration**: Automatically sets up `zodResolver` for validation
 
+#### Using Without Default Values
+
+The `defaultValues` parameter is **optional**. All form fields are automatically treated as optional during editing:
+
+```typescript
+const schema = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+  age: z.number(),
+});
+
+// ✅ No defaultValues needed!
+const form = useZodForm({ schema });
+
+// Fields can be set individually as the user types
+form.setValue("name", "John");
+form.setValue("email", "john@example.com");
+form.setValue("age", 25);
+
+// Validation still enforces the schema on submit
+const onSubmit = form.handleSubmit((data) => {
+  // Type: { name: string; email: string; age: number }
+  console.log(data);
+});
+```
+
+This works because `useZodForm` uses the `Simplify` utility to ensure proper type inference, making all fields optional during editing while preserving exact types after validation.
+
+#### Default Values Type Safety
+
+The `defaultValues` parameter enforces **shallow partial** typing for type safety. This means:
+
+- ✅ **Top-level fields** can be omitted or set to `null`/`undefined`
+- ✅ **Nested objects** can be omitted entirely
+- ❌ **Nested objects** cannot be partially filled - they must be complete if provided
+
+```typescript
+const schema = z.object({
+  user: z.object({
+    name: z.string(),
+    email: z.string().email(),
+    age: z.number(),
+  }),
+  settings: z.object({
+    theme: z.enum(["light", "dark"]),
+    notifications: z.boolean(),
+  }),
+});
+
+// ✅ Correct: Omit nested objects
+const form = useZodForm({
+  schema,
+  defaultValues: {
+    // settings omitted - OK
+  },
+});
+
+// ✅ Correct: Provide complete nested objects
+const form = useZodForm({
+  schema,
+  defaultValues: {
+    user: { name: "John", email: "john@example.com", age: 30 }, // Complete
+    settings: { theme: "dark", notifications: true }, // Complete
+  },
+});
+
+// ❌ TypeScript Error: Partial nested objects not allowed
+const form = useZodForm({
+  schema,
+  defaultValues: {
+    user: { name: "John" }, // ❌ Missing email and age
+  },
+});
+```
+
+**Why this restriction?** This prevents type errors where partial nested objects might be missing required properties. If you need to provide partial nested defaults, use `getSchemaDefaults()` which handles this correctly:
+
+```typescript
+const form = useZodForm({
+  schema,
+  defaultValues: getSchemaDefaults(schema), // ✅ Type-safe partial defaults
+});
+```
+
+**Note:** This restriction only applies to the `defaultValues` parameter. During form editing, all fields still accept `null`/`undefined` as expected:
+
+```typescript
+// ✅ Works! Form inputs still accept null/undefined
+form.setValue("user", null);
+form.setValue("settings", null);
+form.reset({ user: null, settings: undefined });
+```
+
 #### Custom Input Types
 
 You can override the default input type transformation if needed:

package/dist/index.d.mts

@@ -1,6 +1,7 @@
+import { Simplify } from '@zod-utils/core';
 export * from '@zod-utils/core';
 import * as react_hook_form from 'react-hook-form';
-import { FieldValues, DefaultValues, UseFormProps } from 'react-hook-form';
+import { FieldValues, UseFormProps } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
 
@@ -18,14 +19,24 @@ type AddNullToObjects<T> = {
  * - **Arrays**: optional → `type[] | undefined`
  * - **Objects**: optional and nullable → `type | null | undefined`
  *
+ * Uses {@link Simplify} to ensure TypeScript evaluates the type eagerly, which improves
+ * type inference and enables forms to work correctly without `defaultValues`.
+ *
  * @example
  * ```typescript
  * type User = { name: string; tags: string[]; profile: { bio: string } };
  * type FormInput = PartialWithNullableObjects<User>;
- * // { name?: string; tags?: string[]; profile?: { bio: string } | null; }
+ * // Evaluates to: { name?: string; tags?: string[]; profile?: { bio: string } | null; }
+ * ```
+ *
+ * @example
+ * Type inference with useZodForm
+ * ```typescript
+ * const schema = z.object({ name: z.string(), age: z.number() });
+ * const form = useZodForm({ schema }); // ✅ Works without defaultValues
  * ```
  */
-type PartialWithNullableObjects<T> = Partial<AddNullToObjects<T>>;
+type PartialWithNullableObjects<T> = Simplify<Partial<AddNullToObjects<T>>>;
 /**
  * Makes all fields optional and nullable.
  *
@@ -47,8 +58,8 @@ type PartialWithAllNullables<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** (`PartialWithNullableObjects<T>`): Form fields accept `null | undefined` during editing
- * - **Output type** (`T`): Validated data matches exact schema type (no `null | undefined`)
+ * - **Input type** (`PartialWithNullableObjects<TOutput>`): Form fields accept `null | undefined` during editing
+ * - **Output type** (`TOutput`): Validated data matches exact schema type (no `null | undefined`)
  *
  * **Key Benefits:**
  * - ✅ No more "Type 'null' is not assignable to..." TypeScript errors
@@ -56,11 +67,12 @@ type PartialWithAllNullables<T> = {
  * - ✅ Validated output is still type-safe with exact Zod schema types
  * - ✅ Automatic zodResolver setup - no manual configuration needed
  *
- * @template T - The Zod schema output type (extends FieldValues)
+ * @template TOutput - The Zod schema output type (extends FieldValues)
+ * @template TInput - The Zod schema input type (accepts nullable/undefined values during form editing)
  *
  * @param options - Configuration object
- * @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.schema - Zod schema with two-type signature `z.ZodType<TOutput, TInput>`
+ * @param options.defaultValues - Default form values (shallow partial - nested objects must be complete if provided)
  * @param options.zodResolverOptions - Optional zodResolver configuration
  * @param options....formOptions - All other react-hook-form useForm options
  *
@@ -117,6 +129,26 @@ type PartialWithAllNullables<T> = {
  * ```
  *
  * @example
+ * Without default values (all fields are optional during editing)
+ * ```typescript
+ * const schema = z.object({
+ *   name: z.string().min(1),
+ *   email: z.string().email(),
+ *   age: z.number(),
+ * }) satisfies z.ZodType<{ name: string; email: string; age: number }, any>;
+ *
+ * // ✅ No defaultValues needed - fields are optional during editing
+ * const form = useZodForm({ schema });
+ *
+ * // Form fields can be set individually as user types
+ * form.setValue('name', 'John');
+ * form.setValue('email', 'john@example.com');
+ * form.setValue('age', 25);
+ *
+ * // All fields must be valid on submit (per schema validation)
+ * ```
+ *
+ * @example
  * With optional and nullable fields
  * ```typescript
  * const schema = z.object({
@@ -185,10 +217,10 @@ type PartialWithAllNullables<T> = {
  * @see https://zod.dev for Zod schema documentation
  * @since 0.1.0
  */
-declare const useZodForm: <T extends FieldValues, I extends PartialWithAllNullables<T> = PartialWithNullableObjects<T>>({ schema, zodResolverOptions, ...formOptions }: {
-    schema: z.ZodType<T, I>;
-    defaultValues?: DefaultValues<I>;
+declare const useZodForm: <TOutput extends FieldValues, TFormInput extends PartialWithAllNullables<TOutput> = PartialWithNullableObjects<TOutput>, TInput extends TFormInput = TFormInput, TDefault extends TFormInput = TFormInput>({ schema, zodResolverOptions, ...formOptions }: {
+    schema: z.ZodType<TOutput, TInput>;
+    defaultValues?: TDefault;
     zodResolverOptions?: Parameters<typeof zodResolver>[1];
-} & Omit<UseFormProps<I, unknown, T>, "resolver" | "defaultValues">) => react_hook_form.UseFormReturn<I, unknown, T>;
+} & Omit<UseFormProps<TFormInput, unknown, TOutput>, "resolver" | "defaultValues">) => react_hook_form.UseFormReturn<TFormInput, unknown, TOutput>;
 
 export { type PartialWithAllNullables, type PartialWithNullableObjects, useZodForm };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
+import { Simplify } from '@zod-utils/core';
 export * from '@zod-utils/core';
 import * as react_hook_form from 'react-hook-form';
-import { FieldValues, DefaultValues, UseFormProps } from 'react-hook-form';
+import { FieldValues, UseFormProps } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
 
@@ -18,14 +19,24 @@ type AddNullToObjects<T> = {
  * - **Arrays**: optional → `type[] | undefined`
  * - **Objects**: optional and nullable → `type | null | undefined`
  *
+ * Uses {@link Simplify} to ensure TypeScript evaluates the type eagerly, which improves
+ * type inference and enables forms to work correctly without `defaultValues`.
+ *
  * @example
  * ```typescript
  * type User = { name: string; tags: string[]; profile: { bio: string } };
  * type FormInput = PartialWithNullableObjects<User>;
- * // { name?: string; tags?: string[]; profile?: { bio: string } | null; }
+ * // Evaluates to: { name?: string; tags?: string[]; profile?: { bio: string } | null; }
+ * ```
+ *
+ * @example
+ * Type inference with useZodForm
+ * ```typescript
+ * const schema = z.object({ name: z.string(), age: z.number() });
+ * const form = useZodForm({ schema }); // ✅ Works without defaultValues
  * ```
  */
-type PartialWithNullableObjects<T> = Partial<AddNullToObjects<T>>;
+type PartialWithNullableObjects<T> = Simplify<Partial<AddNullToObjects<T>>>;
 /**
  * Makes all fields optional and nullable.
  *
@@ -47,8 +58,8 @@ type PartialWithAllNullables<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** (`PartialWithNullableObjects<T>`): Form fields accept `null | undefined` during editing
- * - **Output type** (`T`): Validated data matches exact schema type (no `null | undefined`)
+ * - **Input type** (`PartialWithNullableObjects<TOutput>`): Form fields accept `null | undefined` during editing
+ * - **Output type** (`TOutput`): Validated data matches exact schema type (no `null | undefined`)
  *
  * **Key Benefits:**
  * - ✅ No more "Type 'null' is not assignable to..." TypeScript errors
@@ -56,11 +67,12 @@ type PartialWithAllNullables<T> = {
  * - ✅ Validated output is still type-safe with exact Zod schema types
  * - ✅ Automatic zodResolver setup - no manual configuration needed
  *
- * @template T - The Zod schema output type (extends FieldValues)
+ * @template TOutput - The Zod schema output type (extends FieldValues)
+ * @template TInput - The Zod schema input type (accepts nullable/undefined values during form editing)
  *
  * @param options - Configuration object
- * @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.schema - Zod schema with two-type signature `z.ZodType<TOutput, TInput>`
+ * @param options.defaultValues - Default form values (shallow partial - nested objects must be complete if provided)
  * @param options.zodResolverOptions - Optional zodResolver configuration
  * @param options....formOptions - All other react-hook-form useForm options
  *
@@ -117,6 +129,26 @@ type PartialWithAllNullables<T> = {
  * ```
  *
  * @example
+ * Without default values (all fields are optional during editing)
+ * ```typescript
+ * const schema = z.object({
+ *   name: z.string().min(1),
+ *   email: z.string().email(),
+ *   age: z.number(),
+ * }) satisfies z.ZodType<{ name: string; email: string; age: number }, any>;
+ *
+ * // ✅ No defaultValues needed - fields are optional during editing
+ * const form = useZodForm({ schema });
+ *
+ * // Form fields can be set individually as user types
+ * form.setValue('name', 'John');
+ * form.setValue('email', 'john@example.com');
+ * form.setValue('age', 25);
+ *
+ * // All fields must be valid on submit (per schema validation)
+ * ```
+ *
+ * @example
  * With optional and nullable fields
  * ```typescript
  * const schema = z.object({
@@ -185,10 +217,10 @@ type PartialWithAllNullables<T> = {
  * @see https://zod.dev for Zod schema documentation
  * @since 0.1.0
  */
-declare const useZodForm: <T extends FieldValues, I extends PartialWithAllNullables<T> = PartialWithNullableObjects<T>>({ schema, zodResolverOptions, ...formOptions }: {
-    schema: z.ZodType<T, I>;
-    defaultValues?: DefaultValues<I>;
+declare const useZodForm: <TOutput extends FieldValues, TFormInput extends PartialWithAllNullables<TOutput> = PartialWithNullableObjects<TOutput>, TInput extends TFormInput = TFormInput, TDefault extends TFormInput = TFormInput>({ schema, zodResolverOptions, ...formOptions }: {
+    schema: z.ZodType<TOutput, TInput>;
+    defaultValues?: TDefault;
     zodResolverOptions?: Parameters<typeof zodResolver>[1];
-} & Omit<UseFormProps<I, unknown, T>, "resolver" | "defaultValues">) => react_hook_form.UseFormReturn<I, unknown, T>;
+} & Omit<UseFormProps<TFormInput, unknown, TOutput>, "resolver" | "defaultValues">) => react_hook_form.UseFormReturn<TFormInput, unknown, TOutput>;
 
 export { type PartialWithAllNullables, type PartialWithNullableObjects, useZodForm };

package/dist/index.js

@@ -5,6 +5,8 @@ var zod = require('@hookform/resolvers/zod');
 var reactHookForm = require('react-hook-form');
 
 var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
 var __getOwnPropSymbols = Object.getOwnPropertySymbols;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __propIsEnum = Object.prototype.propertyIsEnumerable;
@@ -20,6 +22,7 @@ var __spreadValues = (a, b) => {
     }
   return a;
 };
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
 var __objRest = (source, exclude) => {
   var target = {};
   for (var prop in source)
@@ -40,10 +43,16 @@ var useZodForm = (_a) => {
     "schema",
     "zodResolverOptions"
   ]);
-  const resolver = zod.zodResolver(schema, zodResolverOptions);
-  return reactHookForm.useForm(__spreadValues({
+  const resolver = zod.zodResolver(
+    schema,
+    zodResolverOptions
+  );
+  const defaultValues = formOptions.defaultValues;
+  return reactHookForm.useForm(__spreadProps(__spreadValues({
     resolver
-  }, formOptions));
+  }, formOptions), {
+    defaultValues
+  }));
 };
 
 exports.useZodForm = useZodForm;

package/dist/index.js.map

@@ -1 +1 @@
-{"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"]}
+{"version":3,"sources":["../src/use-zod-form.ts"],"names":["zodResolver","useForm"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiLO,IAAM,UAAA,GAAa,CAMxB,EAAA,KAWI;AAXJ,EAAA,IAAA,EAAA,GAAA,EAAA,EACA;AAAA,IAAA,MAAA;AAAA,IACA;AAAA,GAzLF,GAuLE,EAAA,EAGG,WAAA,GAAA,SAAA,CAHH,EAAA,EAGG;AAAA,IAFH,QAAA;AAAA,IACA;AAAA,GAAA,CAAA;AAUA,EAAA,MAAM,QAAA,GAAWA,eAAA;AAAA,IACf,MAAA;AAAA,IACA;AAAA,GACF;AAIA,EAAA,MAAM,gBAAgB,WAAA,CAAY,aAAA;AAElC,EAAA,OAAOC,qBAAA,CAAQ,aAAA,CAAA,cAAA,CAAA;AAAA,IACb;AAAA,GAAA,EACG,WAAA,CAAA,EAFU;AAAA,IAGb;AAAA,GACF,CAAC,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<TOutput>`): Form fields accept `null | undefined` during editing\n * - **Output type** (`TOutput`): 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 TOutput - The Zod schema output type (extends FieldValues)\n * @template TInput - The Zod schema input type (accepts nullable/undefined values during form editing)\n *\n * @param options - Configuration object\n * @param options.schema - Zod schema with two-type signature `z.ZodType<TOutput, TInput>`\n * @param options.defaultValues - Default form values (shallow partial - nested objects must be complete if provided)\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 * Without default values (all fields are optional during editing)\n * ```typescript\n * const schema = z.object({\n *   name: z.string().min(1),\n *   email: z.string().email(),\n *   age: z.number(),\n * }) satisfies z.ZodType<{ name: string; email: string; age: number }, any>;\n *\n * // ✅ No defaultValues needed - fields are optional during editing\n * const form = useZodForm({ schema });\n *\n * // Form fields can be set individually as user types\n * form.setValue('name', 'John');\n * form.setValue('email', 'john@example.com');\n * form.setValue('age', 25);\n *\n * // All fields must be valid on submit (per schema validation)\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  TOutput extends FieldValues,\n  TFormInput extends\n    PartialWithAllNullables<TOutput> = PartialWithNullableObjects<TOutput>,\n  TInput extends TFormInput = TFormInput,\n  TDefault extends TFormInput = TFormInput,\n>({\n  schema,\n  zodResolverOptions,\n  ...formOptions\n}: {\n  schema: z.ZodType<TOutput, TInput>;\n  defaultValues?: TDefault;\n  zodResolverOptions?: Parameters<typeof zodResolver>[1];\n} & Omit<\n  UseFormProps<TFormInput, unknown, TOutput>,\n  'resolver' | 'defaultValues'\n>) => {\n  const resolver = zodResolver<TFormInput, unknown, TOutput>(\n    schema,\n    zodResolverOptions,\n  );\n\n  // can't help but to assert here - because DefaultValues<TDefault> makes object fields DeepPartial\n  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n  const defaultValues = formOptions.defaultValues as DefaultValues<TDefault>;\n\n  return useForm({\n    resolver,\n    ...formOptions,\n    defaultValues,\n  });\n};\n"]}

package/dist/index.mjs

@@ -3,6 +3,8 @@ import { zodResolver } from '@hookform/resolvers/zod';
 import { useForm } from 'react-hook-form';
 
 var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
 var __getOwnPropSymbols = Object.getOwnPropertySymbols;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __propIsEnum = Object.prototype.propertyIsEnumerable;
@@ -18,6 +20,7 @@ var __spreadValues = (a, b) => {
     }
   return a;
 };
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
 var __objRest = (source, exclude) => {
   var target = {};
   for (var prop in source)
@@ -38,10 +41,16 @@ var useZodForm = (_a) => {
     "schema",
     "zodResolverOptions"
   ]);
-  const resolver = zodResolver(schema, zodResolverOptions);
-  return useForm(__spreadValues({
+  const resolver = zodResolver(
+    schema,
+    zodResolverOptions
+  );
+  const defaultValues = formOptions.defaultValues;
+  return useForm(__spreadProps(__spreadValues({
     resolver
-  }, formOptions));
+  }, formOptions), {
+    defaultValues
+  }));
 };
 
 export { useZodForm };

package/dist/index.mjs.map

@@ -1 +1 @@
-{"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"]}
+{"version":3,"sources":["../src/use-zod-form.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiLO,IAAM,UAAA,GAAa,CAMxB,EAAA,KAWI;AAXJ,EAAA,IAAA,EAAA,GAAA,EAAA,EACA;AAAA,IAAA,MAAA;AAAA,IACA;AAAA,GAzLF,GAuLE,EAAA,EAGG,WAAA,GAAA,SAAA,CAHH,EAAA,EAGG;AAAA,IAFH,QAAA;AAAA,IACA;AAAA,GAAA,CAAA;AAUA,EAAA,MAAM,QAAA,GAAW,WAAA;AAAA,IACf,MAAA;AAAA,IACA;AAAA,GACF;AAIA,EAAA,MAAM,gBAAgB,WAAA,CAAY,aAAA;AAElC,EAAA,OAAO,OAAA,CAAQ,aAAA,CAAA,cAAA,CAAA;AAAA,IACb;AAAA,GAAA,EACG,WAAA,CAAA,EAFU;AAAA,IAGb;AAAA,GACF,CAAC,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<TOutput>`): Form fields accept `null | undefined` during editing\n * - **Output type** (`TOutput`): 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 TOutput - The Zod schema output type (extends FieldValues)\n * @template TInput - The Zod schema input type (accepts nullable/undefined values during form editing)\n *\n * @param options - Configuration object\n * @param options.schema - Zod schema with two-type signature `z.ZodType<TOutput, TInput>`\n * @param options.defaultValues - Default form values (shallow partial - nested objects must be complete if provided)\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 * Without default values (all fields are optional during editing)\n * ```typescript\n * const schema = z.object({\n *   name: z.string().min(1),\n *   email: z.string().email(),\n *   age: z.number(),\n * }) satisfies z.ZodType<{ name: string; email: string; age: number }, any>;\n *\n * // ✅ No defaultValues needed - fields are optional during editing\n * const form = useZodForm({ schema });\n *\n * // Form fields can be set individually as user types\n * form.setValue('name', 'John');\n * form.setValue('email', 'john@example.com');\n * form.setValue('age', 25);\n *\n * // All fields must be valid on submit (per schema validation)\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  TOutput extends FieldValues,\n  TFormInput extends\n    PartialWithAllNullables<TOutput> = PartialWithNullableObjects<TOutput>,\n  TInput extends TFormInput = TFormInput,\n  TDefault extends TFormInput = TFormInput,\n>({\n  schema,\n  zodResolverOptions,\n  ...formOptions\n}: {\n  schema: z.ZodType<TOutput, TInput>;\n  defaultValues?: TDefault;\n  zodResolverOptions?: Parameters<typeof zodResolver>[1];\n} & Omit<\n  UseFormProps<TFormInput, unknown, TOutput>,\n  'resolver' | 'defaultValues'\n>) => {\n  const resolver = zodResolver<TFormInput, unknown, TOutput>(\n    schema,\n    zodResolverOptions,\n  );\n\n  // can't help but to assert here - because DefaultValues<TDefault> makes object fields DeepPartial\n  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n  const defaultValues = formOptions.defaultValues as DefaultValues<TDefault>;\n\n  return useForm({\n    resolver,\n    ...formOptions,\n    defaultValues,\n  });\n};\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zod-utils/react-hook-form",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "React Hook Form integration and utilities for Zod schemas",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",