Generic constraints

The error and the contract

Inside a generic body, T is opaque — the checker knows nothing about it, so a.length is rejected. A constraint tells the checker a lower bound: every T will be at least this shape.

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 }'.

The constraint did two jobs simultaneously:

1. It restricts callers. Only arguments assignable to { length: number } are accepted — number is rejected at the call site.
2. It unlocks members inside. Because every T is now guaranteed to have length: number, the body may read a.length.

That is the contract: callers give up freedom; the body gains capability. Lose sight of either side and you either over-restrict the API or can’t use the value you constrained.

Constraining to a key: keyof

The canonical constrained generic is reading a property by key. We need the key to be one of the object’s own keys, not any string:

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 constrains K to the union of T’s keys. The checker infers T from obj, then keyof T becomes "id" | "name" | "admin", and key must be one of those literals. The return type T[K] is the indexed access — the exact type of that property. Pass a key that doesn’t exist and the error names the legal set.

Constraining to a shape or a union

A constraint can be any type, not just an object literal:

// To a shape with an id — useful for "entity" helpers.
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;
}

// To a union — restrict to a known set of tags.
type Tag = "info" | "warn" | "error";
function level<T extends Tag>(t: T): T {
  return t;
}
const l = level("warn");
//    ^? const l: "warn"   — narrow literal preserved

The specificity trap: returning C instead of T

Here is the bug that bites in code review. You constrain T extends C, then carelessly type the return as C. The function still compiles, but it erases the caller’s specific type back down to the constraint.

// BUG: returns the constraint, not the type variable.
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 }   — lost `role`! widened to the constraint

// FIX: return T, preserving everything the caller passed.
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" }   — full type kept

When you see T in a return type, ask yourself: is this the type variable or the constraint? Returning the constraint throws the caller’s precise type away, and you’d have been better off with a plain parameter typed { id: string }. The generic became decorative.

The cost of tightening a constraint

A constraint is also an API decision with a measurable blast radius. Tighten T extends { id: string } to T extends { id: string; tenantId: string } and every caller that used to pass a bare { id } now errors — on a service of a few hundred call sites, that is the difference between a green build and a PR touching forty files. The error is loud and at the right place (the call site), which is the point of the constraint, but the senior reflex is to ask whether the requirement belongs in the signature at all or whether a narrower internal helper would localize the churn. Loosen the constraint instead (drop a required member) and the opposite happens silently: callers that relied on the member keep compiling, and the body that reads it now needs a fallback you didn’t write.

There is a checker cost too. A constraint like K extends keyof T makes T[K] an indexed access the checker resolves per call site; over a wide object — a config type with, say, 120 keys — keyof T is a 120-member union and each getProperty call instantiates and relates against it. One such helper is nothing; a layer of them stacked over large mapped types is where you watch the Instantiations count in --extendedDiagnostics jump and tsc go from snappy to a noticeable pause on every keystroke in the editor.