Utility types em TypeScript: a lista completa com exemplos

Utility types são tipos genéricos embutidos no TypeScript que transformam um tipo em outro. Em vez de escrever um segundo tipo User com todos os campos opcionais, você escreve Partial<User>; em vez de copiar três campos, Pick<User, "id" | "name">. Eles são globais, então não é preciso importar nada.

interface User {
  id: number;
  name: string;
  email: string;
  password: string;
}

type UserPatch = Partial<User>;                 // every field optional
type UserCard = Pick<User, "id" | "name">;      // only id and name
type PublicUser = Omit<User, "password">;       // everything but password
type UsersById = Record<number, PublicUser>;    // an object keyed by id

const patch: UserPatch = { email: "new@example.com" };
const card: UserCard = { id: 1, name: "Ada" };
const users: UsersById = {
  1: { id: 1, name: "Ada", email: "ada@example.com" },
};

console.log(patch, card, users[1].email);
// { email: 'new@example.com' } { id: 1, name: 'Ada' } ada@example.com

Quando User muda, os quatro tipos derivados acompanham. A biblioteca padrão do TypeScript (lib.es5.d.ts) declara 22 utility types. As seções abaixo listam todos eles, agrupados pelo tipo de tipo com que trabalham, com um link para a página detalhada quando ela existe.

Tipos de objeto: Partial, Required, Readonly, Pick, Omit, Record

interface Config {
  host: string;
  port?: number;
  debug?: boolean;
}

const defaults: Required<Omit<Config, "host">> = { port: 8080, debug: false };

function withDefaults(config: Config): Readonly<Required<Config>> {
  return { ...defaults, ...config };
}

const cfg = withDefaults({ host: "localhost", debug: true });
console.log(cfg); // { port: 8080, debug: true, host: 'localhost' }
// cfg.port = 1 would be error TS2540: Cannot assign to 'port' because it is a read-only property.

Required<T> é o oposto de Partial<T>; a página de Partial cobre os dois, incluindo o undefined explícito que um spread como este deixa passar.

Union types: Exclude, Extract, NonNullable

type Status = "draft" | "review" | "published" | "archived";

type Live = Exclude<Status, "draft" | "archived">; // "review" | "published"
type Mixed = string | number | (() => void);
type Callable = Extract<Mixed, (...args: never[]) => unknown>; // () => void

function lookup(id: number): string | undefined {
  return id === 1 ? "Ada" : undefined;
}
type Found = NonNullable<ReturnType<typeof lookup>>; // string

const s: Live = "review";
const run: Callable = () => console.log("called");
const found: Found = lookup(1) ?? "nobody";
run();
console.log(s, found); // review Ada

Esses três trabalham com unions, não com objetos. Essa é a diferença principal em relação a Pick e Omit, que recebem um tipo de objeto e uma lista das chaves dele.

Tipos de função e de classe: Parameters, ReturnType e outros

function createOrder(customer: string, items: string[], express = false) {
  return { customer, items, express, total: items.length * 10 };
}

type OrderArgs = Parameters<typeof createOrder>; // [customer: string, items: string[], express?: boolean | undefined]
type Order = ReturnType<typeof createOrder>;     // { customer: string; items: string[]; express: boolean; total: number }

const args: OrderArgs = ["Ada", ["book", "pen"]];
const order: Order = createOrder(...args);
console.log(order.total, order.express); // 20 false

class Point {
  constructor(public x: number, public y: number) {}
}
const coords: ConstructorParameters<typeof Point> = [3, 4];
const p: InstanceType<typeof Point> = new Point(...coords);
console.log(p); // Point { x: 3, y: 4 }

typeof createOrder é necessário porque esses utilities recebem um tipo, e createOrder é um valor. O mesmo vale para classes: typeof Point é o tipo do construtor, enquanto Point sozinho, como tipo, já significa o tipo da instância.

NoInfer controla de onde um generic tira o seu tipo:

function pickColor<C extends string>(colors: C[], fallback: NoInfer<C>): C {
  return colors[0] ?? fallback;
}

console.log(pickColor(["red", "green"], "green")); // red
// @ts-expect-error: "blue" is not "red" | "green"
pickColor(["red", "green"], "blue");

Sem NoInfer, o TypeScript inferiria C a partir dos dois argumentos e o ampliaria para "red" | "green" | "blue", então o erro de digitação no fallback seria aceito.

Tipos de string: Uppercase, Lowercase, Capitalize, Uncapitalize

Esses quatro são embutidos no compilador em vez de escritos em TypeScript, e são mais úteis dentro de template literal types, como `on${Capitalize<E>}` para nomes de handlers de eventos.

Promises: Awaited

async function fetchUser(id: number) {
  return { id, name: "Ada" };
}

type Pending = ReturnType<typeof fetchUser>;           // Promise<{ id: number; name: string }>
type User = Awaited<ReturnType<typeof fetchUser>>;      // { id: number; name: string }

async function main() {
  const user: User = await fetchUser(1);
  const all: User[] = await Promise.all([fetchUser(2), fetchUser(3)]);
  console.log(user.name, all.map((u) => u.id)); // Ada [ 2, 3 ]
}
main();

Awaited<ReturnType<typeof fn>> é o jeito padrão de dar nome ao tipo do resultado de uma função async sem declará-lo separadamente.

Combinando utility types

Utility types se aninham. Algumas combinações aparecem com frequência suficiente para valer a pena saber de cor:

interface Post {
  id: number;
  title: string;
  body: string;
  tags: string[];
}

// Create: everything except the server-generated id
type NewPost = Omit<Post, "id">;
// Update: id required, everything else optional
type PostUpdate = Pick<Post, "id"> & Partial<Omit<Post, "id">>;
// A lookup table of read-only summaries
type PostIndex = Record<number, Readonly<Pick<Post, "id" | "title">>>;

const created: NewPost = { title: "Hello", body: "...", tags: [] };
const update: PostUpdate = { id: 1, title: "Hello again" };
const index: PostIndex = { 2: { id: 2, title: "Idea" } };
console.log(created.title, update, index[2]);
// Hello { id: 1, title: 'Hello again' } { id: 2, title: 'Idea' }

Leia um utility type aninhado de dentro para fora: Readonly<Pick<Post, "id" | "title">> primeiro mantém duas propriedades e depois as torna somente leitura. As mesmas peças montam um helper PartialBy que torna opcionais só algumas chaves; a página de Partial mostra ele completo.

Utility types não fazem nada em tempo de execução

Todo utility type é apagado quando o código é compilado. Um valor com tipo Omit<User, "password"> ainda pode carregar uma senha em tempo de execução se o objeto de onde veio tinha uma:

interface User {
  name: string;
  password: string;
}

const full: User = { name: "Ada", password: "hunter2" };

const leaky: Omit<User, "password"> = full; // allowed: extra properties are fine
console.log(JSON.stringify(leaky)); // {"name":"Ada","password":"hunter2"}

const { password, ...safe } = full;          // this actually removes it
console.log(JSON.stringify(safe));  // {"name":"Ada"}

O tipo só limita o que o seu código tem permissão para ler. Para remover um campo dos dados, tire-o com desestruturação como nas últimas linhas, e para impedir mutação em tempo de execução use Object.freeze, não Readonly. Os tipos embutidos são mapped types e conditional types de uma linha, então as mesmas ferramentas permitem escrever os seus.