Generic functions

One function for every kind of list

A shop page has many lists: product names, prices, orders. Often you need the same small job on each of them, like getting the first item. Here is a first function typed for a list of text:

1function first(list: string[]): string | undefined {2  return list[0];3}4 5const names = ["Tea", "Cake"];6console.log(first(names));7const prices = [3, 4];8console.log(first(prices));

Line 1 says first takes a list that is a string[], which means an array of strings. It gives back string | undefined: the first item, or undefined when the list is empty. Line 2 reads the item at position 0 (the Array basics lesson covers arrays). Line 6 prints Tea. Line 8 passes prices, an array of numbers, and TypeScript marks it, on purpose:

• Argument of type 'number[]' is not assignable to parameter of type 'string[]' means "you passed a list of numbers where a list of text has to go". An argument is the value you pass in a call.

Run it anyway and line 8 prints 3. The function's code works for any list; only its types say text. You could copy it as firstPrice(list: number[]), and again for every other kind of list. A generic function writes it once:

1function first<T>(list: T[]): T | undefined {2  return list[0];3}4 5const names = ["Tea", "Cake"];6const firstName = first(names);7//    ^?8const prices = [3, 4];9const firstPrice = first(prices);10//    ^?11console.log(firstName, firstPrice);

Line 1 has one new part: <T> after the name. T is a type parameter: a name that stands for a type, the way list stands for a value. list: T[] says the list holds items of type T, and T | undefined says first gives back one of those items, or undefined.

Line 6 calls first(names). TypeScript sees an array of strings, so for this call T is string. The query on line 7 shows const firstName: string | undefined. Line 9 calls it with the prices, so T is number, and line 10 shows const firstPrice: number | undefined. There are no errors, and line 11 prints Tea 3.

Type parameters: a name for a type

A generic function has two kinds of parameters:

• Type parameters, in angle brackets before the round brackets: <T>. They stand for types, and they're removed before the code runs.
• Value parameters, in the round brackets as usual: (list: T[]). They hold the values you pass.

Once declared, T can go anywhere a type goes in that function: on a parameter, in the return type, or inside the body. In first, it appears twice, in list: T[] and in T | undefined. That is what connects them: whatever type the list's items have, the result has the same type.

T is only a name, short for "type". Most code uses it for a function's one type parameter, but <Item> with list: Item[] works the same way. Inside the function, TypeScript doesn't know which type T will be, so it only allows what works for every type:

1function shout<T>(value: T) {2  return value.toUpperCase();3}4 5console.log(shout("sale"));

Line 1 declares T, and line 2 calls value.toUpperCase(). TypeScript marks it: Property 'toUpperCase' does not exist on type 'T'. In plain words: T could be a number, and numbers have no toUpperCase. Line 5 passes text, so the code prints SALE when it runs, but TypeScript checks the function for every T, not just for this call. The next lesson, Generic constraints, shows how to say "T must be text" or "T must have a length".

Arrow functions take type parameters too, written just before the round brackets:

1const last = <T>(list: T[]) => list.at(-1);2//    ^?3 4const sizes = ["S", "M", "L"];5const lastSize = last(sizes);6//    ^?7console.log(lastSize);

Line 1 makes last, an arrow function with a type parameter T. list.at(-1) reads the last item: at counts from the end when you give it a negative number, and gives back undefined for an empty list. The query on line 2 shows the whole function's type: const last: <T>(list: T[]) => T | undefined. You didn't write a return type; TypeScript worked out T | undefined from at. Line 5 calls it with sizes, line 6 shows const lastSize: string | undefined, and line 7 prints L.

TypeScript fills in T from the arguments

You never wrote string or number in the overview's calls. TypeScript worked out T from the arguments. The type that fills in a type parameter is called a type argument, and TypeScript working it out for you is called inference. Try it: type any list of values inside the brackets on line 5, and watch the answer after ^? on line 6.

1function first<T>(list: T[]): T | undefined {2  return list[0];3}4 5const item = first(["Tea", "Cake"]);6//    ^?7console.log(item);

With 3, 4, item is number | undefined. With "Tea", 3, it's string | number | undefined: when the items differ, T becomes a union of their types. An empty box gives undefined: with no items, T is never, a type with no values at all, and never | undefined is just undefined. Tea without quotes gets Cannot find name 'Tea', because it's a name, not text.

When a type parameter appears in two parameters, TypeScript fills it in from both arguments, and they must agree:

1function pair<T>(a: T, b: T): T[] {2  return [a, b];3}4 5const sizes = pair("S", "M");6//    ^?7const mixed = pair(3, "Tea");

Line 1 says a and b are both T, and pair gives back a T[] holding both. Line 5 passes two strings, so T is string, and line 6 shows const sizes: string[]. Line 7 passes 3 and "Tea". TypeScript fills in T as number from the first argument, then marks the second: Argument of type 'string' is not assignable to parameter of type 'number'. In plain words: T is already number for this call, and text doesn't fit. The next section shows how to allow both.

A function can have more than one type parameter, separated by commas. TypeScript fills in each one, even from a callback, a function you pass in for another function to call:

1function mapList<Input, Output>(list: Input[], change: (item: Input) => Output): Output[] {2  return list.map(change);3}4 5const labels = mapList([3, 4], (price) => "$" + price);6//                              ^?7//    ^?8console.log(labels);

Line 1 declares two type parameters, Input and Output. list: Input[] is the list. change: (item: Input) => Output is a function type: "a function that takes an Input and gives back an Output". The result is Output[]. Line 2 uses the array's own map (see map, filter, and reduce).

Line 5 passes [3, 4], so Input is number. The query on line 6 points at the callback's parameter: (parameter) price: number. You didn't write a type for price; TypeScript passed Input down to it. The callback gives back "$" + price, which is text, so Output is string, and line 7 shows const labels: string[]. Line 8 prints [ '$3', '$4' ].

Writing the type argument yourself

You can also write the type argument yourself, in angle brackets after the function's name, just before the round brackets:

1function first<T>(list: T[]): T | undefined {2  return list[0];3}4 5const firstName = first<string>(["Tea", "Cake"]);6//    ^?7const firstPrice = first<number>(["Tea"]);

Line 5 writes first<string>, so T is string for this call, the same type TypeScript would fill in. Line 6 shows const firstName: string | undefined. Line 7 writes first<number> and passes a list of text. Now the type you wrote wins, and TypeScript checks the list against it: Type 'string' is not assignable to type 'number' means "this item is text, and you said the list holds numbers".

A written type argument helps when the type TypeScript would fill in isn't the one you want. The pair from the last section can hold a number and text if you say so:

1function pair<T>(a: T, b: T): T[] {2  return [a, b];3}4 5const mixed = pair<number | string>(3, "Tea");6//    ^?7console.log(mixed);

Line 5 says T is number | string, either one. Both arguments fit, and line 6 shows const mixed: (string | number)[]: an array whose items are each a string or a number. Line 7 prints [ 3, 'Tea' ].

The most common case is an empty list. A page reads a saved cart: localStorage.getItem("cart") gives back the saved text, or null when nothing was saved (the Web storage lesson covers it). parseOr turns the text into a value with JSON.parse (see the JSON lesson), or uses a fallback when there's nothing. Here nothing was saved yet, so the fallback, an empty list, becomes the cart. Press the buttons to write line 6 four ways:

1function parseOr<T>(text: string | null, fallback: T): T {2  return text === null ? fallback : JSON.parse(text);3}4 5const savedCart = null; // nothing saved yet6const cart = parseOr(savedCart, []);7//    ^?8cart.push("Tea");9console.log(cart);

With No type argument, the fallback [] is TypeScript's only clue, and an empty list says nothing about its items. TypeScript fills in never[], so line 8 can't push anything. <string[]> fixes it. <number[]> shows that a type you write is checked too. <string> is a common slip: T stands for the whole fallback, the list, not one item in it.

If no argument mentions T at all, TypeScript has nothing to go on and fills in unknown, a type that means "this could be anything, so check it before you use it":

1function emptyList<T>(): T[] {2  return [];3}4 5const tags = emptyList();6//    ^?7const sizes = emptyList<string>();8//    ^?

Line 1 declares T, but no parameter uses it. Line 5 calls emptyList(), and line 6 shows const tags: unknown[]. Line 7 writes <string>, and line 8 shows const sizes: string[].

The table below shows how T gets its type. Read each row as: this call, what T becomes, and why.

Generics or any?

Before generics, the usual way to write one function for every list was any. any is a type that turns checking off: every value fits it, and anything you do with it is allowed. That sounds handy, but TypeScript stops helping. Press the buttons to write line 1 three ways:

1function first(list: any[]): any {2  return list[0];3}4 5const prices = [3, 4];6const price = first(prices);7//    ^?8console.log(price?.toUpperCase());

Line 8 has the same mistake every time: it calls toUpperCase, a method for text, on a price. The ?. calls it only when price isn't undefined (see Nullish coalescing and optional chaining).

• With any, there are no errors, and the shopper's page throws a TypeError.
• With Only text, TypeScript marks line 6, because this first doesn't take numbers at all.
• With Type parameter T, TypeScript marks the real mistake on line 8. price is number | undefined, so after price?. your editor suggests number methods like toFixed.

The table below compares the two ways to write one function for every list. Read each row as a question, then each answer.

Use a type parameter when it connects two places: a parameter and the return type, like first, or two parameters, like pair. If T appears only once, it connects nothing, and a plain type is clearer: write function logTotal(total: number) rather than function logTotal<T>(total: T).

A search box that filters any list

A search box on a shop page filters products as the shopper types. The admin page filters users with the same kind of box. One generic search does both, and keeps each list's type:

1type Product = { name: string; price: number };2type User = { name: string; email: string };3 4function search<T>(items: T[], matches: (item: T) => boolean): T[] {5  return items.filter(matches);6}7 8const products: Product[] = [9  { name: "Tea", price: 3 },10  { name: "Cake", price: 4 },11];12const users: User[] = [13  { name: "Asha", email: "asha@example.com" },14  { name: "Carla", email: "carla@example.com" },15];16 17const typed = "ca";18const shownProducts = search(products, (product) => product.name.toLowerCase().includes(typed));19//    ^?20const shownUsers = search(users, (user) => user.email.includes(typed));21//    ^?22console.log(shownProducts.map((product) => product.price));23console.log(shownUsers.map((user) => user.name));

Lines 1 and 2 use type to give a name to the shape of a product and of a user. Line 4 declares search with one type parameter, T:

• items: T[] is the list.
• matches: (item: T) => boolean is a function that takes one item and says true (keep it) or false.
• T[] after the brackets says search gives back a list of the same items.

Line 5 keeps the items matches says yes to, with filter. Line 17 is the text typed in the box, "ca". Line 18 searches the products, so T is Product and TypeScript knows product.name is text. Line 19 shows const shownProducts: Product[]. Line 20 searches the users by email, and line 21 shows const shownUsers: User[]. Line 22 prints [ 4 ], the price of Cake, and line 23 prints [ 'Carla' ].

Because T is filled in for each call, a mistake inside the callback is caught too:

1type User = { name: string; email: string };2 3function search<T>(items: T[], matches: (item: T) => boolean): T[] {4  return items.filter(matches);5}6 7const users: User[] = [8  { name: "Asha", email: "asha@example.com" },9  { name: "Carla", email: "carla@example.com" },10];11const cheap = search(users, (user) => user.price < 4);12console.log(cheap);

Line 11 searches the users but reads user.price, a slip copied from a product filter. T is User, and users have no price: Property 'price' does not exist on type 'User'. Run it anyway and it prints [], because undefined < 4 is false for every user. With any, nothing would point at line 11.

Common mix-ups

Type parameters are types, and types are removed before the code runs. So you can't ask for T while the code runs:

1function describe<T>(value: T) {2  console.log(typeof value);3  console.log(T);4}5 6describe(3);

Line 2 is fine: typeof value asks the value itself, and prints number. Line 3 uses T as if it were a value. TypeScript says 'T' only refers to a type, but is being used as a value here. When the code runs, there's no T left, and it stops with a ReferenceError.

• "A type parameter is a value I can check while the code runs." No. T is removed with the other types. Check the value instead, with typeof value.
• "any does the same job as a type parameter." No. Both accept a list of anything, but any forgets the type and turns checking off. T keeps the type, so the result is checked.
• "I have to write the type argument on every call." No. TypeScript fills it in from the arguments. Write it when the arguments don't say enough, like an empty list.
• "The type argument is the type of one item." No. It's whatever T stands for. In parseOr, T is the whole fallback, so a list of text is <string[]>, not <string>.
• "Inside the function, I can use any method on a T value." No. T could be any type, so only what every type has is allowed. The next lesson shows how to ask for more.
• "Every function should be generic, just in case." No. A type parameter is useful when it connects two places. If it appears once, a plain type is clearer.

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.

1function first<T>(list: T[]): T | undefined {2  return list[0];3}4 5const sizes = ["S", "M", "L"];6const size = first(sizes);

1function first<T>(list: T[]): T | undefined {2  return list[0];3}4 5const sizes = ["S", "M", "L"];6const size = first(sizes);7//    ^?

function pair<T>(a: T, b: T): T[] {
  return [a, b];
}

const sizes = pair("S", "M");
const prices = pair(3, 4);
const order = pair("Tea", 2);

1function pair<T>(a: T, b: T): T[] {2  return [a, b];3}4 5const sizes = pair("S", "M");6const prices = pair(3, 4);7const order = pair("Tea", 2); // line 7: T is already string

1function last(list: string[]): string | undefined {2  return list[list.length - 1];3}4 5const sizes = ["S", "M", "L"];6const prices = [3, 4];7console.log(last(sizes));8console.log(last(prices));

1function last<T>(list: T[]): T | undefined {2  return list[list.length - 1];3}4 5const sizes = ["S", "M", "L"];6const prices = [3, 4];7console.log(last(sizes));8console.log(last(prices));

1function parseOr<T>(text: string | null, fallback: T): T {2  return text === null ? fallback : JSON.parse(text);3}4 5const savedTags = null; // nothing saved yet6const tags = parseOr(savedTags, []);7tags.push("sale");8console.log(tags.length);

1function parseOr<T>(text: string | null, fallback: T): T {2  return text === null ? fallback : JSON.parse(text);3}4 5const savedTags = null; // nothing saved yet6const tags = parseOr<string[]>(savedTags, []);7tags.push("sale");8console.log(tags.length);

1function lastViewed(items: any[]): any {2  return items[items.length - 1];3}4 5type Product = { name: string; price: number };6const viewed: Product[] = [7  { name: "Tea", price: 3 },8  { name: "Cake", price: 4 },9];10const product = lastViewed(viewed);11console.log(product.prise);

1function lastViewed<T>(items: T[]): T | undefined {2  return items[items.length - 1];3}4 5type Product = { name: string; price: number };6const viewed: Product[] = [7  { name: "Tea", price: 3 },8  { name: "Cake", price: 4 },9];10const product = lastViewed(viewed);11console.log(product?.price);

1function toggle(list, item) {2  return list.includes(item) ? list.filter((saved) => saved !== item) : [...list, item];3}4 5const favorites = toggle(["Tea", "Cake"], "Tea");6console.log(favorites);

1function toggle<T>(list: T[], item: T): T[] {2  return list.includes(item) ? list.filter((saved) => saved !== item) : [...list, item];3}4 5const favorites = toggle(["Tea", "Cake"], "Tea");6//    ^?7console.log(favorites);

Check your understanding

For each question, ask what T is for that call: filled in from the arguments, or written in angle brackets. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• A type parameter, like <T>, is a name for a type. Each call fills it in, so one function works for every kind of list.
• Using T in a parameter and in the return type connects them: first(prices) gives back number | undefined.
• TypeScript usually fills in T from the arguments. When items differ, T becomes a union.
• Write the type argument yourself, like <string[]>, when the arguments don't say enough, such as an empty list.
• any turns checking off and forgets the type. T keeps the type, so mistakes are still caught.
• Inside the function, only what works for every type is allowed, and T is gone when the code runs.

Coming next: Generic constraints. It shows how to say what T must have, like a length, so you can use it inside the function.