TypeScript `infer`: Create a Self-Typing Fetch Wrapper

Why it exists

Manually creating a typed function for every API endpoint is repetitive, error-prone, and hard to maintain. If an API contract changes, developers must hunt down and update types in multiple places. A generic fetch wrapper solves this by centralizing the request logic and deriving all types from a single, authoritative API schema, ensuring consistency and reducing boilerplate.

The mental model

Think of a generic fetch wrapper as a "smart" function that acts as a type-safe contract for your entire API. You give it an endpoint path and an HTTP method, and it consults a master type definition (your API schema) to figure out exactly what kind of data it needs for the request and what kind of data it will return. It's not just a function that makes an HTTP request; it's a guarantee that your data flow is correct at compile time.

How it works

The magic lies in TypeScript's conditional types and the infer keyword. First, you define a comprehensive type that maps all API paths and HTTP methods to their specific request parameters and response shapes. Your generic fetch function then accepts the path and method as generic type arguments. Inside the function's type signature, you use a conditional type like Path extends keyof ApiSchema ? ... : never. Within that condition, you use infer to extract the specific types. For example, ApiSchema[Path][Method] extends { response: infer R } ? R : never tells TypeScript: "If the schema for this path and method has a response property, infer its type, and use that as this function's return type."

When to use it

This pattern is ideal when you have a well-defined API schema, especially one that is auto-generated from a specification like OpenAPI or Swagger. It's perfect for front-end applications built with frameworks like React or Vue that consume a backend API and need strong type safety to prevent runtime errors and improve developer experience with autocompletion.

When not to use it

Avoid this for simple apps with only one or two API endpoints; the setup overhead isn't justified. It is also less effective if your API lacks a consistent, machine-readable schema or if your endpoint responses are highly dynamic and unpredictable, as this makes it difficult to define a useful master type to infer from.

One canonical example

Imagine an API schema type, ApiSpec, for a birdwatching app. It defines paths like /birds and /sightings. A generic function apiFetch<Path extends keyof ApiSpec>(path: Path, ...) can be called like apiFetch('/birds', { method: 'GET' }). Because the type system knows Path is '/birds', it can look up ApiSpec['/birds']['GET'] and infer that the response will be an array of Bird objects. If you tried to POST to /birds with the wrong request body, TypeScript would throw a compile-time error.