Generics in practice

One fetch helper for every kind of data

A shop page loads its menu from a file on the server, products.json, which holds a tea at 3 and a cake at 4. The browser's fetch asks for the file, and response.json() turns its text into objects (the fetch and async/await lessons cover both). Here is what TypeScript knows about the result:

1async function showMenu() {2  const response = await fetch("products.json");3  const products = await response.json();4  //    ^?5  console.log(products[0].prise);6}7showMenu();

Line 2 asks for the file, and line 3 turns it into objects. The query on line 4 shows const products: any. any means "could be anything, so don't check it" (see any, unknown & never). So line 5 misspells price as prise, TypeScript says nothing, and the code prints undefined.

Every page that loads data has this problem. You could write a type on every fetch call, or write one helper that takes the type as a type argument, the type you put in angle brackets when you call a generic function:

1type Product = { name: string; price: number };2 3async function fetchJson<T>(url: string): Promise<T> {4  const response = await fetch(url);5  return response.json();6}7 8async function showMenu() {9  const products = await fetchJson<Product[]>("products.json");10  //    ^?11  console.log(products[0].prise);12}13showMenu();

Line 1 says what a product is. Lines 3 to 6 are the helper, fetchJson. Its type parameter T stands for "whatever the file holds", and it gives back a Promise<T>, a promise that finishes with a T. Line 9 calls it with <Product[]>, and the query on line 10 shows const products: Product[]. Now line 11 gets an error, on purpose:

• Property 'prise' does not exist on type 'Product'. Did you mean 'price'? means a product has no prise, and price is the closest name it has.

Run it anyway and it still prints undefined: the types are removed before the code runs. But you would have fixed the typo before anyone saw it.

A typed fetchJson<T>

Why does fetch give back any in the first place? Point a query at each step:

1async function loadMenu() {2  const response = await fetch("products.json");3  //    ^?4  const data = response.json();5  //    ^?6  return data;7}8loadMenu().then((data) => console.log(data.length));

The query on line 3 shows const response: Response: TypeScript knows fetch gives back a response. The query on line 5 shows const data: Promise<any>. The browser can't know what a file holds before it arrives, so TypeScript's own description of json() says it gives back a promise of any. Line 8 prints 2, the number of products.

Now read fetchJson from the overview line by line. async function fetchJson<T>(url: string) declares the type parameter T and one ordinary parameter, the address. : Promise<T> says what it gives back. Inside, return response.json() hands over an any, and TypeScript allows any wherever a T goes. So the helper doesn't make the data safer. It moves the any into one place, and every caller gets a named type instead.

Press the buttons to change the type argument on line 9, and watch the query on line 10 and the error list:

1type Product = { name: string; price: number };2 3async function fetchJson<T>(url: string): Promise<T> {4  const response = await fetch(url);5  return response.json();6}7 8async function showMenu() {9  const products = await fetchJson<Product[]>("products.json");10  //    ^?11  const first = products[0];12  console.log(`${first.name} costs $${first.price}`);13}14showMenu();

Product[] is the right answer, and line 12 is fine. Product says "one product", so products[0] on line 11 makes no sense to TypeScript. No type argument gives unknown: T appears in no parameter, so TypeScript has nothing to fill it in from. any switches the checks off again. Look at the console output: it's Tea costs $3 every time. The type argument changes what TypeScript checks, never what the code does.

That cuts both ways. Here the helper is asked for a User while loading the products file:

1type User = { name: string; age: number };2 3async function fetchJson<T>(url: string): Promise<T> {4  const response = await fetch(url);5  return response.json();6}7 8async function showUser() {9  const user = await fetchJson<User>("products.json");10  //    ^?11  console.log(user.age);12}13showUser();

Line 1 describes a user with a name and an age. Line 9 loads products.json but says it holds a User. The query on line 10 shows const user: User, and there are no errors. Line 11 prints undefined, because the file holds a list of products, and a list has no age.

T appears only in the result, Promise<T>, so no argument can disagree with it. A type parameter like that works the same way as as (the Type assertions lesson covers it): you tell TypeScript what the value is, and it believes you. That's fine for data you trust, like your own server. The practical section shows how to check data you don't.

A typed event emitter

A cart sends messages when things happen: "tea was added", "cake was removed". Other parts of the page listen: the badge with the item count, the total, a saved copy. An event emitter lets code listen with on(name, handler) and send with emit(name, payload), where the payload is the data that goes with the message (the Build an event emitter lesson builds one in JavaScript). Here is one typed only with string and any:

1class Emitter {2  private listeners: { name: string; run: (payload: any) => void }[] = [];3 4  on(name: string, handler: (payload: any) => void) {5    this.listeners.push({ name, run: handler });6  }7 8  emit(name: string, payload: any) {9    for (const listener of this.listeners) {10      if (listener.name === name) listener.run(payload);11    }12  }13}14 15const cart = new Emitter();16cart.on("add", (item) => console.log(`Added ${item.name} for $${item.price}`));17cart.emit("add", { name: "Tea", price: 3 });18cart.emit("add", { name: "Cake" });19cart.emit("ad", { name: "Bun", price: 2 });

Line 2 keeps a list of listeners: an event name and the function to run. Line 4's on adds one, and line 8's emit runs every listener with that name. Line 16 listens for "add". Line 17 prints Added Tea for $3. Line 18 forgets the price and prints Added Cake for $undefined. Line 19 misspells the event as "ad", so no listener runs, and nothing prints. TypeScript reports nothing, because any name is a string and any payload is any.

The fix is one type that lists every event and its payload, and a type parameter for the event name. The class takes that list as its own type parameter, Events:

1type CartEvents = {2  add: { name: string; price: number };3  remove: { name: string };4};5 6class Emitter<Events> {7  private listeners: { name: keyof Events; run: (payload: any) => void }[] = [];8 9  on<K extends keyof Events>(name: K, handler: (payload: Events[K]) => void) {10    this.listeners.push({ name, run: handler });11  }12 13  emit<K extends keyof Events>(name: K, payload: Events[K]) {14    for (const listener of this.listeners) {15      if (listener.name === name) listener.run(payload);16    }17  }18}19 20const cart = new Emitter<CartEvents>();21cart.on("add", (item) => console.log(`Added ${item.name} for $${item.price}`));22//              ^?23cart.on("remove", (item) => console.log(`Removed ${item.name}`));24cart.emit("add", { name: "Tea", price: 3 });

Lines 1 to 4 are the event map, CartEvents: each property name is an event, and its type is that event's payload. Line 6 makes the class generic, Emitter<Events>, so the same class works for a cart, a form, or a player. Line 9 is the key line:

• K extends keyof Events: K must be one of the event names, here "add" or "remove" (the Generic constraints lesson covers keyof).
• Events[K]: the type of that property, the payload for that one event. For "add", it's { name: string; price: number }.

Line 13 does the same for emit. Line 7 stores every handler with a payload: any, because one list holds handlers for different events. That any stays inside the class, in a private field (see Access modifiers): code outside only uses on and emit, and those are checked. Line 20 writes the type argument, new Emitter<CartEvents>(), because there's no argument to fill Events in from. The query on line 22 shows that item has a name and a price, and you never wrote its type. Line 24 prints Added Tea for $3.

Now send different events on line 24:

1type CartEvents = {2  add: { name: string; price: number };3  remove: { name: string };4};5 6class Emitter<Events> {7  private listeners: { name: keyof Events; run: (payload: any) => void }[] = [];8 9  on<K extends keyof Events>(name: K, handler: (payload: Events[K]) => void) {10    this.listeners.push({ name, run: handler });11  }12 13  emit<K extends keyof Events>(name: K, payload: Events[K]) {14    for (const listener of this.listeners) {15      if (listener.name === name) listener.run(payload);16    }17  }18}19 20const cart = new Emitter<CartEvents>();21cart.on("add", (item) => console.log(`Added ${item.name} for $${item.price}`));22//              ^?23cart.on("remove", (item) => console.log(`Removed ${item.name}`));24cart.emit("add", { name: "Tea", price: 3 });

The two mistakes from the loose emitter are now errors: Add without a price and Misspell the event. Remove with a price gets an excess property error, because an object written right in the call may only have the properties its type lists (see Excess property checks). In every case the console shows what plain JavaScript would do: a wrong payload still reaches the listener, and a misspelled event is silently lost.

Reading library type signatures

TypeScript describes the browser and JavaScript's built-ins in its own library files, and they're full of generics. When you hover a method in your editor, you see its signature: its name, type parameters, parameters, and what it gives back. Here is map, as TypeScript's lib.es5.d.ts declares it for an array of T:

map<U>(callbackfn: (value: T, index: number, array: T[]) => U, thisArg?: any): U[];

Read it left to right:

1. map<U>: map has a type parameter, U. T isn't declared here: it belongs to the array, and is the type of its items.
2. callbackfn: (value: T, index: number, array: T[]) => U: the first parameter is your callback. It gets an item, its position, and the whole array, and gives back a U.
3. thisArg?: any: an optional second parameter you'll rarely use.
4. : U[]: map gives back a list of whatever your callback gives back.

So the callback decides U. Check it on a call:

1const cart = ["Tea", "Cake"];2const lengths = cart.map((name) => name.length);3//                   ^?4//    ^?5console.log(lengths);

Line 1 makes a cart of names. Line 2 maps each name to its length. The query on line 3 points at map, and shows the signature with everything filled in: T is string, and U is number, because name.length is a number. The query on line 4 asks about lengths on the same line: const lengths: number[]. Line 5 prints [ 3, 4 ].

document.querySelector, which finds the first element matching a CSS selector (see Walking & searching the DOM), has several declarations, called overloads. These two from lib.dom.d.ts matter most:

querySelector<K extends keyof HTMLElementTagNameMap>(selectors: K): HTMLElementTagNameMap[K] | null;
querySelector<E extends Element = Element>(selectors: string): E | null;

1. Line 1 is used when you pass a tag name. HTMLElementTagNameMap is a type that lists every HTML tag with its element type, like input: HTMLInputElement. K extends keyof HTMLElementTagNameMap means K must be one of those tag names, and you get back that tag's element type, or null when nothing matches.
2. Line 2 takes any other string. E extends Element means E must be some kind of element. It also has a default, = Element: when nothing fills in E, it's Element, the most general element type.

1const search = document.querySelector("input");2//    ^?3const total = document.querySelector(".total");4//    ^?5const quantity = document.querySelector<HTMLInputElement>("#quantity");6//    ^?7console.log(quantity?.value);

Line 1 passes the tag name "input", and line 2 shows HTMLInputElement | null. Line 3 passes a class, ".total", which isn't a tag name, so line 4 shows Element | null. Line 5 writes the type argument itself, <HTMLInputElement>, and line 6 shows HTMLInputElement | null. Line 7 prints 2, the value in the page's quantity box. Notice that E appears only in the result, just like T in fetchJson: TypeScript takes your word that #quantity is an input.

Type your own selector, and watch the answer after ^? on line 2:

1const found = document.querySelector("input");2//    ^?

Tag names like button and img give their own element types. #quantity and form input give Element: TypeScript doesn't read CSS, it only checks whether the whole text is a tag name.

Keeping generics simple

Generics are easy to overdo. A good type parameter connects two things: an argument and the result, or two arguments. A type parameter that appears only once connects nothing:

1function logValue<T>(value: T): void {2  console.log(value);3}4 5function logPlain(value: unknown): void {6  console.log(value);7}8 9logValue("Tea");10logPlain("Tea");

Line 1 declares T and uses it once, for value. Line 5 does the same job with value: unknown. Both accept anything, both print Tea on lines 9 and 10, and neither can do more with the value. The second is simpler to read. When you see a type parameter used only once, write unknown or the type you need instead.

Extra type parameters also make a function harder to call:

1function filterBy<T, F extends (item: T) => boolean>(items: T[], test: F): T[] {2  return items.filter(test);3}4 5console.log(filterBy([3, 4, 12], (price) => price < 5));6console.log(filterBy<number>([3, 4, 12], (price: number) => price < 5));

Line 1 gives filterBy two type parameters: T for an item and F for the test function. Line 5 lets TypeScript fill in both, and prints [ 3, 4 ]. Line 6 writes the item type itself, and gets an error on purpose: Expected 2 type arguments, but got 1, meaning "if you write the type arguments, write them all". F is used once, so it only gets in the way:

1function filterBy<T>(items: T[], test: (item: T) => boolean): T[] {2  return items.filter(test);3}4 5console.log(filterBy([3, 4, 12], (price) => price < 5));6console.log(filterBy<number>([3, 4, 12], (price) => price < 5));

Line 1 types the test directly: test: (item: T) => boolean. Line 5 and line 6 now both work, and both print [ 3, 4 ].

The table below sums up the habits. Read each row as: what you wrote, what goes wrong, and what to write instead.

A good way to start: write the function for one type first, like number[]. Add a type parameter only when a second caller needs a different type, and only where it connects an input with an output.

Prices checked as they arrive

A price list comes from another team's server, prices.json, and it sends the prices as text: ["3", "4"]. With fetchJson, you name the type you hope for:

1async function fetchJson<T>(url: string): Promise<T> {2  const response = await fetch(url);3  return response.json();4}5 6async function showTotal() {7  const prices = await fetchJson<number[]>("prices.json");8  console.log(prices[0] + prices[1]);9}10showTotal();

Line 7 says the file holds number[]. There are no errors, but line 8 prints 34: the prices are really text, and + joins text. A better helper takes a second argument, a function that checks the data and gives back the right type:

1async function fetchChecked<T>(url: string, check: (data: unknown) => T): Promise<T> {2  const response = await fetch(url);3  return check(await response.json());4}5 6function toPrices(data: unknown): number[] {7  if (!Array.isArray(data)) throw new Error("Expected a list of prices");8  return data.map((price) => Number(price));9}10 11async function showTotal() {12  const prices = await fetchChecked("prices.json", toPrices);13  //    ^?14  console.log(prices[0] + prices[1]);15}16showTotal();

Line 1 is fetchChecked. Its check parameter is a function that takes the raw data, as unknown, and gives back a T. Line 3 runs it on whatever arrived. Lines 6 to 9 are the check for this file: line 7 stops with an error unless the data is a list (Array.isArray, see Checking types reliably), and line 8 turns every item into a number with Number. Line 12 passes toPrices and no type argument. The query on line 13 shows const prices: number[]: TypeScript filled in T from what toPrices gives back. Line 14 prints 7.

Now T appears twice, in the check and in the result, so it connects something real. The type comes from code that runs while the page runs, not from a claim you wrote.

Library types are full of generics like these. Sort each line by what TypeScript says about it. Each one uses a generic from TypeScript's library: querySelector, map, Map (see Map and Set), or Promise.

Common mix-ups

The biggest mix-up is about who fills in a type parameter, and who checks the value. The table below compares the calls from this lesson. Read each row as: the call, where the type comes from, and who makes sure it's right.

• "fetchJson<Product[]> checks that the file holds products." No. The type argument is a claim you make. Line 11 of the User example printed undefined with no error.
• "I have to write the type argument on every call." No. TypeScript fills it in from the arguments, as in cart.map(…) and fetchChecked(url, toPrices). You write it only when no argument uses it.
• "More type parameters make a function more flexible." No. A type parameter used once connects nothing, and makes callers who write type arguments write more of them.
• "The any inside the emitter makes every call unchecked." No. Callers use on and emit, whose types are exact. The any is hidden inside the class.
• "Library signatures are too hard to read." No. They follow one pattern: the name, the type parameters in angle brackets, the parameters, then what you get back.
• "querySelector reads my CSS selector." No. It only knows whether the whole text is a tag name. "#quantity" and "form input" both give Element.

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. The data files from this lesson come along. Try a guess first, then use the hints.

type CartEvents = {
  add: { name: string; price: number };
  remove: { name: string };
};

class Emitter<Events> {
  on<K extends keyof Events>(name: K, handler: (payload: Events[K]) => void) {}
  emit<K extends keyof Events>(name: K, payload: Events[K]) {}
}

const cart = new Emitter<CartEvents>();
cart.emit("add", { name: "Tea", price: 3 });
cart.emit("remove", { name: "Tea" });
cart.emit("add", { name: "Cake", price: "4" });

1type CartEvents = {2  add: { name: string; price: number };3  remove: { name: string };4};5 6class Emitter<Events> {7  on<K extends keyof Events>(name: K, handler: (payload: Events[K]) => void) {}8  emit<K extends keyof Events>(name: K, payload: Events[K]) {}9}10 11const cart = new Emitter<CartEvents>();12cart.emit("add", { name: "Tea", price: 3 });13cart.emit("remove", { name: "Tea" });14cart.emit("add", { name: "Cake", price: "4" }); // line 14: the price is text

1const prices = ["3", "4"].map((text) => Number(text));2console.log(prices);

1const prices = ["3", "4"].map((text) => Number(text));2//    ^?3console.log(prices);

1type Product = { name: string; price: number };2 3async function fetchJson<T>(url: string): Promise<T> {4  const response = await fetch(url);5  return response.json();6}7 8async function showCake() {9  const products = await fetchJson("products.json");10  //    ^?11  const cake = products[1];12  console.log(`${cake.name} costs $${cake.price}`);13}14showCake();

1type Product = { name: string; price: number };2 3async function fetchJson<T>(url: string): Promise<T> {4  const response = await fetch(url);5  return response.json();6}7 8async function showCake() {9  const products = await fetchJson<Product[]>("products.json");10  //    ^?11  const cake = products[1];12  console.log(`${cake.name} costs $${cake.price}`);13}14showCake();

1type CartEvents = {2  add: { name: string; price: number };3  remove: { name: string };4};5 6class Emitter<Events> {7  private listeners: { name: keyof Events; run: (payload: any) => void }[] = [];8 9  on<K extends keyof Events>(name: K, handler: (payload: Events[K]) => void) {10    this.listeners.push({ name, run: handler });11  }12 13  emit<K extends keyof Events>(name: K, payload: Events[K]) {14    for (const listener of this.listeners) {15      if (listener.name === name) listener.run(payload);16    }17  }18}19 20const cart = new Emitter<CartEvents>();21cart.on("checkout", (order) => console.log(`Paid $${order.total}`));22cart.emit("checkout", { total: 7 });

1type CartEvents = {2  add: { name: string; price: number };3  remove: { name: string };4  checkout: { total: number };5};6 7class Emitter<Events> {8  private listeners: { name: keyof Events; run: (payload: any) => void }[] = [];9 10  on<K extends keyof Events>(name: K, handler: (payload: Events[K]) => void) {11    this.listeners.push({ name, run: handler });12  }13 14  emit<K extends keyof Events>(name: K, payload: Events[K]) {15    for (const listener of this.listeners) {16      if (listener.name === name) listener.run(payload);17    }18  }19}20 21const cart = new Emitter<CartEvents>();22cart.on("checkout", (order) => console.log(`Paid $${order.total}`));23cart.emit("checkout", { total: 7 });

1function filterBy<T, F extends (item: T) => boolean>(items: T[], test: F): T[] {2  return items.filter(test);3}4 5const short = filterBy<string>(["Tea", "Cake", "Bun"], (name: string) => name.length === 3);6console.log(short);

1function filterBy<T>(items: T[], test: (item: T) => boolean): T[] {2  return items.filter(test);3}4 5const short = filterBy<string>(["Tea", "Cake", "Bun"], (name: string) => name.length === 3);6console.log(short);

1async function fetchJson<T>(url: string): Promise<T> {2  const response = await fetch(url);3  return response.json();4}5 6async function showItems() {7  const quantities = await fetchJson<number[]>("quantities.json");8  console.log(quantities[0] + quantities[1]);9}10showItems();

1async function fetchChecked<T>(url: string, check: (data: unknown) => T): Promise<T> {2  const response = await fetch(url);3  return check(await response.json());4}5 6function toNumbers(data: unknown): number[] {7  if (!Array.isArray(data)) throw new Error("Expected a list");8  return data.map((item) => Number(item));9}10 11async function showItems() {12  const quantities = await fetchChecked("quantities.json", toNumbers);13  console.log(quantities[0] + quantities[1]);14}15showItems();

Check your understanding

For each question, ask where each type parameter gets its type: from an argument, or from what someone wrote. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• fetchJson<T> gives every caller a named type instead of any, but the type argument is a claim you make: nothing checks the file.
• A typed event emitter uses an event map, K extends keyof Events for the name, and Events[K] for the payload, so wrong names and payloads are errors.
• Read a signature left to right: type parameters, parameters, result. The arguments you pass usually fill in the type parameters.
• A default like E extends Element = Element is used when nothing fills in E.
• A type parameter should connect two things. If it appears once, use unknown or a plain type.
• For outside data, pass a check function, so the type comes from code that runs, not from a claim you write.

Coming next: keyof & typeof. It looks closely at keyof, which this lesson used for event names, and at typeof, which turns a value into a type.