Enum en TypeScript: enums numéricos, de string y const enum

Un enum en TypeScript es un conjunto de constantes con nombre. enum Direction { Up, Down, Left, Right } crea a la vez un tipo, Direction, y un objeto en tiempo de ejecución a cuyos miembros accedes como Direction.Up. Los miembros se numeran desde 0 salvo que les des valores, y los enums de string dan a cada miembro un string legible.

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

Los enums son una de las pocas características de TypeScript que no son solo tipos: un enum se convierte en un objeto real de JavaScript cuando se compila el código.

Enums numéricos

Sin inicializadores, los miembros reciben 0, 1, 2 y así sucesivamente. Da un número al primer miembro y los demás continúan a partir de él. También puedes fijar cada valor de forma explícita, que es la opción segura cuando los números se guardan en una base de datos o se envían por la red.

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

Confiar en la numeración automática está bien para valores que nunca salen del programa. Si el orden de los miembros puede cambiar y los números se guardan en algún sitio, insertar un miembro en medio renumera sin avisar todo lo que va detrás.

A qué compila un enum

Los tipos se borran, pero un enum no. Este es el JavaScript que genera TypeScript para un enum numérico y uno de strings:

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 devuelve 0, así que Direction[0] = "Up" se asigna en la misma sentencia. Por eso un enum numérico funciona en los dos sentidos: de nombre a número y de número a nombre. Eso es el mapeo inverso (reverse mapping). Los enums de string solo van de nombre a valor.

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

El objeto Direction impreso tiene ocho claves: los cuatro nombres y los cuatro números. Eso importa en cuanto lo recorres.

Enums de string

Cada miembro de un enum de strings necesita un valor de string explícito. Los valores aparecen tal cual en los logs, el JSON y las bases de datos, lo que hace que los enums de string sean más fáciles de depurar que los números.

Un enum de strings es nominal de una manera que sorprende: un string normal no se le puede asignar, aunque el texto coincida con el valor de un miembro.

// 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 sugerencia del mensaje es una suposición del compilador y aquí se equivoca; la solución es Status.Active). En la otra dirección, un valor Status se puede usar en cualquier sitio donde se espere un string. Cuando los valores llegan como strings, desde JSON o un formulario, conviértelos con una comprobación como la de la sección sobre comprobar valores, más abajo.

Usar un enum como tipo

El nombre del enum es un tipo cuyos valores son sus miembros. Junto con switch, TypeScript comprueba que se maneja cada miembro cuando la función debe devolver un valor:

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 se añade un miembro nuevo a Shape sin un case nuevo, sides deja de compilar con TS2366, Function lacks ending return statement and return type does not include 'undefined'. La página de switch muestra la comprobación exhaustiva más estricta basada en never.

Las últimas líneas muestran un punto débil real de los enums numéricos. Un literal numérico que no coincide con ningún miembro, const level: Level = 99, es un error de compilación (TS2322), pero se acepta cualquier valor de tipo number, así que 57 pasa. Los enums de string no tienen este agujero.

Recorrer un enum

Un enum es un objeto en tiempo de ejecución, así que Object.keys, Object.values y Object.entries funcionan. En un enum de strings devuelven exactamente los miembros. En un enum numérico devuelven también las entradas del mapeo inverso, que tienes que filtrar:

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 ]

Para tipar una variable como «uno de los nombres de miembro del enum», usa keyof typeof Direction, que es la unión "Up" | "Down" | "Left" | "Right". Así Direction[name] busca el valor con total seguridad de tipos.

Un enum de strings no tiene mapeo inverso, así que para obtener el nombre de un miembro a partir de su valor, busca en las entradas: Object.entries(Status).find(([, v]) => v === "ACTIVE")?.[0] es "Active", o undefined cuando ningún miembro tiene ese valor.

Comprobar si un valor está en un enum

Los datos que vienen de fuera del programa son un string o un number normal. Un type guard los comprueba contra los valores del enum y los estrecha al tipo del 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 con entradas no fiables: la aserción compila, pero no se comprueba nada en tiempo de ejecución, así que "DELETED" recorrería el programa tipado como un Status válido.

const enum

const enum le pide al compilador que elimine el enum y escriba el valor de cada miembro allí donde se usa. No hay ningún objeto en tiempo de ejecución, así que no se puede recorrer ni usar el mapeo inverso.

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 ahorra unos bytes y una consulta de propiedad, pero depende de que el compilador vea la declaración del enum al compilar cada archivo que lo usa. Las herramientas que transpilan archivo por archivo, como Babel y swc, no pueden ver un const enum declarado en otro archivo; el type stripping de Node rechaza los const enum igual que cualquier otro enum; y con isolatedModules o verbatimModuleSyntax TypeScript da el error TS2748 cuando usas un const enum de un archivo de declaraciones. La mayoría del código de aplicación no necesita const enums.

Enum frente a tipo unión y objeto as const

Hay tres formas habituales de definir un conjunto fijo de valores:

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

Muchos equipos usan ahora por defecto una unión de literales de string, y pasan al objeto as const cuando necesitan los valores en tiempo de ejecución (para recorrerlos o construir un desplegable). Las razones: las uniones son tipos puros y desaparecen de la salida; aceptan los strings normales que entregan el JSON y las APIs; y los enums son la única pieza del TypeScript de todos los días que no es «JavaScript más tipos borrables».

Ese último punto ya tiene consecuencias prácticas. Node ejecuta archivos .ts directamente eliminando los tipos, y un enum no es algo que pueda eliminar:

node status.ts

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

La opción --experimental-transform-types de Node hace que los enums funcionen, y la opción del compilador erasableSyntaxOnly marca cada enum con el error TS1294, This syntax is not allowed when 'erasableSyntaxOnly' is enabled., así que un proyecto puede prohibirlos desde el principio. Consulta ejecutar TypeScript para ver cómo funciona el type stripping. Nada de esto hace que los enums estén mal: el código compilado con tsc o con un bundler los ejecuta sin problema, y un proyecto que ya usa enums gana poco convirtiéndolos.