Условные типы и infer в TypeScript: примеры

Условный тип выбирает между двумя типами с помощью проверки, которая читается как тернарный оператор JavaScript: 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>'.

Два обычных исправления: перегрузки, которые описывают каждую пару входа и выхода и точно проверяют вызывающий код, или утверждение в реализации.

// 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

Перегрузки описаны на странице о перегрузке функций. С утверждением компилятор верит вам на слово: неверная ветка в теле не будет замечена.

Дистрибутивные условные типы

Когда проверяемый тип это голый параметр типа и он получает объединение, условие выполняется по разу для каждого члена, а результаты собираются в новое объединение:

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".

Из того же правила следуют два сюрприза. boolean это объединение true | false, поэтому ToArray<boolean> это false[] | true[], а не boolean[]. А 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 это промис чего-то, назови это что-то 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. Написать его самому это классическое упражнение, после которого обе идеи становятся понятны:

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. Версия из стандартной библиотеки отличается двумя деталями: её параметр ограничен типами функций (T extends (...args: any) => any), поэтому ReturnType<string> это ошибка компиляции, а не never, и её ложная ветка это any. Страница о ReturnType описывает также Parameters, InstanceType и Awaited.

Рекурсивные условные типы

Условный тип может ссылаться на себя, что позволяет разворачивать вложенность любой глубины:

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.

Краткий справочник