The Readability Problem with Giant Union Types
What you'll learn: How union types with 10+ members become increasingly difficult to maintain, understand, and reason about in real-world codebases.
The Scaling Problem
When you first learn about union types in TypeScript, they seem elegant and powerful. A type like string | number is clean and expressive. But what happens when that union grows to encompass 10, 15, or even 20+ members?
type Status =
| 'pending'
| 'processing'
| 'validating'
| 'validated'
| 'approved'
| 'rejected'
| 'cancelled'
| 'on-hold'
| 'escalated'
| 'reviewed'
| 'archived'
| 'deleted'
| 'suspended'
| 'inactive'
| 'expired';
At a glance, can you tell which statuses represent error states? Which ones are terminal? Which transitions are valid? The answer isn't obvious anymore.
Why This Hurts
Cognitive overload: Your brain has to process every single member when reading code that uses this type. There's no grouping, hierarchy, or semantic organization—just a flat list.
Lost relationships: Giant unions hide the relationships between values. Some statuses might be related (like stages in a workflow), but that structure is completely invisible in the type.
Difficult narrowing: When you need to narrow a giant union, your switch statements or if-else chains become massive. Spotting missing cases or redundant checks becomes genuinely difficult.
Poor documentation: The type itself provides little insight into what these values mean or when they're used. You're forced to hunt through implementation code to understand the domain logic.
The Maintenance Tax
When you need to add a new union member months later, you face questions: Does this overlap with existing members? Which functions need updating? The flat structure provides no guidance, making changes risky and time-consuming.
Key Takeaway: Union types with 10+ members sacrifice readability and maintainability. The lack of structure, semantic grouping, and clear relationships makes them hard to understand at a glance and error-prone to modify. This is a signal that your type structure might need a rethink.