TypeScript Generic Constraints: extends and keyof T

A generic constraint limits what a type parameter can be. <T extends { length: number }> accepts only types that have a numeric length (strings, arrays, your own objects), and because of that promise the function is allowed to read .length.

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

console.log(longest("apple", "fig"));        // apple
console.log(longest([1, 2, 3], [4]));        // [ 1, 2, 3 ]
console.log(longest({ length: 2, tag: "x" }, { length: 5, tag: "y" })); // { length: 5, tag: 'y' }

// @ts-expect-error: Argument of type 'number' is not assignable to parameter of type '{ length: number; }'.
longest(10, 20);

The return type is still T, not { length: number }: passing two arrays of numbers gives back number[], and the objects keep their tag. The constraint describes the minimum; the caller's type is preserved.

Why Constraints Are Needed

Inside a generic function, an unconstrained T could be anything: a string, a number, null, a function. So TypeScript only allows what works on every type, which is almost nothing.

// This does not compile: T could be number or undefined, which have no length.
function longest<T>(a: T, b: T): T {
  return a.length >= b.length ? a : b;
}

console.log(longest("apple", "fig"));

The compiler prints:

index.ts(3,12): error TS2339: Property 'length' does not exist on type 'T'.
index.ts(3,24): error TS2339: Property 'length' does not exist on type 'T'.

The fix is to say what you need: <T extends { length: number }>. Constraints turn "any type" into "any type that has this", which is usually what a generic function means.

Constraining to an Interface

The constraint can be any type, including an interface or type alias you already have. The function then works with anything that has at least those members, and still returns the caller's full type.

interface HasId {
  id: number;
}

function byId<T extends HasId>(items: T[], id: number): T | undefined {
  return items.find((item) => item.id === id);
}

function indexById<T extends HasId>(items: T[]): Map<number, T> {
  return new Map(items.map((item) => [item.id, item]));
}

const users = [
  { id: 1, name: "Ada", role: "admin" },
  { id: 2, name: "Grace", role: "editor" },
];

const found = byId(users, 2);
console.log(found?.name);              // Grace (found keeps name and role)
console.log(indexById(users).get(1));  // { id: 1, name: 'Ada', role: 'admin' }

Compare with a plain parameter type: function byId(items: HasId[], id: number): HasId | undefined accepts the same arrays, but the result is only HasId, so found.name would be an error. The generic version passes the full type through.

K extends keyof T: Safe Property Access

The most common constraint relates two type parameters. K extends keyof T says K must be one of T's property names, and T[K] is the type of that property.

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

function pluck<T, K extends keyof T>(items: T[], key: K): T[K][] {
  return items.map((item) => item[key]);
}

const book = { title: "Dune", year: 1965, tags: ["sci-fi"] };

const year = getProperty(book, "year");   // number
const title = getProperty(book, "title"); // string
console.log(year + 1, title.toUpperCase()); // 1966 DUNE

const books = [book, { title: "Emma", year: 1815, tags: [] }];
console.log(pluck(books, "year"));        // [ 1965, 1815 ]

// @ts-expect-error: Argument of type '"author"' is not assignable to parameter of type '"tags" | "title" | "year"'.
getProperty(book, "author");

A misspelled or missing key is a compile error, and the return type follows the key: "year" gives number, "title" gives string. The keyof page covers keyof itself, including how it behaves with index signatures.

Constraining to Primitives

A constraint can be a primitive or a union of them. A useful side effect: when T extends string (or number), TypeScript infers the literal type of the argument instead of widening it.

function maxOf<T extends number | bigint>(values: T[]): T {
  return values.reduce((a, b) => (b > a ? b : a)); // < and > work on the constraint
}

function createEvent<T extends string>(name: T): { type: T } {
  return { type: name };
}

console.log(maxOf([3, 9, 4]));           // 9
console.log(maxOf([10n, 2n]));           // 10n

const evt = createEvent("user.saved");   // evt: { type: "user.saved" }
const same: "user.saved" = evt.type;     // the literal survived
console.log(same);                       // user.saved

Without the constraint, createEvent("user.saved") returns { type: string }: here TypeScript widens the literal it inferred for T to string. With T extends string the literal is kept, which is how typed event and routing helpers get exact names out of plain string arguments.

Common Errors

Returning something that only matches the constraint. A function that returns T must return a T, not just any value that fits the constraint:

interface HasId {
  id: number;
}

function reset<T extends HasId>(item: T): T {
  return { id: item.id };
}
// error TS2322: Type '{ id: number; }' is not assignable to type 'T'.
//   '{ id: number; }' is assignable to the constraint of type 'T', but 'T' could be
//   instantiated with a different subtype of constraint 'HasId'.

If T is { id: number; name: string }, the new object has no name, so it is not a T. Return a spread of the input, return { ...item, id: 0 };, which keeps every property, or declare the return type as HasId if that is all you produce.

Passing a type argument that breaks the constraint. Explicit type arguments are checked too: with function scale<T extends number>(x: T), the call scale<string>("2") fails with Type 'string' does not satisfy the constraint 'number'. (TS2344).

Constraining when you do not need a generic. If T appears only in the parameter, function print<T extends HasId>(item: T): void is just function print(item: HasId): void with extra syntax. Constraints matter when T also appears in the return type or in another parameter.

Constraints With Defaults

A type parameter can have both a constraint and a default. The default must satisfy the constraint.

interface Store<TState extends object = Record<string, unknown>> {
  get(): TState;
  set(next: Partial<TState>): void;
}

type AnyStore = Store;                              // Store<Record<string, unknown>>
type CounterStore = Store<{ count: number }>;       // fine
type BadStore = Store<number>;
// error TS2344: Type 'number' does not satisfy the constraint 'object'.

The same extends keyword also appears in conditional types, T extends string ? A : B, where it is a test rather than a restriction; the conditional types page covers that form.