Сопоставленные типы в TypeScript: синтаксис, модификаторы, as

Сопоставленный тип строит новый объектный тип, перебирая набор ключей. { [K in keyof T]: boolean } означает «для каждого ключа K из T свойство с именем K и типом boolean»:

type Features = {
  darkMode: string;
  search: number;
  export: string[];
};

// Same keys as T, every property turned into a boolean
type Flags<T> = { [K in keyof T]: boolean };

const enabled: Flags<Features> = {
  darkMode: true,
  search: false,
  export: true,
};

console.log(enabled); // { darkMode: true, search: false, export: true }
// Leaving out "export" would be error TS2741: Property 'export' is missing

Добавьте ключ в Features, и Flags<Features> тоже его потребует. Сопоставленные типы существуют только при компиляции: они описывают объекты, но не создают их.

Синтаксис

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

type MappedType = {
  [K in Keys]: PropertyType; // K takes each member of Keys in turn
};

Keys может быть любым объединением строк, чисел или символов. Он не обязан происходить из keyof:

type Size = "small" | "medium" | "large";

type PriceTable = { [S in Size]: number };
// { small: number; medium: number; large: number }

const prices: PriceTable = { small: 3, medium: 4, large: 5 };

for (const size of ["small", "large"] as const) {
  console.log(size, prices[size]);
}
// small 3
// large 5

Именно это делает Record<Size, number>; Record это сопоставленный тип в одну строку. Тип свойства может использовать ключ: { [K in keyof T]: T[K] } копирует тип каждого свойства через доступ по индексу, а { [K in keyof T]: T[K] | null } делает каждое свойство допускающим null.

Модификаторы: readonly и ? с + и -

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

type Account = {
  readonly id: number;
  email?: string;
};

type Mutable<T> = { -readonly [K in keyof T]: T[K] };
type AllRequired<T> = { [K in keyof T]-?: T[K] };
type Frozen<T> = { +readonly [K in keyof T]: T[K] };

const editable: Mutable<Account> = { id: 1 };
editable.id = 2; // allowed: readonly was removed

const complete: AllRequired<Account> = { id: 1, email: "a@b.co" };
// { id: 1 } alone would be error TS2741: Property 'email' is missing

const frozen: Frozen<{ n: number }> = { n: 1 };
// @ts-expect-error: Cannot assign to 'n' because it is a read-only property
frozen.n = 2;

console.log(editable, complete, frozen);
// { id: 2 } { id: 1, email: 'a@b.co' } { n: 2 }

Последняя строка показывает, что readonly это правило только времени компиляции: о присваивании было сообщено (здесь подавлено через @ts-expect-error), но сгенерированный JavaScript всё равно его выполнил. -? делает больше, чем убирает вопросительный знак: он также убирает undefined из типа свойства, поэтому AllRequired<Account> отвергает { id: 1, email: undefined } с ошибкой error TS2322: Type 'undefined' is not assignable to type 'string'.

Как устроены Partial, Readonly, Pick и Record

Встроенные служебные типы, которые меняют форму объектов, это сопоставленные типы. Вот определения из собственного lib.es5.d.ts TypeScript:

type Partial<T> = { [P in keyof T]?: T[P] };
type Required<T> = { [P in keyof T]-?: T[P] };
type Readonly<T> = { readonly [P in keyof T]: T[P] };
type Pick<T, K extends keyof T> = { [P in K]: T[P] };
type Record<K extends keyof any, T> = { [P in K]: T };

Читать их полезно: Pick перебирает только переданные ключи, а Record игнорирует исходный тип и даёт каждому ключу один и тот же тип значения. Omit не является самостоятельным сопоставленным типом: это Pick<T, Exclude<keyof T, K>>. Все они перечислены в справочнике по служебным типам.

Переназначение ключей через as

Конструкция as после ключа меняет имя свойства. В сочетании с шаблонными литеральными типами она может порождать новые имена из старых:

type Getters<T> = {
  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
};

type Person = { name: string; age: number };

// { getName: () => string; getAge: () => number }
const person: Getters<Person> = {
  getName: () => "Ada",
  getAge: () => 36,
};

console.log(person.getName(), person.getAge()); // Ada 36

string & K нужен потому, что keyof T может включать ключи number и symbol, а Capitalize принимает только строки. Пересечение оставляет строковые ключи и отбрасывает остальные.

Фильтрация ключей через never

Если конструкция as даёт never для ключа, этот ключ удаляется. С условным типом можно оставлять или отбрасывать свойства в зависимости от их типа:

type DataOnly<T> = {
  [K in keyof T as T[K] extends (...args: any[]) => unknown ? never : K]: T[K];
};

class Invoice {
  constructor(public id: number, public total: number) {}
  format(): string {
    return `#${this.id}: ${this.total.toFixed(2)}`;
  }
}

// { id: number; total: number }  (format is gone)
const data: DataOnly<Invoice> = { id: 7, total: 19.5 };

console.log(data);                        // { id: 7, total: 19.5 }
console.log(new Invoice(7, 19.5).format()); // #7: 19.50

Типы вроде DataOnly полезны, чтобы описать, что переживает JSON.stringify или что редактирует форма: поля без методов.

Какие модификаторы сохраняются

Сопоставленный тип по keyof T для некоторого типа T называется гомоморфным, и он копирует модификаторы readonly и ? каждого свойства из T. Сопоставленный тип по простому объединению ключей начинается без модификаторов:

type Account = { readonly id: number; email?: string };

type Copy<T> = { [K in keyof T]: T[K] };
type A = Copy<Account>;
// { readonly id: number; email?: string }  (modifiers kept)

type B = { [K in "id" | "email"]: Account[K] };
// { id: number; email: string | undefined }  (email is required now)

В B тип email по-прежнему содержит undefined, потому что его включает Account["email"], но само свойство больше не необязательное: { id: 1 } отвергается. Поэтому Partial<T> и подобные ему перебирают keyof T: они сохраняют всё, что явно не меняют.

Обобщённый гомоморфный сопоставленный тип, применённый к массиву или кортежу, даёт массив или кортеж, а не объект с числовыми ключами. Readonly<string[]> это readonly string[], а при type Box<T> = { [K in keyof T]: { value: T[K] } } Box<[string, number]> это [{ value: string }, { value: number }].

Сопоставленные типы и код времени выполнения

Поскольку сопоставленный тип только описывает объект, функции, которая строит такой объект, нужен собственный цикл времени выполнения. Тогда тип описывает её результат:

type Validators<T> = { [K in keyof T]: (value: T[K]) => boolean };

type SignUp = { email: string; age: number };

const rules: Validators<SignUp> = {
  email: (v) => v.includes("@"), // v is string
  age: (v) => v >= 13,           // v is number
};

function validate(form: SignUp): string[] {
  const failed: string[] = [];
  for (const key of Object.keys(rules) as (keyof SignUp)[]) {
    const ok = key === "email" ? rules.email(form.email) : rules.age(form.age);
    if (!ok) failed.push(key);
  }
  return failed;
}

console.log(validate({ email: "ada@example.com", age: 36 })); // []
console.log(validate({ email: "nope", age: 9 }));             // [ 'email', 'age' ]

Колбэки получают типы параметров из сопоставленного типа (v в одном это string, а в другом number) без всяких аннотаций. Если вы пришли сюда за классом Map, а не за сопоставлением типов, см. Map в TypeScript.