TypeScript Utility Types Reference: Practical Patterns for Safer Application Code
utility typestype transformationsreferenceAPI modelscode review

TypeScript Utility Types Reference: Practical Patterns for Safer Application Code

TTypeScript Website Editorial Team
2026-11-08
6 min read

A practical TypeScript utility types reference for choosing Partial, Pick, Omit, Record, ReturnType, Awaited, and custom combinations.

TypeScript utility types let you transform existing models instead of repeating them by hand. This reference explains which helper to choose for common application and API patterns, with practical examples for forms, update payloads, configuration, event maps, and function types.

Overview

Utility types are built-in type transformations. They do not change JavaScript at runtime; they describe a new compile-time view of an existing type. That distinction matters when typing API data: a utility type can express the shape your code expects, but it cannot verify that an untrusted JSON response actually has that shape. Pair static types with runtime validation when data crosses a network or storage boundary. See the TypeScript runtime validation guide for that part of the workflow.

The most useful decision is usually to start with the smallest transformation that communicates intent:

NeedUtility typeTypical use
Make every property optionalPartial<T>PATCH or draft form data
Make every property requiredRequired<T>Completed configuration
Prevent reassignmentReadonly<T>Immutable input or state views
Keep selected propertiesPick<T, K>Public summaries or form fields
Remove selected propertiesOmit<T, K>Create payloads without server fields
Build a keyed objectRecord<K, V>Event maps, status labels, lookup tables
Remove or retain union membersExclude<T, U> and Extract<T, U>Discriminated unions and allowed keys
Remove null and undefinedNonNullable<T>Validated values and strict branches
Read a function's output or inputsReturnType<T> and Parameters<T>Adapters, wrappers, and tests
Unwrap promise-like resultsAwaited<T>Async service and API result types

Template structure

A useful utility-type pattern has three parts: define a source model, derive a focused type, and use that derived type at the boundary where its rules matter. For example:

type User = {
  id: string;
  email: string;
  displayName: string;
  role: 'admin' | 'member';
  createdAt: string;
};

type UserSummary = Pick<User, 'id' | 'displayName' | 'role'>;
type UserUpdate = Partial<Pick<User, 'email' | 'displayName'>>;
type NewUser = Omit<User, 'id' | 'createdAt'>;

Pick makes the public summary explicit. Combining Partial and Pick says that updates may contain either editable field, but cannot contain server-managed fields such as id or createdAt. Omit is convenient for creation payloads, but use it carefully: if the source model later gains a sensitive or server-only field, an omission-based type may need review.

The order of a combination can also communicate the rule. Partial<Pick<User, ...>> means “select these fields, then make them optional.” Conversely, Pick<Partial<User>, ...> usually produces the same property optionality, but the first form is easier to read because it starts with the business boundary.

How to customize

Choose utilities based on the contract you need, not merely on the shortest type expression.

Use Partial for deliberate partial input

Partial<T> is appropriate for a patch operation or a draft that can be incomplete. It is not a substitute for checking whether an object has the fields required to perform an operation. A function that needs a complete user should accept User, not Partial<User> followed by assumptions.

Prefer Pick for allowlists

When an endpoint accepts only a known set of fields, Pick creates an allowlist. This is often safer to review than a broad model with a few properties removed. For external API contracts, consider defining a dedicated type when the payload has different meaning from the domain model.

Use Record for complete keyed collections

type Status = 'idle' | 'loading' | 'success' | 'error';
type StatusLabel = Record<Status, string>;

const labels: StatusLabel = {
  idle: 'Not started',
  loading: 'Loading',
  success: 'Complete',
  error: 'Failed'
};

This pattern makes missing status keys a type error. If keys are not known in advance and missing entries are valid, a broad index signature such as Record<string, string> may better represent the data.

Use union filters for discriminated models

type Event =
  | { kind: 'user.created'; userId: string }
  | { kind: 'invoice.paid'; invoiceId: string }
  | { kind: 'email.failed'; message: string };

type BillingEvent = Extract<Event, { kind: `invoice.${string}` }>;
type NonBillingEvent = Exclude<Event, BillingEvent>;

Extract retains union members assignable to a pattern, while Exclude removes them. This is useful when handlers, queues, or permissions apply to only part of an event model.

Use function utilities at adapter boundaries

async function loadUser(id: string): Promise<User> {
  // implementation omitted
  throw new Error('example');
}

type LoadUserArgs = Parameters<typeof loadUser>;
type LoadedUser = Awaited<ReturnType<typeof loadUser>>;

Parameters produces a tuple of function arguments, ReturnType reads the declared result, and Awaited unwraps promise-like layers. These are helpful for wrappers and test helpers, but avoid making every internal type depend on an implementation detail. A stable named type is often clearer when it represents a public contract.

Examples

Forms and update payloads

type Product = {
  id: string;
  name: string;
  price: number;
  description: string;
  updatedAt: string;
};

type ProductForm = Pick<Product, 'name' | 'price' | 'description'>;
type ProductPatch = Partial<ProductForm>;

type ProductResponse = Readonly<Product>;

Use ProductForm for a form that requires all editable values, ProductPatch for a partial update, and ProductResponse when consumers should not reassign response properties locally. Remember that Readonly prevents assignment through that TypeScript view; it does not freeze the object at runtime.

Configuration with a complete runtime shape

type FeatureFlags = {
  checkout: boolean;
  redesignedSearch: boolean;
  auditLog: boolean;
};

type OptionalFlags = Partial<FeatureFlags>;
type CompleteFlags = Required<FeatureFlags>;

Configuration often arrives in layers. Accept OptionalFlags while merging defaults, then expose CompleteFlags to application code after the merge and any runtime validation have completed.

Custom mapped combinations

type OptionalExcept<T, K extends keyof T> =
  Partial<T> & Pick<T, K>;

type UserInput = OptionalExcept<User, 'email'>;

This custom combination makes every property optional except email. Mapped types can express more specialized transformations, but give them descriptive names and test their behavior with representative assignments. For a broader application architecture, the TypeScript project structure guide can help place shared models and boundary types sensibly.

A common misuse is expecting utility types to validate JSON, remove object keys, or enforce immutability during execution. They do none of those things by themselves. For runtime behavior, write explicit code, use schema validation, or apply an appropriate immutable-data strategy.

When to update

Revisit this reference when a domain model changes, an API adds or removes fields, or a code review reveals repeated manual type declarations. The most important review question is whether a derived type still matches the boundary it represents. A new server-managed field may make an Omit-based creation payload worth checking. A newly required configuration option may mean that defaults, Required, and runtime validation need to change together.

Also review utility types when upgrading TypeScript or adopting new language features. Built-in helpers and inference behavior can evolve, and a custom mapped type may become unnecessary or behave differently in a newer project configuration. Keep examples compiling under the repository's configured TypeScript version rather than relying on an unrelated playground version. Strict compiler settings and lint rules provide useful feedback; the tsconfig guide and TypeScript ESLint setup guide cover those surrounding checks.

As a practical next step, identify one model in your codebase and write down its boundaries: complete entity, creation input, update input, public response, and internal read-only view. Derive only the shapes that genuinely share the same fields, name combinations such as UserPatch or ProductSummary, and add a compile-time test for each important rule. Then run the normal test suite and inspect the runtime validation path. This keeps utility types useful as living documentation rather than allowing them to become opaque shortcuts.

Related Topics

#utility types#type transformations#reference#API models#code review
T

TypeScript Website Editorial Team

Developer Education Editors

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.