enum и его замена объектом as const

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

enum Direction {
  Up,
  Down,
}

console.log(typeof Direction);
console.log(Direction.Up, Direction.Down);
console.log(Direction[0]);
console.log(Object.keys(Direction));

Ни одной диагностики — и четыре ключа там, где членов объявлено два: ["0", "1", "Up", "Down"]. Числовой enum заполняет объект в обе стороны: имя ведёт к числу, число — обратно к имени. Это называют обратным маппингом — единственное, что enum делает за вас и что в обычном объекте само собой не появится.

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

// то же самое, написанное руками: обычный объект,
// заполненный сразу в обе стороны
var Direction;
(function (Direction) {
  Direction[(Direction["Up"] = 0)] = "Up";
  Direction[(Direction["Down"] = 1)] = "Down";
})(Direction || (Direction = {}));

console.log(Direction.Up, Direction[0]);
console.log(Direction);

Хитрость в одной строке: присваивание возвращает присвоенное, поэтому Direction["Up"] = 0 отдаёт ноль, и он тут же становится индексом для обратной записи. Одно выражение кладёт в объект обе пары.

Отсюда практическое правило: перебирать числовой enum через Object.keys нельзя — половина ключей окажется числами.

Строковый enum устроен проще: обратной записи у него нет, потому что ключ и значение перепутались бы. В объекте останутся ровно объявленные члены, и Object.keys даст два имени.

В главе про объекты выяснилось: TypeScript сравнивает типы по строению, а не по имени — совпали поля, значит типы совместимы. enum — исключение из этого правила, и таких исключений в языке единицы.

enum Status {
  Done = "done",
}

enum Phase {
  Done = "done",
}

function report(s: Status): void {
  console.log("статус: " + s);
}

report(Status.Done);
report(Phase.Done);
report("done");
console.log(Status.Done === Phase.Done);

Два TS2345 и один TS2367 — Это сравнение кажется непреднамеренным, поскольку типы "Status" и "Phase" не перекрываются. А в выводе три одинаковые строки и true. Компилятор сравнивал объявления, движок — строки; в собранном коде от Status и Phase остались два объекта с одинаковым содержимым.

Иногда это ровно то, что нужно: перепутать «статус задачи» и «фазу сделки» — настоящая ошибка, и хорошо, когда её ловят. Гораздо чаще мешает: строка приходит из формы, из адреса, из localStorage — и оказывается, что в свой же enum её не положить.

type Theme = "light" | "dark";

enum ThemeEnum {
  Light = "light",
  Dark = "dark",
}

// то, что вернуло хранилище: для типов это просто string
const stored: string = "dark";

function applyUnion(theme: Theme): void {
  console.log("union: " + theme);
}

function applyEnum(theme: ThemeEnum): void {
  console.log("enum: " + theme);
}

if (stored === "dark") {
  applyUnion(stored);
  applyEnum(stored);
}

Сравнение stored === "dark" сузило тип до литерала — приём из главы про сужение. Объединению этого достаточно: "dark" входит в Theme по строению. А ThemeEnum.Dark — не строка "dark", а член конкретного объявления, и свести к нему нечего.

enum ThemeEnum {
  Light = "light",
  Dark = "dark",
}

function applyEnum(theme: ThemeEnum): void {
  console.log("тема: " + theme);
}

applyEnum("dark" as ThemeEnum);
applyEnum("светлая-презветлая" as ThemeEnum);

Строковый enum строг до неудобства. Числовой — наоборот, и это стоит увидеть до того, как оно случится в бою.

enum Role {
  Guest,
  Admin,
}

const fromServer: number = 42;

const role: Role = fromServer;

const literal: Role = 42;

console.log(role, literal);
console.log(Role[role]);

Одна диагностика вместо двух. Строка с fromServer прошла целиком: значение типа number считается годным для любого числового enum. Литерал 42 строкой ниже компилятор сверил со списком членов и отказал — TS2322. Разница только в том, что в одном случае тип широкий, а в другом — конкретное число.

На запуске в role лежит сорок два, а обратный маппинг Role[role] вернул undefined. Тип обещал одно из двух значений, пришло третье, и заметить это было некому. Именно так числовой enum и подводит: данные приходят числами, числа проходят проверку, а к списку членов они отношения не имеют.

Если enum всё-таки берут, его делают строковым: string в строковый enum не пролезает, а в логах видно слово, а не безымянную цифру.

enum Flag {
  Read = 1,
  Write = 2,
  Exec = 4,
}

const both: Flag = Flag.Read | Flag.Write;
console.log(both);
console.log(Flag[both]);

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

const Level = {
  Debug: "debug",
  Error: "error",
} as const;

// имя занято дважды намеренно: типы и значения живут порознь
type Level = (typeof Level)[keyof typeof Level];

function log(level: Level, text: string): void {
  console.log("[" + level + "] " + text);
}

log(Level.Error, "упало");
log("debug", "подробности");
console.log(Object.values(Level));
log("warn", "нет такого");

Тип читается изнутри наружу. typeof Level — тип самого объекта, { readonly Debug: "debug"; readonly Error: "error"; }. keyof typeof Level — объединение ключей, "Debug" | "Error". Индексный доступ по этому объединению спрашивает «что лежит под любым из ключей» и отдаёт объединение значений: "debug" | "error".

Имя Level занято одновременно константой и типом — и это не конфликт: типы и значения TypeScript держит в разных пространствах имён. Снаружи выходит та же двойственность, что у enum: Level.Error — значение, : Level — тип.

Что получилось взамен. Level.Error пишется как у enum. Object.values(Level) даёт готовый список для перебора — и в нём ровно два элемента, без обратного маппинга. Обычная строка "debug" проходит без приведений, потому что тип — обычное объединение литералов. А "warn" не прошло: TS2345.

Если объект нужен только ради типа, объект можно вообще не писать. Объединение литералов проверяет то же самое и не оставляет в собранном файле ни строчки.

type Level = "debug" | "error";

function log(level: Level, text: string): void {
  console.log("[" + level + "] " + text);
}

log("error", "упало");
log("warn", "нет такого");

Правило простое: нужен только тип — пишите объединение; нужен ещё и список на запуске (отрисовать select, проверить пришедшее) — пишите объект as const и выводите тип из него. Дублировать список в двух местах не нужно ни в одном из случаев.

Последняя строка — самая практическая. enum нельзя просто стереть: за именем стоит объект, который кто-то должен создать. Поэтому node app.ts, который типы именно стирает, на таком файле отказывается работать вовсе, а у компилятора есть флаг erasableSyntaxOnly, запрещающий такой синтаксис заранее. Подробный разбор — в следующей статье главы; для выбора между тремя вариантами достаточно знать, что enum сокращает список инструментов, которыми проект можно запустить.

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

const enum Size {
  Small = 1,
  Big = 2,
}

console.log(Size.Big);
console.log(Object.keys(Size));

Перевод существующего enum на объект as const — почти механический: значения переехали в объект, имя типа осталось прежним, вызовы Level.Error менять не нужно.