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.