TypeScript Enum: numerische, String- und const Enums

Ein TypeScript-Enum ist eine benannte Menge von Konstanten. enum Direction { Up, Down, Left, Right } erzeugt sowohl einen Typ, Direction, als auch ein Objekt zur Laufzeit, auf dessen Member du mit Direction.Up zugreifst. Die Member werden ab 0 durchnummeriert, wenn du ihnen keine Werte gibst, und String-Enums geben jedem Member einen lesbaren 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

Enums gehören zu den wenigen TypeScript-Features, die nicht nur Typen sind: Ein Enum wird beim Kompilieren zu einem echten JavaScript-Objekt.

Numerische Enums

Ohne Initialisierer bekommen die Member 0, 1, 2 und so weiter. Gibst du dem ersten Member eine Zahl, zählen die übrigen von dort weiter. Du kannst auch jeden Wert ausdrücklich setzen, was die sichere Wahl ist, wenn die Zahlen in einer Datenbank gespeichert oder über das Netzwerk gesendet werden.

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

Auf die automatische Nummerierung zu setzen ist in Ordnung für Werte, die das Programm nie verlassen. Kann sich die Reihenfolge der Member ändern und werden die Zahlen irgendwo gespeichert, nummeriert ein in der Mitte eingefügter Member stillschweigend alles danach um.

Wozu ein Enum kompiliert wird

Typen werden entfernt, ein Enum aber nicht. Das ist das JavaScript, das TypeScript für ein numerisches und ein String-Enum erzeugt:

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 gibt 0 zurück, also wird in derselben Anweisung Direction[0] = "Up" gesetzt. Ein numerisches Enum bildet daher in beide Richtungen ab: vom Namen zur Zahl und von der Zahl zurück zum Namen. Das ist das Reverse Mapping. String-Enums bilden nur Namen auf Werte ab.

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

Das ausgegebene Objekt Direction hat acht Schlüssel: die vier Namen und die vier Zahlen. Das wird wichtig, sobald du darüber iterierst.

String-Enums

Jeder Member eines String-Enums braucht einen ausdrücklichen String-Wert. Die Werte erscheinen unverändert in Logs, JSON und Datenbanken, wodurch String-Enums leichter zu debuggen sind als Zahlen.

Ein String-Enum ist in einer Hinsicht nominal, die viele überrascht: Ein einfacher String ist ihm nicht zuweisbar, selbst wenn der Text dem Wert eines Members entspricht.

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

(Der Vorschlag in der Meldung ist eine Vermutung des Compilers und hier falsch; die Lösung ist Status.Active.) In die andere Richtung kann ein Status-Wert überall verwendet werden, wo ein string erwartet wird. Kommen Werte als Strings an, aus JSON oder einem Formular, wandle sie mit einer Prüfung um wie im Abschnitt zum Prüfen von Werten weiter unten.

Ein Enum als Typ verwenden

Der Name des Enums ist ein Typ, dessen Werte seine Member sind. Zusammen mit switch prüft TypeScript, dass jeder Member behandelt wird, wenn die Funktion einen Wert zurückgeben muss:

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

Wird Shape ein neuer Member ohne neuen case hinzugefügt, kompiliert sides nicht mehr und meldet TS2366, Function lacks ending return statement and return type does not include 'undefined'. Die Seite zu switch zeigt die strengere Vollständigkeitsprüfung mit never.

Die letzten Zeilen zeigen eine echte Schwäche numerischer Enums. Ein Zahlenliteral, das zu keinem Member passt, const level: Level = 99, ist ein Compilerfehler (TS2322), aber jeder Wert vom Typ number wird akzeptiert, also kommt 57 durch. String-Enums haben diese Lücke nicht.

Über ein Enum iterieren

Ein Enum ist zur Laufzeit ein Objekt, daher funktionieren Object.keys, Object.values und Object.entries. Bei einem String-Enum liefern sie genau die Member. Bei einem numerischen Enum liefern sie auch die Einträge des Reverse Mappings, die du herausfilterst:

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 ]

Um eine Variable als „einer der Membernamen des Enums“ zu typisieren, nimm keyof typeof Direction, also die Union "Up" | "Down" | "Left" | "Right". Dann schlägt Direction[name] den Wert mit voller Typsicherheit nach.

Ein String-Enum hat kein Reverse Mapping. Um aus einem Wert den Namen eines Members zu bekommen, durchsuchst du die Einträge: Object.entries(Status).find(([, v]) => v === "ACTIVE")?.[0] ist "Active" oder undefined, wenn kein Member diesen Wert hat.

Prüfen, ob ein Wert im Enum liegt

Daten von außerhalb des Programms sind ein einfacher string oder eine number. Ein Type Guard prüft sie gegen die Werte des Enums und engt sie auf den Enum-Typ ein:

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

Vermeide raw as Status bei nicht vertrauenswürdigen Eingaben: Die Assertion kompiliert, aber zur Laufzeit wird nichts geprüft, also würde "DELETED" als gültiger Status typisiert durch das Programm wandern.

const Enums

const enum bittet den Compiler, das Enum zu löschen und den Wert jedes Members dort einzusetzen, wo er verwendet wird. Zur Laufzeit gibt es kein Objekt, also kann nichts iteriert oder rückwärts abgebildet werden.

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 spart ein paar Bytes und einen Eigenschaftszugriff, setzt aber voraus, dass der Compiler die Deklaration des Enums sieht, wenn er jede Datei kompiliert, die es nutzt. Tools, die Datei für Datei transpilieren, etwa Babel und swc, sehen kein const Enum, das in einer anderen Datei deklariert ist; das Type Stripping von Node lehnt const Enums wie jedes andere Enum ab; und mit isolatedModules oder verbatimModuleSyntax meldet TypeScript den Fehler TS2748, wenn du ein const Enum aus einer Deklarationsdatei verwendest. Der meiste Anwendungscode braucht keine const Enums.

Enum vs Union-Typ vs as const Objekt

Es gibt drei gängige Wege, eine feste Menge von Werten zu definieren:

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

Viele Teams nehmen heute standardmäßig eine Union aus String-Literalen und wechseln zum as const Objekt, wenn sie die Werte zur Laufzeit brauchen (um darüber zu iterieren oder ein Dropdown zu bauen). Die Gründe: Unions sind reine Typen und verschwinden aus der Ausgabe; sie akzeptieren die einfachen Strings, die JSON und APIs liefern; und Enums sind das eine Stück alltägliches TypeScript, das nicht „JavaScript plus entfernbare Typen“ ist.

Dieser letzte Punkt ist inzwischen praktisch relevant. Node führt .ts-Dateien direkt aus, indem es die Typen entfernt, und ein Enum lässt sich nicht einfach entfernen:

node status.ts

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

Mit dem Flag --experimental-transform-types laufen Enums in Node, und die Compileroption erasableSyntaxOnly meldet jedes Enum als Fehler TS1294, This syntax is not allowed when 'erasableSyntaxOnly' is enabled., sodass ein Projekt sie von vornherein verbieten kann. Wie Type Stripping funktioniert, steht unter TypeScript ausführen. Nichts davon macht Enums falsch: Code, der mit tsc oder einem Bundler kompiliert wird, führt sie problemlos aus, und eine Codebasis, die Enums bereits nutzt, gewinnt wenig durch eine Umstellung.