Every API client starts the same way: fetch(url).then((r) => r.json()), which returns Promise<any>, and a codebase slowly fills with as Order and as Order[] at call sites. Each cast is a small, unreviewed claim about the server. This lesson puts the whole section together to build a client where callers write no casts and no type arguments, and where a wrong route, a missing field or a mistyped id fails to compile.
Start by writing down every endpoint once, as a type:
\ntype OrderStatus = 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'returned';\ntype Order = { id: number; status: OrderStatus; totalCents: number };\ntype CancelledOrder = { id: number; status: 'cancelled'; cancelReason: string };\ntype Page<T> = { items: T[]; nextCursor: string | null };\n\ntype Routes = {\n 'GET /orders/:id': { input: { id: number }; output: Order };\n 'GET /orders': { input: { status?: OrderStatus; cursor?: string }; output: Page<Order> };\n 'POST /orders/:id/cancel': { input: { id: number; reason: string }; output: CancelledOrder };\n};Each key names an endpoint, method and path together. Each value says what the endpoint takes and what it returns. Nothing else in the client will mention Order or Page directly; it will all be derived from this table. Adding an endpoint means adding one line here.
Now the signature. You want the caller to write the route and the input, and get the right response type back:
\nasync function call<R extends keyof Routes>(\n route: R,\n input: Routes[R]['input'],\n): Promise<Routes[R]['output']> {\n // implementation below\n}\n\nconst order = await call('GET /orders/:id', { id: 1042 }); // Order\nconst page = await call('GET /orders', { status: 'shipped' }); // Page<Order>\nawait call('POST /orders/:id/cancel', { id: 1042 });\n// Error: Argument of type '{ id: number; }' is not assignable to parameter\n// of type '{ id: number; reason: string; }'.\n// Property 'reason' is missing in type '{ id: number; }' but required in type …Every idea from this section is at work here. R appears three times, linking the route to the input and the output. Its constraint, keyof Routes, is a union of string literals, so the argument is inferred as the literal 'GET /orders/:id' rather than string. And R has exactly one inference site, route; input only uses R, through the indexed access Routes[R]['input']. TypeScript infers the route, then checks the input against what that route needs. No NoInfer required, because nothing else could contribute a candidate.
Inside call, input has the type Routes[R]['input'] for some unknown R. TypeScript cannot know which fields it has, so building the URL needs a cast. That is fine, as long as it happens in exactly one place:
type Transport = (method: string, path: string, body: unknown) => Promise<unknown>;\n\nfunction createClient(transport: Transport) {\n return async function call<R extends keyof Routes>(\n route: R,\n input: Routes[R]['input'],\n ): Promise<Routes[R]['output']> {\n const [method, template] = route.split(' ');\n // The route map guarantees every :param has a matching input field.\n const values = input as Record<string, unknown>;\n const rest: Record<string, unknown> = { ...values };\n const path = template.replace(/:(\\w+)/g, (_, name: string) => {\n delete rest[name];\n return encodeURIComponent(String(values[name]));\n });\n const result = await transport(method, path, method === 'GET' ? undefined : rest);\n return result as Routes[R]['output'];\n };\n}There are two casts, both commented, both in the one function every request goes through. Callers get a fully checked API, and a reviewer who wants to audit the unsafe parts reads ten lines. Compare that with a codebase where every one of two hundred call sites says as Order.
Injecting the transport is a design choice worth copying. The real app passes a function that calls fetch; tests pass a fake that records requests and returns canned data. The types do not care which.
Real clients have endpoints that take nothing, such as 'GET /me'. With this design you give them input: {} and callers write call('GET /me', {}). That empty object is a small wart, and it is a fair trade for now: the alternative is a signature that makes input optional only for some routes, which needs a conditional type. You will have that tool after Conditional Types, Distribution and infer, and the change will touch only the signature, not a single call site.
The same goes for query strings versus bodies, headers, or per-route error types. Each is one more property on the route-map values and one more lookup in the signature. The shape of the solution stays the same: describe it once in the table, derive it everywhere else.
\nLook at what the caller never has to do: write <Order>, cast, import response types, or remember which endpoints need which fields. The best generic APIs feel like they have no types at all, because every type is inferred from something the caller had to write anyway (here, the route name).
In the exercise you will build this client against a fake transport. That ends the generics section. Section 3 takes apart the type operators you have been borrowing (keyof, indexed access) and adds mapped, conditional and template literal types, so you can derive even more from a single source of truth.
Given call<R extends keyof Routes>(route: R, input: Routes[R]['input']): Promise<Routes[R]['output']>, how is R determined for call('GET /orders/:id', { id: 1042 })?
input object, by matching its shape against every route.","why":"input is typed as Routes[R]['input'], which depends on R; it is checked after R is known, not used to find it."},{"text":"From the route string, which is the literal 'GET /orders/:id' because the constraint is a union of string literals.","why":"Correct. The literal stays literal thanks to the keyof Routes constraint, and the other types are looked up from it."},{"text":"From the declared return type at the call site.","why":"TypeScript can use a contextual return type in some cases, but here the route argument decides everything."}],"answer":1},{"q":"The implementation of call needs to read path parameters from input, whose type is Routes[R]['input']. What is the most reasonable approach?
input: any so the implementation can read anything.","why":"That throws away the checking callers rely on, which is the whole point of the client."},{"text":"Write one overload per route so each implementation is concrete.","why":"That duplicates the route map and has to be updated by hand for every new endpoint."},{"text":"Keep the generic public signature and treat input as Record<string, unknown> inside, with one commented cast.","why":"Correct. The cast is local, reviewed once, and invisible to callers, who keep full checking."}],"answer":2},{"q":"Your client declares 'GET /orders/:id' as returning Order. The server ships a change that renames status to state. What does TypeScript do?
order.status, gets undefined at runtime, and fails somewhere downstream.","why":"Correct. The route map is a promise about the server that TypeScript cannot check. Validate responses at the boundary to catch this early."},{"text":"It reports an error on the call line the next time you build.","why":"TypeScript never sees the server’s response. It only checks your code against the types you declared."},{"text":"It throws a runtime type error inside call.","why":"Types are erased; nothing checks the response at runtime unless you write that check."}],"answer":0},{"q":"Why is it better to type the route as one string like 'POST /orders/:id/cancel' instead of passing method and path as two separate arguments?
POST being paired with a GET-only path."},{"text":"Because fetch requires the method in the URL.","why":"fetch takes the method in its options object. The single key is a typing choice, not a runtime requirement."}],"answer":1}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"type OrderStatus = 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'returned';\ntype Order = { id: number; status: OrderStatus; totalCents: number };\ntype CancelledOrder = { id: number; status: 'cancelled'; cancelReason: string };\ntype PageBuild Cartwheel’s typed call function.
'POST /orders/:id/cancel' to Routes: its input is { id: number; reason: string } and its output is CancelledOrder.call generic over the route name, so its input and its resolved value are looked up from Routes. The type tests show what callers expect: no type arguments, no casts.:param in the path with the matching input value, and send the remaining fields as the body for non-GET requests. call('POST /orders/:id/cancel', { id: 7, reason: 'Late' }) must send POST /orders/7/cancel with the body {"reason":"Late"}.call<R extends keyof Routes>(route: R, input: Routes[R]['input']): Promise<Routes[R]['output']>.","Inside the function, treat input as Record<string, unknown> with one commented cast, and cast the transport’s result to Routes[R]['output'] once.","template.replace(/:(\\w+)/g, (_, name) => …) gives you each parameter name; copy the input with { ...values } and delete the names you used, so what is left is the body."],"explanation":"R has one inference site, the route string, and its constraint keeps it as a literal key. Every other type is an indexed access on Routes, so adding an endpoint is a one-line change to the map and every caller is checked against it. The two casts live inside call, documented, instead of at every call site. Note that the output type is still a claim about the server: the fake transport returns what the map promises, but a real one could not be trusted without validation.
GET /orders/1042","post-body":"The cancel route posts to /orders/7/cancel with only the remaining fields as the body"}},"words":767,"readMinutes":4}