Conditional types e infer em TypeScript, com exemplos

Um conditional type escolhe entre dois tipos com um teste que se lê como o operador ternário do JavaScript: T extends U ? X : Y. Se T pode ser atribuído a U, o resultado é X; senão, é 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

Aqui extends significa "pode ser atribuído a", a mesma relação que o compilador usa quando você atribui um valor a uma variável. Conditional types existem só em tempo de compilação; eles são apagados da saída JavaScript.

A sintaxe

type Result = CheckedType extends TestType ? TrueType : FalseType;

Conditional types ficam úteis com generics, em que o tipo verificado é um type parameter que recebe um tipo concreto depois. No ramo verdadeiro, o TypeScript sabe que o tipo verificado corresponde ao teste, então o T["message"] acima é permitido, mesmo que um T simples não tenha propriedade message.

Eles também se aninham, como ternários encadeados:

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

O as TypeName<T> no corpo da função não é opcional, como mostra a próxima seção.

Tipos de retorno condicionais precisam de uma assertion

Uma função cujo tipo de retorno é um conditional type sobre o próprio type parameter não consegue retornar diretamente nenhum dos ramos. O TypeScript não estreita T dentro do corpo, então não consegue saber qual ramo vale:

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

Duas soluções comuns: overloads, que declaram cada par de entrada e saída e verificam quem chama com precisão, ou uma assertion na implementação.

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

Os overloads são tratados na página sobre sobrecarga de funções. Com uma assertion, o compilador confia em você: um ramo errado no corpo não seria detectado.

Conditional types distributivos

Quando o tipo verificado é um type parameter sozinho e recebe uma union, a condição roda uma vez para cada membro e os resultados são juntados em uma nova union:

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 ]

A distribuição é o que faz Exclude e Extract funcionarem. Exclude<T, U> é definido como T extends U ? never : T: cada membro que corresponde a U vira never, e never desaparece de uma union. Então Exclude<"a" | "b" | "c", "a"> é "b" | "c".

Duas surpresas vêm da mesma regra. boolean é a union true | false, então ToArray<boolean> é false[] | true[], e não boolean[]. E never é a union vazia, então um conditional type distributivo que recebe never retorna never sem testar nada:

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

Extraindo tipos com infer

O infer declara uma nova variável de tipo dentro da cláusula extends. Se a correspondência dá certo, o TypeScript preenche essa variável a partir do tipo verificado, e você pode usá-la no ramo verdadeiro:

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

Leia T extends Promise<infer V> ? V : T como "se T é uma promise de alguma coisa, chame essa coisa de V e a retorne; senão, retorne T sem mudanças". O infer só é permitido na cláusula extends de um conditional type.

Uma variável infer pode ter a própria restrição com extends. A correspondência então só dá certo se o tipo inferido couber nela:

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

Montando o seu próprio ReturnType

O ReturnType nativo é um conditional type de uma linha com infer. Escrevê-lo você mesmo é o exercício clássico que faz as duas ideias se encaixarem:

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 transforma o valor da função no tipo dela, e então o conditional type o compara com "qualquer função" e captura o tipo de retorno como R. A versão da biblioteca padrão difere em dois detalhes: o parâmetro dela é restrito a tipos de função (T extends (...args: any) => any), então ReturnType<string> é erro de compilação em vez de never, e o ramo falso dela é any. A página sobre ReturnType trata também de Parameters, InstanceType e Awaited.

Conditional types recursivos

Um conditional type pode referenciar a si mesmo, o que permite desembrulhar qualquer profundidade de aninhamento:

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

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

O Awaited<T> nativo funciona assim, desembrulhando Promise<Promise<T>> até T. Na prática, mantenha a recursão rasa: recursão muito profunda ou sem limite faz o compilador desistir com error TS2589: Type instantiation is excessively deep and possibly infinite.

Referência rápida