Type-safe APIs & routes

One table that types every request

A shop's frontend talks to its server through many addresses, called routes: /products gives the product list, /cart/count gives how many items are in the cart. Each route sends back a different kind of data. This lesson writes all of that down once, in one type, and lets TypeScript check every request against it:

1type Product = { id: string; name: string; price: number };2 3type Routes = {4  "/products": Product[];5  "/cart/count": number;6};7 8const server: Routes = {9  "/products": [{ id: "p-7", name: "Tea", price: 3 }],10  "/cart/count": 2,11};12 13function get<Path extends keyof Routes>(path: Path): Routes[Path] {14  return server[path];15}16 17const products = get("/products");18//    ^?19console.log(products[0].name);20console.log(get("/cart/count"));21console.log(get("/prodcts"));

Lines 3 to 6 are the route table: an object type whose keys are paths and whose values are what each path sends back. Lines 8 to 11 stand in for the server. A real app would ask over the network and wait for a promise; this one answers at once from an object, so you can focus on the types (the practical section adds the waiting).

Lines 13 to 15 are get. It takes a path that must be one of the table's keys, and returns that path's reply. Line 17 asks for /products, and the query on line 18 shows const products: Product[]: TypeScript knows the reply is a list of products, so line 19 can read products[0].name and print Tea. Line 20 prints 2.

Line 21 has a typo, and TypeScript marks it, on purpose: Argument of type '"/prodcts"' is not assignable to parameter of type 'keyof Routes'. In plain words: "that path isn't in the table". Run it anyway, and it prints undefined, the kind of bug you would otherwise find on a broken page.

keyof and indexed access do the work

Nothing in the route table is new. get is built from two type operators you already know. Here they are on their own:

1type Product = { id: string; name: string; price: number };2 3type Routes = {4  "/products": Product[];5  "/cart/count": number;6};7 8function showPath(path: keyof Routes) {9  return path;10}11 12type CountReply = Routes["/cart/count"];13//   ^?14console.log(showPath("/cart/count"));

• keyof Routes on line 8 is the union of the table's keys: "/products" | "/cart/count" (the keyof & typeof lesson covers it). So showPath accepts exactly those two paths, and line 14 prints /cart/count.
• Routes["/cart/count"] on line 12 looks up one value's type, and the query on line 13 shows type CountReply = number (the Indexed access types lesson covers it).

get joins them with a type parameter, Path (the Generic functions lesson covers these). Path extends keyof Routes means "Path must be one of the paths". When you call get("/products"), TypeScript sets Path to "/products", and the return type Routes[Path] becomes Routes["/products"]: Product[].

Now type your own path. Only line 17 changes, and the query on line 18 shows the reply's type:

1type Product = { id: string; name: string; price: number };2 3type Routes = {4  "/products": Product[];5  "/cart/count": number;6};7 8const server: Routes = {9  "/products": [{ id: "p-7", name: "Tea", price: 3 }],10  "/cart/count": 2,11};12 13function get<Path extends keyof Routes>(path: Path): Routes[Path] {14  return server[path];15}16 17const reply = get("/products");18//    ^?19console.log(reply);

Each key gives its own reply type, and anything else is refused. Notice /products/p-7: a perfectly good address for one product, but the table has no such key. You can't write a key for every product ID. The next section fixes that.

Reading params from the path

Servers write routes for one item with a placeholder, like /products/:id. The :id part is a path param: when you make the request, you fill it in, and /products/:id with id set to "p-7" becomes /products/p-7. TypeScript can read the param names out of the path itself, with a conditional type, infer, and a template literal type:

1type ParamNames<Path extends string> =2  Path extends `${string}:${infer Name}/${infer Rest}`3    ? Name | ParamNames<Rest>4    : Path extends `${string}:${infer Name}`5      ? Name6      : never;7 8type One = ParamNames<"/products/:id">;9//   ^?10type Two = ParamNames<"/users/:userId/orders/:orderId">;11//   ^?12type None = ParamNames<"/products">;13//   ^?

Read lines 1 to 6 one branch at a time:

1. Line 2 asks: does Path look like `${string}:${infer Name}/${infer Rest}`? That pattern means "any text, a colon, a name, a slash, then the rest". ${string} matches any text, and infer Name captures the text between the colon and the next slash (the Template literal types and The infer keyword lessons cover both).
2. If it matches, line 3 gives that Name, plus whatever ParamNames finds in the Rest. The type uses itself, so it keeps reading until the path runs out.
3. Line 4 handles a param at the very end, with no slash after it: line 5 gives its name.
4. Line 6: no colon anywhere, so no names: never, the empty union.

The queries show the answers: "id" on line 9, "userId" | "orderId" on line 11, and never on line 13 for a path with no params.

Names alone aren't enough; a request needs an object with a value for each one. A mapped type builds it (the Mapped types lesson covers them), and a small function fills the path in:

1type ParamNames<Path extends string> =2  Path extends `${string}:${infer Name}/${infer Rest}`3    ? Name | ParamNames<Rest>4    : Path extends `${string}:${infer Name}`5      ? Name6      : never;7 8type Params<Path extends string> = { [Name in ParamNames<Path>]: string };9 10function buildPath<Path extends string>(path: Path, params: Params<Path>) {11  return path.replace(/:(\w+)/g, (_, name: string) => params[name as ParamNames<Path>]);12}13 14type OrderParams = Params<"/users/:userId/orders/:orderId">;15//   ^?16console.log(buildPath("/products/:id", { id: "p-7" }));17console.log(buildPath("/users/:userId/orders/:orderId", { userId: "u-1", orderId: "o-42" }));

Line 8 says: for each name in ParamNames<Path>, make a property of that name whose value is a string. Every param is text, because a path is text. The query on line 15 shows the result for the order path: { userId: string; orderId: string; }. For /products, with no names, it's {}.

Lines 10 to 12 are buildPath. Line 11 finds each :name with a regular expression and swaps in that param's value (replace with a function is covered in String methods). The regular expression only finds the names, so as ParamNames<Path> tells TypeScript that name is one of them. Lines 16 and 17 print /products/p-7 and /users/u-1/orders/o-42.

Now try other params. Each button changes the object that line 14 passes:

1type ParamNames<Path extends string> =2  Path extends `${string}:${infer Name}/${infer Rest}`3    ? Name | ParamNames<Rest>4    : Path extends `${string}:${infer Name}`5      ? Name6      : never;7 8type Params<Path extends string> = { [Name in ParamNames<Path>]: string };9 10function buildPath<Path extends string>(path: Path, params: Params<Path>) {11  return path.replace(/:(\w+)/g, (_, name: string) => params[name as ParamNames<Path>]);12}13 14console.log(buildPath("/products/:id", { id: "p-7" }));

Only the exact object fits. A missing name, a misspelled name, a number, or an extra name are all errors, and each one would have sent the request to the wrong address.

Typed queries and request bodies

A route can take more than params. A query is the part after a ? in an address, like ?sort=price&page=2, for options such as sorting. Give each route's entry a query as well as its response, and look both up the same way:

1type GetRoutes = {2  "/products": { query: { sort?: "price" | "name"; page?: number }; response: string[] };3  "/search": { query: { q: string }; response: string[] };4};5 6function urlFor<Path extends keyof GetRoutes>(path: Path, query: GetRoutes[Path]["query"]) {7  const search = new URLSearchParams();8  for (const [key, value] of Object.entries(query)) {9    if (value !== undefined) search.set(key, String(value));10  }11  const text = search.toString();12  return text ? `${path}?${text}` : path;13}14 15console.log(urlFor("/products", { sort: "price", page: 2 }));16console.log(urlFor("/products", {}));17console.log(urlFor("/search", { q: "green tea" }));18console.log(urlFor("/products", { sort: "rating" }));

Lines 1 to 4 describe two routes. /products takes an optional sort, which must be "price" or "name", and an optional page. /search needs a q, the search text. Line 6 types the query parameter as GetRoutes[Path]["query"]: two lookups in a row, first the route, then its query.

Lines 7 to 12 build the address with URLSearchParams, the browser's tool for query text (the URL & URLSearchParams lesson covers it). Lines 15 to 17 print /products?sort=price&page=2, /products, and /search?q=green+tea. Line 18 asks to sort by rating, and TypeScript marks it, on purpose: Type '"rating"' is not assignable to type '"price" | "name" | undefined'. The server doesn't sort by rating, and now the frontend can't ask it to.

Routes that create or change something, like adding to a cart, send a body: data in the request itself, as JSON text. The same table idea gives each one a body and a response:

1type PostRoutes = {2  "/cart/items": { body: { productId: string; quantity: number }; response: { count: number } };3  "/reviews": { body: { productId: string; stars: 1 | 2 | 3 | 4 | 5; text: string }; response: { id: string } };4};5 6function postRequest<Path extends keyof PostRoutes>(path: Path, body: PostRoutes[Path]["body"]) {7  return { method: "POST", url: path, body: JSON.stringify(body) };8}9 10type AddReply = PostRoutes["/cart/items"]["response"];11//   ^?12console.log(postRequest("/cart/items", { productId: "p-7", quantity: 2 }).body);13console.log(postRequest("/reviews", { productId: "p-7", stars: 6, text: "Great" }).body);

Lines 1 to 4 pair each route's request with its response: what you send, and what you get back. Line 6's postRequest takes the body that its route asks for, and line 7 builds the request a client would send. The query on line 11 shows what adding to the cart replies with: { count: number; }. Line 12 prints the body as JSON text. Line 13 gives a review 6 stars, and TypeScript marks it, on purpose: Type '6' is not assignable to type '1 | 2 | 3 | 4 | 5'.

Params, queries, and bodies are easy to confuse. The table below compares them. Read each row as a question, then each one's answer.

Checking responses at the edge

The route table says what the server should send. It can't make the server send it. A reply arrives as text, and JSON.parse gives you unknown data (the Typing fetch & JSON lesson explains why, and how to check it). The table can make sure you check every route, though:

1type Routes = {2  "/cart/count": number;3  "/products/names": string[];4};5 6const parsers: { [Path in keyof Routes]: (data: unknown) => Routes[Path] } = {7  "/cart/count": (data) => {8    if (typeof data !== "number") throw new Error("Expected a number");9    return data;10  },11  "/products/names": (data) => {12    if (!Array.isArray(data) || !data.every((item): item is string => typeof item === "string")) {13      throw new Error("Expected a list of names");14    }15    return data;16  },17};18 19// What the server sent, as text. The count is wrong on purpose.20const replies: Record<keyof Routes, string> = {21  "/cart/count": '"two"',22  "/products/names": '["Tea", "Cake"]',23};24 25function get<Path extends keyof Routes>(path: Path): Routes[Path] {26  const data: unknown = JSON.parse(replies[path]);27  return parsers[path](data);28}29 30const names = get("/products/names");31//    ^?32console.log(names.join(", "));33try {34  console.log(get("/cart/count") + 1);35} catch (error) {36  console.log(error instanceof Error ? error.message : error);37}

Line 6 is a mapped type over the table: for each path, a function that takes unknown data and gives back that path's reply type. A function like this is called a parser: it checks the data and returns it typed, or throws. Lines 7 to 10 check the count is a number. Lines 11 to 16 check the names are a list of text; the item is string in line 12 is a type guard, so every narrows the list to string[].

Lines 20 to 23 are what the server sent, with a mistake: the count is the text "two". Lines 25 to 28 are get: it parses the text, then runs the route's parser on line 27. The query on line 31 shows const names: string[], and line 32 prints Tea, Cake. Line 34 asks for the count, the parser throws, and line 36 prints Expected a number, instead of a wrong total somewhere on the page.

The mapped type also stops you from forgetting a parser. Here a new route is added to the table, and nothing else:

1type Routes = {2  "/cart/count": number;3  "/cart/total": number;4};5 6const parsers: { [Path in keyof Routes]: (data: unknown) => Routes[Path] } = {7  "/cart/count": (data) => {8    if (typeof data !== "number") throw new Error("Expected a number");9    return data;10  },11};

Line 6 is marked, on purpose: Property '"/cart/total"' is missing in type, and the message goes on to list both types in full. In plain words: "the table has a route that parsers doesn't cover". Schema libraries like Zod do the same job: one schema per route checks the data and gives you its type.

Sharing the table with the server

So far, only the frontend reads the table. If the server is written in TypeScript too, both sides can import the same file, so they can't drift apart. Here is a project with three files:

1export type Product = { id: string; name: string; price: number };2 3export type Routes = {4  "/products": Product[];5  "/products/:id": Product;6};7 8type ParamNames<Path> = Path extends `${string}:${infer Name}/${infer Rest}`9  ? Name | ParamNames<Rest>10  : Path extends `${string}:${infer Name}`11    ? Name12    : never;13 14export type Params<Path> = { [Name in ParamNames<Path>]: string };

Lines 3 to 6 are the routes, one with a param. Lines 8 to 14 are ParamNames and Params from before, written without the extends string on Path; the template pattern still only matches strings. The file only holds types, so nothing from it is left when the code runs.

1import type { Params, Product, Routes } from "./api-types";2 3const menu: Product[] = [4  { id: "p-7", name: "Tea", price: 3 },5  { id: "p-9", name: "Cake", price: 4 },6];7 8export const handlers: { [Path in keyof Routes]: (params: Params<Path>) => Routes[Path] } = {9  "/products": () => menu,10  "/products/:id": (params) => {11    const found = menu.find((item) => item.id === params.id);12    if (!found) throw new Error(`No product ${params.id}`);13    return found;14  },15};

Line 1 imports the types with import type, which is removed with the other types (the Modules & type imports lesson covers it). Line 8 is another mapped type: for each route, a handler, the server's function that answers it. Each handler gets that route's params and must return that route's reply. Line 11 can read params.id because the path is /products/:id.

1import type { Params, Routes } from "./api-types";2import { handlers } from "./server";3 4// Stands in for the network: a real client sends a request, and the server runs the handler.5function get<Path extends keyof Routes>(path: Path, params: Params<Path>): Routes[Path] {6  return handlers[path](params);7}8 9const tea = get("/products/:id", { id: "p-7" });10//    ^?11console.log(tea.name);12console.log(get("/products", {}).length);

Lines 5 to 7 are the client's get. In a real app it would send a request over the network; here line 6 calls the server's handler directly, so the example runs without a server. The query on line 10 shows const tea: Product, and lines 11 and 12 print Tea and 2. A real client imports only types from api-types.ts, never the server's code.

Now the server forgets a route:

1import type { Params, Product, Routes } from "./api-types";2 3const menu: Product[] = [{ id: "p-7", name: "Tea", price: 3 }];4 5export const handlers: { [Path in keyof Routes]: (params: Params<Path>) => Routes[Path] } = {6  "/products": () => menu,7};

Line 5 is marked, on purpose: Property '"/products/:id"' is missing in type. The route is in the shared table, so the server must answer it. In the same way, if someone changes price to text in api-types.ts, both the server's menu, which gives numbers as prices, and any client code that uses the price as a number, like tea.price.toFixed(2), get errors.

Writing the table by hand works well for a small API. For bigger ones, tools make it for you. The table below compares the common ones. Read each row as one tool, then where its types come from, and what checks the data.

A product page that loads through the client

Here is everything together, as a real client does it: the requests wait for their replies, params fill the path, and two requests run at the same time. fakeFetch stands in for fetch, so nothing touches the network:

1type Product = { id: string; name: string; price: number };2type Review = { stars: number; text: string };3 4type Routes = {5  "/products/:id": Product;6  "/products/:id/reviews": Review[];7};8 9type ParamNames<Path> = Path extends `${string}:${infer Name}/${infer Rest}`10  ? Name | ParamNames<Rest>11  : Path extends `${string}:${infer Name}`12    ? Name13    : never;14type Params<Path> = { [Name in ParamNames<Path>]: string };15 16// Stands in for fetch: answers from this object instead of a server.17async function fakeFetch(url: string): Promise<string> {18  const replies: Record<string, unknown> = {19    "/products/p-7": { id: "p-7", name: "Tea", price: 3 },20    "/products/p-7/reviews": [{ stars: 5, text: "Lovely" }, { stars: 4, text: "Good" }],21  };22  return JSON.stringify(replies[url]);23}24 25async function get<Path extends keyof Routes>(path: Path, params: Params<Path>): Promise<Routes[Path]> {26  const url = path.replace(/:(\w+)/g, (_, name: string) => params[name as ParamNames<Path>]);27  const data: unknown = JSON.parse(await fakeFetch(url));28  return data as Routes[Path];29}30 31async function showProduct(id: string) {32  const [product, reviews] = await Promise.all([33    get("/products/:id", { id }),34    get("/products/:id/reviews", { id }),35  ]);36  console.log(`${product.name}: $${product.price}, ${reviews.length} reviews`);37}38 39showProduct("p-7");

Lines 4 to 7 are the table: a product, and its reviews. Lines 9 to 14 are ParamNames and Params. Lines 17 to 23 are fakeFetch, which answers with JSON text from an object, after a promise, like fetch.

Lines 25 to 29 are get, now async: it returns a Promise<Routes[Path]> (the Promises & async functions lesson covers this). Line 26 fills the params in, line 27 parses the reply, and line 28 says "trust that it fits" with as. In a real app, line 28 is where the route's parser from "Checking responses at the edge" goes.

Lines 32 to 35 ask for the product and its reviews at once with Promise.all (the Promise combinators lesson covers it). TypeScript knows product is a Product and reviews is a Review[], each from its own path. Line 36 prints Tea: $3, 2 reviews. Point at product or reviews to see their types.

Now sort some calls. Each one is checked after these lines:

1type Product = { id: string; name: string; price: number };2 3type Routes = {4  "/products": Product[];5  "/products/:id": Product;6  "/cart/count": number;7};8 9type ParamNames<Path> = Path extends `${string}:${infer Name}/${infer Rest}`10  ? Name | ParamNames<Rest>11  : Path extends `${string}:${infer Name}`12    ? Name13    : never;14type Params<Path> = { [Name in ParamNames<Path>]: string };15 16declare function get<Path extends keyof Routes>(path: Path, params: Params<Path>): Routes[Path];

Line 16 uses declare function: it describes get's parameters and return type without a body, which is all the checker needs.

Common mix-ups

The biggest mix-up is thinking the table checks the server. It doesn't. Here a reply breaks its promise:

1type Product = { id: string; name: string; price: number };2 3const reply = '{ "id": "p-7", "name": "Tea", "price": "3" }';4const product = JSON.parse(reply) as Product;5console.log(product.price + 1);

Line 3 is the server's reply, with the price as the text "3". Line 4 says it's a Product with as, and TypeScript believes it. Line 5 prints 31: the text "3" joined with 1, not 4. Only a parser catches this.

• "The route table checks what the server sends." No. It describes what should arrive. Parsers or a schema library check what does arrive.
• "/products/p-7 is a key of the table." No. The keys are patterns like /products/:id. You pass the pattern and fill the ID in as a param.
• "Path params and the query are the same thing." No. Params fill the :name parts inside the path; the query comes after the ?.
• "A param like :id can be a number." No. A path is text, so every param is a string. Turn numbers into text first.
• "Sharing types means the client ships the server's code." No. The client uses import type, which is removed before the code runs. Only types cross over.
• "You need a library for type-safe APIs." No. keyof, indexed access, mapped types, and template literal types are enough. Libraries like tRPC and OpenAPI generators make the types for you on bigger APIs.

Practice exercises

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

1type Product = { id: string; name: string; price: number };2 3type Routes = {4  "/products": Product[];5  "/cart/count": number;6};7 8const server: Routes = {9  "/products": [{ id: "p-7", name: "Tea", price: 3 }],10  "/cart/count": 2,11};12 13function get<Path extends keyof Routes>(path: Path): Routes[Path] {14  return server[path];15}16 17const count = get("/cart/count");

1type Product = { id: string; name: string; price: number };2 3type Routes = {4  "/products": Product[];5  "/cart/count": number;6};7 8const server: Routes = {9  "/products": [{ id: "p-7", name: "Tea", price: 3 }],10  "/cart/count": 2,11};12 13function get<Path extends keyof Routes>(path: Path): Routes[Path] {14  return server[path];15}16 17const count = get("/cart/count");18//    ^?

type Product = { id: string; name: string; price: number };

type Routes = {
  "/products": Product[];
  "/cart/count": number;
};

const server: Routes = {
  "/products": [{ id: "p-7", name: "Tea", price: 3 }],
  "/cart/count": 2,
};

function get<Path extends keyof Routes>(path: Path): Routes[Path] {
  return server[path];
}

console.log(get("/products").length);
console.log(get("/cart/cuont"));

1type Product = { id: string; name: string; price: number };2 3type Routes = {4  "/products": Product[];5  "/cart/count": number;6};7 8const server: Routes = {9  "/products": [{ id: "p-7", name: "Tea", price: 3 }],10  "/cart/count": 2,11};12 13function get<Path extends keyof Routes>(path: Path): Routes[Path] {14  return server[path];15}16 17console.log(get("/products").length);18console.log(get("/cart/count"));

1type Routes = {2  "/cart/count": number;3};4 5const server: Routes = {6  "/cart/count": 2,7};8 9function get<Path extends keyof Routes>(path: Path): Routes[Path] {10  return server[path];11}12 13console.log(get("/cart/total"));

1type Routes = {2  "/cart/count": number;3  "/cart/total": number;4};5 6const server: Routes = {7  "/cart/count": 2,8  "/cart/total": 7.5,9};10 11function get<Path extends keyof Routes>(path: Path): Routes[Path] {12  return server[path];13}14 15console.log(get("/cart/total"));

1type ParamNames<Path extends string> =2  Path extends `${string}:${infer Name}/${infer Rest}`3    ? Name | ParamNames<Rest>4    : Path extends `${string}:${infer Name}`5      ? Name6      : never;7 8type Names = ParamNames<"/shops/:shopId/items/:itemId">;

1type ParamNames<Path extends string> =2  Path extends `${string}:${infer Name}/${infer Rest}`3    ? Name | ParamNames<Rest>4    : Path extends `${string}:${infer Name}`5      ? Name6      : never;7 8type Names = ParamNames<"/shops/:shopId/items/:itemId">;9//   ^?

type ParamNames<Path extends string> =
  Path extends `${string}:${infer Name}/${infer Rest}`
    ? Name | ParamNames<Rest>
    : Path extends `${string}:${infer Name}`
      ? Name
      : never;

type Params<Path extends string> = { [Name in ParamNames<Path>]: string };

function buildPath<Path extends string>(path: Path, params: Params<Path>) {
  return path.replace(/:(\w+)/g, (_, name: string) => params[name as ParamNames<Path>]);
}

console.log(buildPath("/users/:userId/orders/:orderId", { userId: "u-1" }));

1type ParamNames<Path extends string> =2  Path extends `${string}:${infer Name}/${infer Rest}`3    ? Name | ParamNames<Rest>4    : Path extends `${string}:${infer Name}`5      ? Name6      : never;7 8type Params<Path extends string> = { [Name in ParamNames<Path>]: string };9 10function buildPath<Path extends string>(path: Path, params: Params<Path>) {11  return path.replace(/:(\w+)/g, (_, name: string) => params[name as ParamNames<Path>]);12}13 14console.log(buildPath("/users/:userId/orders/:orderId", { userId: "u-1", orderId: "o-42" }));

1type Routes = {2  "/cart/count": number;3  "/cart/total": number;4};5 6const parsers: { [Path in keyof Routes]: (data: unknown) => Routes[Path] } = {7  "/cart/count": (data) => {8    if (typeof data !== "number") throw new Error("Expected a number");9    return data;10  },11};12 13console.log(parsers["/cart/total"](JSON.parse("7.5")).toFixed(2));

1type Routes = {2  "/cart/count": number;3  "/cart/total": number;4};5 6const parsers: { [Path in keyof Routes]: (data: unknown) => Routes[Path] } = {7  "/cart/count": (data) => {8    if (typeof data !== "number") throw new Error("Expected a number");9    return data;10  },11  "/cart/total": (data) => {12    if (typeof data !== "number") throw new Error("Expected a number");13    return data;14  },15};16 17console.log(parsers["/cart/total"](JSON.parse("7.5")).toFixed(2));

Check your understanding

For each question, ask two things: what does the table say, and what really arrives when the code runs? The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• A route table is an object type from paths to replies. Path extends keyof Routes checks the path, and Routes[Path] gives the reply's type.
• A template literal type with infer reads :name params out of a path, and a mapped type turns them into a required object of strings.
• Each route's entry can pair its request, a query or a body, with its response.
• The table describes replies; it doesn't check them. A mapped type of parsers makes sure every route has a check.
• A shared types file keeps the server's handlers and the client's calls in agreement. tRPC, OpenAPI generators, and Zod can make the types for you.

Coming next: Variance & assignability. Why a list of dogs isn't always a list of animals, and how TypeScript compares function parameters.