Distributive Conditional Types

Distributive Conditional Types — the core idea

When a conditional type checks a naked type parameter, a union is distributed: the conditional applies to each union member independently. Wrapping both sides in single-element tuples disables that distribution.

What you’ll learn

Explain distributive conditional types with a concrete use case.
Run the example and account for every line of its output.
Recognize the difference between compile-time checking and runtime behavior.

Understand the rules and when to use them

Reading the code: KeepStrings tests string, number, and "ready" separately, removing number with never. The tuple-wrapped check asks whether the entire string | number union extends string: it does not.

Keep the boundary clear: Dropping the tuple brackets accidentally changes a whole-union test into separate branch tests.

See the idea as a flow

Follow the three stages and identify what happens in TypeScript versus JavaScript.

Run the complete TypeScript example

Save the code as distributive-conditional-types.ts. The result below was captured after compiling this exact example with strict TypeScript checking and executing the emitted JavaScript in Node.js.

TypeScript code

type KeepStrings<T> = T extends string ? T : never;
type A = KeepStrings<string | number | "ready">;
type AllStrings<T> = [T] extends [string] ? true : false;
type B = AllStrings<string | number>;
const message: A = "ready";
const answer: B = false;
console.log(message);
console.log(answer);

Verified output

ready
false

Build: npx tsc --strict --target es2022 --module commonjs --lib es2022,dom,esnext.disposable distributive-conditional-types.ts; run: node distributive-conditional-types.js. The exact filename may be changed freely. When a multi-file project exists, prefer its tsconfig.json and build scripts.

Trace the example line by line

KeepStrings tests string, number, and "ready" separately, removing number with never. The tuple-wrapped check asks whether the entire string | number union extends string: it does not.

The output shown above comes from the initialized values in this program. Replacing a type annotation alone does not transform a JavaScript value.

Avoid this common mistake

Dropping the tuple brackets accidentally changes a whole-union test into separate branch tests.

Check both the TypeScript diagnostic and the emitted JavaScript behavior. A program can compile correctly and still need runtime validation or error handling.

Practice independently

Implement ToArray<T> = T extends unknown ? T[] : never and compare it with [T] extends [unknown] ? T[] : never.

Before running your change, write down the type you expect TypeScript to infer and the output you expect JavaScript to print. Then check both predictions.

What to remember

When a conditional type checks a naked type parameter, a union is distributed: the conditional applies to each union member independently.

Try the practice change and re-run the exact program to test your understanding.

Reaching the recap and completing the quizzes are separate milestones.

Next lesson: The infer Keyword →