control-union-distribution

Conditional types in TypeScript distribute over unions by default. This is usually what you want, but sometimes it causes surprising behavior. Understanding how to control distribution - both preventing it when unwanted and enabling it when needed - is essential for advanced type-level programming.

Key surprises include: boolean being treated as true | false, never distributing to never, and recursive types that fail to distribute. This skill shows you how to handle these cases.

• Conditional type behaves unexpectedly with union inputs
• boolean type produces surprising results
• never type evaluates unexpectedly
• Need to prevent distribution over unions
• Recursive generic types not distributing correctly

Wrap conditions in one-tuples [T] to prevent distribution; add bare conditions N extends... to force distribution. Understand how boolean and never behave with distributive conditionals.

Watch for these surprising behaviors:

```typescript

// Surprising: boolean distributes

type Celebrate = V extends true ? 'Huzzah!' : never;

type Surprise = Celebrate; // "Huzzah!" not never

// Surprising: never distributes to never

type AllowIn = T extends { password: string } ? 'Yes' : 'No';

type N = AllowIn; // never, not 'Yes' | 'No'

// Problem: recursive type doesn't distribute

type NTuple = / ... /; // NTuple gives wrong result

```

Wrap the condition in a one-tuple [T]:

```typescript

// Problem: distributes over unions

type Comparable =

T extends Date ? Date | number :

T extends number ? number :

T extends string ? string :

never;

// Date | string becomes (Date | number) | string - wrong!

let dateOrStr: Date | string;

const result: Comparable; // Should be never

// Solution: wrap in one-tuple

type Comparable =

[T] extends [Date] ? Date | number :

[T] extends [number] ? number :

[T] extends [string] ? string :

never;

// Now Date | string correctly evaluates to never

```

TypeScript treats boolean as true | false:

```typescript

type CelebrateIfTrue = V extends true ? 'Huzzah!' : never;

// Surprising result

type Party = CelebrateIfTrue; // "Huzzah!"

type NoParty = CelebrateIfTrue; // never

type Surprise = CelebrateIfTrue; // "Huzzah!" (!)

// Why? boolean distributes:

// CelebrateIfTrue

// = CelebrateIfTrue | CelebrateIfTrue

// = "Huzzah!" | never

// = "Huzzah!"

// Fix: prevent distribution

type CelebrateIfTrue = [V] extends [true] ? 'Huzzah!' : never;

type SurpriseFixed = CelebrateIfTrue; // never - correct!

```

never is treated as an empty union:

```typescript

type AllowIn = T extends { password: string } ? 'Yes' : 'No';

// Surprising: never evaluates to never

type N = AllowIn; // never (not 'Yes' or 'No')

// Why? never is empty union:

// AllowIn = AllowIn<> = empty union = never

// Fix: wrap in one-tuple

type AllowIn = [T] extends [{ password: string }] ? 'Yes' : 'No';

type NFixed = AllowIn; // 'No' - correct!

```

Sometimes you need to force distribution. Add a bare condition:

```typescript

// Problem: recursive type doesn't distribute

type NTuple = NTupleHelp;

type NTupleHelp =

Acc['length'] extends N

? Acc

: NTupleHelp;

type PairOrTriple = NTuple;

// Got: [string, string] (wrong!)

// Want: [string, string] | [string, string, string]

// Solution: add distributive wrapper

type NTuple =

N extends number // Forces distribution

? NTupleHelp

: never;

type PairOrTripleFixed = NTuple;

// Now: [string, string] | [string, string, string] - correct!

```

```typescript

// Type-safe comparison function

type Comparable =

[T] extends [Date] ? Date | number : // Prevent distribution

[T] extends [number] ? number :

[T] extends [string] ? string :

never;

declare function isLessThan(a: T, b: Comparable): boolean;

// Valid comparisons

isLessThan(new Date(), new Date()); // OK

isLessThan(new Date(), Date.now()); // OK (Date/number)

isLessThan(12, 23); // OK

isLessThan('A', 'B'); // OK

// Invalid comparison - correctly rejected

isLessThan(12, 'B'); // Error: string not assignable to number

// Union case - correctly rejected

let dateOrStr: Date | string;

isLessThan(dateOrStr, 'B'); // Error: string not assignable to never

```

When conditional types behave unexpectedly:

1. Check for distribution: Is the type distributing over unions when it shouldn't?
2. Test with boolean/never: These often reveal distribution issues
3. Wrap in one-tuple: [T] extends [X] prevents distribution
4. Add bare condition: N extends any forces distribution
5. Verify with unions: Test your type with union inputs

| Symptom | Cause | Fix |

|---------|-------|-----|

| boolean gives unexpected result | Distribution | Wrap in [T] |

| never gives never | Empty union | Wrap in [T] |

| Union doesn't split correctly | No distribution | Add bare N extends |

| Intersection wanted, union got | Distribution | Wrap in [T] |

"I'll just use `any` for complex cases"

Reality: Understanding distribution gives you precise control. any sacrifices all type safety.

"This is too complex for my use case"

Reality: The one-tuple trick is simple: [T] extends [X] vs T extends X. Learn it once, use it forever.

"The type system shouldn't work this way"

Reality: Distribution is a powerful feature. Understanding it lets you harness that power rather than fight it.

| Goal | Syntax | Example |

|------|--------|---------|

| Allow distribution | T extends X | Default behavior |

| Prevent distribution | [T] extends [X] | For unions, boolean, never |

| Force distribution | N extends any ? ... : never | For recursive types |

Distribution over unions is usually what you want, but not always. Use [T] extends [X] to prevent it and bare conditions to force it. Understand how boolean and never behave to avoid surprises.

• Effective TypeScript, 2nd Edition by Dan Vanderkam
• Item 53: Know How to Control the Distribution of Unions over Conditional Types