{"id":12709,"library":"zod-deep-partial","title":"Zod Deep Partial Utility","description":"zod-deep-partial is a lightweight utility package designed to recursively make all properties within a given Zod schema optional. The package is currently at version 1.4.4 and is actively maintained, indicated by recent updates to support Zod v4 and ongoing development on its GitHub repository. Its primary differentiator from Zod's native `.partial()` method is its deep, recursive application of optionality, making it ideal for scenarios like patch updates or handling partially complete data structures. It boasts comprehensive support for a wide array of Zod types, including nested objects, arrays, unions, discriminated unions, intersections, and various transformations, all while maintaining Zod's robust type inference. Crucially, `zod-deep-partial` maintains a minimal footprint by having zero direct dependencies, relying solely on `zod` as a peer dependency.","status":"active","version":"1.4.4","language":"javascript","source_language":"en","source_url":"https://github.com/amirfarzamnia/zod-deep-partial","tags":["javascript","zod","deep","partial","nested","object","typescript"],"install":[{"cmd":"npm install zod-deep-partial","lang":"bash","label":"npm"},{"cmd":"yarn add zod-deep-partial","lang":"bash","label":"yarn"},{"cmd":"pnpm add zod-deep-partial","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the schema definition and validation capabilities that `zod-deep-partial` operates on.","package":"zod","optional":false}],"imports":[{"note":"`zod-deep-partial` is an ESM-first package. Use ES module `import` syntax. Direct `require` in CommonJS might fail or require specific configuration.","wrong":"const { zodDeepPartial } = require('zod-deep-partial');","symbol":"zodDeepPartial","correct":"import { zodDeepPartial } from 'zod-deep-partial';"},{"note":"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.","wrong":"const z = require('zod');","symbol":"z","correct":"import { z } from 'zod';"}],"quickstart":{"code":"import { z } from \"zod\";\nimport { zodDeepPartial } from \"zod-deep-partial\";\n\n// 1. Define your base schema\nconst userSchema = z.object({\n  name: z.string().min(1, \"Name is required\"),\n  email: z.string().email(\"Invalid email format\"),\n  profile: z.object({\n    bio: z.string().max(200, \"Bio too long\"),\n    avatar: z.string().url(\"Invalid URL format\").nullable().optional(),\n  }),\n  tags: z.array(z.string().min(1, \"Tag cannot be empty\")),\n  settings: z.record(z.string(), z.boolean()),\n  createdAt: z.date(),\n});\n\n// 2. Create the deep partial schema\nconst partialUserSchema = zodDeepPartial(userSchema);\n\n// 3. Use the partial schema for validation and observe type inference\n\n// All of these are now valid:\ntry {\n  partialUserSchema.parse({});\n  console.log(\"Empty object valid.\");\n} catch (error) {\n  console.error(\"Validation failed for empty object:\", error);\n}\n\ntry {\n  partialUserSchema.parse({ name: \"John Doe\" });\n  console.log(\"Object with name valid.\");\n} catch (error) {\n  console.error(\"Validation failed for object with name:\", error);\n}\n\ntry {\n  partialUserSchema.parse({ profile: {} });\n  console.log(\"Object with empty profile valid.\");\n} catch (error) {\n  console.error(\"Validation failed for object with empty profile:\", error);\n}\n\ntry {\n  partialUserSchema.parse({ profile: { bio: \"A developer\" } });\n  console.log(\"Object with partial profile valid.\");\n} catch (error) {\n  console.error(\"Validation failed for object with partial profile:\", error);\n}\n\ntry {\n  partialUserSchema.parse({ tags: [\"developer\"] });\n  console.log(\"Object with tags valid.\");\n} catch (error) {\n  console.error(\"Validation failed for object with tags:\", error);\n}\n\n// Example of what still fails (underlying type validations still apply if present)\ntry {\n  partialUserSchema.parse({ email: \"invalid-email\" }); // Should fail because 'email' is present but malformed\n  console.log(\"This should not be valid but passed (check expected behavior).\");\n} catch (error: any) {\n  console.log(\"Expected validation failure for invalid email:\", error.issues[0].message);\n}\n\n// Type inference is preserved correctly\ntype PartialUser = z.infer<typeof partialUserSchema>;\n// Expected type:\n/*\n{\n    name?: string | undefined;\n    email?: string | undefined;\n    profile?: {\n        bio?: string | undefined;\n        avatar?: string | null | undefined;\n    } | undefined;\n    tags?: (string | undefined)[] | undefined;\n    settings?: Record<string, boolean> | undefined;\n    createdAt?: Date | undefined;\n}\n*/\nconsole.log(\"Type inference for PartialUser looks correct in IDE.\");","lang":"typescript","description":"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."},"warnings":[{"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.","message":"`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`.","severity":"breaking","affected_versions":">=1.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"},{"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.","message":"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).","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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');`.","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.","error":"TypeError: zodDeepPartial is not a function"},{"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.","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.","error":"ZodError: Required"}],"ecosystem":"npm"}