Generic constraints

Telling TypeScript what T must have

When a shopper signs in, a shop page may find two carts: the one saved on this device and the one saved in their account. It keeps the longer one. A generic longest should work for any two lists. Here is a first try, with a plain type parameter T (the Generic functions lesson covers type parameters):

1function longest<T>(a: T, b: T): T {2  return a.length >= b.length ? a : b;3}4 5console.log(longest(["Tea"], ["Tea", "Cake"]));

Line 1 says a and b are both T, and longest gives back a T. Line 2 compares their lengths and gives back the longer one. TypeScript marks both .length reads on line 2, on purpose:

• Property 'length' does not exist on type 'T' means "T could be any type, and not every type has a length". A caller could pass two numbers, and numbers have no length.

Line 5 passes two carts, so the code prints [ 'Tea', 'Cake' ] when it runs. But TypeScript checks the function for every possible T, not just this call. You need a way to say "T may be any type, as long as it has a length". That is a constraint:

1function longest<T extends { length: number }>(a: T, b: T): T {2  return a.length >= b.length ? a : b;3}4 5const savedCart = ["Tea"];6const newCart = ["Tea", "Cake"];7const cart = longest(savedCart, newCart);8//    ^?9console.log(cart);

The only change is on line 1: T extends { length: number }. It says T must be a type with a length that is a number. Now every T has a length, so line 2 is allowed. Lines 5 and 6 make the two carts, and line 7 keeps the longer. The query on line 8 shows const cart: string[]: T is still exactly the type that went in, not just "something with a length". Line 9 prints [ 'Tea', 'Cake' ].

Constraints with extends

In angle brackets, extends means "must fit". T extends { length: number } lets T be any type that has at least a length that is a number. Extra properties are fine. TypeScript compares shapes, not names (the Structural typing lesson explains this). Press the buttons to pass different arguments on line 5:

1function longest<T extends { length: number }>(a: T, b: T): T {2  return a.length >= b.length ? a : b;3}4 5const result = longest(["Tea"], ["Tea", "Cake"]);6//    ^?7console.log(result);

Two carts fit, and result is string[]. Two numbers get Argument of type 'number' is not assignable to parameter of type '{ length: number; }': in plain words, "a number doesn't have the length this function needs". Two objects with a length fit, though they're plain objects. A cart and a number shows that every argument typed T is checked.

A constraint can be any type, including one you named with type. Strings have a length too:

1type HasLength = { length: number };2 3function longest<T extends HasLength>(a: T, b: T): T {4  return a.length >= b.length ? a : b;5}6 7const tags = longest(["sale"], ["sale", "new"]);8//    ^?9console.log(tags.join(", "), longest("Tea", "Cake"));

Line 1 gives the shape a name, HasLength, and line 3 uses it: T extends HasLength. Line 7 passes two lists of tags, and line 8 shows const tags: string[]. Line 9 prints sale, new, then calls longest("Tea", "Cake"), which prints Cake: four letters beat three.

Why not skip T and type the parameters as { length: number }? Because then nothing connects what goes in with what comes out:

1function longest(a: { length: number }, b: { length: number }) {2  return a.length >= b.length ? a : b;3}4 5const cart = longest(["Tea"], ["Tea", "Cake"]);6//    ^?7cart.push("Pie");

Line 1 types both parameters as "something with a length". Line 5 passes two carts, but the query on line 6 shows { length: number; }: that's all TypeScript knows about the result. Line 7 tries to add to the cart and gets Property 'push' does not exist on type '{ length: number; }'. The type parameter in the overview kept string[].

A constraint is the least T has, not all it has. So a function that promises to give back a T can't give back a new object that only matches the constraint:

1function atLeast<T extends { length: number }>(value: T, minimum: number): T {2  if (value.length >= minimum) {3    return value;4  }5  return { length: minimum };6}

Line 1 promises to give back a T. Line 3 gives back value, which is a T, so that's fine. Line 5 gives back a new object { length: minimum }. TypeScript marks it with a message in two lines:

• Type '{ length: number; }' is not assignable to type 'T': this object isn't necessarily a T.
• 'T' could be instantiated with a different subtype of constraint '{ length: number; }': "a caller could fill in T with a more specific type". If they pass a cart, T is string[], and they expect a cart back, with push and map, not a plain object.

Only real property names with keyof

A settings page reads one setting at a time by its name. Names are text, but not any text: only the names the settings object has. TypeScript has a word for that list. keyof before an object type gives the names of its properties:

1type Settings = { theme: string; fontSize: number; showTips: boolean };2 3type SettingName = keyof Settings;4const picked: SettingName = "fontSize";5const typo: SettingName = "colour";

Line 1 describes the settings. Line 3 makes SettingName the type keyof Settings, which means "theme" | "fontSize" | "showTips": one of those three names, as text. Line 4 picks "fontSize", which is fine. Line 5 tries "colour" and gets an error on purpose: Type '"colour"' is not assignable to type 'keyof Settings', "Settings has no property called colour". (The keyof & typeof lesson covers keyof in depth.)

You can type a parameter with keyof directly. That stops typos, but the result is vague:

1type Settings = { theme: string; fontSize: number; showTips: boolean };2 3const settings: Settings = { theme: "dark", fontSize: 16, showTips: true };4 5function getSetting(key: keyof Settings) {6  return settings[key];7}8 9const size = getSetting("fontSize");10//    ^?11console.log(size);

Line 5 says key is one of the setting names. Line 9 asks for "fontSize", but the query on line 10 shows const size: string | number | boolean. The function doesn't know which name you passed, so the result could be any setting's type. Line 11 prints 16.

Make the key a type parameter instead: K extends keyof Settings. Now K is the exact name you pass, and the return type Settings[K] means "the type of property K in Settings". Type a name on line 9, and watch the error list and the answer after ^?:

1type Settings = { theme: string; fontSize: number; showTips: boolean };2 3const settings: Settings = { theme: "dark", fontSize: 16, showTips: true };4 5function getSetting<K extends keyof Settings>(key: K): Settings[K] {6  return settings[key];7}8 9const value = getSetting("fontSize");10//    ^?11console.log(value);

With "fontSize", value is a number. With "theme", it's a string, and with "showTips", a boolean. "colour" gets Argument of type '"colour"' is not assignable to parameter of type 'keyof Settings'. theme without quotes gets Cannot find name 'theme', because a name without quotes means a variable.

One type parameter in another's constraint

getSetting only works for Settings. To read a property of any object, use two type parameters: T for the object and K for the key. Then K's constraint can mention T:

1function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {2  return obj[key];3}4 5const user = { name: "Asha", age: 30 };6const product = { name: "Tea", price: 3 };7const age = getProperty(user, "age");8//    ^?9const price = getProperty(product, "price");10//    ^?11console.log(age, price);12getProperty(user, "price");

Line 1 declares T and K extends keyof T: whatever object you pass, the key must be one of its property names. The return type T[K] is that property's type. Lines 5 and 6 make a user and a product. Line 7 reads the user's age, and line 8 shows const age: number. Line 9 reads the product's price, and line 10 shows const price: number. Line 11 prints 30 3.

Line 12 asks the user for a price, a slip from the product line. TypeScript fills in T from the user first, so the keys allowed are the user's. It says Argument of type '"price"' is not assignable to parameter of type '"age" | "name"': a user only has an age and a name.

A form that updates one field at a time uses the same idea, with a third parameter: the new value must have the type of that field. { ...form, [key]: value } copies the form and sets one property, named by key (see Spread and rest). Press the buttons to change line 8:

1type ProfileForm = { name: string; age: number; newsletter: boolean };2 3function updateField<T, K extends keyof T>(form: T, key: K, value: T[K]): T {4  return { ...form, [key]: value };5}6 7const form: ProfileForm = { name: "Asha", age: 30, newsletter: false };8const next = updateField(form, "age", 31);9console.log(next);

value: T[K] ties the value to the key. With age, 31, the value must be a number. age, "31" is the bug from a text box: the age would become text, and adding 1 later would make "311". email isn't a field of the form at all.

Constraints that ask for too much

A constraint should ask for what the function uses, and no more. Here an order search asks for a name it never reads:

1type Order = { id: number; total: number };2 3function findById<T extends { id: number; name: string }>(items: T[], id: number) {4  return items.find((item) => item.id === id);5}6 7const orders: Order[] = [{ id: 7, total: 9 }];8const order = findById(orders, 7);

Line 1 says an Order has an id and a total. Line 3 asks every item for an id and a name, but line 4 only reads id. Line 8 passes the orders, and TypeScript turns them away: Argument of type 'Order[]' is not assignable to parameter of type '{ id: number; name: string; }[]', followed by the reason, Property 'name' is missing in type 'Order'. Ask only for the id:

1type Order = { id: number; total: number };2 3function findById<T extends { id: number }>(items: T[], id: number) {4  return items.find((item) => item.id === id);5}6 7const orders: Order[] = [{ id: 7, total: 9 }];8const order = findById(orders, 7);9//    ^?10console.log(order?.total);

Line 3 now asks only for id. Line 8 is fine, and line 9 shows const order: Order | undefined: T is still Order, so order?.total on line 10 is allowed and prints 9.

Another way to ask for too much is to make the type parameter the whole list, when you only need its items:

1function firstItem<T>(list: T[]) {2  return list[0];3}4function firstOfList<L extends any[]>(list: L) {5  return list[0];6}7 8const price = firstItem([3, 4]);9//    ^?10const lost = firstOfList([3, 4]);11//    ^?

Lines 1 to 3 use T for one item, and list: T[]. Lines 4 to 6 use L extends any[] for the whole list. Both give back list[0]. Line 9 shows const price: number, but line 11 shows const lost: any: TypeScript reads the item through the constraint any[], so the type is gone. Let the type parameter be the simplest thing you need, here one item.

Finally, a function may not need a type parameter at all. If T would appear only once, write the constraint as a plain parameter type:

1function isTooLong(value: { length: number }, max: number) {2  return value.length > max;3}4 5console.log(isTooLong("Asha", 3));6console.log(isTooLong(["Tea", "Cake"], 3));

Line 1 takes anything with a length and gives back a boolean, not the value, so nothing needs connecting. Line 5 prints true: "Asha" has 4 letters, more than 3. Line 6 prints false: the cart has 2 items.

The table below lists the three ways a constraint asks for too much. Read each row as: what you wrote, what goes wrong, and what to write.

A product table sorted by any column

A product table on an admin page sorts by whichever column header you press. One generic sortBy works for any table, and only accepts real column names:

1type Product = { name: string; price: number };2 3function sortBy<T, K extends keyof T>(rows: T[], key: K): T[] {4  return [...rows].sort((a, b) => (a[key] < b[key] ? -1 : 1));5}6 7const products: Product[] = [8  { name: "Tea", price: 3 },9  { name: "Cake", price: 4 },10  { name: "Bun", price: 2 },11];12const byPrice = sortBy(products, "price");13//    ^?14console.log(byPrice.map((product) => product.name));15sortBy(products, "colour");

Line 3 declares T for a row and K extends keyof T for the column. Line 4 copies the rows with [...rows], so the original array stays as it was, and sorts the copy by that column, smaller values first (the Sorting arrays lesson covers sort). Lines 7 to 11 are three products. Line 12 sorts them by price, and line 13 shows const byPrice: Product[]. Line 14 prints [ 'Bun', 'Tea', 'Cake' ]: 2, 3, then 4.

Line 15 is a column header someone misspelled, or a column that was removed. TypeScript marks it on purpose: Argument of type '"colour"' is not assignable to parameter of type 'keyof Product'. If that call ran, every a[key] would be undefined, so the sort would compare nothing. Without K extends keyof T, nothing would tell you.

Common mix-ups

You have now seen extends in three places, and only one of them is a constraint. The table below compares them. Read each row as: what you write, what it means, and whether it makes something new. (A fourth use, T extends U ? X : Y, asks a question about a type; Conditional types covers it later.)

• "T extends User means T must be a class that inherits from User." No. Any type that fits User is allowed, even a plain object. Nothing is inherited.
• "Inside the function, T is the constraint type." No. The constraint is the least T has. A caller can fill in something more specific, like string[], so a new { length: 3 } isn't a T.
• "A constraint makes the result lose its type." No. T stays the exact type of the argument. Plain parameter types like a: { length: number } lose it.
• "Asking for more properties is safer." No. Every extra property turns away values that would have worked. Ask for what the function uses.
• "key: string is fine for a property name." No. Any text is a string, typos included. K extends keyof T allows only the object's real names, and tells TypeScript which one you passed.
• "Constraints are checked while the code runs." No. Like every type, they're removed before the code runs. They only stop wrong calls while you write them.

Practice exercises

Each exercise is TypeScript. When you change code, press Edit & run on the starter code: the errors and ^? answers update as you type, and the console shows what it prints. Try a guess first, then use the hints.

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

const tags = longest(["sale"], ["new"]);
const sizes = longest({ length: 2 }, { length: 3 });
const totals = longest(9, 12);

1function longest<T extends { length: number }>(a: T, b: T): T {2  return a.length >= b.length ? a : b;3}4 5const tags = longest(["sale"], ["new"]);6const sizes = longest({ length: 2 }, { length: 3 });7const totals = longest(9, 12); // line 7: numbers have no length

1type Settings = { theme: string; fontSize: number; showTips: boolean };2 3const settings: Settings = { theme: "dark", fontSize: 16, showTips: true };4 5function getSetting<K extends keyof Settings>(key: K): Settings[K] {6  return settings[key];7}8 9const tips = getSetting("showTips");

1type Settings = { theme: string; fontSize: number; showTips: boolean };2 3const settings: Settings = { theme: "dark", fontSize: 16, showTips: true };4 5function getSetting<K extends keyof Settings>(key: K): Settings[K] {6  return settings[key];7}8 9const tips = getSetting("showTips");10//    ^?

1function shortest<T>(a: T, b: T): T {2  return a.length <= b.length ? a : b;3}4 5console.log(shortest(["Tea", "Cake"], ["Pie"]));

1function shortest<T extends { length: number }>(a: T, b: T): T {2  return a.length <= b.length ? a : b;3}4 5console.log(shortest(["Tea", "Cake"], ["Pie"]));

1type Product = { name: string; price: number };2 3function pluck<T>(items: T[], key: string) {4  return items.map((item) => item[key]);5}6 7const products: Product[] = [8  { name: "Tea", price: 3 },9  { name: "Cake", price: 4 },10];11console.log(pluck(products, "price"));

1type Product = { name: string; price: number };2 3function pluck<T, K extends keyof T>(items: T[], key: K) {4  return items.map((item) => item[key]);5}6 7const products: Product[] = [8  { name: "Tea", price: 3 },9  { name: "Cake", price: 4 },10];11const prices = pluck(products, "price");12//    ^?13console.log(prices);

1type Order = { id: number; total: number };2 3function findById<T extends { id: number; name: string }>(items: T[], id: number) {4  return items.find((item) => item.id === id);5}6 7const orders: Order[] = [{ id: 7, total: 9 }];8const order = findById(orders, 7);

1type Order = { id: number; total: number };2 3function findById<T extends { id: number }>(items: T[], id: number) {4  return items.find((item) => item.id === id);5}6 7const orders: Order[] = [{ id: 7, total: 9 }];8const order = findById(orders, 7);9console.log(order?.total);

1type ProfileForm = { name: string; age: number; newsletter: boolean };2 3function updateField<T, K extends keyof T>(form: T, key: K, value: any): T {4  return { ...form, [key]: value };5}6 7const form: ProfileForm = { name: "Asha", age: 30, newsletter: false };8const next = updateField(form, "age", "31");9console.log(next.age + 1);

1type ProfileForm = { name: string; age: number; newsletter: boolean };2 3function updateField<T, K extends keyof T>(form: T, key: K, value: T[K]): T {4  return { ...form, [key]: value };5}6 7const form: ProfileForm = { name: "Asha", age: 30, newsletter: false };8const next = updateField(form, "age", Number("31"));9console.log(next.age + 1);

Check your understanding

For each question, ask two things: what must T (or K) have, and what is it for this call? The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• Without a constraint, T could be any type, so you can't read .length or any property on it.
• T extends { length: number } allows any type with at least a numeric length, and T stays the exact type of the argument.
• keyof Settings is the list of a type's property names. K extends keyof T allows only real names, and T[K] is that property's type.
• One type parameter can appear in another's constraint, which ties a key to its object and a value to its key.
• A constraint is a minimum. A function that returns T can't give back something that only matches the constraint.
• Ask for what the function uses, keep the type parameter as simple as possible, and skip it when it would appear only once.

Coming next: Generic types & interfaces. It puts type parameters on types themselves, like ApiResponse<T>.