Enum в TypeScript: числовые, строковые и const enum

Enum в TypeScript это именованный набор констант. enum Direction { Up, Down, Left, Right } создаёт и тип Direction, и объект во время выполнения, к членам которого обращаются как Direction.Up. Члены нумеруются с 0, если вы не задали им значения, а строковые перечисления дают каждому члену читаемую строку.

enum Direction {
    Up,    // 0
    Down,  // 1
    Left,  // 2
    Right, // 3
}

enum Status {
    Active = "ACTIVE",
    Inactive = "INACTIVE",
}

function move(dir: Direction): string {
    return `moving ${Direction[dir]} (${dir})`;
}

console.log(move(Direction.Left)); // moving Left (2)
console.log(Status.Active);        // ACTIVE

let current: Status = Status.Inactive;
console.log(current === Status.Inactive); // true

Enum одна из немногих возможностей TypeScript, которые не являются просто типами: при компиляции enum становится настоящим объектом JavaScript.

Числовые enum

Без инициализаторов члены получают 0, 1, 2 и так далее. Задайте первому члену число, и остальные продолжат от него. Можно также явно задать каждое значение; это безопасный выбор, когда числа хранятся в базе данных или передаются по сети.

enum Priority {
    Low = 1,
    Medium, // 2
    High,   // 3
}

enum HttpStatus {
    Ok = 200,
    NotFound = 404,
    ServerError = 500,
}

// Bit flags: combine members with |, test with &
enum Permission {
    None = 0,
    Read = 1 << 0,  // 1
    Write = 1 << 1, // 2
    Delete = 1 << 2, // 4
    All = Read | Write | Delete, // 7
}

console.log(Priority.High, HttpStatus.NotFound); // 3 404

const mine = Permission.Read | Permission.Write;
console.log(mine, (mine & Permission.Write) !== 0, (mine & Permission.Delete) !== 0); // 3 true false

Автонумерация подходит для значений, которые никогда не покидают программу. Если порядок членов может поменяться, а числа где-то сохраняются, вставка члена в середину молча перенумерует всё, что идёт после него.

Во что компилируется enum

Типы стираются, а enum нет. Вот JavaScript, который TypeScript генерирует для числового и строкового enum:

enum Direction { Up, Down, Left, Right }
enum Status { Active = "ACTIVE", Inactive = "INACTIVE" }

var Direction;
(function (Direction) {
    Direction[Direction["Up"] = 0] = "Up";
    Direction[Direction["Down"] = 1] = "Down";
    Direction[Direction["Left"] = 2] = "Left";
    Direction[Direction["Right"] = 3] = "Right";
})(Direction || (Direction = {}));
var Status;
(function (Status) {
    Status["Active"] = "ACTIVE";
    Status["Inactive"] = "INACTIVE";
})(Status || (Status = {}));

Direction["Up"] = 0 возвращает 0, поэтому в том же выражении задаётся Direction[0] = "Up". Значит, числовой enum отображает в обе стороны: имя в число и число обратно в имя. Это и есть обратное отображение. Строковые enum отображают только имена в значения.

enum Direction { Up, Down, Left, Right }
enum Status { Active = "ACTIVE", Inactive = "INACTIVE" }

console.log(Direction);
console.log(Direction[2]);    // Left: number to name
console.log(Direction.Left);  // 2: name to number
console.log(Status);          // { Active: 'ACTIVE', Inactive: 'INACTIVE' }

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

Строковые enum

Каждому члену строкового enum нужно явное строковое значение. Значения попадают в логи, JSON и базы данных как есть, поэтому строковые enum отлаживать проще, чем числа.

Строковый enum в одном отношении номинален, и это удивляет: обычную строку нельзя ему присвоить, даже если текст совпадает со значением члена.

// This does not compile: "ACTIVE" is a string, not a Status.
enum Status {
    Active = "ACTIVE",
    Inactive = "INACTIVE",
}

let current: Status = "ACTIVE";
console.log(current);

index.ts(7,5): error TS2820: Type '"ACTIVE"' is not assignable to type 'Status'. Did you mean 'Status.Inactive'?

(Подсказка в сообщении это догадка компилятора, и здесь она неверна; исправление: Status.Active.) В обратную сторону значение Status можно использовать везде, где ожидается string. Когда значения приходят строками, из JSON или формы, преобразуйте их с проверкой, как в разделе о проверке значений ниже.

Enum как тип

Имя enum это тип, значения которого его члены. Вместе со switch TypeScript проверяет, что обработан каждый член, если функция должна вернуть значение:

enum Shape { Circle = "circle", Square = "square", Triangle = "triangle" }

function sides(shape: Shape): number {
    switch (shape) {
        case Shape.Circle: return 0;
        case Shape.Square: return 4;
        case Shape.Triangle: return 3;
    }
}

console.log(sides(Shape.Square)); // 4

// Numeric enums accept any number, not only member values:
enum Level { Low, High }
const fromDb: number = 57;
const level: Level = fromDb; // compiles
console.log(level);           // 57

Если в Shape добавить новый член без нового case, sides перестанет компилироваться с ошибкой TS2366, Function lacks ending return statement and return type does not include 'undefined'. На странице switch показана более строгая проверка полноты через never.

Последние строки показывают реальную слабость числовых enum. Числовой литерал, который не совпадает ни с одним членом, const level: Level = 99, даёт ошибку компиляции (TS2322), но любое значение типа number принимается, поэтому 57 проходит. У строковых enum такой дыры нет.

Перебор enum

Во время выполнения enum это объект, поэтому Object.keys, Object.values и Object.entries работают. Для строкового enum они возвращают ровно его члены. Для числового они возвращают ещё и записи обратного отображения, которые нужно отфильтровать:

enum Status { Active = "ACTIVE", Inactive = "INACTIVE", Banned = "BANNED" }
enum Direction { Up, Down, Left, Right }

console.log(Object.keys(Status));   // [ 'Active', 'Inactive', 'Banned' ]
console.log(Object.values(Status)); // [ 'ACTIVE', 'INACTIVE', 'BANNED' ]

for (const [name, value] of Object.entries(Status)) {
    console.log(`${name} = ${value}`);
}

// Numeric enum: keys include "0", "1", ... from the reverse mapping
const names = Object.keys(Direction).filter((k) => isNaN(Number(k)));
const values = Object.values(Direction).filter((v) => typeof v === "number");
console.log(names);  // [ 'Up', 'Down', 'Left', 'Right' ]
console.log(values); // [ 0, 1, 2, 3 ]

Чтобы типизировать переменную как «одно из имён членов enum», используйте keyof typeof Direction: это объединение "Up" | "Down" | "Left" | "Right". Тогда Direction[name] найдёт значение с полной типобезопасностью.

У строкового enum обратного отображения нет, поэтому, чтобы получить имя члена по значению, ищите в записях: Object.entries(Status).find(([, v]) => v === "ACTIVE")?.[0] даёт "Active" или undefined, если ни у одного члена такого значения нет.

Проверка, входит ли значение в enum

Данные извне программы это обычные string или number. Защитник типа сверяет их со значениями enum и сужает до типа enum:

enum Status { Active = "ACTIVE", Inactive = "INACTIVE" }

function isStatus(value: string): value is Status {
    return (Object.values(Status) as string[]).includes(value);
}

function parseStatus(raw: string): Status {
    if (!isStatus(raw)) throw new Error(`unknown status: ${raw}`);
    return raw; // narrowed to Status
}

console.log(parseStatus("ACTIVE") === Status.Active); // true
try {
    parseStatus("DELETED");
} catch (e) {
    if (e instanceof Error) console.log(e.message); // unknown status: DELETED
}

// Enum member name from a string key:
const key: string = "Inactive";
console.log(Status[key as keyof typeof Status]); // INACTIVE

Не пишите raw as Status для непроверенного ввода: утверждение компилируется, но во время выполнения ничего не проверяется, и "DELETED" пойдёт по программе с типом корректного Status.

const enum

const enum просит компилятор удалить enum и подставить значение каждого члена туда, где он используется. Объекта во время выполнения нет, поэтому ничего нельзя перебрать или обратно отобразить.

const enum Size {
    Small = 1,
    Medium = 2,
    Large = 3,
}

const chosen = Size.Large;
console.log(chosen); // 3

// Emitted JavaScript for the line above:
//   const chosen = 3 /* Size.Large */;
// There is no Size object; Object.keys(Size) is a compile error (TS2475).

const enum экономит несколько байтов и одно обращение к свойству, но зависит от того, видит ли компилятор объявление enum при компиляции каждого файла, который его использует. Инструменты, транспилирующие по одному файлу, например Babel и swc, не видят const enum, объявленный в другом файле; удаление типов в Node отвергает const enum, как и любой другой enum; а при isolatedModules или verbatimModuleSyntax TypeScript сообщает об ошибке TS2748, если вы используете const enum из файла объявлений. Большинству прикладного кода const enum не нужны.

Enum, объединение типов или объект с as const

Есть три распространённых способа задать фиксированный набор значений:

// 1. Enum
enum ColorEnum { Red = "red", Green = "green" }

// 2. Union of string literals: types only, nothing at runtime
type ColorUnion = "red" | "green";

// 3. as const object: runtime values plus a derived union type
const Color = { Red: "red", Green: "green" } as const;
type Color = (typeof Color)[keyof typeof Color]; // "red" | "green"

function paintEnum(c: ColorEnum) { return `enum ${c}`; }
function paintUnion(c: ColorUnion) { return `union ${c}`; }
function paintConst(c: Color) { return `const ${c}`; }

console.log(paintEnum(ColorEnum.Red)); // needs the enum member
console.log(paintUnion("red"));        // plain strings work
console.log(paintConst(Color.Red), paintConst("green")); // both work
console.log(Object.values(Color));     // [ 'red', 'green' ]

Многие команды сейчас по умолчанию используют объединение строковых литералов и переходят на объект с as const, когда значения нужны во время выполнения (чтобы их перебрать или построить выпадающий список). Причины: объединения это чистые типы и исчезают из результата; они принимают обычные строки, которые приходят из JSON и API; а enum единственная часть повседневного TypeScript, которая не укладывается в формулу «JavaScript плюс стираемые типы».

Последний пункт стал практическим. Node запускает файлы .ts напрямую, удаляя типы, а enum удалить нельзя:

node status.ts

SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript enum is not supported in strip-only mode

Флаг Node --experimental-transform-types позволяет запускать enum, а опция компилятора erasableSyntaxOnly отмечает каждый enum ошибкой TS1294, This syntax is not allowed when 'erasableSyntaxOnly' is enabled., так что проект может запретить их заранее. Как работает удаление типов, описано на странице запуск TypeScript. Всё это не делает enum неправильными: код, скомпилированный tsc или бандлером, выполняет их без проблем, а кодовая база, где enum уже используются, мало что выиграет от их замены.