Conditional types, infer, and distributivity

Conditional types, infer, and distributive behavior over unions, including how any and never are treated.

テーマページの本文は現在英語です。

A conditional type has the form T extends U ? X : Y. When T is a naked type parameter, the conditional is distributive: it is applied to each member of a union. Conditional types and infer arrived in TypeScript 2.8. Exclude, Extract, Parameters, and ReturnType are built from these features; those aliases stay on their own pages.

The checked behaviors below were measured with TypeScript 5.9.3. Distributing over never produces never, because it is an empty union. A conditional that is not a naked type parameter, such as never extends string, takes the true branch because never extends every type. any extends U ? X : Y is the union of both branches. Wrapping the checked type in a tuple turns off distribution.

Examples were checked with TypeScript 5.9.3 using tsc --strict. See the TypeScript handbook for the complete utility-type catalog.

TypeScript reference overview →

API index

APISummary
Conditional typesA naked type parameter distributes over unions. any takes both branches. never distributes to never, but a wrapped never follows the ordinary extends rule.
inferBind a type from a successful extends match. infer is only legal in the extends clause of a conditional type.

Distributivity, any, and never

IsString<"a" | 1> is "yes" | "no", because the type parameter is a naked extends check and the union is split. A value of that type can be "yes" or "no", not "maybe". IsString<never> is never, so "yes" is not assignable. By contrast, any extends string ? "yes" : "no" is "yes" | "no" without going through a type parameter.

Wrapped uses a tuple so the check is not distributive: "a" | 1 is tested as a whole and produces "no". Wrapped<never> is "yes", because [never] extends [string] is true. That is the opposite of the naked IsString<never> result, and a common source of surprises.

Conditional types

type IsString<T> = T extends string ? "yes" : "no";
type Wrapped<T> = [T] extends [string] ? "yes" : "no";

A naked type parameter distributes over unions. any takes both branches. never distributes to never, but a wrapped never follows the ordinary extends rule.

Type parameterDescription
TThe type being tested. If it is a bare type parameter, a union argument is split into members before the check.
UThe type in the extends clause. The true and false branches are chosen per member when the check is distributive.

Produces: The chosen branch, a union of branches for a distributed union or for any, or never when a distributive check is applied to never.

Type errors

  • type error — Assigning a value that is not in the resulting type is a type error, such as "maybe" for a "yes" | "no" result, or "yes" for a never result, or "no" for Wrapped of never.
  • Conditional types were added in TypeScript 2.8. These results were measured with TypeScript 5.9.3.
  • Exclude and Extract are distributive conditionals in the standard typings. See that page for those aliases; this page does not repeat those examples.
typescript
type IsString<T> = T extends string ? "yes" : "no";
const yes: IsString<"a"> = "yes";
const no: IsString<1> = "no";
const split: IsString<"a" | 1> = "yes";
const also: IsString<"a" | 1> = "no";
// @ts-expect-error the distributed result is "yes" | "no", not a single "maybe"
const notOnlyYes: IsString<"a" | 1> = "maybe";

type DistNever = IsString<never>;
// @ts-expect-error distributing over never produces never
const fromNever: DistNever = "yes";

type AnyBranch = any extends string ? "yes" : "no";
const anyYes: AnyBranch = "yes";
const anyNo: AnyBranch = "no";

type Wrapped<T> = [T] extends [string] ? "yes" : "no";
const wrappedUnion: Wrapped<"a" | 1> = "no";
const wrappedNever: Wrapped<never> = "yes";
// @ts-expect-error wrapping disables distribution, and never extends string
const wrappedNeverNo: Wrapped<never> = "no";

console.log(yes, split, wrappedUnion, wrappedNever);

Expected output

yes yes no yes

Related: Exclude, Extract, and NonNullable

Official documentation →

infer

infer declares a type variable in the extends clause of a conditional type and nowhere else. Flatten inspects Array of some element type and yields that element; a non-array input is left unchanged. Head reads the first element of a tuple. infer is also how Parameters and ReturnType are defined; those utilities remain on the Parameters page.

infer

type Flatten<T> = T extends Array<infer Item> ? Item : T;
type Head<T> = T extends [infer First, ...unknown[]] ? First : never;

Bind a type from a successful extends match. infer is only legal in the extends clause of a conditional type.

Type parameterDescription
Item / FirstNames introduced by infer, available in the true branch of the conditional. They are not usable outside that conditional type.

Produces: The inferred type when the match succeeds, or the false-branch type when it does not.

Type errors

  • type error — Writing infer outside an extends clause is a type error. Assigning a value that is not the inferred type, such as an array to Flatten of string[], or 2 to the head of [1, 2, 3], is also a type error.
  • The signatures of Parameters and ReturnType use infer in the same way. See that page for overloaded functions and constructor types.
typescript
type Flatten<T> = T extends Array<infer Item> ? Item : T;
const item: Flatten<string[]> = "ok";
const kept: Flatten<number> = 1;
// @ts-expect-error Flatten<string[]> is string
const notArray: Flatten<string[]> = ["no"];

type Head<T> = T extends [infer First, ...unknown[]] ? First : never;
const first: Head<[1, 2, 3]> = 1;
// @ts-expect-error the inferred head is 1
const second: Head<[1, 2, 3]> = 2;

// @ts-expect-error infer is only allowed in the extends clause of a conditional type
type Illegal = infer U;

console.log(item, kept, first);

Expected output

ok 1 1

Related: Parameters and ReturnType

Official documentation →