Typy warunkowe i infer w TypeScript z przykładami

Typ warunkowy wybiera między dwoma typami za pomocą testu, który wygląda jak operator trójargumentowy z JavaScriptu: T extends U ? X : Y. Jeśli T da się przypisać do U, wynikiem jest X; w przeciwnym razie 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 oznacza tu „da się przypisać do”, czyli tę samą relację, której kompilator używa, gdy przypisujesz wartość do zmiennej. Typy warunkowe istnieją tylko w czasie kompilacji; znikają z wynikowego JavaScriptu.

Składnia

type Result = CheckedType extends TestType ? TrueType : FalseType;

Typy warunkowe stają się przydatne razem z typami generycznymi, gdzie sprawdzany typ to parametr typu, który później dostaje konkretny typ. W gałęzi true TypeScript wie, że sprawdzany typ pasuje do testu, więc T["message"] powyżej jest dozwolone, choć zwykłe T nie ma właściwości message.

Można je też zagnieżdżać, jak łańcuch operatorów trójargumentowych:

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> w ciele funkcji nie jest opcjonalne, co pokazuje następna sekcja.

Warunkowe typy zwracane wymagają asercji

Funkcja, której typ zwracany to typ warunkowy zależny od jej własnego parametru typu, nie może bezpośrednio zwrócić żadnej z gałęzi. TypeScript nie zawęża T wewnątrz ciała, więc nie wie, która gałąź obowiązuje:

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

Dwa popularne rozwiązania: przeciążenia, które opisują każdą parę wejście i wyjście oraz precyzyjnie sprawdzają wywołujących, albo asercja w implementacji.

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

Przeciążenia opisuje strona o przeciążaniu funkcji. Przy asercji kompilator ci ufa: zła gałąź w ciele nie zostałaby wyłapana.

Rozdzielające typy warunkowe

Gdy sprawdzany typ to goły parametr typu i dostaje on unię, warunek wykonuje się raz dla każdego członu, a wyniki są łączone w nową unię:

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 ]

Właśnie rozdzielanie sprawia, że działają Exclude i Extract. Exclude<T, U> jest zdefiniowane jako T extends U ? never : T: każdy człon pasujący do U staje się never, a never znika z unii. Dlatego Exclude<"a" | "b" | "c", "a"> to "b" | "c".

Z tej samej reguły wynikają dwie niespodzianki. boolean to unia true | false, więc ToArray<boolean> to false[] | true[], a nie boolean[]. Poza tym never to pusta unia, więc rozdzielający typ warunkowy, który dostaje never, zwraca never bez żadnego testu:

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

Wyciąganie typów przez infer

infer deklaruje nową zmienną typu wewnątrz klauzuli extends. Jeśli dopasowanie się uda, TypeScript wypełnia tę zmienną na podstawie sprawdzanego typu i możesz jej użyć w gałęzi 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

Czytaj T extends Promise<infer V> ? V : T jako „jeśli T jest obietnicą czegoś, nazwij to coś V i je zwróć; w przeciwnym razie zwróć T bez zmian”. infer jest dozwolone tylko w klauzuli extends typu warunkowego.

Zmienna infer może mieć własne ograniczenie przez extends. Dopasowanie udaje się wtedy tylko, gdy wywnioskowany typ pasuje:

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

Własna implementacja ReturnType

Wbudowany ReturnType to jednolinijkowy typ warunkowy z infer. Samodzielne napisanie go to klasyczne ćwiczenie, po którym obie idee stają się jasne:

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 zamienia wartość funkcji w jej typ, a potem typ warunkowy dopasowuje go do „dowolnej funkcji” i przechwytuje typ zwracany jako R. Wersja z biblioteki standardowej różni się dwoma szczegółami: jej parametr jest ograniczony do typów funkcji (T extends (...args: any) => any), więc ReturnType<string> to błąd kompilacji, a nie never, a jej gałąź fałszywa to any. Strona o ReturnType omawia też Parameters, InstanceType i Awaited.

Rekurencyjne typy warunkowe

Typ warunkowy może odwoływać się do samego siebie, co pozwala rozpakować zagnieżdżenie dowolnej głębokości:

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

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

Wbudowany Awaited<T> działa w ten sposób, rozpakowując Promise<Promise<T>> aż do T. W praktyce trzymaj rekurencję płytką: bardzo głęboka albo nieograniczona rekurencja sprawia, że kompilator się poddaje z error TS2589: Type instantiation is excessively deep and possibly infinite.

Ściąga