Enum in TypeScript: enum numerici, di stringhe e const

Un enum TypeScript è un insieme di costanti con nome. enum Direction { Up, Down, Left, Right } crea sia un tipo, Direction, sia un oggetto a runtime i cui membri raggiungi come Direction.Up. I membri sono numerati da 0 se non dai loro dei valori, e gli enum di stringhe danno a ogni membro una stringa leggibile.

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

Gli enum sono una delle poche funzionalità di TypeScript che non sono solo tipi: un enum diventa un vero oggetto JavaScript quando il codice viene compilato.

Enum numerici

Senza inizializzatori, i membri ricevono 0, 1, 2 e così via. Dai un numero al primo membro e gli altri proseguono da lì. Puoi anche impostare esplicitamente ogni valore, che è la scelta sicura quando i numeri vengono salvati in un database o inviati in rete.

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

Affidarsi alla numerazione automatica va bene per valori che non escono mai dal programma. Se l'ordine dei membri potrebbe cambiare e i numeri vengono salvati da qualche parte, inserire un membro in mezzo rinumera in silenzio tutto ciò che viene dopo.

In cosa viene compilato un enum

I tipi vengono cancellati, ma un enum no. Questo è il JavaScript che TypeScript emette per un enum numerico e uno di stringhe:

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 restituisce 0, quindi Direction[0] = "Up" viene impostato nella stessa istruzione. Un enum numerico mappa quindi in entrambe le direzioni: dal nome al numero e dal numero di nuovo al nome. È la mappatura inversa. Gli enum di stringhe mappano solo dai nomi ai valori.

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'oggetto Direction stampato ha otto chiavi: i quattro nomi e i quattro numeri. Conta non appena ci iteri sopra.

Enum di stringhe

Ogni membro di un enum di stringhe ha bisogno di un valore stringa esplicito. I valori compaiono così come sono in log, JSON e database, e questo rende gli enum di stringhe più facili da debuggare dei numeri.

Un enum di stringhe è nominale in un modo che sorprende molti: una stringa semplice non gli è assegnabile, anche quando il testo corrisponde al valore di un membro.

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

(Il suggerimento nel messaggio è un'ipotesi del compilatore e qui è sbagliato; la soluzione è Status.Active.) Nell'altra direzione, un valore Status si può usare ovunque sia attesa una string. Quando i valori arrivano come stringhe, da JSON o da un form, convertili con un controllo come quello della sezione sul controllo dei valori più sotto.

Usare un enum come tipo

Il nome dell'enum è un tipo i cui valori sono i suoi membri. Combinato con switch, TypeScript verifica che ogni membro sia gestito quando la funzione deve restituire un valore:

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

Se viene aggiunto un nuovo membro a Shape senza un nuovo case, sides smette di compilare con TS2366, Function lacks ending return statement and return type does not include 'undefined'. La pagina su switch mostra il controllo di esaustività più rigoroso basato su never.

Le ultime righe mostrano una debolezza reale degli enum numerici. Un letterale numerico che non corrisponde a nessun membro, const level: Level = 99, è un errore di compilazione (TS2322), ma qualsiasi valore tipizzato number viene accettato, quindi 57 passa. Gli enum di stringhe non hanno questa falla.

Iterare su un enum

A runtime un enum è un oggetto, quindi Object.keys, Object.values e Object.entries funzionano. Per un enum di stringhe restituiscono esattamente i membri. Per un enum numerico restituiscono anche le voci della mappatura inversa, che vanno filtrate:

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 ]

Per tipizzare una variabile come "uno dei nomi dei membri dell'enum", usa keyof typeof Direction, che è la union "Up" | "Down" | "Left" | "Right". Allora Direction[name] recupera il valore con piena sicurezza dei tipi.

Un enum di stringhe non ha mappatura inversa, quindi per ottenere il nome di un membro dal suo valore cerca tra le voci: Object.entries(Status).find(([, v]) => v === "ACTIVE")?.[0] è "Active", oppure undefined quando nessun membro ha quel valore.

Verificare se un valore è in un enum

I dati che arrivano da fuori dal programma sono una semplice string o un number. Una type guard li confronta con i valori dell'enum e li restringe al tipo dell'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

Evita raw as Status su input non affidabili: l'asserzione compila, ma a runtime non viene controllato nulla, quindi "DELETED" attraverserebbe il programma tipizzato come Status valido.

const enum

const enum chiede al compilatore di eliminare l'enum e scrivere il valore di ogni membro dove viene usato. A runtime non c'è alcun oggetto, quindi non si può iterare né usare la mappatura inversa.

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 fa risparmiare qualche byte e una ricerca di proprietà, ma richiede che il compilatore veda la dichiarazione dell'enum quando compila ogni file che lo usa. Gli strumenti che traspilano un file alla volta, come Babel e swc, non vedono un const enum dichiarato in un altro file; il type stripping di Node rifiuta i const enum come ogni altro enum; e con isolatedModules o verbatimModuleSyntax TypeScript segnala l'errore TS2748 quando usi un const enum da un file di dichiarazione. La maggior parte del codice applicativo non ha bisogno dei const enum.

Enum vs tipo union vs oggetto as const

Ci sono tre modi comuni per definire un insieme fisso di valori:

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

Molti team oggi partono da una union di letterali stringa, e passano all'oggetto as const quando servono i valori a runtime (per iterarli o costruire un menu a tendina). I motivi: le union sono tipi puri e spariscono dall'output; accettano le stringhe semplici che arrivano da JSON e API; e gli enum sono l'unico pezzo di TypeScript di tutti i giorni che non è "JavaScript più tipi cancellabili".

Quest'ultimo punto è diventato concreto. Node esegue direttamente i file .ts togliendo i tipi, e un enum non è qualcosa che possa togliere:

node status.ts

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

Il flag di Node --experimental-transform-types fa funzionare gli enum, e l'opzione del compilatore erasableSyntaxOnly segnala ogni enum come errore TS1294, This syntax is not allowed when 'erasableSyntaxOnly' is enabled., così un progetto può vietarli fin dall'inizio. Vedi eseguire TypeScript per come funziona il type stripping. Niente di tutto questo rende sbagliati gli enum: il codice compilato con tsc o con un bundler li esegue senza problemi, e un codebase che usa già gli enum guadagna poco a convertirli.