keyof и typeof: тип из значения и его ключи

Компилятор читает файл в двух режимах. После двоеточия, после type, внутри угловых скобок — это мир типов. Всё остальное — мир значений. Одно и то же слово в этих мирах может означать разное, и typeof — самый заметный такой случай.

const settings = {
  theme: "dark",
  fontSize: 16,
};

// справа от знака равенства работает не оператор из части I, а его тёзка
type Settings = typeof settings;

const backup: Settings = { theme: "light", fontSize: 14 };
console.log(typeof settings);
console.log(backup.fontSize);

const broken: Settings = { theme: "light", fontSize: "14" };
console.log(broken.fontSize);

В console.log сработал знакомый оператор — тот, что честно отвечает object и не умеет отличить объект от массива. В строке с type тот же typeof сделал другое: заглянул в settings и выдал его тип целиком — { theme: string; fontSize: number }. Дальше Settings живёт как обычный именованный тип, и объявление broken получило за это TS2322: Тип "string" не может быть назначен для типа "number".

Обратите внимание на вторую половину вывода: строка "14" всё равно легла в объект и напечаталась. Компилятор высказался и отошёл в сторону — до выполнения от типов не доезжает ничего, ровно как с readonly-полем из главы про объекты.

Снять тип можно не только с объекта. Функция — тоже значение, и у неё есть тип: список параметров и то, что она возвращает.

function formatDate(value: number, short: boolean): string {
  return short ? String(value) : "дата " + value;
}

// сигнатуру не переписываем руками — берём у оригинала
type Formatter = typeof formatDate;

const f: Formatter = (v, s) => (s ? "!" : String(v));
console.log(f(7, false));

console.log(f(7, "нет"));

Параметры v и s не размечены, и всё же неявного any здесь нет: типы пришли из Formatter сверху вниз — контекстная типизация из статьи про вывод типов. А вызов с "нет" получил TS2345, но выполнился: непустая строка истинна, поэтому в консоли восклицательный знак.

Что именно вывел typeof, проще всего увидеть наведением курсора в редакторе — подсказка покажет развёрнутый тип, а не само выражение.

let mode = "dark";
const fixed = "dark";

type Mode = typeof mode;
type Fixed = typeof fixed;

const m: Mode = "что угодно";
console.log(m);

const f: Fixed = "light";
console.log(f);

keyof работает только в мире типов и делает одну вещь: берёт тип объекта и отдаёт объединение его ключей. Не string, а перечисление конкретных имён — каждое из них литеральный тип.

interface User {
  id: number;
  name: string;
  email: string;
}

type UserKey = keyof User;

const key: UserKey = "name";
console.log(key);

const wrong: UserKey = "age";
console.log(wrong);

keyof User — это "id" | "name" | "email", обычное объединение из главы про сужение типов. Диагностика TS2322 напечатала его не раскрывая: Тип "age" не может быть назначен для типа "keyof User". Компилятор часто оставляет короткую запись, если она читается лучше развёрнутой; развёрнутый вариант всегда покажет редактор при наведении.

Главное про keyof — это не «список строк». Это список, привязанный к типу: поменяли User, и UserKey изменился в ту же секунду, а все места, где ключи перечислялись, компилятор проверит заново.

Чаще всего ключи нужны не от интерфейса, а от конкретного объекта — словаря, таблицы настроек, набора обработчиков. Первое, что хочется написать, — keyof settings. Так нельзя, и причина ровно та, с которой начиналась статья.

const settings = { theme: "dark", fontSize: 16 };
interface Config {
  theme: string;
}

type WrongKeys = keyof settings;

type WrongValue = typeof Config;

// значение превращаем в тип, у типа берём ключи
type Keys = keyof typeof settings;
const key: Keys = "fontSize";
console.log(key);

Две зеркальные диагностики. TS2749: "settings" относится к значению, но здесь используется как тип — и тут же подсказывает недостающее слово — Возможно, вы имели в виду "typeof settings"? TS2693: "Config" относится только к типу, но используется здесь как значение — интерфейс существует лишь на этапе проверки, брать у него typeof нечего.

Отсюда и связка keyof typeof. Читается справа налево: typeof settings достаёт тип из значения, keyof берёт у этого типа ключи. Два оператора, две ступени, и ни одной строки в собранном коде.

const currencies = {
  RUB: "рубль",
  USD: "доллар",
  EUR: "евро",
};

type Currency = keyof typeof currencies;

function nameOf(code: Currency): string {
  return currencies[code];
}

console.log(nameOf("EUR"));
console.log(nameOf("GBP"));

TS2345 развернул объединение полностью: Аргумент типа "GBP" нельзя назначить параметру типа "RUB" | "USD" | "EUR". Список валют написан один раз — в самом объекте; тип подтянулся сам. Добавьте туда четвёртую строку, и Currency расширится без единой правки.

Вторая строка вывода — про то, чего типы не могут. Предупреждение проигнорировали, выполнение продолжилось, обращение к несуществующему ключу вернуло undefined. Функция обещала string и вернула undefined — компилятор не соврал, просто он проверяет исходник, а не то, что происходит с ним потом.

Ключи описаны типом, функция их принимает — казалось бы, перебор словаря теперь безопасен насквозь. Спрогнозируйте, что скажет компилятор.

const rates = { RUB: 1, USD: 95, EUR: 105 };
type Code = keyof typeof rates;

function show(code: Code): void {
  console.log(code, rates[code]);
}

for (const key of Object.keys(rates)) {
  show(key);
}

Аргумент типа "string" нельзя назначить параметру типа "RUB" | "USD" | "EUR". Обидно: объект прямо здесь, ключи известны, а key оказался просто строкой. Дело в сигнатуре: Object.keys объявлена как возвращающая string[] — без всякой связи с тем, что ей передали.

Это не недосмотр, а следствие структурной типизации из главы про объекты. Тип обещает, какие поля у объекта есть, но не обещает, что других нет. Значит, во время выполнения ключей может оказаться больше, чем в типе, — и честно назвать их keyof невозможно.

const rates = { RUB: 1, USD: 95 };
type Code = keyof typeof rates;

const fromServer = { RUB: 1, USD: 95, BTC: 9000000 };
const safe: typeof rates = fromServer;

for (const key of Object.keys(safe) as Code[]) {
  console.log(key, rates[key]);
}

Ни одной диагностики — и BTC undefined в консоли. Утверждение as Code[] сказало компилятору «здесь только мои ключи», проверять он это не стал, а объект пришёл с третьим полем. Проверка лишних свойств срабатывает на литералах, а fromServer положили через переменную — и она промолчала.

Компилятор молчит не потому, что всё хорошо, а потому, что вы попросили его молчать. Каждый as — обещание, которое дальше держите вы.

const rates = { RUB: 1, USD: 95, EUR: 105 };
type Code = keyof typeof rates;

// перебираем не объект, а проверенный список
const CODES: Code[] = ["RUB", "USD", "EUR"];
for (const code of CODES) {
  console.log(code, rates[code]);
}

const WRONG: Code[] = ["RUB", "UDS"];
console.log(WRONG.length);

У keyof простое правило и несколько неочевидных следствий. Первое встречается сразу, как только под руку попадает тип с индексной сигнатурой.

type Dict = { [key: string]: number };
type DictKey = keyof Dict;

const a: DictKey = "любая строка";
const b: DictKey = 42;
console.log(a, b);

Компилятор промолчал на обеих строках: keyof от индексной сигнатуры со строковым ключом — это string | number. Число попало в набор не по ошибке. В JavaScript ключом бывает строка или символ, а число приводится к строке: obj[0] — то же самое, что obj["0"]; раз запись с числом разрешена, число обязано входить в объединение ключей.

Второе следствие — про объединения. Тут интуиция подсказывает «сложить ключи», а компилятор делает наоборот.

type Circle = { kind: "circle"; radius: number };
type Square = { kind: "square"; side: number };
type Shape = Circle | Square;

type ShapeKey = keyof Shape;

const ok: ShapeKey = "kind";
console.log(ok);

const no: ShapeKey = "radius";
console.log(no);

Тип "radius" не может быть назначен для типа "kind" — от объединения keyof оставил только общие ключи. И это единственный безопасный ответ: значение типа Shape может оказаться квадратом, у которого никакого radius нет. Если общих полей у вариантов не окажется вовсе, keyof честно вернёт never — тип без единого значения.

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

const list = ["север", "юг", "запад"];
type ListKey = keyof typeof list;

const i: ListKey = 0;
const m: ListKey = "map";
console.log(i, m);

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

const icons = { ok: "готово", fail: "ошибка", wait: "ждём" };

type Hand = "ok" | "fail"; // написали руками и забыли дополнить
type Derived = keyof typeof icons; // выведено из объекта

const a: Derived = "wait";
console.log(icons[a]);

const b: Hand = "wait";
console.log(icons[b]);

Оба обращения к icons сработали одинаково — но одно из них компилятор считает ошибкой, потому что сверяется с устаревшим списком. Тип Derived такой проблемы иметь не может в принципе: он не копия объекта, а его отражение.

Четыре записи закрывают почти все повседневные случаи. Последняя достаёт из типа не ключи, а сами значения — её подробно разбирает следующая статья.

И ещё одно место, где keyof встречается постоянно, — ограничения дженериков: запись K extends keyof T означает «ключ, который у этого объекта действительно есть». Идея та же самая, просто тип, у которого берут ключи, приходит параметром.