Enum w TypeScript: enumy numeryczne, tekstowe i const enum

Enum w TypeScript to nazwany zbiór stałych. enum Direction { Up, Down, Left, Right } tworzy jednocześnie typ Direction i obiekt istniejący w czasie działania programu, do którego członów odwołujesz się przez Direction.Up. Człony są numerowane od 0, chyba że nadasz im wartości, a enumy tekstowe dają każdemu członowi czytelny string.

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

Enumy to jedna z nielicznych funkcji TypeScriptu, które nie są wyłącznie typami: po kompilacji enum staje się prawdziwym obiektem JavaScriptu.

Enumy numeryczne

Bez inicjalizatorów człony dostają 0, 1, 2 i tak dalej. Jeśli nadasz liczbę pierwszemu członowi, kolejne liczą dalej od niej. Możesz też ustawić każdą wartość jawnie, co jest bezpiecznym wyborem, gdy liczby trafiają do bazy danych albo są przesyłane przez sieć.

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

Automatyczne numerowanie wystarcza dla wartości, które nigdy nie opuszczają programu. Jeśli kolejność członów może się zmienić, a liczby są gdziekolwiek zapisywane, wstawienie członu w środek po cichu przenumeruje wszystko, co jest za nim.

Do czego kompiluje się enum

Typy są wymazywane, ale enum nie. Tak wygląda JavaScript, który TypeScript generuje dla enuma numerycznego i tekstowego:

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 zwraca 0, więc w tej samej instrukcji ustawiane jest też Direction[0] = "Up". Enum numeryczny działa więc w obie strony: z nazwy na liczbę i z liczby z powrotem na nazwę. To jest mapowanie odwrotne (reverse mapping). Enumy tekstowe mapują tylko nazwy na wartości.

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' }

Wypisany obiekt Direction ma osiem kluczy: cztery nazwy i cztery liczby. Ma to znaczenie, gdy tylko zaczniesz po nim iterować.

Enumy tekstowe

Każdy człon enuma tekstowego potrzebuje jawnej wartości tekstowej. Wartości pojawiają się bez zmian w logach, JSON-ie i bazach danych, dlatego enumy tekstowe łatwiej debugować niż liczby.

Enum tekstowy jest pod jednym względem nominalny, co często zaskakuje: zwykłego stringa nie można do niego przypisać, nawet jeśli tekst jest taki sam jak wartość któregoś członu.

// 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'?

(Podpowiedź w komunikacie to zgadywanie kompilatora i tutaj jest błędna; poprawka to Status.Active.) W drugą stronę wartość typu Status można użyć wszędzie tam, gdzie oczekiwany jest string. Gdy wartości przychodzą jako stringi, z JSON-a albo z formularza, zamieniaj je z użyciem sprawdzenia takiego jak w sekcji o sprawdzaniu wartości poniżej.

Enum jako typ

Nazwa enuma jest typem, którego wartościami są jego człony. W połączeniu ze switch TypeScript sprawdza, czy obsłużono każdy człon, gdy funkcja musi zwrócić wartość:

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

Jeśli do Shape dojdzie nowy człon bez nowego case, sides przestanie się kompilować z błędem TS2366, Function lacks ending return statement and return type does not include 'undefined'. Strona o switch pokazuje ostrzejsze sprawdzenie wyczerpujące oparte na never.

Ostatnie linie pokazują prawdziwą słabość enumów numerycznych. Literał liczbowy, który nie pasuje do żadnego członu, const level: Level = 99, to błąd kompilacji (TS2322), ale każda wartość typu number zostanie przyjęta, więc 57 przechodzi. Enumy tekstowe nie mają tej luki.

Iterowanie po enumie

W czasie działania enum jest obiektem, więc działają Object.keys, Object.values i Object.entries. Dla enuma tekstowego zwracają dokładnie jego człony. Dla enuma numerycznego zwracają też wpisy mapowania odwrotnego, które trzeba odfiltrować:

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 ]

Aby zmienna miała typ „jedna z nazw członów enuma”, użyj keyof typeof Direction, czyli unii "Up" | "Down" | "Left" | "Right". Wtedy Direction[name] odczytuje wartość z pełnym bezpieczeństwem typów.

Enum tekstowy nie ma mapowania odwrotnego, więc żeby uzyskać nazwę członu z jego wartości, przeszukaj wpisy: Object.entries(Status).find(([, v]) => v === "ACTIVE")?.[0] daje "Active" albo undefined, gdy żaden człon nie ma takiej wartości.

Sprawdzanie, czy wartość należy do enuma

Dane spoza programu to zwykły string albo number. Strażnik typu sprawdza je względem wartości enuma i zawęża do typu enuma:

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

Unikaj raw as Status dla niezaufanych danych: asercja się kompiluje, ale w czasie działania nic nie jest sprawdzane, więc "DELETED" wędrowałoby przez program z typem poprawnego Status.

const enum

const enum prosi kompilator, żeby usunął enum i w każdym miejscu użycia wpisał wartość członu. W czasie działania nie ma żadnego obiektu, więc nie da się po nim iterować ani korzystać z mapowania odwrotnego.

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 oszczędza kilka bajtów i jedno odczytanie właściwości, ale wymaga, żeby kompilator widział deklarację enuma przy kompilacji każdego pliku, który go używa. Narzędzia transpilujące po jednym pliku, takie jak Babel i swc, nie widzą const enuma zadeklarowanego w innym pliku; usuwanie typów w Node odrzuca const enumy tak samo jak każdy inny enum; a przy isolatedModules albo verbatimModuleSyntax TypeScript zgłasza błąd TS2748, gdy używasz const enuma z pliku deklaracji. Większość kodu aplikacji nie potrzebuje const enumów.

Enum a typ unii i obiekt as const

Są trzy popularne sposoby na zdefiniowanie stałego zbioru wartości:

// 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' ]

Wiele zespołów domyślnie wybiera dziś unię literałów tekstowych, a na obiekt as const przechodzi, gdy potrzebuje wartości w czasie działania (żeby po nich iterować albo zbudować listę rozwijaną). Powody: unie są czystymi typami i znikają z wyniku kompilacji; przyjmują zwykłe stringi, które dostarczają JSON i API; a enumy to jedyny element codziennego TypeScriptu, który nie jest „JavaScriptem plus wymazywalnymi typami”.

Ten ostatni punkt ma dziś praktyczne znaczenie. Node uruchamia pliki .ts bezpośrednio, usuwając typy, a enuma nie da się po prostu usunąć:

node status.ts

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

Flaga Node --experimental-transform-types pozwala uruchomić enumy, a opcja kompilatora erasableSyntaxOnly zgłasza każdy enum jako błąd TS1294, This syntax is not allowed when 'erasableSyntaxOnly' is enabled., więc projekt może zakazać ich z góry. Jak działa usuwanie typów, wyjaśnia strona o uruchamianiu TypeScriptu. Nic z tego nie oznacza, że enumy są złe: kod kompilowany przez tsc albo bundler uruchamia je bez problemu, a projekt, który już używa enumów, niewiele zyska na ich przepisaniu.