Common Pitfalls with Distribution
You'll learn the most frequent mistakes developers make when working with distributive conditional types—and how to spot them before they bite you.
The Naked vs Non-Naked Problem
The most common pitfall: expecting distribution when the type parameter isn't "naked". Remember, distribution only happens when the checked type is a bare type parameter with no wrapping.
// ✅ DISTRIBUTIVE - T is naked
type Distribute<T> = T extends string ? T[] : never;
type Result1 = Distribute<'a' | 'b'>; // 'a'[] | 'b'[]
// ❌ NOT DISTRIBUTIVE - T is wrapped in an array
type NoDistribute<T> = T[] extends string[] ? T : never;
type Result2 = NoDistribute<'a' | 'b'>; // 'a' | 'b' (entire union checked at once)
In the second example, T[] means the type parameter isn't naked anymore—it's already wrapped. TypeScript evaluates ('a' | 'b')[] as one thing, not distributing over members.
The Tuple-Wrapped Trap
When you deliberately disable distribution using [T], it's easy to forget you're now working with a tuple, not the original type:
type NonDist<T> = [T] extends [string] ? true : false;
type Check = NonDist<'hello' | 42>; // false (entire union isn't string)
// The trap: forgetting you need to unwrap later
type Unwrap<T> = [T] extends [infer U] ? U : never;
If you disable distribution, remember you've changed the structure of what you're checking. The entire union gets tuple-wrapped, not individual members.
Forgetting never Behavior
When distribution produces never for some union members, those disappear from the final result. This can surprise you:
type FilterStrings<T> = T extends string ? T : never;
type Filtered = FilterStrings<'a' | 42 | 'b' | null>; // 'a' | 'b'
// The 42 and null quietly vanish!
This is correct behavior, but forgetting it leads to "where did my types go?" confusion.
Key Takeaway: Distribution only works with naked type parameters—any wrapping (T[], [T], Promise<T>) disables it. When you deliberately prevent distribution with tuple wrapping, remember you're checking the whole union structure, not individual members.