TypeScript Enums vs Const Enums vs Union Types

Also Known As

TL;DR

Explanation

Regular enum: generates JavaScript object, supports reverse mapping (Direction[0] === 'Up'). Const enum: fully inlined at compile time — zero JavaScript generated, faster but no runtime access. String union type: type Direction = 'Up' | 'Down' — no JavaScript emitted, readable, tree-shakeable, and more compatible with JSON APIs. The TypeScript community trend: prefer string union types over enums for most cases; use const enums only when performance is critical and runtime access is not needed; avoid regular numeric enums (they allow invalid values).

Common Misconception

Why It Matters

Common Mistakes

• Numeric enums in APIs — JSON serialises as numbers, not readable names.
• Regular enums where const enums or union types would be better — unnecessary JavaScript overhead.
• Mixing enum and non-enum values — direction: Direction | null requires careful handling.
• Using enum as a namespace — use a regular object const as a namespace instead.

Code Examples

// Numeric enum — allows invalid values, generates JS:
enum Direction { Up, Down, Left, Right }
const d: Direction = 99; // No error! 99 is not a valid direction
JSON.stringify(Direction.Up); // '0' — not readable

// Regular enum generates runtime JS object:
// var Direction;
// Direction[Direction.Up = 0] = 'Up'; ...

// String union — zero JS, type-safe, readable JSON:
type Direction = 'Up' | 'Down' | 'Left' | 'Right';
const d: Direction = 'Invalid'; // Compile error!
JSON.stringify('Up'); // 'Up' — readable

// Const enum — inlined, no JS:
const enum Color { Red = 'red', Blue = 'blue' }
const c = Color.Red; // Compiled to: const c = 'red'

// Object const as namespace when runtime needed:
export const Direction = { Up: 'up', Down: 'down' } as const;
export type Direction = typeof Direction[keyof typeof Direction];

References

• ↗ https://www.typescriptlang.org/docs/handbook/enums.html

Tags

Related Terms