Сопоставленные типы: пройти по ключам

Индексная сигнатура из главы про объекты описывает правило: «любой ключ типа string даёт number». Правило хорошо, пока ключи и правда любые. Но чаще список ключей известен заранее — статусы заказа, коды валют, названия вкладок, — и хочется словарь ровно по этому списку. Первая мысль: подставить объединение литералов туда, где раньше стоял string.

type Status = "new" | "paid" | "shipped";
// прямолинейная попытка: словарь ровно по трём ключам
type Labels = { [key: Status]: string };
const labels: Labels = { new: "новый", paid: "оплачен", shipped: "отправлен" };
console.log(labels.new);

Диагностик две, и первая — TS1337: Тип параметра сигнатуры индекса не может быть типом литерала или универсальным типом. Рекомендуется использовать тип сопоставляемого объекта. Вторая, TS2339, — уже следствие: испорченный тип не содержит ни одного свойства, поэтому обращение к labels.new тоже не проходит.

Обратите внимание, на что именно жалоба. Дело не в объединении как таковом — { [key: string | number]: string } компилятор принимает без единого слова. Мешают литералы. Параметр индексной сигнатуры описывает бесконечное множество возможных ключей, а "new" | "paid" | "shipped" — это конечный перечень из трёх штук. Перечень означает «вот эти три свойства, каждое обязательно», и это совсем другое обещание, чем «что бы вы ни спросили, получите строку».

Вторая фраза диагностики — прямая инструкция. «Сопоставляемый тип объекта» в переводе компилятора — это mapped type, сопоставленный тип. Меняется в коде ровно одно слово.

type Status = "new" | "paid" | "shipped";
// одно слово вместо двоеточия — и это уже не правило, а перечень
type Labels = { [K in Status]: string };
const labels: Labels = { new: "новый", paid: "оплачен" };
console.log(labels.shipped);

in вместо двоеточия — и разговор пошёл по существу: Свойство "shipped" отсутствует в типе "{ new: string; paid: string; }" и является обязательным в типе "Labels". Тип перестал быть заглушкой и начал требовать все три ключа. Предупреждение мы, как обычно, проигнорировали — и получили на исполнении undefined вместо подписи.

Практическая ценность как раз в этом: добавили в Status четвёртый статус — и компилятор сам обошёл все словари, где про него забыли.

Внутри фигурных скобок помещается одно выражение вида [K in Keys]: Value. K — имя переменной прохода, любое, как в цикле for..of. Keys — тип-источник ключей, объединение строк, чисел или символов. Value — тип значения, и в нём K уже можно использовать.

Самое интересное начинается, когда источником ключей становится keyof T, а типом значения — T[K]: тогда сопоставленный тип не сочиняет объект с нуля, а перерабатывает уже существующий. Вот функция, которая превращает все поля в строки, — и тип, который повторяет её работу на уровне типов.

type Product = { id: number; title: string; price: number };
type Formatted<T> = { [K in keyof T]: string };

function stringify<T extends object>(source: T): Formatted<T> {
  // ключи придут только во время работы, поэтому пустышку приходится утверждать
  const out = {} as Formatted<T>;
  for (const key of Object.keys(source) as (keyof T)[]) {
    out[key] = String(source[key]);
  }
  return out;
}
const row: Formatted<Product> = stringify({ id: 7, title: "Лампа", price: 1200 });
console.log(row.price);
console.log(row.price.padStart(7, "."));

Ни одной диагностики, и это важнее, чем кажется. У row.price теперь тип string, поэтому padStart разрешён — хотя в исходном Product цена была числом. Список полей при этом не продублирован: добавится четвёртое поле — Formatted подхватит его сам.

Если Value вообще не зависит от T, а ключи задаются отдельно, получается словарь с фиксированным набором ключей. Именно так — в одну строку — устроен Record из стандартной библиотеки.

// ровно так объявлен Record в стандартной библиотеке
type MyRecord<K extends PropertyKey, V> = { [P in K]: V };
type Counters = MyRecord<"clicks" | "views", number>;

const stats: Counters = { clicks: 0, views: 0 };
stats.clicks += 1;
console.log(stats);
console.log(stats.scrolls);

В lib.es5.d.ts вместо PropertyKey написано keyof any, но это одно и то же — string | number | symbol. Никакого особого статуса у Record нет: это обычный сопоставленный тип, который вы теперь умеете написать сами.

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

К проходу по ключам разрешено приписать те же модификаторы, что и обычному свойству: ? после имени ключа и readonly перед ним. Приписываются они сразу ко всем полям — и из этого получаются два самых ходовых утилитных типа.

type User = { id: number; name: string; email?: string };
type MyPartial<T> = { [K in keyof T]?: T[K] };
type MyReadonly<T> = { readonly [K in keyof T]: T[K] };

function applyPatch(user: User, patch: MyPartial<User>): User {
  return { ...user, ...patch };
}
const base: User = { id: 1, name: "Рико" };
console.log(applyPatch(base, { name: "Рико Второй" }).name);

const frozen: MyReadonly<User> = base;
frozen.id = 2;
console.log(frozen.id);

MyPartial и MyReadonly — это дословно Partial и Readonly из стандартной библиотеки, отличаются только имена переменных прохода. А последние две строки — знакомое по статье про readonly напоминание: запрет живёт в типах, объект base ничем не защищён, и присваивание на исполнении прошло.

Обратное действие пишется через минус. -? снимает необязательность, -readonly снимает запрет на запись. Плюс тоже существует (+?, +readonly), но его никто не пишет: он и так подразумевается.

type Settings = { readonly theme?: "light" | "dark"; readonly lang?: string };
// минус снимает модификатор; знак по умолчанию — плюс, поэтому его и не пишут
type MyRequired<T> = { [K in keyof T]-?: T[K] };
type Mutable<T> = { -readonly [K in keyof T]: T[K] };

const defaults: Mutable<MyRequired<Settings>> = { theme: "dark", lang: "ru" };
defaults.theme = "light";
console.log(defaults.theme.length);

const half: MyRequired<Settings> = { theme: "dark" };
console.log(half.lang);

Первый тип — это Required из библиотеки, второй в неё не входит, хотя нужен постоянно: после as const или после чужого Readonly объект бывает нужно всё-таки собрать по кусочкам. Своего Mutable в стандартной библиотеке нет — пишут его сами, вот этой одной строкой.

Строка defaults.theme.length заслуживает отдельного взгляда. Поле было объявлено как theme?: "light" | "dark", то есть могло оказаться undefined, и обращение к .length без проверки не прошло бы. После -? проверка не нужна: вопрос снят вместе с undefined.

type Marked = { value?: string };
type Explicit = { value: string | undefined };
type MyRequired<T> = { [K in keyof T]-?: T[K] };

const a: MyRequired<Marked> = { value: "есть" };
const b: MyRequired<Explicit> = { value: undefined };
console.log(a.value.length, b.value);

До сих пор ключ переезжал в новый тип под своим именем. Приписка as после in позволяет его подменить: слева от неё — исходный ключ, справа — тип, который станет ключом в результате. Это третье значение слова as в языке, рядом с as const и утверждением типа, и с ними оно никак не связано.

Самое неожиданное применение — не переименование, а удаление. Если справа от as получается never, свойство просто не попадает в результат.

type User = { id: number; name: string; passwordHash: string };
// never на месте ключа означает «этого свойства в результате не будет»
type Without<T, Drop extends keyof T> = { [K in keyof T as K extends Drop ? never : K]: T[K] };

function toPublic(user: User): Without<User, "passwordHash"> {
  const { passwordHash, ...rest } = user;
  return rest;
}
const safe = toPublic({ id: 1, name: "Рико", passwordHash: "x7f3" });
console.log(safe.name);
console.log(safe.passwordHash);

Условный тип внутри as — тот самый, с которого началась глава: для каждого ключа спрашиваем, входит ли он в список на выброс, и отвечаем либо never, либо самим ключом. Получившийся Without делает то же, что Omit, — но заглянуть в библиотеку всё равно стоит: там Omit собран из двух знакомых утилит, type Omit<T, K extends keyof any> = Pick<T, Exclude<keyof T, K>>. Сначала Exclude выбрасывает ненужные имена из объединения ключей, потом Pick проходит по остатку. Два прохода вместо одного — и тот же результат.

Настоящее переименование выглядит так же, но справа от as стоит не условие, а преобразование строки. Простейшее — встроенное Uppercase.

type Row = { id: number; title: string };
// Uppercase — встроенное преобразование строки на уровне типов; & string отсекает символьные ключи
type Shout<T> = { [K in keyof T as Uppercase<K & string>]: T[K] };

function shout<T extends object>(source: T): Shout<T> {
  const out = {} as Record<string, unknown>;
  for (const [key, value] of Object.entries(source)) {
    out[key.toUpperCase()] = value;
  }
  return out as Shout<T>;
}
const loud: Shout<Row> = shout({ id: 1, title: "Лампа" });
console.log(loud.TITLE);
console.log(loud.title);

K & string здесь не украшение. keyof T может содержать числа и символы, а Uppercase работает только со строками; пересечение отбрасывает всё лишнее. Диагностика на последней строке получилась говорящая: компилятор не просто отказал, а назвал новое имя ключа.

Переименование в as ограничено только тем, что вы умеете вычислять из строкового типа. Пока это Uppercase и его родня — но настоящий простор дают шаблонные литеральные типы, о них следующая статья.

У прохода вида [K in keyof T] есть особенность, о которой не догадываешься, пока не наткнёшься. Такой проход компилятор считает не построением нового объекта, а копированием старого — и старается сохранить его форму. Проверим на массиве и кортеже.

type Boxed<T> = { [K in keyof T]: T[K][] };

const pair: Boxed<[number, string]> = [[1, 2], ["ок"]];
console.log(pair[1]);

const many: Boxed<number[]> = [[1, 2], [3]];
console.log(many.length);

Ни одной диагностики. Хотя по букве кода keyof number[] — это number | "length" | "push" | "map" | ..., и честный проход по всем ключам дал бы объект с полем length типа number[]. Компилятор поступил иначе: узнал в T массив, обошёл только элементы и вернул number[][]. То же с кортежем — длина и порядок сохранились.

А теперь добавим as K. Ключ остаётся тот же самый, переименования нет — казалось бы, ничего не изменится.

type BoxedRenamed<T> = { [K in keyof T as K]: T[K][] };

const many: BoxedRenamed<number[]> = [[1, 2], [3]];
console.log(many);

Изменилось всё: Тип "number[][]" не может быть назначен для типа "BoxedRenamed<number[]>", а вложенная причина называет виновника — Типы свойства "length" несовместимы. Тип "number" не может быть назначен для типа "number[]". Стоило появиться приписке as, и компилятор перестал считать проход копированием: он послушно обошёл все ключи массива, включая length, и завернул каждый в массив.

Отсюда правило, которое стоит помнить: [K in keyof T] без as — это «то же самое, но с изменёнными значениями», а с as — «новый объект, собранный по ключам». Если ваш утилитный тип должен работать и с массивами, as в нём лишний.

type User = { readonly id: number; email?: string };
type Copy<T> = { [K in keyof T]: T[K] };
type CopyRenamed<T> = { [K in keyof T as K]: T[K] };

const a: Copy<User> = { id: 1 };
const b: CopyRenamed<User> = { id: 1 };
a.id = 2;
b.id = 3;
console.log(a.id, b.id);