re:re:actable
Урок 073 минуты чтения

enum в TypeScript и почему его часто считают антипаттерном

На этой странице
Кратко

enum — именованный набор констант: числовых (Direction.Up = 0) или строковых (Status.Done = "done"). В отличие от большинства конструкций TypeScript, enum генерирует JavaScript-код (объект) и ведет себя номинально. Из-за этого, а также из-за небезопасных числовых enum и несовместимости с режимами «только удаление типов» (Node.js type stripping, erasableSyntaxOnly), многие команды заменяют enum на union литералов или объект as const.

Вопрос

Что такое enum в TypeScript? Почему enum часто считают антипаттерном и чем его заменить?

Виды enum

// числовой: значения с 0 по порядку
enum Direction {
  Up,      // 0
  Down,    // 1
  Left,    // 2
  Right,   // 3
}
 
// строковый
enum Status {
  Idle = "idle",
  Loading = "loading",
  Done = "done",
}
 
// const enum — инлайнится при компиляции, объекта нет
const enum Size {
  Small = "s",
  Large = "l",
}

Что генерирует компилятор

var Direction;
(function (Direction) {
  Direction[Direction["Up"] = 0] = "Up"; // обратное отображение для числовых enum
  Direction[Direction["Down"] = 1] = "Down";
})(Direction || (Direction = {}));

Проблемы enum

ПроблемаПояснение
Генерирует runtime-кодпротиворечит идее «TS = JS + стираемые типы»
Числовые enum небезопасныв старых версиях TS любое число присваивалось в числовой enum
Номинальностьстроковое значение "done" нельзя передать туда, где ждут Status, без приведения
const enumломается при изолированной компиляции (isolatedModules, Babel, esbuild)
Type strippingNode.js и флаг erasableSyntaxOnly не поддерживают enum
Обратное отображениеObject.keys(Direction) содержит и имена, и числа
function setStatus(status: Status) {}
setStatus("done");       // ошибка: строка не совместима с enum
setStatus(Status.Done);  // OK

Альтернативы

Union литералов — проще всего, кода в runtime нет:

type Status = "idle" | "loading" | "done";
 
function setStatus(status: Status) {}
setStatus("done"); // OK, автодополнение работает

Объект as const — если нужны и значения в runtime, и тип:

export const Status = {
  Idle: "idle",
  Loading: "loading",
  Done: "done",
} as const;
 
export type Status = (typeof Status)[keyof typeof Status]; // "idle" | "loading" | "done"
 
Object.values(Status); // ["idle", "loading", "done"] — удобно для select

Когда enum всё же уместен

  • проект уже использует enum повсеместно и единообразие важнее;
  • нужны битовые флаги (Read = 1 << 0, Write = 1 << 1);
  • кодогенерация из схемы (GraphQL, OpenAPI) создает enum.

Что важно помнить

  • Строковые enum безопаснее числовых — значение видно в логах и при отладке.
  • as const делает значения объекта readonly и литеральными.
  • Union литералов отлично работает с exhaustive check через never.
  • В TypeScript 5.8+ флаг erasableSyntaxOnly запрещает enum, namespace и parameter properties — для совместимости с Node.js type stripping.

Мини-шпаргалка

  • enum — именованные константы, генерирует JS-объект.
  • Числовые — с обратным отображением, строковые — безопаснее.
  • Проблемы: runtime-код, номинальность, const enum и изолированная компиляция.
  • Замена: union литералов или объект as const.
  • Тип из объекта: (typeof Obj)[keyof typeof Obj].

Документация

TypeScript Handbook: Enums, TypeScript Handbook: Objects vs Enums, TypeScript: erasableSyntaxOnly.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам