TypeScript utility types turn common model transformations into readable, reusable type expressions. This guide explains when to choose Partial, Pick, Omit, Record, and related built-ins, then shows how to extend them with custom mapped and conditional types without making your code harder to maintain.
Overview
Utility types are generic types supplied by TypeScript for transforming existing types. Instead of rewriting a second interface by hand, you can describe the relationship between two models directly. That is especially useful for API request and response types, form state, configuration objects, immutable data, and generated client models.
The best choice depends on the transformation you need:
- Use
Partial<T>when every property is optional, such as a patch or update payload. - Use
Pick<T, K>when you want an explicit allowlist of properties. - Use
Omit<T, K>when you want nearly the whole model except selected properties. - Use
Record<K, V>when a set of keys should map to one value type. - Use
Readonly<T>when consumers should not mutate an object through a particular reference. - Use conditional utilities such as
Exclude,Extract, andNonNullableto filter unions. - Use
ReturnTypeandAwaitedwhen a type should follow an existing function's result.
These utilities do not validate runtime input. An API payload can still contain invalid data unless it is checked at runtime with validation code or a suitable schema tool. Treat utility types as compile-time design constraints, not as a replacement for parsing untrusted data.
Template structure
A useful way to choose a utility type is to describe the transformation in plain language before writing code. Start with a source model, name the boundary being designed, and state what changes.
type User = {
id: string;
email: string;
displayName: string;
role: "admin" | "member";
createdAt: Date;
};
// Boundary: an update request may contain any editable field.
type UserUpdate = Partial<Pick<User, "email" | "displayName">>;
// Boundary: a public view excludes internal fields.
type PublicUser = Omit<User, "createdAt" | "role">;
The reference table below provides a compact decision guide.
| Utility | Transformation | Typical use |
|---|---|---|
Partial<T> | All properties become optional | Patch and update payloads |
Required<T> | All properties become required | Completed configuration or normalized data |
Readonly<T> | Properties become readonly | Immutable input and state views |
Pick<T, K> | Keeps only selected keys | Public views and focused props |
Omit<T, K> | Removes selected keys | Derived models without identifiers or secrets |
Record<K, V> | Maps keys K to values V | Lookup tables and keyed configuration |
Exclude<T, U> | Removes union members assignable to U | Filtering literal unions |
Extract<T, U> | Keeps union members assignable to U | Selecting compatible variants |
NonNullable<T> | Removes null and undefined | Types after a presence check |
ReturnType<F> | Gets a function's return type | Keeping consumers aligned with a factory |
Awaited<T> | Unwraps promise-like results | Async service and API result types |
Prefer the smallest expression that communicates the boundary. A short composition such as Partial<Pick<User, "email" | "displayName">> is often clearer than a new interface that duplicates two properties and can drift from the source model.
How to customize
Built-in utilities cover common cases, but real models often need a more precise transformation. Mapped types let you iterate over keys and change each property according to a rule.
type NullableFields<T> = {
[K in keyof T]: T[K] | null;
};
type UserWithNullableFields = NullableFields<Pick<User, "email" | "displayName">>;
Use a custom mapped type when the same property-level rule applies across a model: adding null, making values optional, changing mutability, or wrapping values in another type. If only one or two keys need special treatment, a named type alias can be easier to read than a generalized abstraction.
Conditional types are useful when the output depends on the input:
type IdOf<T> = T extends { id: infer Id } ? Id : never;
type UserId = IdOf<User>; // string
Here, infer captures the type of id when the input matches the required structure. Conditional types become especially valuable for reusable libraries, but they can be difficult to debug when nested deeply. Give complex expressions a descriptive name and test them with representative examples.
For keyed maps, distinguish between a closed set of keys and arbitrary string keys:
type Status = "draft" | "published" | "archived";
type StatusLabels = Record<Status, string>;
const labels: StatusLabels = {
draft: "Draft",
published: "Published",
archived: "Archived"
};
// Allows any string key, including misspellings.
type LooseLabels = Record<string, string>;
A union of literal keys makes missing or extra known statuses visible during type checking. Record<string, V> is intentionally more open and should be chosen only when arbitrary keys are part of the design.
Examples
API models and DTOs
For create and update operations, separate the server-owned fields from client-editable fields. Omit is useful for a create input when the server supplies an identifier; Partial can then express a patch operation.
type CreateUser = Omit<User, "id" | "createdAt">;
type UpdateUser = Partial<Pick<User, "email" | "displayName">>;
This pattern is a starting point, not a universal API contract. If an endpoint has different validation, permissions, or field semantics, define a dedicated type rather than forcing it to mirror the domain model. For generated API clients, keep generated types separate from hand-authored boundary types so regeneration does not erase intentional adaptations. See the guide to TypeScript API client generation for related workflow considerations.
React props and immutable state
Component props commonly use Pick to accept only the data a component renders. Readonly can document that a helper does not mutate its input.
type UserSummaryProps = Readonly<Pick<User, "displayName" | "role">>;
function formatUser(user: Readonly<User>): string {
return `${user.displayName} (${user.role})`;
}
In React code, utility types should support the component's public contract rather than expose an entire domain object by convenience. More examples of props and event typing are available in this React TypeScript patterns guide.
Union filtering and async results
type Result =
| { kind: "success"; value: User }
| { kind: "error"; message: string };
type SuccessResult = Extract<Result, { kind: "success" }>;
type ErrorResult = Extract<Result, { kind: "error" }>;
type UserFromLoader = Awaited<ReturnType<typeof loadUser>>;
Extract works well with discriminated unions because it selects variants by their identifying property. That keeps related code aligned with exhaustive narrowing patterns; avoid replacing a useful union with a broad object type just to simplify one expression.
When to update
Revisit utility-type choices when a model crosses a new boundary: an API becomes public, a field changes ownership, a generated schema is introduced, or a component starts serving a different use case. These changes can make an old Omit or broad Partial misleading.
- Check the source model. Confirm that derived types still reference the intended fields and that renamed properties have not left stale aliases behind.
- Review optionality. Distinguish “may be absent” from “may be present with an undefined value,” especially when compiler settings and serialization behavior matter.
- Inspect public boundaries. Prefer explicit
Pickallowlists for public responses, package exports, and security-sensitive objects. - Test representative assignments. Add compile-time examples for valid and invalid shapes, and use runtime tests for parsing and validation.
- Simplify before generalizing. If a mapped or conditional type is hard to explain, replace it with a named domain type or split the transformation into smaller aliases.
Keep the project's TypeScript version and compiler settings in mind when reviewing utility behavior. A strict, consistent configuration makes these transformations more useful, while inconsistent settings can hide optionality mistakes. For configuration context, consult the TypeScript tsconfig guide. As a practical next step, choose one duplicated DTO or component prop type, write its source-to-target relationship in plain language, and replace it with the smallest appropriate utility composition. Then run the compiler and tests before applying the pattern elsewhere.