Distributive Conditionals & Disabling Distribution

## The rule A conditional type has the shape `T extends U ? X : Y`. TypeScript gives it one extra behaviour that surprises almost everyone the first time: when the type being *checked* is a **naked type parameter** and the type argument supplied for it is a **union**, the conditional is not evaluated once against the whole union. It is evaluated once per union member, and the results are combined back into a union. That is called *distribution*, by analogy with distributing multiplication over addition: ```ts type ToArray<T> = T extends unknown ? T[] : never; type A = ToArray<string | number>; // evaluated as ToArray<string> | ToArray<number> // => string[] | number[] ``` The condition `T extends unknown` is deliberately trivially true here — the conditional exists only to trigger distribution, not to make a decision. `T extends any` is used interchangeably for the same purpose. ## What "naked" means Naked means the checked position contains the type parameter and nothing else. These distribute: ```ts type One<T> = T extends string ? 1 : 0; // naked T type Two<T> = T extends { id: string } ? 1 : 0; // naked T, structural condition ``` These do **not**, because `T` is wrapped in something before the check: ```ts type Three<T> = T[] extends string[] ? 1 : 0; // T[] is not naked type Four<T> = { x: T } extends { x: string } ? 1 : 0; type Five<T> = [T] extends [string] ? 1 : 0; // the standard opt-out ``` Only the checked (left) side matters. What appears after `extends`, and what the branches produce, has no effect on whether distribution happens. There is a second precondition that is easy to miss: distribution is a property of *instantiating a type parameter*. A union written literally in the checked position does not distribute, because no substitution takes place: ```ts type Direct = string | number extends string ? 1 : 0; // => 0, one single check ``` ## Why the compiler does this Distribution is what turns conditional types into a mapping operation over unions, which is where most of their practical value lives. Two idioms fall out of it directly. **Mapping.** Transform every member and keep the union shape — that is exactly the `ToArray` example, and the same pattern wraps each member in a `Promise`, a box type, or a nullable. **Filtering.** Return `T` in one branch and `never` in the other. Because `never` is the empty union, a member that resolves to `never` simply vanishes when the results are unioned: ```ts type OnlyStrings<T> = T extends string ? T : never; type B = OnlyStrings<string | 42 | boolean>; // => string ``` Notice `boolean` disappeared entirely. `boolean` is internally the union `true | false`, so it splits into two members, and neither is a string. This filtering idiom is the machinery underneath the built-in union-filtering utilities in `lib.es5.d.ts`. ## Turning it off The canonical opt-out is to wrap **both** sides in a one-element tuple: ```ts type IsExactlyString<T> = [T] extends [string] ? true : false; type C = IsExactlyString<string | number>; // => false ``` Now the checked type is `[T]`, a tuple containing the parameter rather than the bare parameter, so no substitution-per-member happens; the compiler asks a single assignability question about the whole union. Wrapping only one side does not work — the two sides must be comparable, so both get the tuple. ## Two edge inputs worth remembering `never` is the empty union. Distributing over zero members yields zero results, so a distributive conditional given `never` returns `never` without evaluating either branch. And instantiating a distributive conditional with `any` produces the union of *both* branches, because `any` is treated as matching and not matching simultaneously: ```ts type YesNo<T> = T extends string ? 'yes' : 'no'; type D = YesNo<any>; // => 'yes' | 'no' ``` ## It costs nothing at runtime All of this is compile-time arithmetic over types. TypeScript erases types on emit, so a distributive conditional produces no JavaScript at all — no checks, no branches, no allocation. The cost is compiler time and reader comprehension, never program speed. ## What an interviewer is listening for The strong answer names the precondition (naked type parameter plus a union argument), states the substitute-and-union mechanic, and shows the tuple opt-out. The weak answer treats distribution as something conditional types always do, and is then unable to explain why `[T] extends [U]` behaves differently or why a filter with `never` removes members instead of inserting `never` into the result.