Genéricos en TypeScript: funciones, tipos y clases genéricas

Los genéricos son parámetros de tipo. Una función genérica declara un tipo marcador, normalmente llamado T, y cada llamada lo rellena, así que los tipos que entran deciden los tipos que salen. Una misma función funciona entonces con números, strings y tus propios objetos, y cada llamada sigue estando totalmente tipada.

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> después del nombre de la función declara el parámetro de tipo. items: T[] lo usa para la entrada y T | undefined para la salida, lo que une las dos. Nunca escribiste number ni string: TypeScript infirió T a partir del argumento.

¿Por qué no any o unknown?

Sin genéricos tiparías el parámetro como any o unknown. Los dos aceptan cualquier array, y los dos pierden la conexión entre la entrada y la salida:

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

Inferencia de los argumentos de tipo

Normalmente TypeScript infiere los argumentos de tipo a partir de los valores que pasas. También puedes escribirlos de forma explícita entre corchetes angulares en la llamada, lo que hace falta cuando nada en los argumentos menciona T, o cuando la inferencia elige algo que no querías.

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' ]

Hay dos resultados de la inferencia que conviene conocer. pair(1, "one") sin el argumento explícito es un error: TypeScript infiere T = number a partir del primer argumento y luego informa Argument of type 'string' is not assignable to parameter of type 'number'. (TS2345). Y emptyList() sin ningún argumento obtiene T = unknown, lo que da unknown[], que rara vez es lo que quieres.

Varios parámetros de tipo

Una función puede declarar tantos parámetros de tipo como necesite, separados por comas. Cada uno se infiere por separado.

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 infiere tres cosas a la vez: K es "tea" | "cake", V es number y R es string por lo que devuelve el callback. K extends string es una restricción, que se explica en la página siguiente.

Interfaces y alias de tipo genéricos

Los tipos también pueden recibir parámetros. Entonces escribes el argumento al usar el tipo: Box<number>, ApiResponse<User>. La mayoría de los tipos de colección integrados funcionan así: 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> también muestra un parámetro de tipo por defecto: Result<number> significa Result<number, string>. Igual que los parámetros opcionales de una función, los parámetros con valor por defecto deben ir después de los obligatorios.

Clases genéricas

Una clase recibe parámetros de tipo después de su nombre, y cada instancia los fija. Los campos, los métodos y los parámetros del constructor pueden usarlos.

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

Si el constructor recibe un T, puedes omitir el argumento explícito: new Box(5) infiere Box<number>. Los miembros estáticos pertenecen a la propia clase, no a una instancia, así que no pueden usar el parámetro de tipo de la clase (Static members cannot reference class type parameters., TS2302).

Funciones flecha genéricas y tipos de función

La lista de parámetros de tipo va antes de la lista de parámetros. La misma sintaxis describe un tipo de función genérico.

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];

Inferir tipos literales con parámetros de tipo const

Por defecto un genérico infiere tipos ensanchados: pair("a", "b") da [string, string]. Cuando importan los valores exactos (nombres de rutas, nombres de eventos, listas de columnas), marca el parámetro como const (TypeScript 5.0 y posteriores) y se infiere como si el argumento estuviera escrito con 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

Quien llama escribe un array normal, y la función conserva los tipos literales.

Cuándo no usar genéricos

Un parámetro de tipo se gana su sitio cuando conecta dos cosas: un parámetro y el tipo de retorno, dos parámetros, o un parámetro y un callback. Si T aparece una sola vez, no aporta nada y un tipo normal es más claro.

// 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);
}

El último es habitual y engañoso: parseJson<User>(text) parece seguro en tipos pero no comprueba nada, exactamente igual que JSON.parse(text) as User. Devuelve unknown y valida. Otras señales de abuso: un parámetro de tipo al que siempre se le pasa el mismo argumento, o uno que se podría sustituir por una unión de dos tipos conocidos.

Para genéricos que necesitan saber algo de T (que tiene un length, o que K es una clave de T), el siguiente paso son las restricciones con extends.