iiinova — where your digital self keeps evolving

DEV Community [Unofficial] @dev.to.web.brid.gy · 5h

TypeScript `Partial`, `Required`, and `DeepPartial` in 2026: Which Utility Type Actually Fits Your Use Case

# TypeScript `Partial`, `Required`, and `DeepPartial` in 2026: Which Utility Type Actually Fits Your Use Case > _This article was written with the assistance of AI, under human supervision and review._ Most TypeScript utility type problems stem from teams treating `Partial<T>`, `Required<T>`, and `DeepPartial<T>` as interchangeable shortcuts when each solves a distinct problem. Developers reach for `Partial` to silence compiler errors during form updates, then spend weeks debugging why incomplete objects reached the database. Teams copy `DeepPartial` implementations from Stack Overflow without understanding where the recursion breaks down on arrays and unions. The result is production bugs where the type system promised safety but delivered silent failures. The core issue is that these utilities operate at different depths and serve different phases of data flow. `Partial<T>` makes every property optional at one level. `Required<T>` does the inverse, forcing every property to exist. `DeepPartial<T>` recurses through nested objects, making everything optional all the way down. When you pick the wrong one, the compiler either rejects valid code or accepts broken code. Neither outcome is acceptable in production systems. The solution is a decision tree based on three questions: are you updating or creating, is the structure flat or nested, and do you need guarantees before persistence. Answer those and the right utility type becomes obvious. Apply `Partial` for patch operations where missing fields should be ignored. Use `Required` as a type guard before database writes to enforce completeness. Reserve `DeepPartial` for configuration objects where every nested layer needs optional overrides, and understand its limitations with arrays. This post shows when each utility type fits, how to compose them with `Pick` and `Omit` for precise control, and where `DeepPartial` breaks down in real codebases. The patterns here eliminate the guesswork and give you a reproducible selection process. ## Key Takeaways * `Partial<T>` makes all properties optional at the top level only, ideal for update operations where the client sends a subset of fields. * `Required<T>` forces all properties to be present, serving as a type guard before database writes or API calls that need complete objects. * `DeepPartial<T>` recurses through nested objects to make everything optional, but breaks on arrays and unions without custom conditional logic. * Composing utilities like `Partial<Pick<T, K>>` gives surgical control over which fields are optional and which remain required. * The decision between these types depends on whether you are creating or updating data, whether the structure is flat or nested, and whether you need compile-time guarantees of completeness. ## Understanding Partial: When Optional Properties Save Time (and When They Hide Bugs) `Partial<T>` transforms every property in a type to optional, making it the standard choice for update operations where the client sends only changed fields. The implementation is straightforward: it maps over all keys in `T` and adds the `?` modifier. type Partial<T> = { [P in keyof T]?: T[P]; }; The utility shines when an API receives a PATCH request with a subset of user fields. Without `Partial`, the function signature would require every property, forcing the client to send the entire object even when updating a single field. With `Partial`, the function accepts any combination of properties. interface User { id: string; name: string; email: string; role: string; } function updateUser(id: string, changes: Partial<User>) { // Only the fields in `changes` will be applied // The database layer handles merging with existing record } // Valid calls: updateUser("123", { name: "Alice" }); updateUser("123", { email: "alice@example.com", role: "admin" }); The failure mode here is subtle but expensive. `Partial<T>` does not validate that at least one property exists. An empty object satisfies the type, so code that expects meaningful updates can receive a no-op. When the update function forwards this to a database layer that interprets an empty changeset as "do nothing," the operation silently succeeds without modifying the record. The client receives a 200 response, the user believes the update worked, but the database remains unchanged. // This compiles and runs without error: updateUser("123", {}); // The database operation succeeds but changes nothing // The user sees success but their data is stale The second issue is depth. `Partial<T>` only affects the immediate properties of `T`. Nested objects remain fully required. When the type includes a nested structure, applying `Partial` leaves the nested properties mandatory. interface UserProfile { id: string; settings: { theme: string; notifications: boolean; }; } type PartialProfile = Partial<UserProfile>; // Equivalent to: // { // id?: string; // settings?: { // theme: string; // Still required if settings is provided // notifications: boolean; // Still required if settings is provided // }; // } This matters because developers expect `Partial` to make the entire structure optional. When they try to update just the theme, they must provide the full `settings` object or omit it entirely. The type system rejects a partial settings object. // This fails at compile time: const update: PartialProfile = { settings: { theme: "dark" } // Error: Property 'notifications' is missing }; // Developer is forced to either: // 1. Provide the complete nested object const update1: PartialProfile = { settings: { theme: "dark", notifications: true } }; // 2. Or omit settings entirely const update2: PartialProfile = { id: "123" }; Use `Partial<T>` when the type is flat and you want to allow any subset of properties. Pair it with runtime validation that ensures at least one property exists if the operation should reject empty updates. For nested structures, reach for `DeepPartial<T>` or compose `Partial` with `Pick` to target specific layers. ## Required in Practice: Forcing Complete Objects Before Database Writes `Required<T>` removes the optional modifier from all properties, converting a type with optional fields into one where every property must be present. The built-in implementation mirrors `Partial` but uses the `-?` modifier to strip optionality. type Required<T> = { [P in keyof T]-?: T[P]; }; The primary use case is enforcing completeness at persistence boundaries. When a database table has NOT NULL constraints on certain columns, the ORM or query builder should reject incomplete objects at compile time. `Required` serves as a type guard that runs before the write operation. Consider a user registration flow where the form allows optional fields during editing but the database requires a complete record. The form state uses `Partial<User>` to track incremental changes. Before calling the create method, the code narrows the type to `Required<User>` through a validation function. interface User { id: string; name: string; email: string; age?: number; } type CompleteUser = Required<User>; // Equivalent to: // { // id: string; // name: string; // email: string; // age: number; // No longer optional // } function isCompleteUser(user: Partial<User>): user is CompleteUser { return ( typeof user.id === "string" && typeof user.name === "string" && typeof user.email === "string" && typeof user.age === "number" ); } async function createUser(draft: Partial<User>) { if (!isCompleteUser(draft)) { throw new Error("User data incomplete"); } // TypeScript knows `draft` is CompleteUser here await db.users.insert(draft); // The database receives a guaranteed complete object } This pattern surfaces incomplete data at the application boundary instead of letting it propagate to the database where constraint violations produce runtime errors. The failure happens early with a clear message, and the type system prevents the database call from compiling if the guard is removed. The limitation of `Required` is the same as `Partial`: it only operates on the immediate properties. Nested objects with optional fields remain partially optional after applying `Required` to the parent type. interface Config { api?: { endpoint?: string; timeout?: number; }; } type RequiredConfig = Required<Config>; // Equivalent to: // { // api: { // endpoint?: string; // Still optional // timeout?: number; // Still optional // }; // } The `api` property becomes required, meaning it cannot be undefined. But the properties inside `api` retain their optional status. This is correct for many use cases where the nested object must exist but can be partially populated. When full depth is needed, combine `Required` with a recursive type or apply it to nested interfaces separately. Use `Required<T>` as a type guard before operations that demand complete data. Pair it with runtime validation functions that return type predicates, so the type system narrows the input type to the required form. For nested structures, apply `Required` to each level explicitly or build a recursive `DeepRequired` utility when every layer must be complete. ## DeepPartial: Building the Recursive Type and Why It's Not Built-In `DeepPartial<T>` makes every property optional at all levels of nesting, transforming a deeply nested type into a structure where every leaf and branch can be omitted. TypeScript does not include this as a built-in utility because the recursive logic introduces complexity around edge cases like arrays, unions, and functions. The basic implementation uses conditional types to check if a property is an object, then recursively applies `Partial` to it. If the property is a primitive, it simply becomes optional. type DeepPartial<T> = { [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P]; }; This works for plain nested objects where every layer is a record with string keys. When the type includes an address object with a nested location object, `DeepPartial` makes every property at every level optional. interface User { id: string; profile: { name: string; address: { street: string; city: string; coordinates: { lat: number; lng: number; }; }; }; } type PartialUser = DeepPartial<User>; // Equivalent to: // { // id?: string; // profile?: { // name?: string; // address?: { // street?: string; // city?: string; // coordinates?: { // lat?: number; // lng?: number; // }; // }; // }; // } The utility becomes essential for configuration objects where every nested section should support partial overrides. A deeply nested config with database, cache, and logging sections can accept a minimal override object that only specifies the changed values. The merge logic fills in defaults for missing properties. const defaultConfig = { database: { host: "localhost", port: 5432, pool: { min: 2, max: 10, }, }, cache: { enabled: true, ttl: 300, }, }; function createConfig(overrides: DeepPartial<typeof defaultConfig>) { // Merge overrides with defaults return { database: { ...defaultConfig.database, ...overrides.database, pool: { ...defaultConfig.database.pool, ...overrides.database?.pool, }, }, cache: { ...defaultConfig.cache, ...overrides.cache, }, }; } // Valid calls: createConfig({ database: { port: 3000 } }); createConfig({ cache: { ttl: 600 } }); createConfig({ database: { pool: { max: 20 } } }); The reason TypeScript omits `DeepPartial` from the standard library is that the simple implementation breaks on non-object types. Arrays are objects in JavaScript, so `T[P] extends object` evaluates to true for array properties. The recursion applies `DeepPartial` to the array itself instead of its element type, producing nonsensical results. interface Data { items: string[]; } type PartialData = DeepPartial<Data>; // The naive implementation produces: // { // items?: DeepPartial<string[]>; // } // Which is effectively: // { // items?: { // [index: number]?: string; // length?: number; // // ... plus all Array methods as optional // }; // } The array properties like `length` and methods like `map` become optional, which is meaningless for an array type. The fix requires checking if the type is an array before recursing, then applying `DeepPartial` to the element type and wrapping it back into an array. type DeepPartial<T> = T extends Array<infer U> ? Array<DeepPartial> : T extends object ? { [P in keyof T]?: DeepPartial<T[P]> } : T; This handles arrays correctly by checking `extends Array<infer U>` first, extracting the element type `U`, recursing on it, and returning `Array<DeepPartial>`. The array itself remains an array, and only its elements become deeply partial. The second edge case is union types. When a property is a union like `string | number`, the `extends object` check fails for the entire union even if one branch is an object. The recursion stops prematurely, leaving nested objects in union branches fully required. interface Data { value: { nested: string } | string; } type PartialData = DeepPartial<Data>; // The simple implementation produces: // { // value?: { nested: string } | string; // } // The object branch stays fully required Handling this correctly requires distributive conditional types that apply the recursion to each branch of the union separately. The revised implementation wraps the conditional in a way that distributes over unions. type DeepPartial<T> = T extends Array<infer U> ? Array<DeepPartial> : T extends object ? { [P in keyof T]?: DeepPartialUnion<T[P]> } : T; type DeepPartialUnion<T> = T extends Array<infer U> ? Array<DeepPartial> : T extends object ? { [P in keyof T]?: DeepPartialUnion<T[P]> } : T; This matters because configuration objects in production codebases frequently include unions where a setting can be a simple value or a complex object. Without correct union handling, the type system fails to make those nested objects optional. Use `DeepPartial<T>` for configuration merge operations where every layer needs to support partial overrides. Implement the full version with array and union handling if the types include those structures. For types with arrays of primitives, the simple implementation often suffices. For complex schemas with arrays of objects or union branches with nested properties, the edge case handling becomes mandatory. ## Partial vs Required vs DeepPartial: A Side-by-Side Comparison for Real-World Scenarios The decision between `Partial`, `Required`, and `DeepPartial` depends on whether you are creating or updating data, whether the structure is flat or nested, and whether you need compile-time guarantees of completeness. `Partial<T>` fits update operations on flat types where the client sends a subset of fields. Use it when the API accepts a PATCH request that modifies only the provided properties. The type allows any combination of fields, including an empty object. Pair it with runtime validation if an empty update should be rejected. Do not use `Partial` for nested structures, as it only affects the top level. `Required<T>` fits creation operations or pre-persistence validation where every field must be present. Use it as a type guard before database writes or API calls that demand complete objects. The type forces all properties to exist, surfacing incomplete data at compile time. Do not use `Required` when optional fields are semantically correct, such as a user bio that can be empty. `DeepPartial<T>` fits configuration merges or deeply nested update operations where every layer needs to support partial overrides. Use it when the type has multiple levels of nesting and the client should be able to override any leaf property without providing the entire tree. Implement the full version with array and union handling if the type includes those structures. Do not use `DeepPartial` when only the top level needs to be optional, as it adds unnecessary complexity. A concrete example clarifies the distinctions. Consider a user profile API with create, update, and merge endpoints. The create endpoint requires all fields, so the input type is the base `User` interface or `Required<User>` if the base includes optional properties. The update endpoint accepts a subset of fields, so the input type is `Partial<User>`. The merge endpoint combines a partial nested config with defaults, so the input type is `DeepPartial<UserConfig>`. interface User { id: string; name: string; email: string; bio?: string; } interface UserConfig { preferences: { theme: string; notifications: { email: boolean; push: boolean; }; }; } // Create: all required fields must be present async function createUser(data: Required<Omit<User, "bio">>) { // id, name, email are mandatory; bio is excluded await db.users.insert(data); } // Update: any subset of fields can be modified async function updateUser(id: string, changes: Partial<User>) { // Only the fields in `changes` will be updated await db.users.update(id, changes); } // Merge: deeply nested config with partial overrides function mergeConfig( defaults: UserConfig, overrides: DeepPartial<UserConfig> ): UserConfig { return { preferences: { theme: overrides.preferences?.theme ?? defaults.preferences.theme, notifications: { email: overrides.preferences?.notifications?.email ?? defaults.preferences.notifications.email, push: overrides.preferences?.notifications?.push ?? defaults.preferences.notifications.push, }, }, }; } The implications are immediate. When the create endpoint accidentally accepts `Partial<User>`, incomplete records reach the database and violate NOT NULL constraints. When the update endpoint mistakenly requires `Required<User>`, the client must send the entire object even when changing a single field. When the merge function uses `Partial<UserConfig>` instead of `DeepPartial<UserConfig>`, nested overrides fail to compile unless the client provides the complete nested object. This distinction is critical. Teams that default to `Partial` for all input types encounter runtime errors at persistence boundaries. Teams that over-apply `Required` create APIs that reject valid partial updates. Teams that avoid `DeepPartial` build merge logic that cannot handle granular overrides without verbose type assertions. ## Combining Utility Types: Partial>, Required>, and Composition Patterns Composing utility types with `Pick` and `Omit` provides surgical control over which properties are optional and which remain required. The pattern `Partial<Pick<T, K>>` makes only the picked properties optional while leaving the rest unchanged. The pattern `Required<Omit<T, K>>` makes all properties except the omitted ones required. These compositions solve the problem where `Partial<T>` is too broad and `Required<T>` is too strict. When a form allows editing some fields but others are read-only, the input type should make the editable fields optional and the read-only fields required. `Partial<Pick<T, EditableKeys>>` combined with `Pick<T, ReadOnlyKeys>` expresses this precisely. interface User { id: string; name: string; email: string; role: string; createdAt: Date; } type EditableFields = "name" | "email" | "role"; type ReadOnlyFields = "id" | "createdAt"; type UserUpdateInput = Partial<Pick<User, EditableFields>> & Pick<User, ReadOnlyFields>; // Equivalent to: // { // id: string; // createdAt: Date; // name?: string; // email?: string; // role?: string; // } function updateUser(data: UserUpdateInput) { // id and createdAt are always present // name, email, role are optional const { id, createdAt, ...updates } = data; // Process updates while preserving read-only fields } The inverse pattern uses `Required<Omit<T, K>>` to force all properties except a few to be required. This fits creation endpoints where most fields are mandatory but a small subset is optional. Instead of marking the entire type as required and then making exceptions, omit the optional fields and apply `Required` to the rest. interface User { id: string; name: string; email: string; bio?: string; avatar?: string; } type UserCreateInput = Required<Omit<User, "bio" | "avatar">> & Pick<User, "bio" | "avatar">; // Equivalent to: // { // id: string; // name: string; // email: string; // bio?: string; // avatar?: string; // } function createUser(data: UserCreateInput) { // id, name, email are mandatory // bio, avatar are optional await db.users.insert(data); } This pattern eliminates the need to redefine the type or write verbose conditional logic. The composition expresses the intent directly: these fields are required, those fields are optional. Another useful composition is `Partial<T> & Pick<T, K>` to make most properties optional while keeping a few required. This fits scenarios where the majority of fields can be omitted but a minimal set must be present. interface SearchFilters { query: string; category?: string; minPrice?: number; maxPrice?: number; inStock?: boolean; tags?: string[]; } type MinimalSearch = Partial<SearchFilters> & Pick<SearchFilters, "query">; // Equivalent to: // { // query: string; // Required // category?: string; // minPrice?: number; // maxPrice?: number; // inStock?: boolean; // tags?: string[]; // } function search(filters: MinimalSearch) { // query is guaranteed to exist // All other filters are optional } The failure mode of these compositions is forgetting that intersections with conflicting optionality produce `never`. If `Partial<T>` makes a property optional and `Pick<T, K>` includes the same property as required, the intersection is impossible to satisfy. interface User { id: string; name: string; } // This produces a never type for `name`: type Broken = Partial<User> & Pick<User, "name">; // Because `name?` (from Partial) and `name` (from Pick) conflict Avoid this by ensuring the sets of properties in `Partial` and `Pick` are disjoint. When you want some fields optional and others required, pick the required fields separately and intersect them with a `Partial` of the remaining fields. Use `Partial<Pick<T, K>>` when only specific fields should be optional. Use `Required<Omit<T, K>>` when most fields should be required except a few. Use `Partial<T> & Pick<T, K>` when most fields are optional but a minimal set must be present. Verify that the composed type does not produce `never` for any property by hovering over the type in your editor. ## When DeepPartial Breaks Down: Arrays, Unions, and the Edge Cases Teams Hit in Production `DeepPartial<T>` fails silently on arrays and unions unless the implementation includes special handling for those cases. The naive version treats arrays as objects and recurses into their properties, making array methods like `map` and `length` optional. The result compiles but produces a type that does not match runtime behavior. The specific failure occurs when a type includes an array of objects. Developers expect `DeepPartial` to make the object properties optional while keeping the array itself an array. The naive implementation makes the array structure itself optional, turning it into an object with numeric keys and array methods as optional properties. interface Post { id: string; title: string; tags: string[]; comments: Array<{ id: string; text: string; author: { name: string; email: string; }; }>; } type NaiveDeepPartial<T> = { [P in keyof T]?: T[P] extends object ? NaiveDeepPartial<T[P]> : T[P]; }; type PartialPost = NaiveDeepPartial<Post>; // tags becomes: // { // [index: number]?: string; // length?: number; // map?: (...) => ...; // // All array methods become optional // } The correct implementation checks for arrays before checking for objects. When the type is an array, extract the element type, apply `DeepPartial` to it, and return a new array of the partial element type. This preserves the array structure while making the elements deeply partial. type DeepPartial<T> = T extends Array<infer U> ? Array<DeepPartial> : T extends object ? { [P in keyof T]?: DeepPartial<T[P]> } : T; type PartialPost = DeepPartial<Post>; // tags becomes: string[] // comments becomes: Array<{ // id?: string; // text?: string; // author?: { // name?: string; // email?: string; // }; // }> The second edge case is union types where one branch is an object and the other is a primitive. The `extends object` check evaluates the entire union and fails if any branch is not an object. The recursion stops at the union level, leaving nested objects in the object branch fully required. interface Data { value: { nested: string } | string; } type PartialData = DeepPartial<Data>; // Without union distribution: // { // value?: { nested: string } | string; // } // The object branch stays required The fix uses a helper type that distributes over unions. When `T` is a union `A | B`, the conditional type `T extends any ? ... : ...` applies the true branch to each union member separately. This allows the recursion to handle the object branch and primitive branch independently. type DeepPartial<T> = T extends any ? T extends Array<infer U> ? Array<DeepPartial> : T extends object ? { [P in keyof T]?: DeepPartial<T[P]> } : T : never; type PartialData = DeepPartial<Data>; // With union distribution: // { // value?: { nested?: string } | string; // } // The object branch becomes partial The third edge case is functions. When a property is a function, the naive implementation treats it as an object and tries to recurse into its properties. Functions have properties like `length` and `name`, so the type system allows this. The result is that function properties become optional objects with optional `length` and `name` properties instead of remaining function types. interface Handler { callback: (data: string) => void; } type PartialHandler = DeepPartial<Handler>; // Without function check: // { // callback?: { // length?: number; // name?: string; // // ... // }; // } The fix adds a check for functions before checking for objects. Functions satisfy `extends (...args: any[]) => any`, so that conditional branch returns the function type unchanged. type DeepPartial<T> = T extends any ? T extends Array<infer U> ? Array<DeepPartial> : T extends (...args: any[]) => any ? T : T extends object ? { [P in keyof T]?: DeepPartial<T[P]> } : T : never; The complete implementation handles arrays, unions, and functions. Use it when the type includes any of these structures. For simpler types with only nested objects, the basic version suffices. The additional checks add complexity but prevent silent type errors where the inferred type diverges from runtime behavior. The implication here is immediate. When teams copy a naive `DeepPartial` implementation and apply it to a schema with array properties, the type system accepts code that will fail at runtime. The editor shows no errors, but the code assumes array methods exist when the type has made them optional. The failure surfaces during testing or production when a method call on an array property throws undefined. ## Frequently Asked Questions ### When should I use Partial instead of making properties optional in the interface definition? Use `Partial<T>` when you have a base type that represents complete data but need a variant for update operations. Define optional properties in the interface when those fields are semantically optional in all contexts. `Partial` is a transformation applied to an existing type, while optional properties in the definition are part of the type's core contract. ### Can I use Required to remove undefined from union types like string or undefined? No. `Required<T>` only removes the optional modifier from properties. It does not affect union types that explicitly include `undefined`. Use `NonNullable<T>` to remove `null` and `undefined` from a union type, or use the `-?` mapped type modifier in a custom utility to strip both optionality and undefined from properties. ### Why does DeepPartial make array methods like map and filter optional? The naive `DeepPartial` implementation treats arrays as objects and recurses into their properties, which include methods like `map`. The correct implementation checks for arrays before objects using `T extends Array<infer U>` and applies `DeepPartial` to the element type only, preserving the array structure. ### How do I make only specific nested properties optional without using DeepPartial? Compose `Partial` with `Pick` and intersect the result with the unchanged portions of the type. For a type with a nested object where only some nested properties should be optional, use an intersection type that combines `Partial<Pick<NestedType, Keys>>` with the parent type. ### Can I combine Partial and Required on the same type? Yes, but they must target different properties. Use `Partial<Pick<T, K>>` to make specific properties optional, intersect with `Required<Omit<T, K>>` to require the rest. Applying both to the same property produces a type conflict where the property is simultaneously optional and required, resulting in `never`. ## Conclusion: Choosing the Right Utility Type for Your Use Case The decision tree is straightforward. For flat types where the client sends a subset of fields, use `Partial<T>`. For operations that demand complete objects before persistence, use `Required<T>` as a type guard with runtime validation. For deeply nested structures where every layer needs optional overrides, use `DeepPartial<T>` with array and union handling. For precise control over which properties are optional, compose utilities with `Pick` and `Omit`. The failure modes are predictable. `Partial` on nested types leaves inner objects required. `Required` on creation endpoints with optional fields forces the client to send defaults. `DeepPartial` without edge case handling breaks on arrays and unions. Composition without disjoint property sets produces `never` types. That covers the essential patterns for TypeScript utility types. Apply these in production and the difference will be immediate. The type system will surface incomplete data at compile time, APIs will accept precisely the fields they need, and merge operations will handle granular overrides without verbose assertions. The decision between `Partial`, `Required`, and `DeepPartial` stops being a guess and becomes a reproducible selection based on data flow and structure depth.

010