TypeScript Enums and Better Alternatives

TypeScript enums have quirks. Here's when to use them and better alternatives.

Numeric Enums#

// Basic numeric enum
enum Direction {
  Up,      // 0
  Down,    // 1
  Left,    // 2
  Right,   // 3
}

const move = Direction.Up;
console.log(move); // 0

// Custom values
enum Status {
  Pending = 1,
  Active = 2,
  Completed = 10,
  Cancelled = 20,
}

// Problem: Reverse mapping allows invalid values
const status: Status = 999; // No error!

// Computed values
enum FileAccess {
  None = 0,
  Read = 1 << 0,      // 1
  Write = 1 << 1,     // 2
  ReadWrite = Read | Write, // 3
}

// Bitwise operations
const access = FileAccess.Read | FileAccess.Write;
const canRead = (access & FileAccess.Read) !== 0;

String Enums#

// String enum - more explicit
enum Color {
  Red = 'RED',
  Green = 'GREEN',
  Blue = 'BLUE',
}

const color: Color = Color.Red;
console.log(color); // 'RED'

// No reverse mapping
// Color['RED'] is undefined

// Safer, but still has issues
enum OrderStatus {
  Pending = 'pending',
  Processing = 'processing',
  Shipped = 'shipped',
  Delivered = 'delivered',
}

// Problem: Can assign any string to enum value
function processOrder(status: OrderStatus) {
  // status is actually just a string at runtime
}

Const Enums#

// Const enum - inlined at compile time
const enum HttpStatus {
  OK = 200,
  NotFound = 404,
  ServerError = 500,
}

const status = HttpStatus.OK;
// Compiles to: const status = 200;

// No runtime object exists
// Can't iterate over values
// Can't use computed expressions

// Benefits:
// - Smaller bundle size
// - Better performance
// - No runtime overhead

// Limitations:
// - No reverse mapping
// - Can't be exported from ambient contexts
// - isolatedModules compatibility issues

String Literal Unions (Preferred)#

// Better alternative to string enums
type Direction = 'up' | 'down' | 'left' | 'right';

function move(direction: Direction) {
  switch (direction) {
    case 'up':
      return { y: -1 };
    case 'down':
      return { y: 1 };
    case 'left':
      return { x: -1 };
    case 'right':
      return { x: 1 };
  }
}

// Type-safe!
move('up');    // ✓
move('Up');    // ✗ Error
move('foo');   // ✗ Error

// Exhaustiveness checking works
function exhaustive(direction: Direction): never {
  // TypeScript errors if not all cases handled
}

// Extract values
const directions = ['up', 'down', 'left', 'right'] as const;
type Direction2 = typeof directions[number];

// Check if value is valid
function isDirection(value: string): value is Direction {
  return ['up', 'down', 'left', 'right'].includes(value);
}

Object as Enum#

// Object pattern - runtime values + type safety
const Color = {
  Red: 'red',
  Green: 'green',
  Blue: 'blue',
} as const;

type Color = typeof Color[keyof typeof Color];
// type Color = 'red' | 'green' | 'blue'

// Usage
function setColor(color: Color) {
  console.log(color);
}

setColor(Color.Red);  // ✓
setColor('red');      // ✓
setColor('purple');   // ✗ Error

// Get all values
const colorValues = Object.values(Color);
// ['red', 'green', 'blue']

// Get all keys
const colorKeys = Object.keys(Color) as (keyof typeof Color)[];
// ['Red', 'Green', 'Blue']

// More complex object enum
const HttpStatus = {
  OK: { code: 200, message: 'OK' },
  NotFound: { code: 404, message: 'Not Found' },
  ServerError: { code: 500, message: 'Internal Server Error' },
} as const;

type HttpStatusKey = keyof typeof HttpStatus;
type HttpStatusValue = typeof HttpStatus[HttpStatusKey];

function handleStatus(status: HttpStatusKey) {
  const { code, message } = HttpStatus[status];
  console.log(`${code}: ${message}`);
}

Discriminated Unions#

// For complex state
type LoadingState = { status: 'loading' };
type SuccessState<T> = { status: 'success'; data: T };
type ErrorState = { status: 'error'; error: Error };

type AsyncState<T> = LoadingState | SuccessState<T> | ErrorState;

function handleState<T>(state: AsyncState<T>) {
  switch (state.status) {
    case 'loading':
      return 'Loading...';
    case 'success':
      return state.data; // TypeScript knows data exists
    case 'error':
      return state.error.message;
  }
}

// More practical example
type PaymentMethod =
  | { type: 'card'; cardNumber: string; cvv: string }
  | { type: 'bank'; accountNumber: string; routingNumber: string }
  | { type: 'paypal'; email: string };

function processPayment(method: PaymentMethod) {
  switch (method.type) {
    case 'card':
      return chargeCard(method.cardNumber, method.cvv);
    case 'bank':
      return bankTransfer(method.accountNumber, method.routingNumber);
    case 'paypal':
      return paypalCheckout(method.email);
  }
}

Helper Utilities#

// Create enum-like object with type safety
function createEnum<T extends readonly string[]>(values: T) {
  const obj = {} as { [K in T[number]]: K };
  for (const value of values) {
    (obj as any)[value] = value;
  }
  return Object.freeze(obj);
}

const Status = createEnum(['pending', 'active', 'completed'] as const);
type Status = keyof typeof Status;
// type Status = 'pending' | 'active' | 'completed'

// Enum with descriptions
function createEnumWithLabels<T extends Record<string, string>>(obj: T) {
  return Object.freeze(obj);
}

const OrderStatus = createEnumWithLabels({
  pending: 'Order Pending',
  processing: 'Order Processing',
  shipped: 'Order Shipped',
  delivered: 'Order Delivered',
});

type OrderStatusKey = keyof typeof OrderStatus;
// 'pending' | 'processing' | 'shipped' | 'delivered'

// Get label
const label = OrderStatus.pending; // 'Order Pending'

When to Use What#

// Use string literal unions for simple cases
type Theme = 'light' | 'dark';

// Use const object for runtime access to values
const Theme = {
  Light: 'light',
  Dark: 'dark',
} as const;
type Theme = typeof Theme[keyof typeof Theme];

// Use discriminated unions for complex state
type RequestState<T> =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; error: Error };

// Use numeric enum for flags/bitwise operations
enum Permission {
  None = 0,
  Read = 1 << 0,
  Write = 1 << 1,
  Execute = 1 << 2,
}

// Avoid regular enums when possible
// They have confusing runtime behavior

Migration from Enums#

// Before: TypeScript enum
enum OldStatus {
  Pending = 'PENDING',
  Active = 'ACTIVE',
  Completed = 'COMPLETED',
}

// After: Const object
const Status = {
  Pending: 'PENDING',
  Active: 'ACTIVE',
  Completed: 'COMPLETED',
} as const;

type Status = typeof Status[keyof typeof Status];

// Migration is mostly search-and-replace
// OldStatus.Pending -> Status.Pending
// Works the same at runtime

// Type annotations update
// (status: OldStatus) -> (status: Status)

Best Practices#

Prefer:
✓ String literal unions for types
✓ Const objects for runtime values
✓ Discriminated unions for state
✓ const enum only when needed

Avoid:
✗ Regular numeric enums
✗ Heterogeneous enums
✗ Enums when simple types work
✗ Over-engineering simple cases

Consider:
✓ Bundle size impact
✓ Runtime iteration needs
✓ Type safety requirements
✓ Team familiarity

TypeScript enums have their place but often better alternatives exist. String literal unions provide type safety without runtime overhead. Const objects give both runtime values and type safety. Discriminated unions handle complex state elegantly. Reserve enums for bitwise operations or when you specifically need their behavior.