Course contentsShow
← TypeScript
Lesson 789 of 1,79618. Conditional TypesFree lesson

Common Pitfalls with Distribution

Identify mistakes like expecting distribution on non-naked parameters or misunderstanding tuple-wrapped behavior.

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.