TypeScript
Uso de enums numéricos, string enums y const enum, su representación en runtime y alternativas con objetos as const y union types.
Un define un conjunto de miembros relacionados y, a diferencia de una literal union, normalmente crea también un objeto durante ejecución.
enumenum OrderStatus {
Pending,
Completed,
Cancelled,
}enum Direction {
Up,
Down,
Left,
Right,
}Los valores comienzan en cero y se incrementan automáticamente.
Direction.Up; // 0
Direction.Down; // 1Puedes definir un inicio:
enum HttpStatus {
Ok = 200,
Created = 201,
NoContent = 204,
}console.log(Direction);Los numeric enums suelen emitir un objeto con mapeo en ambas direcciones:
Direction[Direction.Up];
// "Up"Esta reverse mapping aumenta la salida y solo existe para miembros numéricos.
enum PaymentStatus {
Pending = "pending",
Approved = "approved",
Rejected = "rejected",
}Los valores son legibles al serializar y no tienen reverse mapping automática.
enum Mixed {
No = 0,
Yes = "YES",
}Es válido, pero mezcla dos representaciones y rara vez comunica un dominio claro. Prefiere un solo tipo de valor.
enum FileAccess {
None,
Read = 1 << 1,
Write = 1 << 2,
ReadWrite = Read | Write,
Generated = "abc".length,
}Los miembros constantes pueden calcularse durante compilación. Los calculados dependen de una expresión evaluada en runtime y afectan qué miembros posteriores pueden omitir initializer.
function updateStatus(status: OrderStatus): void {}Cada miembro literal puede participar también como tipo:
type FinalStatus =
| OrderStatus.Completed
| OrderStatus.Cancelled;Cuando todos los miembros son literales, TypeScript conoce el conjunto cerrado y detecta comparaciones imposibles.
function process(status: OrderStatus): void {
if (
status !== OrderStatus.Pending ||
status !== OrderStatus.Completed
) {
// condición sospechosa
}
}type DirectionName = keyof typeof Direction;
// "Up" | "Down" | "Left" | "Right"keyof Direction no consulta el objeto enum. Necesitas typeof para llevar el valor constructor al espacio de tipos.
type OrderStatus =
| "pending"
| "completed"
| "cancelled";La union:
as const.El enum:
const OrderStatus = {
Pending: "pending",
Completed: "completed",
Cancelled: "cancelled",
} as const;
type OrderStatus = (
typeof OrderStatus
)[keyof typeof OrderStatus];Ofrece objeto runtime y literal union sin la emisión especial de enum.
Para muchas aplicaciones modernas esta alternativa es simple, compatible con JavaScript y fácil de serializar.
Los numeric enums han tenido históricamente compatibilidad permisiva con numbers. En versiones modernas, TypeScript asigna tipos únicos a miembros calculados y mejora la comprobación, pero una frontera externa sigue necesitando validar que el número corresponda a un miembro válido.
function parseDirection(value: unknown): Direction {
if (
typeof value !== "number" ||
!(value in Direction)
) {
throw new TypeError("Invalid direction");
}
return value;
}Con reverse mapping, in también encuentra nombres string; limita primero el tipo esperado.
const enum Direction {
Up,
Down,
}
const direction = Direction.Up;El compilador puede inlinear el valor y eliminar el objeto enum.
Salida conceptual:
const direction = 0;Un consumidor puede compilar contra una versión del .d.ts e instalar otra versión runtime. Los valores inlineados pueden quedar desalineados.
También crea problemas con herramientas que transpilan de forma aislada y no pueden resolver declarations externas de forma completa.
Por eso evita publicar ambient const enums en librerías salvo una estrategia muy controlada.
{
"compilerOptions": {
"preserveConstEnums": true
}
}Conserva el objeto runtime de const enums de forma parecida a enums normales. El propio proyecto TypeScript puede eliminar const de declarations publicadas para evitar que consumidores inlineen valores externos.
Los ambient const enums son incompatibles con varios flujos de isolatedModules, porque el transformador por archivo no puede conocer sus valores con seguridad.
declare enum LegacyStatus {
Pending,
Completed,
}Describe un objeto enum proporcionado externamente. Los miembros sin initializer se consideran calculados bajo reglas ambient y deben coincidir con el runtime.
enum Permission {
None = 0,
Read = 1 << 0,
Write = 1 << 1,
Delete = 1 << 2,
}
const permissions = Permission.Read | Permission.Write;Los numeric enums pueden expresar flags, pero documenta operaciones y valida combinaciones.
enum NativeErrorCode {
NotFound = 1,
PermissionDenied = 2,
Timeout = 3,
}Tiene sentido cuando una API externa utiliza códigos numéricos estables y los nombres mejoran legibilidad interna.
keyof typeof Enum obtiene nombres de miembros.as const son alternativas comunes.¿Por qué cambiar el orden de un numeric enum puede romper datos persistidos?
Porque los miembros sin initializer reciben números según su posición. Al reordenarlos, el mismo número guardado puede pasar a representar otro miembro.
Decorators explica metaprogramación runtime y diferencia el estándar moderno del sistema legacy.