Utility types

What it is and why it exists

TypeScript utility types are generic type aliases supplied by the standard library. They accept one or more types and produce a new type, such as an object with selected optional fields, a filtered union, or a function’s parameter tuple. The result exists only for the type checker; it doesn’t emit a JavaScript function or object.

Utility types solve the problem of keeping related contracts synchronized. If Invoice gains a field, handwritten versions of InvoicePreview, InvoicePatch, and a status index can quietly fall behind; when Pick, Partial, and Record express the transformation, the compiler recalculates the derived type. A reviewer sees the rule between the contracts instead of merely seeing two similar interfaces.

You’ll encounter these types in update commands, public responses, state-handler tables, function wrappers, and union filters. They work best when the derivation itself belongs to the domain contract. If two shapes only happen to look alike today, separate named types are often more honest because their future changes may not belong together.

Utility types don’t validate data, copy objects, freeze values, or remove properties. That boundary follows from type erasure : after compilation, neither Partial<Account> nor Omit<Account, "passwordHash"> exists. Network input, permission fields, and secrets still require runtime validation and projection code.

Choose by intent

Pick is an allowlist: only named fields enter the result, which suits public DTOs and restricted updates. Omit is a denylist: a new source field automatically enters the result, which suits internal transforms that retain everything except a few infrastructure fields. This isn’t a style preference; it decides whether source growth allows or rejects fields by default.

How source changes propagate

A derived type turns source changes into compile-time feedback, but different utilities send that feedback in different directions. Before choosing a public type, simulate adding, removing, and changing source fields and decide whether automatic propagation matches the compatibility policy.

Public responses usually should not expose a field merely because the source grew, so Pick is safer than Omit. An internal persistence preparation step may want the opposite: after removing only an ID and timestamps, all remaining domain fields should continue to flow through, which makes Omit direct.

Partial, Required, and Readonly apply one modifier rule across the entire top-level key set. If a business rule covers only some fields, narrow the keys first or derive groups with different rules separately and combine them. Don’t encode domain permissions as a side effect of technical convenience.

Automatic propagation doesn’t replace versioning judgment. Changing a source field from string to a literal union can still break consumers even though the derived type updates cleanly. Public libraries should review declaration output and run consumer-facing type tests.

How it works

Most object utilities build on mapped types . A mapped type walks the property keys from keyof T, reads each value type through T[P], and can add or remove ? and readonly modifiers. It redescribes properties without traversing or changing a runtime object.

Property mapping and selection

Pick<T, K> requires K to belong to keyof T, so a misspelled field normally fails immediately. The standard Omit<T, K> permits any property key for K; Omit<Account, "paswordHash"> can be valid while omitting nothing. Add type tests for secret fields and migrations, or use a local strict wrapper that constrains K extends keyof T.

Modifiers preserve anything they don’t explicitly change. Partial<T> doesn’t remove readonly, and Readonly<T> doesn’t make an optional property required. Readonly<Partial<T>> therefore means that top-level properties may be absent and may not be reassigned; it doesn’t mean “complete and immutable.”

Union filtering

Exclude, Extract, and NonNullable build on conditional types . When the checked side is a naked type parameter containing a union, the condition distributes over each member and unions the results. That’s why Exclude<"draft" | "paid", "paid"> produces "draft".

The test is assignability, not a nominal label. Extract<Shape, { kind: "circle" }> can select a matching object member because that member is assignable to the target shape. If the target also requires a field the source member lacks, the result may be never; the more specific the filter, the more carefully you should check that it hasn’t discarded valid members.

Function and constructor shapes

Parameters<F> produces a parameter tuple, and ReturnType<F> extracts a function’s return type. ConstructorParameters<C> and InstanceType<C> perform the matching operations on construct signatures. Awaited<T> recursively extracts the eventual value of a Promise or compatible thenable.

These utilities take the function’s type, not the result of calling the function. The usual forms are ReturnType<typeof buildInvoice> and Parameters<typeof buildInvoice>; without typeof, a runtime function value can’t be used directly in a type position. An async function’s ReturnType is still Promise<...>, so add Awaited when you need its fulfilled value.

Overloaded functions need extra care. Conditional inference from several call signatures uses the last signature, usually the broad implementation-compatible one, so Parameters or ReturnType may not preserve the exact relationship represented by every overload. A wrapper that must retain overloads should declare its public overloads explicitly or use a discriminated parameter union instead.

Static structure and runtime values

TypeScript uses structural typing : a value is assignable when it has the required structure. A complete Account value is therefore assignable to Omit<Account, "passwordHash"> because the target stops requiring that field; it doesn’t forbid extra fields.

Object literals receive excess-property checking in some direct assignment positions, but the behavior changes after storing a value in a variable, returning it from a function, or applying an assertion. That check isn’t proof that an object contains no extra properties. If a response must not contain secrets, construct a new object from allowed fields and test the serialized result.

Examples

These four examples build through selection, modifiers, union filtering, read-only shapes, and function-shape utilities in one billing domain. Every output comes from running the shown source with local npx tsx, and the source also passed strict checks with TypeScript 6.0.3.

Derive a minimal update contract

Use Pick to name the fields that callers may change, then use Partial to let a caller submit only some of them. Neither id nor status ever enters the update type, which expresses the permission boundary better than Partial<Invoice>.

Object spread creates the new invoice and retains untouched fields, but that behavior comes from the runtime function, not from Partial. Partial only lets patch omit top-level fields. If a caller supplies recipient, it must still contain both name and email.

This design also performs no runtime validation. If the patch comes from JSON, start from unknown and check allowed keys, value types, and the unknown-field policy before calling applyPatch. Type annotations constrain only data that has already crossed into TypeScript’s trusted boundary.

Keep a closed status table complete

Exclude and Extract derive active and terminal sets from the same status union, while Record requires a next action for every invoice status. Adding a status produces a compile error until the action table receives its matching key.

type InvoiceStatus = "draft" | "sent" | "overdue" | "paid" | "void";
type ActiveStatus = Exclude<InvoiceStatus, "paid" | "void">;
type TerminalStatus = Extract<InvoiceStatus, "paid" | "void">;

const nextAction: Record<InvoiceStatus, string> = {
  draft: "edit",
  sent: "wait",
  overdue: "remind",
  paid: "archive",
  void: "retain",
};

function describe(status: InvoiceStatus): string {
  return `${status}: ${nextAction[status]}`;
}

const active: readonly ActiveStatus[] = ["draft", "sent", "overdue"];
const terminal: readonly TerminalStatus[] = ["paid", "void"];
console.log(active.map(describe).join(" | "));
console.log(terminal.map(describe).join(" | "));

draft: edit | sent: wait | overdue: remind
paid: archive | void: retain

Safe indexing here follows from status: InvoiceStatus matching the finite key set exactly. If the parameter were just string, Record<InvoiceStatus, string> couldn’t prove that the string is a valid status; the boundary would still need to validate or narrow it.

Record<string, string> expresses a different contract: every string key is treated as having a string value. An ordinary JavaScript object doesn’t automatically uphold that runtime promise, so dynamic dictionaries normally need noUncheckedIndexedAccess, an explicit missing-value check, or a Map.

See shallow Readonly in action

Readonly<QueueState> prevents reassignment of the name and jobs properties, but it doesn’t change the array type stored in jobs. To make the snapshot’s array read-only too, declare it as readonly string[] in the source contract or use a recursive type designed for the domain.

interface QueueState {
  name: string;
  jobs: string[];
}

const shallow: Readonly<QueueState> = {
  name: "billing",
  jobs: ["draft"],
};
shallow.jobs.push("send");
console.log(shallow.jobs.join(","));

type QueueSnapshot = Readonly<{ name: string; jobs: readonly string[] }>;
const before: QueueSnapshot = { name: "billing", jobs: ["draft"] };
const after: QueueSnapshot = { ...before, jobs: [...before.jobs, "send"] };
console.log(before.jobs.join(","));
console.log(after.jobs.join(","));

draft,send
draft
draft,send

The second form rejects array mutation at the type level and expresses the state transition by creating a new array. It still isn’t runtime freezing: JavaScript, an assertion, or a mutable alias can change the same object, so untrusted boundaries and shared mutable state require separate controls.

Reuse an async function contract

The wrapper reuses the parameter tuple through Parameters and gets the eventual invoice through Awaited<ReturnType<...>>. If the original function adds a parameter or changes its return shape, the wrapper’s signature is checked again.

async function loadInvoice(id: string, includeTax: boolean) {
  const subtotalCents = 2400;
  return {
    id,
    totalCents: includeTax ? subtotalCents + 480 : subtotalCents,
  };
}

type LoadArgs = Parameters<typeof loadInvoice>;
type LoadedInvoice = Awaited<ReturnType<typeof loadInvoice>>;

async function tracedLoad(...args: LoadArgs): Promise<LoadedInvoice> {
  console.log(`load ${args[0]} tax=${args[1]}`);
  return loadInvoice(...args);
}

async function main(): Promise<void> {
  const invoice = await tracedLoad("inv-42", true);
  console.log(`${invoice.id}: ${invoice.totalCents}`);
}

void main();

load inv-42 tax=true
inv-42: 2880

Type reuse reduces signature duplication, but it doesn’t verify implementation semantics. A generated wrapper can still reorder arguments, swallow rejections, log secrets, or change the this binding; runtime tests and review must cover those behaviors.

Pitfalls

Treating a top-level transform as recursive

Fix: Name the exact nodes that need recursion and prefer domain-specific command types. If you truly need a general recursive utility, handle arrays, tuples, functions, and built-ins separately and review the boundaries in typescript/custom-utility-types; a one-line T[P] extends object definition isn’t enough.

Treating Omit as data redaction

Fix: Construct a new object at runtime through destructuring or an explicit allowlist, then test JSON.stringify or the actual transport payload. Use deny-by-default projections for secrets; don’t expect a return annotation, assertion, or excess-property check to perform deletion.

Designing a patch as Partial of the entity

Fix: Establish the update allowlist with Pick before deciding which fields may be omitted. Give nested patches explicit command types, reject unknown keys at runtime, and use different patch types for operations with different permissions.

Confusing absence with explicit undefined

Fix: Define the API semantics for absence, clearing, and explicit undefined, enable exactOptionalPropertyTypes, and use an explicit null or operation tag when clearing is valid. Test whether the object owns a key instead of relying only on truthiness.

Using Record<string, V> to guarantee any lookup

Fix: Use a literal union for a closed key set. For an open set, enable noUncheckedIndexedAccess and handle absence, or use Map#get, which returns V | undefined. Validate external strings before indexing.

Letting a misspelled Omit pass silently

Fix: Add negative type tests for security-sensitive exclusions, or define StrictOmit<T, K extends keyof T> = Omit<T, K>. Prefer a Pick allowlist for public responses and verify the serialized result at runtime too.

Further reading

• TypeScript Handbook: Utility Types
• TypeScript Handbook: Mapped Types
• TypeScript Handbook: Conditional Types
• TypeScript TSConfig: exactOptionalPropertyTypes
• TypeScript TSConfig: noUncheckedIndexedAccess