Type Checking Large Union Types
You'll learn why unions with hundreds of members cause performance problems and how TypeScript's type checker struggles with them.
The Performance Wall
When TypeScript checks if a type is assignable to a union, it must check compatibility against every single member of that union. For small unions like string | number | boolean, this is instant. But when you have 100, 200, or 500 members, the checking time explodes.
Think of it like checking if someone is on a guest list. With 5 names, you scan the list quickly. With 500 names, you're still checking every single entry, and it takes dramatically longer.
Why Large Unions Scale Poorly
TypeScript uses a structural type system. To verify assignability, it compares the structure of your type against each union member:
- 100-member union: 100 structural comparisons
- 200-member union: 200 structural comparisons
- Nested objects in the union: Each comparison gets even more expensive
The work grows linearly with union size, but because type checking happens constantly (on every keystroke in your editor), even linear growth feels exponential in real-world use.
The Nested Property Problem
Large unions of object types are especially costly. If each union member has nested properties, TypeScript must recursively compare structures at every level, multiplying the computational cost.
Common Culprits
Large unions often appear in:
- Auto-generated types from APIs with hundreds of endpoints
- Event type systems with many event shapes
- Component prop unions in large UI libraries
- Error code enums represented as string literal unions
Key Takeaway: Type checking assignability against unions scales linearly with the number of members, making unions with hundreds of elements a significant performance bottleneck in both compilation and IDE responsiveness.