実行できるTypeScriptドキュメント: 条件型

Q: TypeScriptの条件型とは何ですか？

T extends U ? X : Y という形の型です。T が U に代入できれば結果は X、そうでなければ Y です。型のための if/else で、コンパイル時に評価され、出力されるJavaScriptには何も残りません。

Q: TypeScriptの infer キーワードは何をしますか？

infer は条件型の extends 句の中で型変数を宣言し、一致した型からTypeScriptにそれを埋めさせます。T extends Promise ? V : T は、Promise の型から解決される値の型を取り出します。使えるのは条件型の extends 句の中だけです。

Q: TypeScriptで関数の戻り値の型を取得するには？

組み込みの ReturnType を使います。これは infer を使った条件型です: T extends (...args: any) => infer R ? R : any。async 関数なら、Promise ではなく解決される値を得るために Awaited で囲みます。

Q: IsNever が true ではなく never を返すのはなぜですか？

never は空のユニオン型で、分配条件型はユニオン型のメンバーに対してマップするからです。メンバーがなければマップするものがなく、結果は never になります。never そのものをテストするには [T] extends [never] ? true : false と書きます。

条件型は、JavaScriptの三項演算子のように読めるテストで2つの型のどちらかを選びます: T extends U ? X : Y。T が U に代入できれば結果は X、そうでなければ Y です。

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

type A = IsString<"hello">; // "yes"
type B = IsString<42>;      // "no"

// A practical one: the type of a "message" property, if there is one
type MessageOf<T> = T extends { message: unknown } ? T["message"] : never;

type ErrText = MessageOf<{ message: string; code: number }>; // string
type Nothing = MessageOf<{ code: number }>;                  // never

const a: A = "yes";
const text: ErrText = "disk full";
console.log(a, text); // yes disk full

ここでの extends は「代入できる」という意味で、値を変数に代入するときにコンパイラーが使うのと同じ関係です。条件型はコンパイル時にしか存在せず、JavaScriptの出力からは消去されます。

構文

type Result = CheckedType extends TestType ? TrueType : FalseType;

条件型が役に立つのはジェネリクスと組み合わせたときです。チェックする型は型パラメーターで、あとで具体的な型が入ります。true のブランチでは、チェックした型がテストに一致することをTypeScriptが知っているので、普通の T には message プロパティがないのに、上の T["message"] が許されます。

三項演算子の連鎖のようにネストもできます:

type TypeName<T> =
  T extends string ? "string" :
  T extends number ? "number" :
  T extends boolean ? "boolean" :
  T extends undefined ? "undefined" :
  "object";

function typeName<T>(value: T): TypeName<T> {
  return typeof value as TypeName<T>;
}

console.log(typeName("hi"), typeName(3), typeName(true)); // string number boolean
const n: TypeName<number[]> = "object";
console.log(n); // object

関数の本体の as TypeName<T> は省略できません。その理由は次のセクションで説明します。

条件型の戻り値にはアサーションが必要

自分の型パラメーターに対する条件型を戻り値の型に持つ関数は、どちらのブランチも直接は返せません。TypeScriptは本体の中で T を絞り込まないので、どのブランチが当てはまるかわからないからです:

// This does not compile: TypeScript cannot pick a branch of Flip<T> inside the body
type Flip<T> = T extends string ? number : string;

function flip<T extends string | number>(x: T): Flip<T> {
  return typeof x === "string" ? x.length : String(x);
}

console.log(flip("abc"), flip(7));

index.ts(5,34): error TS2322: Type 'number' is not assignable to type 'Flip<T>'.
index.ts(5,45): error TS2322: Type 'string' is not assignable to type 'Flip<T>'.

よくある直し方は2つあります。入力と出力の組をそれぞれ明示して呼び出し側を正確にチェックするオーバーロードか、実装の中でのアサーションです。

// Fix 1: overloads
function flip(x: string): number;
function flip(x: number): string;
function flip(x: string | number): string | number {
  return typeof x === "string" ? x.length : String(x);
}

const len = flip("abc"); // number
const str = flip(7);     // string
console.log(len + 1, str.padStart(3, "0")); // 4 007

// Fix 2: keep the conditional type and assert inside the body
type Flip<T> = T extends string ? number : string;
function flip2<T extends string | number>(x: T): Flip<T> {
  return (typeof x === "string" ? x.length : String(x)) as Flip<T>;
}
console.log(flip2("hello")); // 5

オーバーロードについては関数のオーバーロードのページで扱っています。アサーションを使うとコンパイラーはあなたを信用するので、本体で間違ったブランチを返しても捕まえられません。

分配条件型

チェックする型がむき出しの型パラメーターで、ユニオン型を受け取ると、条件はメンバーごとに1回ずつ実行され、結果が新しいユニオン型に結合されます:

type ToArray<T> = T extends unknown ? T[] : never;

type A = ToArray<string | number>; // string[] | number[]

// Wrapping both sides in [ ] turns distribution off
type ToArrayWhole<T> = [T] extends [unknown] ? T[] : never;
type B = ToArrayWhole<string | number>; // (string | number)[]

const a: A = ["x", "y"];  // an array of strings, or an array of numbers
const b: B = ["x", 1];    // a mixed array
// const bad: A = ["x", 1] would be error TS2322:
// Type '(string | number)[]' is not assignable to type 'string[] | number[]'.
console.log(a, b); // [ 'x', 'y' ] [ 'x', 1 ]

Exclude と Extract を動かしているのが分配です。Exclude<T, U> は T extends U ? never : T と定義されています。U に一致する各メンバーは never になり、never はユニオン型から消えます。そのため Exclude<"a" | "b" | "c", "a"> は "b" | "c" です。

同じルールから意外な結果が2つ生まれます。boolean はユニオン型 true | false なので、ToArray<boolean> は boolean[] ではなく false[] | true[] です。そして never は空のユニオン型なので、never を与えられた分配条件型は何もテストせずに never を返します:

type IsNever<T> = T extends never ? true : false;
type X = IsNever<never>; // never, not true

type IsNeverFixed<T> = [T] extends [never] ? true : false;
type Y = IsNeverFixed<never>; // true

infer で型を取り出す

infer は extends 句の中で新しい型変数を宣言します。一致すれば、TypeScriptはチェックした型からその変数を埋め、true のブランチでそれを使えます:

type ElementOf<T> = T extends readonly (infer E)[] ? E : T;
type Unpromise<T> = T extends Promise<infer V> ? V : T;
type FirstArg<F> = F extends (first: infer A, ...rest: any[]) => unknown ? A : never;
type Head<T> = T extends [infer H, ...unknown[]] ? H : never;

type E1 = ElementOf<string[]>;              // string
type V1 = Unpromise<Promise<{ id: number }>>; // { id: number }
type A1 = FirstArg<(name: string, age: number) => void>; // string
type H1 = Head<[Date, number]>;              // Date

const id: V1 = { id: 7 };
const first: A1 = "Ada";
const when: H1 = new Date("2024-03-15T10:30:00Z");
console.log(id, first, when.toISOString());
// { id: 7 } Ada 2024-03-15T10:30:00.000Z

T extends Promise<infer V> ? V : T は「T が何かの Promise なら、その何かを V と呼んでそれを返す。そうでなければ T をそのまま返す」と読みます。infer を使えるのは条件型の extends 句の中だけです。

infer の変数には extends で独自の制約を付けられます。その場合、推論された型が制約に合うときだけ一致します:

type FirstString<T> = T extends [infer S extends string, ...unknown[]] ? S : never;

type A = FirstString<["a", 1]>; // "a"
type B = FirstString<[1, "a"]>; // never: the first element is not a string

ReturnType を自分で作る

組み込みの ReturnType は、infer を使った1行の条件型です。自分で書いてみるのは、2つの考え方を腑に落とす定番の練習です:

type MyReturnType<T> = T extends (...args: any[]) => infer R ? R : never;

function makeUser(name: string) {
  return { name, joined: new Date("2024-03-15T10:30:00Z") };
}

type User = MyReturnType<typeof makeUser>; // { name: string; joined: Date }
type Same = ReturnType<typeof makeUser>;   // the built-in gives the same type

const u: User = makeUser("Ada");
const copy: Same = { ...u, name: "Grace" };
console.log(copy.name, copy.joined.getUTCFullYear()); // Grace 2024

typeof makeUser が関数の値を型に変え、条件型がそれを「任意の関数」と照らし合わせて、戻り値の型を R として捉えます。標準ライブラリの版は2点が違います。型パラメーターが関数型に制約されている（T extends (...args: any) => any）ので、ReturnType<string> は never ではなくコンパイルエラーになり、false のブランチは any です。Parameters、InstanceType、Awaited も ReturnType のページで扱っています。

再帰的な条件型

条件型は自分自身を参照でき、任意の深さのネストを展開できます:

type Flatten<T> = T extends readonly (infer U)[] ? Flatten<U> : T;

type A = Flatten<number[][][]>; // number
type B = Flatten<string>;       // string

組み込みの Awaited<T> はこの方法で Promise<Promise<T>> を T まで展開しています。実際には再帰は浅く保ちましょう。非常に深い再帰や終わりのない再帰では、コンパイラーは error TS2589: Type instantiation is excessively deep and possibly infinite で諦めてしまいます。

クイックリファレンス

パターン	意味
`T extends U ? X : Y`	`T` が `U` に代入できれば `X`、そうでなければ `Y`
`T extends U ? never : T`	`U` に一致するメンバーを取り除く（これが `Exclude`）
`T extends U ? T : never`	`U` に一致するメンバーを残す（これが `Extract`）
`[T] extends [U] ? X : Y`	同じテストを、ユニオン型に分配せずに行う
`T extends (infer E)[] ? E : T`	配列の要素の型
`T extends Promise<infer V> ? V : T`	Promise の値の型
`T extends (...args: any[]) => infer R ? R : never`	関数の戻り値の型
`T extends [infer H, ...infer Rest] ? ...`	タプルの最初の要素と残り

よくある質問

TypeScriptの条件型とは何ですか？

T extends U ? X : Y という形の型です。T が U に代入できれば結果は X、そうでなければ Y です。型のための if/else で、コンパイル時に評価され、出力されるJavaScriptには何も残りません。

TypeScriptの infer キーワードは何をしますか？

infer は条件型の extends 句の中で型変数を宣言し、一致した型からTypeScriptにそれを埋めさせます。T extends Promise<infer V> ? V : T は、Promise の型から解決される値の型を取り出します。使えるのは条件型の extends 句の中だけです。

分配条件型とは何ですか？

チェックする型がむき出しの型パラメーターで、そこにユニオン型を渡すと、条件は各メンバーに別々に適用され、結果が結合されます。type ToArray<T> = T extends unknown ? T[] : never に対する ToArray<string | number> は string[] | number[] になります。これを止めるには両辺をかっこで囲みます: [T] extends [unknown]。

TypeScriptで関数の戻り値の型を取得するには？

組み込みの ReturnType<typeof fn> を使います。これは infer を使った条件型です: T extends (...args: any) => infer R ? R : any。async 関数なら、Promise ではなく解決される値を得るために Awaited<...> で囲みます。

IsNever<never> が true ではなく never を返すのはなぜですか？

never は空のユニオン型で、分配条件型はユニオン型のメンバーに対してマップするからです。メンバーがなければマップするものがなく、結果は never になります。never そのものをテストするには [T] extends [never] ? true : false と書きます。