Generics in TypeScript: funzioni, tipi e classi generiche

I generics sono parametri di tipo. Una funzione generica dichiara un tipo segnaposto, di solito chiamato T, e ogni chiamata lo riempie, così i tipi che entrano decidono i tipi che escono. Una sola funzione funziona allora con numeri, stringhe e i tuoi oggetti, e ogni chiamata resta tipizzata al completo.

function first<T>(items: T[]): T | undefined {
  return items[0];
}

const n = first([10, 20, 30]);        // T = number, n: number | undefined
const s = first(["ada", "grace"]);    // T = string, s: string | undefined
const u = first([{ id: 1 }]);         // T = { id: number }

console.log(n?.toFixed(1));           // 10.0
console.log(s?.toUpperCase());        // ADA
console.log(u?.id);                   // 1

<T> dopo il nome della funzione dichiara il parametro di tipo. items: T[] lo usa per l'input e T | undefined per l'output, e questo lega i due. Non hai mai scritto number o string: TypeScript ha dedotto T dall'argomento.

Perché non any o unknown?

Senza generics tipizzeresti il parametro come any o unknown. Entrambi accettano qualsiasi array, ed entrambi perdono il legame tra input e output:

function firstAny(items: any[]): any {
  return items[0];
}

function firstUnknown(items: unknown[]): unknown {
  return items[0];
}

function firstGeneric<T>(items: T[]): T | undefined {
  return items[0];
}

const a = firstAny(["x"]);
console.log(typeof a.toFixed);         // undefined: a.toFixed(2) would compile, then throw

const b = firstUnknown(["x"]);
// b.toUpperCase();                    // error TS18046: 'b' is of type 'unknown'.
console.log(typeof b === "string" ? b.toUpperCase() : "?"); // X (after narrowing)

const c = firstGeneric(["x"]);
console.log(c?.toUpperCase());         // X, with no narrowing needed

Deduzione degli argomenti di tipo

Di solito TypeScript deduce gli argomenti di tipo dai valori che passi. Puoi anche scriverli in modo esplicito tra parentesi angolari nella chiamata, cosa necessaria quando niente negli argomenti menziona T, o quando la deduzione sceglie qualcosa che non volevi.

function pair<T>(a: T, b: T): [T, T] {
  return [a, b];
}

function emptyList<T>(): T[] {
  return [];
}

const p1 = pair(1, 2);                      // T inferred as number
const p2 = pair<string | number>(1, "one"); // explicit: mixing allowed
const names = emptyList<string>();          // nothing to infer from, so pass it
names.push("Ada");

console.log(p1, p2, names); // [ 1, 2 ] [ 1, 'one' ] [ 'Ada' ]

Vale la pena conoscere due risultati della deduzione. pair(1, "one") senza l'argomento esplicito è un errore: TypeScript deduce T = number dal primo argomento e poi segnala Argument of type 'string' is not assignable to parameter of type 'number'. (TS2345). E emptyList() senza alcun argomento ottiene T = unknown, cioè unknown[], che raramente è ciò che vuoi.

Più parametri di tipo

Una funzione può dichiarare tutti i parametri di tipo che le servono, separati da virgole. Ciascuno viene dedotto in modo indipendente.

function zip<A, B>(left: A[], right: B[]): [A, B][] {
  const length = Math.min(left.length, right.length);
  const out: [A, B][] = [];
  for (let i = 0; i < length; i++) out.push([left[i], right[i]]);
  return out;
}

function mapValues<K extends string, V, R>(obj: Record<K, V>, fn: (value: V) => R): Record<K, R> {
  const out = {} as Record<K, R>;
  for (const key of Object.keys(obj) as K[]) out[key] = fn(obj[key]);
  return out;
}

console.log(zip(["a", "b", "c"], [1, 2]));        // [ [ 'a', 1 ], [ 'b', 2 ] ]
const prices = mapValues({ tea: 2.5, cake: 4 }, (v) => `$${v.toFixed(2)}`);
console.log(prices);                               // { tea: '$2.50', cake: '$4.00' }

mapValues deduce tre cose insieme: K è "tea" | "cake", V è number e R è string dal valore restituito dalla callback. K extends string è un vincolo, spiegato nella pagina successiva.

Interfacce e alias di tipo generici

Anche i tipi possono avere parametri. Scrivi allora l'argomento quando usi il tipo: Box<number>, ApiResponse<User>. La maggior parte dei tipi di collezione integrati funziona così: Array<T>, Map<K, V>, Promise<T>, Record<K, V>.

interface ApiResponse<T> {
  status: number;
  data: T;
}

type Result<T, E = string> =
  | { ok: true; value: T }
  | { ok: false; error: E };

interface User {
  id: number;
  name: string;
}

function parseAge(text: string): Result<number> {
  const n = Number(text);
  return Number.isInteger(n) && n >= 0 ? { ok: true, value: n } : { ok: false, error: `bad age: ${text}` };
}

const res: ApiResponse<User[]> = { status: 200, data: [{ id: 1, name: "Ada" }] };
console.log(res.data[0].name);   // Ada

for (const input of ["36", "abc"]) {
  const r = parseAge(input);
  console.log(r.ok ? r.value + 1 : r.error); // 37, then bad age: abc
}

Result<T, E = string> mostra anche un parametro di tipo di default: Result<number> significa Result<number, string>. Come i parametri facoltativi delle funzioni, i parametri con default devono venire dopo quelli obbligatori.

Classi generiche

Una classe riceve i parametri di tipo dopo il suo nome, e ogni istanza li fissa. Campi, metodi e parametri del costruttore possono usarli tutti.

class Stack<T> {
  private items: T[] = [];

  push(item: T): void {
    this.items.push(item);
  }

  pop(): T | undefined {
    return this.items.pop();
  }

  peek(): T | undefined {
    return this.items.at(-1);
  }

  get size(): number {
    return this.items.length;
  }
}

const visited = new Stack<string>();
visited.push("/home");
visited.push("/docs");
console.log(visited.pop(), visited.size); // /docs 1

const numbers = new Stack<number>();
numbers.push(42);
// numbers.push("42"); // error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.
console.log(numbers.peek()); // 42

Se il costruttore prende un T, puoi omettere l'argomento esplicito: new Box(5) deduce Box<number>. I membri statici appartengono alla classe stessa, non a un'istanza, quindi non possono usare il parametro di tipo della classe (Static members cannot reference class type parameters., TS2302).

Arrow function generiche e tipi funzione

La lista dei parametri di tipo va prima della lista dei parametri. La stessa sintassi descrive un tipo funzione generico.

const last = <T>(items: T[]): T | undefined => items[items.length - 1];

type Mapper = <T, R>(items: T[], fn: (item: T) => R) => R[];
const mapAll: Mapper = (items, fn) => items.map(fn);

// In a .tsx file, <T> looks like a JSX tag. Add a trailing comma:
const lastTsx = <T,>(items: T[]) => items[items.length - 1];

Dedurre tipi letterali con i const type parameter

Di default un generic deduce tipi allargati: pair("a", "b") dà [string, string]. Quando contano i valori esatti (nomi di route, nomi di eventi, elenchi di colonne), marca il parametro come const (da TypeScript 5.0 in poi) e la deduzione avviene come se l'argomento fosse scritto as const:

function defineColumns<const T extends readonly string[]>(columns: T): T {
  return columns;
}

const loose = ["id", "name"];                  // string[]
const columns = defineColumns(["id", "name"]); // readonly ["id", "name"]

type Column = (typeof columns)[number];        // "id" | "name"
const sortBy: Column = "name";
console.log(columns, sortBy, loose.length);    // [ 'id', 'name' ] name 2

Chi chiama scrive un normale array, e la funzione conserva i tipi letterali.

Quando non usare i generics

Un parametro di tipo si guadagna il posto quando collega due cose: un parametro e il tipo di ritorno, due parametri, oppure un parametro e una callback. Se T compare una sola volta non aggiunge nulla, e un tipo semplice è più chiaro.

// Pointless: T is used once, so it is just a longer way to write unknown
function logValue<T>(value: T): void {
  console.log(value);
}

// Clearer
function logValueSimple(value: unknown): void {
  console.log(value);
}

// Also pointless: returns T but nothing connects T to an argument,
// so the caller is really just asserting a type
function parseJson<T>(text: string): T {
  return JSON.parse(text);
}

L'ultimo caso è comune e ingannevole: parseJson<User>(text) sembra type-safe ma non controlla nulla, esattamente come JSON.parse(text) as User. Restituisci invece unknown e valida il dato. Altri segnali di abuso: un parametro di tipo che riceve sempre lo stesso argomento, o uno che si potrebbe sostituire con un'unione di due tipi noti.

Per i generics che devono sapere qualcosa di T (che ha un length, o che K è una chiave di T), il passo successivo sono i vincoli con extends.