Служебные типы TypeScript: полный список с примерами

Служебные типы это встроенные в TypeScript обобщённые типы, которые превращают один тип в другой. Вместо второго типа User со всеми необязательными полями вы пишете Partial<User>; вместо копирования трёх полей Pick<User, "id" | "name">. Они глобальные, поэтому импорт не нужен.

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

Когда меняется User, все четыре производных типа следуют за ним. Стандартная библиотека TypeScript (lib.es5.d.ts) объявляет 22 служебных типа. Ниже перечислены все они, сгруппированные по виду типов, с которыми работают, со ссылкой на подробную страницу там, где она есть.

Объектные типы: 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> противоположен Partial<T>; страница о Partial описывает оба, включая явное undefined, которое пропускает такое развёртывание.

Типы объединения: 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

Эти три работают с объединениями, а не с объектами. В этом ключевое отличие от Pick и Omit, которые принимают объектный тип и список его ключей.

Типы функций и классов: Parameters, ReturnType и другие

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 нужен потому, что эти утилиты принимают тип, а createOrder это значение. С классами то же самое: typeof Point это тип конструктора, а просто Point как тип уже означает тип экземпляра.

NoInfer управляет тем, откуда дженерик берёт свой тип:

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

Без NoInfer TypeScript вывел бы C из обоих аргументов и расширил бы его до "red" | "green" | "blue", так что опечатка в запасном значении была бы принята.

Строковые типы: Uppercase, Lowercase, Capitalize, Uncapitalize

Эти четыре встроены в компилятор, а не написаны на TypeScript, и полезнее всего внутри шаблонных литеральных типов, например `on${Capitalize<E>}` для имён обработчиков событий.

Промисы: 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>> это стандартный способ назвать тип результата асинхронной функции, не объявляя его отдельно.

Сочетание служебных типов

Служебные типы вкладываются друг в друга. Несколько сочетаний встречаются так часто, что их стоит знать наизусть:

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

Читайте вложенный служебный тип изнутри наружу: Readonly<Pick<Post, "id" | "title">> сначала оставляет два свойства, а затем делает их доступными только для чтения. Из тех же частей строится помощник PartialBy, который делает необязательными только некоторые ключи; он выписан на странице о Partial.

Служебные типы ничего не делают во время выполнения

Каждый служебный тип стирается при компиляции кода. Значение с типом Omit<User, "password"> во время выполнения всё равно может нести пароль, если он был в исходном объекте:

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

Тип только ограничивает то, что вашему коду разрешено читать. Чтобы удалить поле из данных, уберите его деструктуризацией, как в последних строках, а чтобы запретить изменения во время выполнения, используйте Object.freeze, а не Readonly. Встроенные типы это однострочные сопоставленные и условные типы, так что теми же средствами можно написать и свои.