Generics em TypeScript: funções, tipos e classes genéricas

Generics são type parameters. Uma função genérica declara um tipo marcador, normalmente chamado T, e cada chamada o preenche, então os tipos que entram decidem os tipos que saem. Uma única função passa a funcionar com números, strings e seus próprios objetos, e toda chamada continua 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> depois do nome da função declara o type parameter. items: T[] o usa na entrada e T | undefined na saída, o que liga as duas. Você nunca escreveu number nem string: o TypeScript inferiu T a partir do argumento.

Por que não any ou unknown?

Sem generics, você tiparia o parâmetro como any ou unknown. Os dois aceitam qualquer array, e os dois perdem a ligação entre entrada e saída:

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

Inferência de argumentos de tipo

Normalmente o TypeScript infere os argumentos de tipo a partir dos valores que você passa. Você também pode escrevê-los explicitamente entre sinais de menor e maior na chamada, o que é necessário quando nada nos argumentos menciona T, ou quando a inferência escolhe algo que você não queria.

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

Dois resultados de inferência merecem atenção. pair(1, "one") sem o argumento explícito é um erro: o TypeScript infere T = number a partir do primeiro argumento e depois mostra Argument of type 'string' is not assignable to parameter of type 'number'. (TS2345). E emptyList() sem argumento nenhum recebe T = unknown, dando unknown[], o que raramente é o que você quer.

Vários type parameters

Uma função pode declarar quantos type parameters precisar, separados por vírgulas. Cada um é inferido de forma independente.

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 infere três coisas de uma vez: K é "tea" | "cake", V é number e R é string, a partir do retorno do callback. K extends string é uma restrição, tratada na próxima página.

Interfaces e type aliases genéricos

Tipos também podem receber parâmetros. Você então escreve o argumento ao usar o tipo: Box<number>, ApiResponse<User>. A maioria dos tipos de coleção nativos funciona assim: 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> também mostra um type parameter com valor padrão: Result<number> significa Result<number, string>. Como nos parâmetros opcionais de função, os parâmetros com padrão precisam vir depois dos obrigatórios.

Classes genéricas

Uma classe recebe type parameters depois do nome, e cada instância os fixa. Campos, métodos e parâmetros do construtor podem usá-los.

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 o construtor recebe um T, você pode omitir o argumento explícito: new Box(5) infere Box<number>. Membros estáticos pertencem à própria classe, não a uma instância, então não podem usar o type parameter da classe (Static members cannot reference class type parameters., TS2302).

Arrow functions e tipos de função genéricos

A lista de type parameters vai antes da lista de parâmetros. A mesma sintaxe descreve um tipo de função 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];

Inferindo literal types com const type parameters

Por padrão, um generic infere tipos alargados: pair("a", "b") dá [string, string]. Quando os valores exatos importam (nomes de rotas, nomes de eventos, listas de colunas), marque o parâmetro como const (TypeScript 5.0 e posteriores) e ele infere como se o argumento tivesse sido escrito 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

Quem chama escreve um array comum, e a função mantém os literal types.

Quando não usar generics

Um type parameter vale a pena quando liga duas coisas: um parâmetro e o tipo de retorno, dois parâmetros, ou um parâmetro e um callback. Se T aparece só uma vez, ele não acrescenta nada, e um tipo simples é mais 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);
}

O último é comum e enganoso: parseJson<User>(text) parece seguro, mas não verifica nada, exatamente como JSON.parse(text) as User. Retorne unknown e valide. Outros sinais de exagero: um type parameter que sempre recebe o mesmo argumento, ou um que poderia ser trocado por uma union de dois tipos conhecidos.

Para generics que precisam saber algo sobre T (que ele tem um length, ou que K é uma chave de T), o próximo passo são as restrições com extends.