Union Distribution Performance Impact
What you'll learn: How TypeScript's distributive conditional types multiply compilation work when unions grow large, and why this can slow down your build.
The Distributive Multiplication Problem
When you write a conditional type like T extends SomeType ? X : Y, TypeScript distributes this check across every member of a union type individually. This isn't just one check — it's N checks where N is the number of union members.
Think of it like copying a document: copying one page takes 1 second, but copying a 100-page document takes 100 seconds. Distribution turns one type operation into many separate operations.
How Distribution Multiplies Work
When you have a union of 10 types passing through a distributive conditional, TypeScript performs 10 separate type checks. If those results feed into another distributive conditional, you now have 10 × N more checks. The work multiplies at each distributive layer.
// Each member distributes separately
type Example<T> = T extends string ? "text" : "other";
// With 3 members: 3 separate checks
type Result = Example<string | number | boolean>;
// Becomes: "text" | "other" | "other"
With 50 union members, that's 50 checks. With nested conditionals, it becomes 50 × 50 = 2,500 checks. This quadratic or exponential growth kills compilation speed.
The Large Union Trap
The real danger appears when combining distribution with large unions extracted from real-world data — perhaps 30+ string literals representing API routes, or dozens of action types in a state machine.
Each additional union member adds another full pass through your conditional type logic. A type that compiled instantly with 10 members might take seconds with 100 members.
Key Takeaway: Distributive conditional types multiply compilation work by the number of union members, causing exponential slowdowns when unions are large or conditionals are nested. Avoid distributing over unions with dozens of members, or wrap unions in tuples to prevent distribution.