Utility types w TypeScript: pełna lista z przykładami

Utility types to typy generyczne wbudowane w TypeScript, które zamieniają jeden typ w inny. Zamiast pisać drugi typ User ze wszystkimi polami opcjonalnymi, piszesz Partial<User>; zamiast kopiować trzy pola, Pick<User, "id" | "name">. Są globalne, więc nie trzeba ich importować.

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

Kiedy User się zmienia, wszystkie cztery typy pochodne zmieniają się razem z nim. Biblioteka standardowa TypeScript (lib.es5.d.ts) deklaruje 22 utility types. Sekcje poniżej wymieniają je wszystkie, pogrupowane według rodzaju typu, na którym działają, z linkiem do szczegółowej strony tam, gdzie taka istnieje.

Typy obiektowe: 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> to przeciwieństwo Partial<T>; strona o Partial omawia oba, łącznie z jawnym undefined, które przepuszcza taki spread jak ten.

Typy unii: 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

Te trzy działają na uniach, nie na obiektach. To najważniejsza różnica względem Pick i Omit, które przyjmują typ obiektowy i listę jego kluczy.

Typy funkcji i klas: Parameters, ReturnType i inne

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 jest potrzebne, bo te utility types przyjmują typ, a createOrder jest wartością. Z klasami jest tak samo: typeof Point to typ konstruktora, a samo Point użyte jako typ oznacza już typ instancji.

NoInfer decyduje, skąd typ generyczny bierze swój typ:

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");

Bez NoInfer TypeScript wywnioskowałby C z obu argumentów i rozszerzył go do "red" | "green" | "blue", więc literówka w wartości zapasowej przeszłaby bez błędu.

Typy dla stringów: Uppercase, Lowercase, Capitalize, Uncapitalize

Te cztery są wbudowane w kompilator, a nie napisane w TypeScript, i najbardziej przydają się w template literal types, na przykład `on${Capitalize<E>}` dla nazw handlerów zdarzeń.

Promise: 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>> to standardowy sposób, żeby nazwać typ wyniku funkcji async bez deklarowania go osobno.

Łączenie utility types

Utility types można zagnieżdżać. Kilka kombinacji pojawia się na tyle często, że warto znać je na pamięć:

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' }

Zagnieżdżony utility type czyta się od środka na zewnątrz: Readonly<Pick<Post, "id" | "title">> najpierw zostawia dwie właściwości, a potem robi je tylko do odczytu. Z tych samych części powstaje helper PartialBy, który robi opcjonalnymi tylko niektóre klucze; strona o Partial pokazuje go w całości.

Utility types nic nie robią w czasie działania programu

Każdy utility type znika podczas kompilacji. Wartość z typem Omit<User, "password"> może w czasie działania nadal zawierać hasło, jeśli obiekt, z którego pochodzi, je miał:

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"}

Typ ogranicza tylko to, co twój kod może odczytać. Żeby usunąć pole z danych, wyjmij je destrukturyzacją jak w ostatnich liniach, a żeby zablokować zmiany w czasie działania, użyj Object.freeze, nie Readonly. Wbudowane typy to jednolinijkowe mapped types i conditional types, więc tymi samymi narzędziami napiszesz własne.