Control the Distribution of Unions over Conditional Types

Overview

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.

When to Use This Skill

• 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

The Iron Rule

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.