Distributive Behavior with Union Types
What you'll learn: How conditional types automatically distribute over union members, applying the condition to each member separately instead of the whole union at once.
When you pass a union type to a conditional type like T extends U ? X : Y, TypeScript does something special: it distributes the conditional over each member of the union individually.
Think of it like a mail sorting machine. Instead of checking if the entire bag of mail meets a condition, it opens the bag, checks each letter individually, and sorts them one by one. Then it combines the results.
How It Works
type ToArray<T> = T extends any ? T[] : never;
// When T is a union:
type Result = ToArray<string | number>;
// TypeScript distributes this as:
// (string extends any ? string[] : never) | (number extends any ? number[] : never)
// Result: string[] | number[]
Without distribution, you might expect (string | number)[], but distribution gives you string[] | number[] — a union of separate arrays.
Filtering Union Members
type ExtractStrings<T> = T extends string ? T : never;
type OnlyStrings = ExtractStrings<string | number | boolean>;
// Distributes to:
// (string extends string ? string : never) |
// (number extends string ? never : never) |
// (boolean extends string ? never : never)
// Result: string
The never results disappear from the union, effectively filtering it.
Real-World Pattern
type Nullable<T> = T extends any ? T | null : never;
type MaybeNull = Nullable<string | number>;
// Result: string | null | number | null
// Which simplifies to: string | number | null
Each union member gets | null added to it separately.
Key Takeaway: When a union type is passed as a type parameter to a conditional type, TypeScript distributes the condition across each member individually, evaluating them separately and combining the results into a new union.