Course contentsShow
← TypeScript
Lesson 1741 of 1,79639. TypeScript PerformanceFree lesson

Break Large Union Types into Smaller Chunks

Split massive unions into multiple smaller unions or use discriminated unions for faster narrowing.

Break Large Union Types into Smaller Chunks

What you'll learn: How splitting massive union types into focused, smaller unions dramatically improves TypeScript's compilation performance and type-checking speed.

The Problem with Giant Unions

TypeScript performs structural type checking on unions by testing each member individually. When you have a union with dozens or hundreds of members, the compiler must check compatibility with every single one. This creates a performance bottleneck that grows exponentially.

Imagine TypeScript as a librarian checking if a book belongs on a shelf. With 5 options, it's quick. With 200 options scattered everywhere, every lookup becomes a marathon.

The Performance Impact

Large flat unions cause:

  • Slow type narrowing — each typeof, in, or === check tests against all members
  • Exponential intersection checks — combining unions multiplies complexity
  • IDE lag — autocomplete and hover tooltips slow down dramatically
  • Build time increases — type instantiation happens repeatedly

Split by Category

Instead of one massive union, create semantically grouped smaller unions:

// ❌ Slow: One giant union
type AllEvents = 
  | UserLoginEvent 
  | UserLogoutEvent 
  | UserCreatedEvent
  | ProductAddedEvent
  | ProductRemovedEvent
  | ProductUpdatedEvent
  // ...50 more event types

// ✅ Faster: Grouped by domain
type UserEvent = UserLoginEvent | UserLogoutEvent | UserCreatedEvent;
type ProductEvent = ProductAddedEvent | ProductRemovedEvent | ProductUpdatedEvent;
type PaymentEvent = PaymentStartedEvent | PaymentCompletedEvent;

type AllEvents = UserEvent | ProductEvent | PaymentEvent;

The compiler now checks three categories first, then drills into the relevant subset.

Use Discriminated Unions for Faster Narrowing

Add a discriminant property that TypeScript can check instantly:

// Each group has its own discriminant
type UserEvent = 
  | { category: 'user'; type: 'login'; userId: string }
  | { category: 'user'; type: 'logout'; userId: string };

type ProductEvent = 
  | { category: 'product'; type: 'added'; productId: string }
  | { category: 'product'; type: 'removed'; productId: string };

type AllEvents = UserEvent | ProductEvent;

function handle(event: AllEvents) {
  switch (event.category) {
    case 'user':
      // TypeScript narrows to UserEvent instantly
      // Now only check 2 types, not 50+
      break;
  }
}

The two-level discriminant (category then type) creates a hierarchy that TypeScript navigates efficiently.

When This Matters

This optimization pays off when you have:

  • 15+ union members (compiler strain becomes noticeable)
  • Deeply nested or frequently intersected unions
  • Hot code paths where narrowing happens repeatedly
  • IDE performance issues with autocomplete

Key Takeaway: Split massive unions into semantically meaningful smaller unions or use discriminated unions with hierarchical narrowing — the compiler checks fewer types per operation, drastically improving performance and developer experience.