Codectionary / Developer documentation / TypeScript

Distributive Conditional Types

A conditional type with a naked type parameter on the left of extends distributes over union members.

What it is and why to use it

A conditional type with a naked type parameter on the left of extends distributes over union members. Wrapping both sides in tuples prevents that automatic distribution. This matters when a type should ask about each alternative separately or about the union as one whole.

Common mistakes and limitations

A concrete union on the left of a conditional does not always behave like a naked generic parameter. Be deliberate about distribution, especially with never. Complex conditional types can also make error messages harder for beginners to understand.

Run this example

Use TypeScript 5.8 or later with strict checking and an ES2022 target. Save each complete example independently as example.ts, compile it, then run the generated JavaScript with a compatible Node.js installation. Compiler-only options below affect checking; they do not add runtime validation.

Terminal — compile and run

npx tsc example.ts --strict --target ES2022 --module commonjs
node example.js

Syntax

type Each<T> = T extends string ? T[] : never;

Examples

Distributive Conditional Types

Standalone TypeScript 5.8+ example; expected output is explained below.

type Each<T> = T extends string ? T[] : never;
type Whole<T> = [T] extends [string] ? T[] : never;
const individual: Each<"read" | 42> = ["read"];
const together: Whole<"read" | "write"> = ["read", "write"];
console.log(individual.join(","));
console.log(together.join(","));
  1. Each evaluates read and 42 separately; the numeric branch becomes never and disappears from the union.
  2. Whole checks its entire union against string and creates one array type when all members qualify.
  3. These are compile-time calculations. The runtime output comes from the arrays that are explicitly constructed.
  4. Expected output: read read,write

Best practices

  • A concrete union on the left of a conditional does not always behave like a naked generic parameter. Be deliberate about distribution, especially with never. Complex conditional types can also make error messages harder for beginners to understand.
  • Keep external-input validation separate from compile-time type descriptions.

Runtime & versions

Compiled to JavaScript. Feature availability depends on the language and runtime version used by your project; consult the official reference below.

TypeScript Handbook

Specifications & further reading