Ограничения дженериков

Ошибка и контракт

Внутри тела дженерика T непрозрачен — проверяющий ничего о нём не знает, поэтому a.length отвергается. Ограничение сообщает проверяющему нижнюю границу: каждый T будет как минимум этой формы.

function longest<T extends { length: number }>(a: T, b: T): T {
  return a.length > b.length ? a : b;
}

const s = longest("alpha", "beta");
//    ^? const s: string
const arr = longest([1, 2], [3, 4, 5]);
//    ^? const arr: number[]
longest(10, 20);
// Error: Argument of type 'number' is not assignable to
//        parameter of type '{ length: number }'.

Ограничение выполнило две задачи одновременно:

1. Ограничило вызывающих. Принимаются только аргументы, присваиваемые { length: number } — number отвергается в точке вызова.
2. Открыло члены внутри. Поскольку каждый T теперь гарантированно имеет length: number, тело вправе читать a.length.

Это и есть контракт: вызывающие отдают свободу; тело получает возможности. Упустите любую сторону — и вы либо чрезмерно ограничите API, либо не сможете использовать значение, которое ограничили.

Ограничение по ключу: keyof

Канонический ограниченный дженерик — чтение свойства по ключу. Нам нужен ключ, который один из собственных ключей объекта, а не любая строка:

function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

const user = { id: 1, name: "Ada", admin: true };

const name = getProperty(user, "name");
//    ^? const name: string
const admin = getProperty(user, "admin");
//    ^? const admin: boolean
getProperty(user, "email");
// Error: Argument of type '"email"' is not assignable to
//        parameter of type '"id" | "name" | "admin"'.

K extends keyof T ограничивает K объединением ключей T. Проверяющий выводит T из obj, затем keyof T становится "id" | "name" | "admin", и key должен быть одним из этих литералов. Возвращаемый тип T[K] — это индексный доступ, точный тип именно того свойства. Передайте несуществующий ключ — и ошибка назовёт допустимый набор.

Ограничение по форме или объединению

Ограничением может быть любой тип, не только объектный литерал:

// По форме с id — полезно для хелперов «сущностей».
function withId<T extends { id: string }>(items: T[]): Map<string, T> {
  const m = new Map<string, T>();
  for (const it of items) m.set(it.id, it);
  return m;
}

// По объединению — ограничить известным набором тегов.
type Tag = "info" | "warn" | "error";
function level<T extends Tag>(t: T): T {
  return t;
}
const l = level("warn");
//    ^? const l: "warn"   — узкий литерал сохранён

Ловушка точности: вернуть C вместо T

Вот баг, который ловят на ревью. Вы ограничиваете T extends C, а потом небрежно типизируете возврат как C. Функция всё равно компилируется, но стирает точный тип вызывающего вниз до ограничения.

// БАГ: возвращает ограничение, а не переменную типа.
function identityBad<T extends { id: string }>(x: T): { id: string } {
  return x;
}
const r1 = identityBad({ id: "u1", role: "admin" as const });
//    ^? const r1: { id: string }   — потерян `role`! сужено до ограничения

// ФИКС: вернуть T, сохранив всё, что передал вызывающий.
function identityGood<T extends { id: string }>(x: T): T {
  return x;
}
const r2 = identityGood({ id: "u1", role: "admin" as const });
//    ^? const r2: { id: string; role: "admin" }   — полный тип сохранён

Спросите себя: в возвращаемом типе написан T или само ограничение C? Возврат ограничения выбрасывает точный тип вызывающего, и лучше бы вы взяли обычный параметр типа { id: string }. Дженерик стал декоративным.

Цена ужесточения ограничения

Ограничение — это ещё и решение про API с измеримым радиусом поражения. Ужесточите T extends { id: string } до T extends { id: string; tenantId: string } — и каждый вызывающий, кто раньше передавал голый { id }, теперь падает с ошибкой: на сервисе с парой сотен точек вызова это разница между зелёной сборкой и PR, который трогает сорок файлов. Ошибка громкая и в правильном месте (на точке вызова), и в этом весь смысл ограничения, но рефлекс сеньора — спросить, место ли этому требованию в сигнатуре вообще, или более узкий внутренний хелпер локализовал бы churn. Ослабьте ограничение наоборот (уберите обязательный член) — и происходит обратное, молча: вызывающие, опиравшиеся на этот член, продолжают компилироваться, а телу, которое его читает, теперь нужен запасной путь, который вы не написали.

Есть и цена для проверяющего. Ограничение вроде K extends keyof T делает T[K] индексным доступом (indexed access), который проверяющий разрешает на каждой точке вызова; над широким объектом — типом конфига, скажем, со 120 ключами — keyof T это union из 120 членов, и каждый вызов getProperty инстанцируется и сопоставляется с ним. Один такой хелпер — ничто; слой из них поверх больших mapped-типов — это там, где вы наблюдаете скачок счётчика Instantiations в --extendedDiagnostics, и tsc из шустрого превращается в заметную паузу на каждое нажатие клавиши в редакторе.