Enums

The Bundle Size Explosion

It was performance review time. Our web app was loading slowly on mobile. I opened the Chrome DevTools Network tab and saw our main JavaScript bundle: 487KB. For a relatively simple app.

I ran webpack-bundle-analyzer and found the culprit:

// constants.ts - Our old enum-heavy code
enum UserRole {
  Admin = 'ADMIN',
  Moderator = 'MODERATOR',
  User = 'USER',
  Guest = 'GUEST'
}

enum ProductCategory {
  Electronics = 'ELECTRONICS',
  Clothing = 'CLOTHING',
  Books = 'BOOKS',
  Home = 'HOME',
  Sports = 'SPORTS'
  // ... 47 more categories
}

enum EventType {
  Click = 'CLICK',
  Hover = 'HOVER',
  Scroll = 'SCROLL',
  // ... 23 more event types
}

// ... 15 more large enums

TypeScript compiled these to:

// Compiled output
var UserRole;
(function (UserRole) {
    UserRole["Admin"] = "ADMIN";
    UserRole["Moderator"] = "MODERATOR";
    UserRole["User"] = "USER";
    UserRole["Guest"] = "GUEST";
})(UserRole || (UserRole = {}));

// Multiplied by 18 enums = bloat!

Each enum generated an IIFE (Immediately Invoked Function Expression). With 18 enums averaging 20 values each, we had 40KB of enum boilerplate in the bundle.

I refactored to const enums and union types:

// New approach
const enum UserRole {
  Admin = 'ADMIN',
  Moderator = 'MODERATOR',
  User = 'USER',
  Guest = 'GUEST'
}

// For some cases, just use union types
type ProductCategory = 'ELECTRONICS' | 'CLOTHING' | 'BOOKS' | 'HOME' | 'SPORTS';

Result: Bundle size dropped to 447KB (40KB saved). Page load improved by 0.8 seconds on 3G.

This article covers when to use enums, when to avoid them, and the patterns that keep your bundle lean.

---

Numeric Enums

Default enum type with auto-incrementing numbers.

Basic Numeric Enum

enum Direction {
  North,
  South,
  East,
  West
}

console.log(Direction.North);  // 0
console.log(Direction.South);  // 1
console.log(Direction.East);   // 2
console.log(Direction.West);   // 3

function move(direction: Direction): void {
  console.log(`Moving ${Direction[direction]}`);
}

move(Direction.North);  // "Moving North"

Custom Starting Value

enum StatusCode {
  OK = 200,
  Created = 201,
  BadRequest = 400,
  Unauthorized = 401,
  NotFound = 404,
  ServerError = 500
}

function handleResponse(code: StatusCode): void {
  if (code === StatusCode.OK) {
    console.log('Success!');
  } else if (code >= 400) {
    console.error('Error occurred');
  }
}

Mixed Auto-Increment

enum Priority {
  Low = 1,
  Medium,     // 2
  High,       // 3
  Critical = 10,
  Urgent      // 11
}

---

String Enums

Enums with string values.

Basic String Enum

enum UserRole {
  Admin = 'ADMIN',
  Moderator = 'MODERATOR',
  User = 'USER',
  Guest = 'GUEST'
}

function checkPermission(role: UserRole): boolean {
  return role === UserRole.Admin || role === UserRole.Moderator;
}

console.log(checkPermission(UserRole.Admin));  // true

Why String Enums?

enum LogLevel {
  Debug = 'DEBUG',
  Info = 'INFO',
  Warn = 'WARN',
  Error = 'ERROR'
}

function log(level: LogLevel, message: string): void {
  console.log(`[${level}] ${message}`);
  // Output: [INFO] Server started
  // Not: [1] Server started  (what numeric enums would give)
}

log(LogLevel.Info, 'Server started');

---

Const Enums

Compile-time-only enums that don't generate runtime code.

Regular Enum (Runtime Code)

enum Direction {
  North = 'NORTH',
  South = 'SOUTH'
}

// Compiles to:
var Direction;
(function (Direction) {
    Direction["North"] = "NORTH";
    Direction["South"] = "SOUTH";
})(Direction || (Direction = {}));

const dir = Direction.North;  // Compiles to: const dir = Direction.North;

Const Enum (No Runtime Code)

const enum Direction {
  North = 'NORTH',
  South = 'SOUTH'
}

const dir = Direction.North;
// Compiles to: const dir = "NORTH";  // Inlined!
// No Direction object in output

Real-World Example

const enum HttpMethod {
  GET = 'GET',
  POST = 'POST',
  PUT = 'PUT',
  DELETE = 'DELETE',
  PATCH = 'PATCH'
}

function request(method: HttpMethod, url: string): Promise<Response> {
  return fetch(url, { method });
}

// Usage
request(HttpMethod.GET, '/api/users');
// Compiles to: request("GET", "/api/users");  // String is inlined

Bundle size benefit: If you use an enum 100 times, regular enum = IIFE + 100 references. Const enum = 100 inlined strings.

---

Enum Member Types

Each enum member is its own type.

Literal Type Narrowing

enum TrafficLight {
  Red = 'RED',
  Yellow = 'YELLOW',
  Green = 'GREEN'
}

function handleLight(light: TrafficLight): void {
  if (light === TrafficLight.Red) {
    // TypeScript knows light is exactly TrafficLight.Red
    console.log('Stop');
  } else if (light === TrafficLight.Yellow) {
    console.log('Slow down');
  } else {
    // Must be Green
    console.log('Go');
  }
}

---

Computed and Constant Members

Constant Members

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

function hasAccess(access: FileAccess, required: FileAccess): boolean {
  return (access & required) === required;
}

console.log(hasAccess(FileAccess.ReadWrite, FileAccess.Read));  // true
console.log(hasAccess(FileAccess.Read, FileAccess.Write));      // false

---

Reverse Mappings

Numeric enums have automatic reverse mappings.

Numeric Enum Reverse Mapping

enum Status {
  Active = 1,
  Inactive = 2,
  Pending = 3
}

console.log(Status.Active);    // 1
console.log(Status[1]);        // "Active"  // Reverse mapping!

// Useful for debugging
function getStatusName(code: number): string | undefined {
  return Status[code];
}

console.log(getStatusName(1));  // "Active"

String Enums Don't Have Reverse Mappings

enum Color {
  Red = 'RED',
  Green = 'GREEN',
  Blue = 'BLUE'
}

console.log(Color.Red);        // "RED"
console.log(Color['RED']);     // undefined  // No reverse mapping

---

Enums at Runtime

Understanding how enums compile helps you choose the right approach.

Regular Enum Compiled Output

enum UserRole {
  Admin = 'ADMIN',
  User = 'USER'
}

// Compiles to:
var UserRole;
(function (UserRole) {
    UserRole["Admin"] = "ADMIN";
    UserRole["User"] = "USER";
})(UserRole || (UserRole = {}));

// You can iterate at runtime
Object.keys(UserRole).forEach(key => {
  console.log(key, UserRole[key as keyof typeof UserRole]);
});

Const Enum Compiled Output

const enum UserRole {
  Admin = 'ADMIN',
  User = 'USER'
}

const role = UserRole.Admin;

// Compiles to:
const role = "ADMIN";  // Completely inlined

// Cannot iterate - no runtime object exists
// Object.keys(UserRole)  // ✗ Error: 'UserRole' only refers to a type

---

When to Use Enums

Good Use Cases

1. Fixed Set of Related Constants

const enum HttpStatus {
  OK = 200,
  Created = 201,
  BadRequest = 400,
  Unauthorized = 401,
  NotFound = 404
}

2. State Machines

enum ConnectionState {
  Disconnected,
  Connecting,
  Connected,
  Reconnecting,
  Failed
}

class WebSocketClient {
  private state: ConnectionState = ConnectionState.Disconnected;
  
  connect(): void {
    if (this.state === ConnectionState.Disconnected) {
      this.state = ConnectionState.Connecting;
      // ...
    }
  }
}

3. Bit Flags

enum Permission {
  None = 0,
  Read = 1 << 0,
  Write = 1 << 1,
  Delete = 1 << 2,
  Admin = Read | Write | Delete
}

function hasPermission(userPerms: Permission, required: Permission): boolean {
  return (userPerms & required) === required;
}

---

When NOT to Use Enums

Use Union Types Instead

Bad - Enum Overkill:

enum ButtonSize {
  Small = 'small',
  Medium = 'medium',
  Large = 'large'
}

// Generates runtime code

Good - Union Type:

type ButtonSize = 'small' | 'medium' | 'large';

// No runtime code, just as type-safe

Use Constants for Single Values

Bad - Enum for API Constants:

enum API {
  BaseURL = 'https://api.example.com',
  Timeout = 5000
}

// Different types mixed in one enum

Good - Separate Constants:

const API_BASE_URL = 'https://api.example.com';
const API_TIMEOUT = 5000;

// Or object with as const
const API = {
  baseUrl: 'https://api.example.com',
  timeout: 5000
} as const;

---

Enum Alternatives

Union Types

// Instead of:
enum Status {
  Pending = 'pending',
  Approved = 'approved',
  Rejected = 'rejected'
}

// Use:
type Status = 'pending' | 'approved' | 'rejected';

// Benefits:
// - No runtime code
// - Simpler
// - Same type safety

as const Objects

const UserRole = {
  Admin: 'ADMIN',
  User: 'USER',
  Guest: 'GUEST'
} as const;

type UserRole = typeof UserRole[keyof typeof UserRole];
// Type: 'ADMIN' | 'USER' | 'GUEST'

// Benefits:
// - Can iterate at runtime
// - No IIFE overhead
// - Type-safe

Branded Types

type UserId = string & { __brand: 'UserId' };
type ProductId = string & { __brand: 'ProductId' };

function getUser(id: UserId): User {
  // Implementation
}

function getProduct(id: ProductId): Product {
  // Implementation
}

const userId = 'user-123' as UserId;
const productId = 'prod-456' as ProductId;

getUser(userId);      // ✓
// getUser(productId);   // ✗ Error: ProductId not assignable to UserId

---

Real-World Patterns

1. HTTP Status Codes

const enum HttpStatus {
  // Success
  OK = 200,
  Created = 201,
  Accepted = 202,
  NoContent = 204,
  
  // Redirection
  MovedPermanently = 301,
  Found = 302,
  NotModified = 304,
  
  // Client Errors
  BadRequest = 400,
  Unauthorized = 401,
  Forbidden = 403,
  NotFound = 404,
  
  // Server Errors
  InternalServerError = 500,
  BadGateway = 502,
  ServiceUnavailable = 503
}

function handleResponse(status: HttpStatus): void {
  if (status >= 200 && status < 300) {
    console.log('Success');
  } else if (status >= 400 && status < 500) {
    console.error('Client error');
  } else if (status >= 500) {
    console.error('Server error');
  }
}

2. Feature Flags

const enum Feature {
  NewDashboard = 'NEW_DASHBOARD',
  BetaAPI = 'BETA_API',
  DarkMode = 'DARK_MODE',
  Analytics = 'ANALYTICS'
}

class FeatureFlags {
  private flags: Map<string, boolean> = new Map();
  
  enable(feature: Feature): void {
    this.flags.set(feature, true);
  }
  
  isEnabled(feature: Feature): boolean {
    return this.flags.get(feature) ?? false;
  }
}

const features = new FeatureFlags();
features.enable(Feature.NewDashboard);

if (features.isEnabled(Feature.NewDashboard)) {
  renderNewDashboard();
}

3. Event Types

const enum EventType {
  UserLogin = 'USER_LOGIN',
  UserLogout = 'USER_LOGOUT',
  PageView = 'PAGE_VIEW',
  ButtonClick = 'BUTTON_CLICK',
  FormSubmit = 'FORM_SUBMIT'
}

interface Event<T = unknown> {
  type: EventType;
  timestamp: Date;
  data: T;
}

function trackEvent<T>(type: EventType, data: T): void {
  const event: Event<T> = {
    type,
    timestamp: new Date(),
    data
  };
  
  console.log('Track:', event);
  // Send to analytics
}

trackEvent(EventType.UserLogin, { userId: '123' });
trackEvent(EventType.ButtonClick, { buttonId: 'submit-btn', page: '/checkout' });

---

Common Mistakes I Made

1. Using Enums for Configuration

Bad:

enum Config {
  APIUrl = 'https://api.example.com',
  Timeout = 5000  // ✗ Different types in one enum
}

Good:

const CONFIG = {
  apiUrl: 'https://api.example.com',
  timeout: 5000
} as const;

2. Not Using Const Enums

Bad (Bloats Bundle):

enum Direction {
  North = 'NORTH',
  South = 'SOUTH',
  East = 'EAST',
  West = 'WEST'
}

// Used 50 times = IIFE + 50 references

Good (Inlined):

const enum Direction {
  North = 'NORTH',
  South = 'SOUTH',
  East = 'EAST',
  West = 'WEST'
}

// Used 50 times = 50 inlined strings (smaller)

3. Using Enums When Union Types Suffice

Bad:

enum Size {
  Small = 'S',
  Medium = 'M',
  Large = 'L'
}

Good:

type Size = 'S' | 'M' | 'L';

---

Your Challenge

Build a type-safe state machine for an order system:

// TODO: Define enums/types for order states

// Options:
// 1. Use enum for states
// 2. Use union types
// 3. Use const enum

// States: pending, paid, processing, shipped, delivered, cancelled

// TODO: Implement OrderStateMachine class

class OrderStateMachine {
  // Track current state
  // Implement valid state transitions
  // Only allow valid transitions
  
  // Example transitions:
  // pending -> paid
  // paid -> processing
  // processing -> shipped
  // shipped -> delivered
  // Any state -> cancelled (except delivered)
  
  canTransitionTo(newState: /* state type */): boolean {
    // Check if transition is valid
  }
  
  transitionTo(newState: /* state type */): void {
    // Transition if valid, throw if not
  }
}

// Requirements:
// 1. Type-safe state definitions
// 2. Prevent invalid state transitions
// 3. Minimize bundle size
// 4. Clear and maintainable
// 5. Good error messages

---

Key Takeaways

1. Numeric enums - auto-incrementing numbers, have reverse mappings

2. String enums - explicit string values, better debugging

3. Const enums - compile-time only, no runtime code, smaller bundle

4. Regular enums - generate runtime code (IIFEs)

5. Union types - often better than enums for simple cases

6. as const objects - alternative with runtime iteration

7. Use const enum when you don't need runtime reflection

8. Use union types for simple string literals

---

What I Learned

The bundle size incident taught me: not every constant needs an enum.

Before optimization:

enum UserRole {
  Admin = 'ADMIN',
  User = 'USER'
}
enum ProductCategory { /* 50 values */ }
enum EventType { /* 30 values */ }
// ... 15 more enums

// Result: 40KB of IIFE boilerplate

After refactoring:

const enum UserRole {  // Used often, needs type safety
  Admin = 'ADMIN',
  User = 'USER'
}

type ProductCategory = 'electronics' | 'clothing' | /* ... */;  // Simple union

const EventType = {  // Need runtime iteration
  Click: 'CLICK',
  Hover: 'HOVER'
} as const;

// Result: 40KB saved

The decision tree I use now:

1. Need runtime iteration? → as const object

2. Simple string literals? → Union type

3. Bit flags or numeric values? → Enum (maybe const)

4. Complex state machine? → Const enum

5. Small, frequently used set? → Const enum

Enums aren't bad – they're just often overkill. TypeScript gives us multiple ways to express constants. Use the lightest tool that solves the problem.

A 40KB bundle reduction is 0.8 seconds faster on 3G. Choose wisely.

---

Next: Modules and Declaration Files

In the next article, we'll explore TypeScript's module system and declaration files. You'll learn how I debugged a 6-hour "module not found" nightmare and the patterns that prevent it.