Partial, Pick, Omit, Record, ReturnType, Awaited

Функция обновления настроек принимает не весь объект, а его кусок: пользователь поменял размер шрифта — про тему и перенос строк в этом вызове не сказано ничего. Описать «кусок» отдельным типом руками несложно, но это копия, которая разойдётся с оригиналом на первом же новом поле.

type Options = { theme: string; fontSize: number; wrap: boolean };
const DEFAULTS: Options = { theme: "dark", fontSize: 14, wrap: true };
// Partial<Options> — тот же набор полей, но каждое стало необязательным
function withDefaults(user: Partial<Options>): Options {
  return { ...DEFAULTS, ...user };
}
console.log(withDefaults({ fontSize: 18 }).theme);
console.log(withDefaults({}).fontSize);
console.log(withDefaults({ wrap: "нет" }).wrap);

Последняя строка ловит TS2322: Тип "string" не может быть назначен для типа "boolean | undefined". Необязательность — единственное, что Partial поменял: поле wrap теперь можно не писать вовсе, но написать в него что попало по-прежнему нельзя.

Особого статуса у Partial нет. Он объявлен в lib.es5.d.ts — файле, который компилятор подкладывает к любому проекту, — а всё объявление — одно выражение в фигурных скобках. Его можно переписать себе и получить неотличимый тип.

type User = { id: number; name: string };
// ровно этот тип лежит в lib.es5.d.ts под именем Partial
type MyPartial<T> = { [P in keyof T]?: T[P] };
const draft: MyPartial<User> = { name: "Боб" };
const same: Partial<User> = draft;
console.log(same.name);
console.log(same.id);

[P in keyof T] читается как «пройти по всем ключам T», ? — «сделать необязательным», T[P] — «оставить тот же тип значения», тот самый индексный доступ из прошлой статьи. Механику сопоставленных типов разбираем в следующей главе, а здесь важнее обратное: из этой строки видно, чего Partial не делает.

Он идёт по ключам верхнего уровня и на этом останавливается. Вложенный объект переносится как есть — со всеми своими обязательными полями.

type Settings = {
  theme: string;
  editor: { font: string; size: number };
};
const draft: Partial<Settings> = { editor: { font: "Menlo" } };
console.log(draft.theme);

TS2741: Свойство "size" отсутствует в типе "{ font: string; }". Само поле editor стало необязательным — но раз уж вы его пишете, объект внутри должен быть полным. Готового «глубокого» Partial в стандартной библиотеке нет: такой пишется рекурсивным сопоставленным типом, и это тема главы про условные и сопоставленные типы.

Partial ничего не меняет в объекте — он строит новый тип. В скомпилированном JavaScript от него не остаётся ни следа.

type Options = { theme: string; fontSize: number };
const DEFAULTS: Options = { theme: "dark", fontSize: 14 };
function withDefaults(user: Partial<Options>): Options {
  return { ...DEFAULTS, ...user };
}
const settings = withDefaults({ theme: undefined });
console.log(settings.theme);
console.log(settings.theme.toUpperCase());

Из одного типа сущности почти всегда вырастает несколько: полная запись, урезанная карточка для списка, безопасный вид для отдачи наружу. Pick перечисляет, что оставить, Omit — что выбросить.

type User = { id: number; name: string; email: string; passwordHash: string };
type UserCard = Pick<User, "id" | "name">;
type PublicUser = Omit<User, "passwordHash">;
const card: UserCard = { id: 1, name: "Боб" };
const shown: PublicUser = { id: 1, name: "Боб", email: "bob@mail.ru" };
console.log(card.name, shown.email);
const leak: PublicUser = { id: 1, name: "Боб", email: "bob@mail.ru", passwordHash: "x" };
console.log(leak.id);

Строка с leak — TS2353: Объектный литерал может использовать только известные свойства. "passwordHash" не существует в типе "PublicUser". Поле не помечено «не показывать», его в типе просто нет, и проверка лишних свойств из главы про структурную типизацию срабатывает на нём как на чужом.

Выглядят эти двое парой, но устроены по-разному, и разница вылезает на первой же опечатке.

type User = { id: number; name: string; email: string };
type Card = Pick<User, "nmae">; // опечатка
type Safe = Omit<User, "emial">; // такая же опечатка
const safe: Safe = { id: 2, name: "Ева", email: "eva@mail.ru" };
console.log(safe.email);

Диагностика ровно одна, на второй строке: TS2344: Тип ""nmae"" не удовлетворяет ограничению "keyof User" — двойные кавычки не опечатка, так компилятор оформляет имя литерального типа. На Omit — тишина: тип получился полным, и ошибку вы найдёте не раньше, чем заметите почту там, где её быть не должно.

Ответ снова в определениях: type Pick<T, K extends keyof T> против type Omit<T, K extends keyof any>. У Pick второй параметр ограничен ключами T, у Omit — «чем угодно, что вообще бывает ключом», то есть string | number | symbol. Так задумано: Omit разрешают применять и к типам, где такого ключа может не быть. Цена свободы — непойманная опечатка.

Перечисляйте то, чего меньше. Но помните про строгость: Pick сломается сразу, если поле в исходном типе переименовали, а Omit молча вернёт лишнее.

type Guest = { kind: "guest"; visits: number };
type Member = { kind: "member"; email: string };
type Person = Guest | Member;
type Anon = Omit<Person, "kind">;
const eva: Anon = { email: "eva@mail.ru" };
console.log(eva.email);

Record вы уже применяли как словарь — Record<string, number> вместо индексной сигнатуры. В этой главе у него другая работа: набор ключей не обязан быть написан руками, его можно вычислить из существующего типа.

type User = { id: number; name: string; email: string; age: number };
// подписи для формы: ключи берём не из головы, а из самого User
const labels: Record<keyof User, string> = {
  id: "Номер",
  name: "Имя",
  email: "Почта"
};
console.log(labels.name);

TS2741: Свойство "age" отсутствует в типе "{ id: string; name: string; email: string; }" и является обязательным в типе "Record<keyof User, string>". Таблица подписей перестала жить своей жизнью: добавили поле в User — компилятор сам привёл вас туда, где для него нет подписи.

Определение и здесь короткое: type Record<K extends keyof any, T> = { [P in K]: T }. Отсюда сразу два следствия. Ключи обязательны все до одного — просто потому, что в строке нет ?. И утилиты складываются друг с другом: Record отдаёт обычный тип объекта, а Partial принимает любой тип.

type Status = "новая" | "работа" | "готово";
const counts: Partial<Record<Status, number>> = { "новая": 2 };
console.log(counts["новая"]);
console.log(counts["готово"]);
console.log((counts["готово"] ?? 0) + 1);

Partial<Record<Status, number>> — честная запись «таблица, которая заполняется постепенно»: тип значения стал number | undefined, и без ?? прибавить единицу компилятор не даст. Именно так стоит описывать счётчики, к которым добавляют по ключу за раз.

Record<keyof T, X> и Record<Объединение, X> дают проверку полноты. Record<string, X> — нет: там ключи произвольные, проверять нечего.

Функция уже описывает форму своего результата — телом. Записать рядом тип, повторяющий ту же форму, значит завести вторую копию правды и обречь себя следить за обеими. ReturnType и Parameters достают из функции её собственные типы.

function makePoint(x: number, y: number) {
  return { x, y, label: x + ":" + y };
}
type Point = ReturnType<makePoint>;
const p: ReturnType<typeof makePoint> = makePoint(1, 2);
console.log(p.label);
type Args = Parameters<typeof makePoint>;
const args: Args = [3, 4]; // кортеж из типов параметров
console.log(makePoint(...args).label);

Четвёртая строка — TS2749: "makePoint" относится к значению, но здесь используется как тип. Возможно, вы имели в виду "typeof makePoint"? Компилятор угадал верно: ReturnType ждёт тип функции, а makePoint — значение. Мост между мирами один — typeof из первой статьи главы, и без него утилиты по функциям не работают.

Parameters отдаёт кортеж — [number, number], а не объект; отсюда и расширение makePoint(...args) в последней строке. Но чаще нужен всё-таки ReturnType, и особенно там, где тип возврата не написан нигде: компилятор вывел его сам, а вам нужно то же самое имя для этого типа.

function parseQuery(raw: string) {
  const params: Record<string, string> = {};
  for (const pair of raw.split("&")) {
    const [key, value] = pair.split("=");
    params[key] = value ?? "";
  }
  return { raw, params, count: Object.keys(params).length };
}
// тип возврата нигде не написан — ни в функции, ни рядом с ней
type Query = ReturnType<typeof parseQuery>;
function describe(query: Query): string {
  return "параметров: " + query.count + ", первый — " + Object.keys(query.params)[0];
}
console.log(describe(parseQuery("page=2&sort=new")));

У parseQuery нет ни одной аннотации возврата, и всё равно describe знает про count и params. Добавите в возвращаемый объект поле — Query получит его сам; уберёте count — describe перестанет компилироваться в ту же секунду.

function first<T>(items: T[]): T {
  return items[0];
}
type First = ReturnType<typeof first>;
const value: First = 5;
console.log(value.toFixed(2));

С асинхронной функцией ReturnType честен до неудобства: она возвращает промис, его он и отдаёт.

async function loadUser(id: number) {
  return { id, name: "Боб", roles: ["admin"] };
}
type Loaded = ReturnType<typeof loadUser>;
const bad: Loaded = { id: 1, name: "Боб", roles: [] };
type User = Awaited<ReturnType<typeof loadUser>>;
function greet(user: User) {
  console.log("Привет, " + user.name);
}
loadUser(1).then(greet);

TS2353 с говорящим хвостом: "id" не существует в типе "Promise<{ id: number; name: string; roles: string[]; }>". Компилятор не ошибся — в Loaded действительно промис. До нужного типа не хватает одного шага: снять обёртку, и это Awaited.

type Deep = Awaited<Promise<Promise<number>>>;
const n: Deep = "текст";
type Plain = Awaited<string>;
const s: Plain = 42;
console.log(n, s);

Две диагностики говорят одно и то же с разных сторон: Тип "string" не может быть назначен для типа "number" — значит, обе обёртки сняты; Тип "number" не может быть назначен для типа "string" — значит, с непромисом Awaited не делает ничего. Он повторяет в типах поведение самого await, вплоть до рекурсии, и потому в его определении стоит условный тип, а не одна строка.

В связке с индексным доступом получается приём, ради которого эту главу и писали: тип одного элемента ответа, ни разу не описанный руками.

async function loadOrders(userId: number) {
  await new Promise<void>((done) => setTimeout(done, 10));
  return [
    { id: 1, sum: 100, userId },
    { id: 2, sum: 250, userId }
  ];
}
// взять тип возврата, снять промис, взять элемент массива
type Order = Awaited<ReturnType<typeof loadOrders>>[number];
function renderOrder(order: Order): string {
  return "заказ №" + order.id + " на " + order.sum;
}
loadOrders(7).then((orders) => console.log(orders.map(renderOrder).join(", ")));

Три шага в одну строку — и ни одного поля, написанного дважды. Поменяется тело loadOrders, и renderOrder перестанет компилироваться ровно там, где перестал быть правдой.

Awaited нужен не только для async: то же самое достаёт тип из любого значения-промиса, включая чужие функции, которые вернули Promise<Promise<T>>.

Утилит в стандартной библиотеке пара десятков, и почти все — такие же короткие определения. Вот те, что встречаются в реальном коде чаще прочих.

Половина колонки «определение» пока выглядит шифром — in, extends ? : и infer разбираются в следующей главе, и пользоваться утилитами это не мешает. Две из таблицы стоит попробовать прямо сейчас: они закрывают самые частые бытовые нужды.

type Draft = { title?: string; price?: number };
type Ready = Required<Draft>;
const ok: Ready = { title: "Кофе", price: 300 };
console.log(ok.title.toUpperCase());
const bad: Ready = { title: "Чай" };
type Sure = NonNullable<string | null | undefined>;
const s: Sure = null;
console.log(bad, s);

Required снял ? со всех полей сразу — TS2741 на неполном объекте и никаких проверок на undefined при чтении. NonNullable вырезал из объединения null и undefined, поэтому null в него уже не кладётся: TS2322. Это тот же приём, что и ручное сужение, только выраженный типом.

Общее правило простое: прежде чем писать тип руками, посмотрите, не выводится ли он из того, что уже есть. А если утилита повела себя не так, как вы ждали, ответ лежит в её определении, а не в документации — в редакторе до него один переход «Перейти к определению» по имени утилиты.