Zod Deep Partial Utility

Common errors

• TypeError: zodDeepPartial is not a function

  cause This error typically occurs when attempting to use `zodDeepPartial` in a CommonJS (`require`) environment where it's incorrectly imported, or when destructuring a named export incorrectly.
  fix Ensure you are using ES module `import` syntax (`import { zodDeepPartial } from 'zod-deep-partial';`) in an environment that supports it. If you must use CommonJS, ensure proper interoperability or transpile your code, or try `const { zodDeepPartial } = require('zod-deep-partial');`.

• ZodError: Required

  cause Even after applying `zodDeepPartial`, some Zod schema types or custom refinements might still enforce 'required' behavior if not handled correctly by the deep partial logic, or if a specific Zod version causes an edge case.
  fix Review your original Zod schema for any `.nonoptional()` or `.required()` calls that might override the deep partial behavior. If the issue persists with basic types, check for a compatibility issue with your `zod` version and `zod-deep-partial` version.

Warnings

• breaking `zod-deep-partial` versions 1.2.0 and later require Zod v4. If your project is still using Zod v3, you must use `zod-deep-partial` versions prior to 1.2.0 (e.g., v1.1.0 or earlier). Zod v4 introduced significant breaking changes in its API and internal types, making it incompatible with older versions of `zod-deep-partial`.
  Fix: Upgrade your project to Zod v4 if possible, ensuring all Zod-related libraries are compatible. If upgrading Zod is not feasible, downgrade `zod-deep-partial` to a version compatible with Zod v3 (e.g., `npm install zod-deep-partial@1.1.0`). Consult Zod's official migration guide for details on updating from Zod v3 to v4.
• gotcha Zod's native `.partial()` method only makes properties optional at the top level of an object schema. Many developers mistakenly expect it to apply recursively. `zodDeepPartial` is specifically designed to address this by recursively applying optionality to all nested properties within a schema.
  Fix: For recursive optionality, always use `zodDeepPartial`. Use Zod's built-in `schema.partial()` only when you intend to make only the top-level properties optional.
• gotcha While `zodDeepPartial` makes properties optional, it does not alter the fundamental type constraints of the properties themselves. For example, a `z.string().email()` property, even if optional, will still fail validation if a non-email string is provided for it (rather than being omitted).
  Fix: Ensure that if an optional property is provided in the input data, it still adheres to the underlying Zod type definition. `zodDeepPartial` loosens the *presence* requirement, not the *type validity* requirement.

Install

• npm install zod-deep-partial npm
• yarn add zod-deep-partial yarn
• pnpm add zod-deep-partial pnpm

Imports

• zodDeepPartial
  wrong:

  const { zodDeepPartial } = require('zod-deep-partial');

  correct:

  import { zodDeepPartial } from 'zod-deep-partial';

  `zod-deep-partial` is an ESM-first package. Use ES module `import` syntax. Direct `require` in CommonJS might fail or require specific configuration.
• z
  wrong:

  const z = require('zod');

  correct:

  import { z } from 'zod';

  While not directly part of `zod-deep-partial`, Zod's `z` object is fundamental for defining schemas and is always used in conjunction with this utility. Use named import for Zod.

Quickstart

This quickstart defines a complex Zod schema including primitives, objects, arrays, records, and dates. It then demonstrates how `zodDeepPartial` recursively applies optionality to all properties, showcasing various valid partial inputs and verifying that type inference is correctly preserved, while also illustrating how underlying type validations (like email format) still apply if the property is provided.

import { z } from "zod";
import { zodDeepPartial } from "zod-deep-partial";

// 1. Define your base schema
const userSchema = z.object({
  name: z.string().min(1, "Name is required"),
  email: z.string().email("Invalid email format"),
  profile: z.object({
    bio: z.string().max(200, "Bio too long"),
    avatar: z.string().url("Invalid URL format").nullable().optional(),
  }),
  tags: z.array(z.string().min(1, "Tag cannot be empty")),
  settings: z.record(z.string(), z.boolean()),
  createdAt: z.date(),
});

// 2. Create the deep partial schema
const partialUserSchema = zodDeepPartial(userSchema);

// 3. Use the partial schema for validation and observe type inference

// All of these are now valid:
try {
  partialUserSchema.parse({});
  console.log("Empty object valid.");
} catch (error) {
  console.error("Validation failed for empty object:", error);
}

try {
  partialUserSchema.parse({ name: "John Doe" });
  console.log("Object with name valid.");
} catch (error) {
  console.error("Validation failed for object with name:", error);
}

try {
  partialUserSchema.parse({ profile: {} });
  console.log("Object with empty profile valid.");
} catch (error) {
  console.error("Validation failed for object with empty profile:", error);
}

try {
  partialUserSchema.parse({ profile: { bio: "A developer" } });
  console.log("Object with partial profile valid.");
} catch (error) {
  console.error("Validation failed for object with partial profile:", error);
}

try {
  partialUserSchema.parse({ tags: ["developer"] });
  console.log("Object with tags valid.");
} catch (error) {
  console.error("Validation failed for object with tags:", error);
}

// Example of what still fails (underlying type validations still apply if present)
try {
  partialUserSchema.parse({ email: "invalid-email" }); // Should fail because 'email' is present but malformed
  console.log("This should not be valid but passed (check expected behavior).");
} catch (error: any) {
  console.log("Expected validation failure for invalid email:", error.issues[0].message);
}

// Type inference is preserved correctly
type PartialUser = z.infer<typeof partialUserSchema>;
// Expected type:
/*
{
    name?: string | undefined;
    email?: string | undefined;
    profile?: {
        bio?: string | undefined;
        avatar?: string | null | undefined;
    } | undefined;
    tags?: (string | undefined)[] | undefined;
    settings?: Record<string, boolean> | undefined;
    createdAt?: Date | undefined;
}
*/
console.log("Type inference for PartialUser looks correct in IDE.");