Индексные сигнатуры и Record: ключи заранее неизвестны

Тип объекта, с которого началась эта глава, — это список: компилятор знает, что у scores есть math и physics, и каждое обращение сверяет со списком. Пока ключ написан прямо в коде, сверка сходится.

const scores = { math: 5, physics: 4 };
console.log(scores["math"]);
const exact = "math"; // const даёт литеральный тип "math", а не string
console.log(scores[exact]);
let loose: string = "math";
console.log(scores[loose]);

Диагностика ровно одна, на последней строке, и в ней две части: Элемент неявно имеет тип "any", так как выражение типа "string" не может использоваться для индексации типа "{ math: number; physics: number; }", а следом причина — В типе "{ math: number; physics: number; }" не обнаружена сигнатура индекса с параметром типа "string". Вложенную причину читаем как в статье про диагностику: она и есть настоящий ответ.

Компилятор здесь не придирается. exact имеет литеральный тип "math" — конкретный ключ, он в списке есть. А loose имеет тип string, то есть «любая строка»: "math", "milk", "". Тип из двух полей не может пообещать значение для любой строки, и вместо обещания компилятор честно говорит, что тип результата ему неизвестен.

На игрушечном примере это выглядит формальностью. Стоит завести функцию — и становится видно, что за диагностикой стоит настоящая ложь в коде.

const prices = { apple: 50, bread: 40 };
function priceOf(name: string): number {
  // что придёт в name, на этапе сборки не известно
  return prices[name];
}
console.log(priceOf("apple"));
console.log(priceOf("milk"));

Функция объявлена возвращающей number, а вернула undefined — и возражения не последовало. Возражать было не с чем: результат индексации получил тип any, а any, как мы выяснили в прошлой главе, проходит куда угодно. Одна диагностика, но проблем в ней две: неизвестный тип и невыполненное обещание.

TS7053 — это не «объект нельзя индексировать». Это «вы просите значение по ключу, которого в типе нет, и я не знаю, что вам вернуть».

const scores = { math: 5, physics: 4, history: 3 };
let sum = 0;
for (const key of Object.keys(scores)) {
  sum += scores[key];
}
console.log(sum / 3);

const scores = { math: 5, physics: 4, history: 3 };
let sum = 0;
for (const [subject, mark] of Object.entries(scores)) {
  console.log(subject, mark);
  sum += mark;
}
console.log(sum / 3);

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

const prices: { [key: string]: number } = { apple: 50, bread: 40 };
prices["milk"] = 90;
prices.tea = 120;
console.log(Object.keys(prices).length);
console.log(prices["milk"] + prices.tea);

Слово key ни на что не влияет — это подпись для человека, компилятор смотрит только на его тип. Типов ключа разрешено немного: string, number, symbol и шаблонные литеральные типы, до которых доберёмся в главе про условные и сопоставленные типы.

Ключи объектов в JavaScript всё равно строки. Сигнатура { [id: number]: string } — заявление о намерении, а Object.keys вернёт вам ["1", "2"].

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

type Options = { [key: string]: boolean };
const options: Options = { dark: true, compact: false };
if (options.darkk) {
  console.log("тёмная тема");
} else {
  console.log("светлая тема");
}

Ни одной диагностики, и тема осталась светлой. Замените первую строку на type Options = { dark: boolean; compact: boolean } — и получите TS2551: Свойство "darkk" не существует в типе "Options". Вы имели в виду "dark"?. Отсюда простое следствие: индексная сигнатура нужна там, где ключи действительно неизвестны, а не там, где лень их перечислить.

interface Config {
  [key: string]: string;
  host: string;
  retries: number;
}
const config: Config = { host: "localhost", retries: 3 };
console.log(config.host);

interface Config {
  [key: string]: string | number;
  host: string;
  retries: number;
}
const config: Config = { host: "localhost", retries: 3, mode: "быстрый" };
console.log(config.host, config.retries);

Record<K, V> — готовый тип из стандартной библиотеки. Для компилятора Record<string, number> и { [key: string]: number } — одно и то же, разница только в длине записи.

const prices: Record<string, number> = { apple: 50, bread: 40 };
let total = 0;
for (const key of Object.keys(prices)) {
  total += prices[key];
}
console.log(total);

Интересное начинается, когда в первый параметр попадает не string, а объединение литералов — тех самых, из статьи про литеральные типы. Тогда Record перестаёт быть словарём с произвольными ключами и превращается в таблицу с заранее известным набором строк.

type Status = "новая" | "работа" | "готово";
const labels: Record<Status, string> = {
  "новая": "Новая задача",
  "работа": "В работе"
};
console.log(labels["новая"]);

Свойство "готово" отсутствует в типе { новая: string; работа: string; } и является обязательным в типе Record<Status, string>. Это ровно то, чего от таблицы и хотят: добавили статус в объединение — компилятор сам обошёл все места, где для него забыли написать подпись. Ключи Record по умолчанию обязательные, все до одного.

Проверка работает и на чтении: ключ, которого нет в объединении, компилятор не пропустит.

type Status = "новая" | "работа" | "готово";
const labels: Record<Status, string> = {
  "новая": "Новая задача",
  "работа": "В работе",
  "готово": "Готово"
};
console.log(labels["готово"]);
console.log(labels["архив"]);

Диагностика та же самая, TS7053, но причина в ней другая: Свойство "архив" не существует в типе "Record<Status, string>". В первом разделе компилятор жаловался, что ключ слишком широкий; здесь — что ключ конкретный, но чужой.

Record — не встроенное ключевое слово, а обычный сопоставленный тип в одну строку. Как он устроен изнутри, разбираем в главе про типы, вычисляемые из значений.

Здесь начинается вторая половина темы, и она важнее первой. Индексная сигнатура — это утверждение: «по любому строковому ключу здесь лежит число». Компилятор принимает утверждение за правду и больше ничего не проверяет. Что объект при этом пуст, знает только исполнение.

const prices: { [key: string]: number } = { apple: 50, bread: 40 };
function priceOf(name: string): number {
  return prices[name];
}
console.log(priceOf("apple"));
console.log(priceOf("milk").toFixed(2));

Тот же код, что в первом разделе, только с аннотацией — и вместо диагностики падение. Мы не проверили данные, а описали, какими они должны быть; по духу это тот же приём, что и утверждение через as: ответственность за правду перешла к нам.

Обиднее падения — тихий NaN, который никто не заметит до отчёта.

function countWords(text: string): Record<string, number> {
  const result: Record<string, number> = {};
  for (const word of text.split(" ")) {
    result[word] = result[word] + 1;
  }
  return result;
}
const stat = countWords("кот и кот");
console.log(stat["кот"]);

Ноль диагностик. Компилятор видит number + 1 и не имеет ни малейшего повода придраться — сигнатура ему пообещала число. Спасают обычные проверки из части I: оператор in или значение по умолчанию через ??.

const prices: Record<string, number> = { apple: 50 };
const key = "milk";
if (key in prices) {
  console.log(prices[key].toFixed(2));
} else {
  console.log("нет такого товара");
}
console.log((prices[key] ?? 0).toFixed(2));

Эти строки написаны не для компилятора — он их не требовал. Они написаны потому, что без них код врёт: обещает число, а отдаёт пустоту.

Требовать компилятор всё-таки умеет, просто соответствующая проверка выключена по умолчанию — и в песочнице учебника тоже. Флаг noUncheckedIndexedAccess заставляет считать результат любой индексации «значением или undefined»: тогда на const p = prices["milk"]; p.toFixed(2) появится TS18048: Возможно, "p" имеет значение undefined, и проверку придётся написать. Включать ли его в своём проекте — разговор в статье «Строгость сверх strict: noUncheckedIndexedAccess и exactOptionalPropertyTypes» из главы про настройку.

Индексная сигнатура описывает форму словаря, а не его содержимое. Есть ли ключ на самом деле — вопрос к исполнению, и отвечать на него по-прежнему вам.

У объекта-словаря есть особенность, к типам отношения не имеющая, но выстреливающая именно в словарях: у него есть прототип. Ключи вроде toString, constructor и valueOf в нём уже «есть», а тип об этом молчит.

const dict: Record<string, number> = { apple: 50 };
console.log(dict["toString"].toFixed(2));

Для словаря цен это курьёз. Для счётчика слов, который считает пользовательский ввод, — настоящая ошибка: достаточно, чтобы кто-то написал слово «constructor». И ?? здесь не спасёт, потому что унаследованный метод — не undefined.

function countWords(text: string): Record<string, number> {
  const result: Record<string, number> = {};
  for (const word of text.split(" ")) {
    result[word] = (result[word] ?? 0) + 1;
  }
  return result;
}
console.log(countWords("кот и кот")["кот"]);
console.log(countWords("constructor")["constructor"]);

Способ первый: объект без прототипа. Object.create(null) создаёт голый объект, наследовать которому не от кого.

const dict: Record<string, number> = Object.create(null);
dict["apple"] = 50;
console.log(dict["apple"]);
console.log(dict["toString"]);

Способ второй и более честный: Map из части I. Она сделана для словарей, чужих ключей у неё не бывает, а тип у неё не врёт — get объявлен возвращающим «значение или undefined», и проверку компилятор потребует сам.

const prices = new Map<string, number>();
prices.set("apple", 50);
console.log(prices.get("apple").toFixed(2));
const apple = prices.get("apple");
console.log(apple === undefined ? "нет товара" : apple.toFixed(2));
console.log(prices.has("toString"));

Обратите внимание на разницу в характере. Объект с индексной сигнатурой молчал до самого падения; Map начала спорить на третьей строке — потому что её тип описывает не то, чего мы хотим, а то, что есть на самом деле.

Отсюда и правило выбора. Набор ключей известен заранее — Record по объединению литералов: получите проверку полноты. Ключи приходят из данных и особенно от пользователя — Map. Record<string, T> остаётся для своих, заведомо безопасных ключей: разобранного конфига, таблицы констант, кеша по идентификатору, который вы же и сгенерировали.