Enum en TypeScript : enums numériques, string et const enum

Un enum TypeScript est un ensemble nommé de constantes. enum Direction { Up, Down, Left, Right } crée à la fois un type, Direction, et un objet à l'exécution dont vous accédez aux membres par Direction.Up. Les membres sont numérotés à partir de 0, sauf si vous leur donnez des valeurs, et les enums string attribuent à chaque membre une chaîne lisible.

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

Les enums font partie des rares fonctionnalités de TypeScript qui ne sont pas que des types : un enum devient un véritable objet JavaScript quand le code est compilé.

Enums numériques

Sans initialiseur, les membres reçoivent 0, 1, 2 et ainsi de suite. Donnez un nombre au premier membre et les suivants continuent à partir de lui. Vous pouvez aussi fixer explicitement chaque valeur, ce qui est le choix sûr quand les nombres sont stockés en base de données ou envoyés sur le réseau.

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

S'appuyer sur la numérotation automatique convient aux valeurs qui ne quittent jamais le programme. Si l'ordre des membres peut changer et que les nombres sont enregistrés quelque part, insérer un membre au milieu renumérote en silence tout ce qui le suit.

Ce que produit un enum à la compilation

Les types sont effacés, mais pas un enum. Voici le JavaScript que TypeScript émet pour un enum numérique et un enum string :

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 renvoie 0, donc Direction[0] = "Up" est défini dans la même instruction. Un enum numérique fonctionne ainsi dans les deux sens : du nom vers le nombre, et du nombre vers le nom. C'est le reverse mapping. Les enums string ne vont que des noms vers les valeurs.

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

L'objet Direction affiché a huit clés : les quatre noms et les quatre nombres. Cela compte dès que vous le parcourez.

Enums string

Chaque membre d'un enum string doit avoir une valeur de chaîne explicite. Les valeurs apparaissent telles quelles dans les logs, le JSON et les bases de données, ce qui rend les enums string plus faciles à déboguer que les nombres.

Un enum string est nominal d'une manière qui surprend : une chaîne simple ne lui est pas assignable, même quand le texte correspond à la valeur d'un membre.

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

(La suggestion du message est une supposition du compilateur, fausse ici ; la correction est Status.Active.) Dans l'autre sens, une valeur Status peut être utilisée partout où un string est attendu. Quand les valeurs arrivent sous forme de chaînes, depuis du JSON ou un formulaire, convertissez-les avec une vérification comme celle de la section sur la vérification des valeurs, plus bas.

Utiliser un enum comme type

Le nom de l'enum est un type dont les valeurs sont ses membres. Combiné à switch, TypeScript vérifie que chaque membre est traité quand la fonction doit renvoyer une valeur :

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

Si un nouveau membre est ajouté à Shape sans nouveau case, sides ne compile plus et signale TS2366, Function lacks ending return statement and return type does not include 'undefined'. La page switch montre la vérification exhaustive plus stricte, basée sur never.

Les dernières lignes montrent une vraie faiblesse des enums numériques. Un littéral numérique qui ne correspond à aucun membre, const level: Level = 99, est une erreur de compilation (TS2322), mais toute valeur typée number est acceptée, donc 57 passe. Les enums string n'ont pas cette faille.

Parcourir un enum

Un enum est un objet à l'exécution, donc Object.keys, Object.values et Object.entries fonctionnent. Pour un enum string, ils renvoient exactement les membres. Pour un enum numérique, ils renvoient aussi les entrées du reverse mapping, que vous filtrez :

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 ]

Pour typer une variable comme « l'un des noms de membres de l'enum », utilisez keyof typeof Direction, qui est l'union "Up" | "Down" | "Left" | "Right". Direction[name] récupère alors la valeur en toute sécurité de typage.

Un enum string n'a pas de reverse mapping : pour obtenir le nom d'un membre à partir de sa valeur, cherchez dans les entrées. Object.entries(Status).find(([, v]) => v === "ACTIVE")?.[0] vaut "Active", ou undefined quand aucun membre n'a cette valeur.

Vérifier qu'une valeur appartient à un enum

Les données venues de l'extérieur du programme sont un simple string ou number. Un type guard les compare aux valeurs de l'enum et les affine en type 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

Évitez raw as Status sur une entrée non fiable : l'assertion compile, mais rien n'est vérifié à l'exécution, et "DELETED" traverserait le programme typé comme un Status valide.

const enum

const enum demande au compilateur de supprimer l'enum et d'écrire la valeur de chaque membre là où il est utilisé. Il n'y a aucun objet à l'exécution, donc rien ne peut être parcouru ni faire l'objet d'un reverse mapping.

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 économise quelques octets et une lecture de propriété, mais il suppose que le compilateur voie la déclaration de l'enum quand il compile chaque fichier qui l'utilise. Les outils qui transpilent un fichier à la fois, comme Babel et swc, ne peuvent pas voir un const enum déclaré dans un autre fichier ; le type stripping de Node refuse les const enums comme tous les autres enums ; et avec isolatedModules ou verbatimModuleSyntax, TypeScript signale l'erreur TS2748 quand vous utilisez un const enum provenant d'un fichier de déclaration. La plupart du code applicatif n'a pas besoin de const enums.

Enum, type union ou objet as const

Il existe trois façons courantes de définir un ensemble fixe de valeurs :

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

Beaucoup d'équipes choisissent aujourd'hui par défaut une union de littéraux de chaîne, et passent à l'objet as const quand elles ont besoin des valeurs à l'exécution (pour les parcourir ou construire une liste déroulante). Les raisons : les unions sont de purs types et disparaissent de la sortie ; elles acceptent les chaînes simples que livrent le JSON et les API ; et les enums sont la seule brique du TypeScript courant qui ne soit pas « du JavaScript plus des types effaçables ».

Ce dernier point est devenu concret. Node exécute directement les fichiers .ts en retirant les types, et un enum n'est pas quelque chose qu'il peut retirer :

node status.ts

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

L'option --experimental-transform-types de Node permet d'exécuter les enums, et l'option de compilation erasableSyntaxOnly signale chaque enum par l'erreur TS1294, This syntax is not allowed when 'erasableSyntaxOnly' is enabled., ce qui permet à un projet de les interdire d'emblée. Voir exécuter TypeScript pour le fonctionnement du type stripping. Rien de tout cela ne rend les enums mauvais : le code compilé avec tsc ou un bundler les exécute sans problème, et une base de code qui utilise déjà des enums a peu à gagner à les convertir.