Guida TypeScript interattiva: Tipi condizionali

Q: Che cos'è un tipo condizionale in TypeScript?

Un tipo della forma T extends U ? X : Y. Se T è assegnabile a U, il risultato è X, altrimenti Y. È un if/else per i tipi, valutato in compilazione; nel JavaScript emesso non ne resta nulla.

Q: Cosa fa la parola chiave infer in TypeScript?

infer dichiara una variabile di tipo dentro la clausola extends di un tipo condizionale e lascia che TypeScript la riempia a partire dal tipo corrispondente. T extends Promise ? V : T estrae il tipo del valore risolto da un tipo promise. Si può usare solo nella clausola extends di un tipo condizionale.

Q: Come si ottiene il tipo di ritorno di una funzione in TypeScript?

Usa il predefinito ReturnType . È un tipo condizionale con infer: T extends (...args: any) => infer R ? R : any. Per le funzioni async, avvolgilo in Awaited per ottenere il valore risolto invece della promise.

Q: Perché IsNever restituisce never invece di true?

never è la union vuota, e un tipo condizionale distributivo agisce sui membri di una union. Senza membri non c'è nulla su cui agire e il risultato è never. Scrivi [T] extends [never] ? true : false per verificare never in sé.

Un tipo condizionale sceglie tra due tipi con un test che si legge come l'operatore ternario di JavaScript: T extends U ? X : Y. Se T è assegnabile a U, il risultato è X; altrimenti è 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

Qui extends significa "è assegnabile a", la stessa relazione che il compilatore usa quando assegni un valore a una variabile. I tipi condizionali esistono solo in compilazione; vengono cancellati dall'output JavaScript.

La sintassi

type Result = CheckedType extends TestType ? TrueType : FalseType;

I tipi condizionali diventano utili con i generics, dove il tipo controllato è un parametro di tipo che riceverà un tipo concreto più tardi. Nel ramo true TypeScript sa che il tipo controllato soddisfa il test, quindi T["message"] qui sopra è consentito anche se T da solo non ha una proprietà message.

Si possono anche annidare, come ternari concatenati:

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

L'as TypeName<T> nel corpo della funzione non è facoltativo, come mostra la prossima sezione.

I tipi di ritorno condizionali richiedono un'asserzione

Una funzione il cui tipo di ritorno è un tipo condizionale sul proprio parametro di tipo non può restituire direttamente nessuno dei due rami. TypeScript non restringe T dentro il corpo, quindi non può sapere quale ramo si applica:

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

Due soluzioni comuni: gli overload, che dichiarano ogni coppia input-output e controllano con precisione chi chiama, oppure un'asserzione nell'implementazione.

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

Gli overload sono trattati nella pagina sull'overloading delle funzioni. Con un'asserzione, il compilatore si fida di te: un ramo sbagliato nel corpo non verrebbe intercettato.

Tipi condizionali distributivi

Quando il tipo controllato è un parametro di tipo nudo e riceve una union, la condizione viene eseguita una volta per membro e i risultati vengono uniti in una nuova 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 ]

La distribuzione è ciò che fa funzionare Exclude ed Extract. Exclude<T, U> è definito come T extends U ? never : T: ogni membro che corrisponde a U diventa never, e never sparisce da una union. Quindi Exclude<"a" | "b" | "c", "a"> è "b" | "c".

Due sorprese derivano dalla stessa regola. boolean è la union true | false, quindi ToArray<boolean> è false[] | true[], non boolean[]. E never è la union vuota, quindi un tipo condizionale distributivo che riceve never restituisce never senza testare nulla:

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

Estrarre tipi con infer

infer dichiara una nuova variabile di tipo dentro la clausola extends. Se la corrispondenza riesce, TypeScript riempie quella variabile a partire dal tipo controllato, e puoi usarla nel ramo 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

Leggi T extends Promise<infer V> ? V : T come "se T è una promise di qualcosa, chiama quel qualcosa V e restituiscilo; altrimenti restituisci T invariato". infer è consentito solo nella clausola extends di un tipo condizionale.

Una variabile infer può avere un proprio vincolo con extends. La corrispondenza riesce allora solo se il tipo dedotto lo rispetta:

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

Costruire ReturnType da solo

Il ReturnType predefinito è un tipo condizionale di una riga con infer. Scriverlo da solo è l'esercizio classico che fa scattare entrambe le idee:

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 trasforma il valore della funzione nel suo tipo, poi il tipo condizionale lo confronta con "qualsiasi funzione" e cattura il tipo di ritorno come R. La versione della libreria standard differisce in due dettagli: il suo parametro è vincolato ai tipi funzione (T extends (...args: any) => any), quindi ReturnType<string> è un errore di compilazione invece di never, e il suo ramo falso è any. La pagina su ReturnType tratta anche Parameters, InstanceType e Awaited.

Tipi condizionali ricorsivi

Un tipo condizionale può riferirsi a se stesso, e questo gli permette di scartare qualsiasi livello di annidamento:

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

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

Il predefinito Awaited<T> funziona così, scartando Promise<Promise<T>> fino a T. In pratica, tieni la ricorsione poco profonda: una ricorsione molto profonda o illimitata fa arrendere il compilatore con error TS2589: Type instantiation is excessively deep and possibly infinite.

Riferimento rapido

Pattern	Significato
`T extends U ? X : Y`	`X` se `T` è assegnabile a `U`, altrimenti `Y`
`T extends U ? never : T`	rimuove i membri che corrispondono a `U` (è `Exclude`)
`T extends U ? T : never`	tiene i membri che corrispondono a `U` (è `Extract`)
`[T] extends [U] ? X : Y`	stesso test, senza distribuire su una union
`T extends (infer E)[] ? E : T`	tipo dell'elemento di un array
`T extends Promise<infer V> ? V : T`	tipo del valore di una promise
`T extends (...args: any[]) => infer R ? R : never`	tipo di ritorno di una funzione
`T extends [infer H, ...infer Rest] ? ...`	primo elemento e resto di una tupla

Domande frequenti

Che cos'è un tipo condizionale in TypeScript?

Un tipo della forma T extends U ? X : Y. Se T è assegnabile a U, il risultato è X, altrimenti Y. È un if/else per i tipi, valutato in compilazione; nel JavaScript emesso non ne resta nulla.

Cosa fa la parola chiave infer in TypeScript?

infer dichiara una variabile di tipo dentro la clausola extends di un tipo condizionale e lascia che TypeScript la riempia a partire dal tipo corrispondente. T extends Promise<infer V> ? V : T estrae il tipo del valore risolto da un tipo promise. Si può usare solo nella clausola extends di un tipo condizionale.

Che cos'è un tipo condizionale distributivo?

Quando il tipo controllato è un parametro di tipo nudo e passi una union, la condizione viene applicata a ogni membro separatamente e i risultati vengono uniti. ToArray<string | number> con type ToArray<T> = T extends unknown ? T[] : never diventa string[] | number[]. Racchiudi entrambi i lati tra parentesi quadre, [T] extends [unknown], per disattivarlo.

Come si ottiene il tipo di ritorno di una funzione in TypeScript?

Usa il predefinito ReturnType<typeof fn>. È un tipo condizionale con infer: T extends (...args: any) => infer R ? R : any. Per le funzioni async, avvolgilo in Awaited<...> per ottenere il valore risolto invece della promise.

Perché IsNever<never> restituisce never invece di true?

never è la union vuota, e un tipo condizionale distributivo agisce sui membri di una union. Senza membri non c'è nulla su cui agire e il risultato è never. Scrivi [T] extends [never] ? true : false per verificare never in sé.

Concetti correlati