Дженерики в TypeScript: обобщённые функции, типы и классы

Дженерики это параметры типа. Обобщённая функция объявляет тип-заполнитель, обычно с именем T, и каждый вызов его подставляет, так что входящие типы определяют выходящие. Одна функция тогда работает с числами, строками и вашими собственными объектами, и каждый вызов при этом полностью типизирован.

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> после имени функции объявляет параметр типа. items: T[] использует его для входа, а T | undefined для выхода, и это связывает их. Вы ни разу не написали number или string: TypeScript вывел T из аргумента.

Почему не any или unknown?

Без дженериков параметр пришлось бы типизировать как any или unknown. Оба принимают любой массив, и оба теряют связь между входом и выходом:

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

Вывод аргументов типа

Обычно TypeScript выводит аргументы типа из переданных значений. Их также можно написать явно в угловых скобках при вызове; это нужно, когда T не упоминается ни в одном аргументе или когда вывод выбирает не то, что нужно.

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

Стоит знать два результата вывода. pair(1, "one") без явного аргумента даёт ошибку: TypeScript выводит T = number из первого аргумента и затем сообщает Argument of type 'string' is not assignable to parameter of type 'number'. (TS2345). А emptyList() вообще без аргумента получает T = unknown, то есть unknown[], что редко бывает нужно.

Несколько параметров типа

Функция может объявить столько параметров типа, сколько ей нужно, через запятую. Каждый выводится независимо.

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 выводит сразу три вещи: K это "tea" | "cake", V это number, а R это string из возвращаемого значения колбэка. K extends string это ограничение, о нём на следующей странице.

Обобщённые интерфейсы и псевдонимы типов

Типы тоже могут принимать параметры. Тогда аргумент пишется при использовании типа: Box<number>, ApiResponse<User>. Так устроено большинство встроенных типов коллекций: 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> показывает также параметр типа по умолчанию: Result<number> означает Result<number, string>. Как и опциональные параметры функций, параметры со значениями по умолчанию должны идти после обязательных.

Обобщённые классы

Класс принимает параметры типа после своего имени, и каждый экземпляр их фиксирует. Их могут использовать поля, методы и параметры конструктора.

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

Если конструктор принимает T, явный аргумент можно опустить: new Box(5) выводит Box<number>. Статические члены принадлежат самому классу, а не экземпляру, поэтому не могут использовать параметр типа класса (Static members cannot reference class type parameters., TS2302).

Обобщённые стрелочные функции и типы функций

Список параметров типа идёт перед списком параметров. Тот же синтаксис описывает обобщённый тип функции.

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

Вывод литеральных типов через const-параметры типа

По умолчанию дженерик выводит расширенные типы: pair("a", "b") даёт [string, string]. Когда важны точные значения (имена маршрутов, имена событий, списки колонок), пометьте параметр как const (TypeScript 5.0 и новее), и он будет выводить тип так, будто аргумент записан с 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

Вызывающий код пишет обычный массив, а функция сохраняет литеральные типы.

Когда дженерики не нужны

Параметр типа оправдан, когда связывает две вещи: параметр и возвращаемый тип, два параметра или параметр и колбэк. Если T встречается лишь один раз, он ничего не добавляет, и обычный тип понятнее.

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

Последний вариант распространён и вводит в заблуждение: parseJson<User>(text) выглядит типобезопасным, но ничего не проверяет, ровно как JSON.parse(text) as User. Вместо этого возвращайте unknown и проверяйте. Другие признаки злоупотребления: параметр типа, которому всегда передаётся один и тот же аргумент, или параметр, который можно заменить объединением двух известных типов.

Для дженериков, которым нужно что-то знать о T (что у него есть length или что K это ключ T), следующий шаг это ограничения через extends.