typed-openapi

typed-openapi is a tool designed to generate type-safe TypeScript API clients, TypeScript types, and runtime validators directly from an OpenAPI specification document.

It is designed to be flexible regarding how you consume the generated code:

• Types-only: Generate paths, parameters, responses, and endpoint contracts without adding runtime dependencies, allowing you to keep your existing HTTP layer.
• Runtime Validation: Generate validators using your preferred library (Zod, Effect, Valibot, ArkType, TypeBox, or Typia). It uses a 'runtime type sidecar' approach where validator implementations are kept in sibling declaration files to prevent large validator logic from slowing down TypeScript editor inference.
• Client Generation: Generate Fetch-based clients or integrate with other data layers like TanStack Query, Promise, or Effect.
• Specification Filtering: For large API specifications, you can filter the spec to generate a smaller, domain-specific client.

The client supports two response styles for handling API results:

1. Direct data return (default): The method returns the typed data directly. If the response status is an error, it throws a TypedStatusError (which includes the parsed error data).

   const user = await api.get("/users/{id}", { path: { id: "123" } });

2. Union-style response (withResponse: true): The method returns a response object. This prevents throwing and allows you to check result.ok to handle success or error branches manually.

   const result = await api.get("/users/{id}", { path: { id: "123" }, withResponse: true });
   if (result.ok) {
     // result.data is typed as User
   } else {
     // result.data is typed as your error schema for that status
   }

All errors thrown by the client are instances of TypedStatusError and include the parsed error data.

// Direct data return (default)
const user = await api.get("/users/{id}", { path: { id: "123" } });

// Union-style response
const result = await api.get("/users/{id}", { path: { id: "123" }, withResponse: true });
if (result.ok) {
  // result.data is typed as User
} else {
  // result.data is typed as your error schema for that status
}

All errors thrown by TanStack Query mutations follow a consistent structure that extends the native Response object. This ensures that error handling is predictable and integrates well with standard web APIs.

An error object (often referred to as ApiError) includes:

• status: The HTTP status code (e.g., 400, 409, 500), which is properly typed as a union of the error codes defined in your OpenAPI spec.
• data: The typed error response body parsed from the JSON response.
• ok: A boolean indicating if the response was successful.
• headers: The Headers object from the response.
• url: The request URL.

Because they are Response instances, you can use error instanceof Response to verify them at runtime.

interface ApiError<TData = unknown> extends Omit<Response, "status"> {
  status: number; // HTTP status code (400-511) - properly typed
  data: TData; // Typed error response body
  // All other Response properties are available:
  // ok: boolean
  // headers: Headers
  // url: string
  // etc.
}

Using the --default-fetcher flag generates a second TypeScript file that acts as the transport layer.

Key behaviors:

• Parameter Handling: It replaces path parameters, serializes query parameters, and adds OpenAPI cookie/header parameters before execution.
• Body Encoding: It encodes POST/PUT/PATCH/DELETE bodies based on the requestFormat contract.
• Overrides: It forwards request overrides and returns a native Response object.
• Client Parsing: The generated API client is responsible for parsing the returned Response.
• Initialization: It exports createApi(baseUrl), allowing browser applications to provide a bundler-specific URL without modifying generated code.
• Base URL: It reads globalThis.process?.env?.API_BASE_URL by default, falling back to https://api.example.com.
• Authentication: If the OpenAPI spec defines securitySchemes, you must call configureFetcher({ getAuth }) before making the first request. The fetcher selects only the first satisfied security requirement and will not send credentials to operations that declare no security requirements.

By default, runtime clients in typed-openapi generate a sibling .types.d.ts file (a "sidecar"). This sidecar contains the public schema aliases and API-client route types.

To optimize TypeScript performance, the generated runtime module uses // @ts-nocheck to skip semantic checking of the large validator implementation. This ensures that while the runtime validation logic executes normally, TypeScript does not waste time checking the internal expressions of the validator. Consumers still benefit from strict type safety because they consume types from the .types.d.ts sidecar, not the unchecked runtime module.

Important Requirements:

• File Proximity: You must keep the generated .types.d.ts file alongside its corresponding runtime module when copying or publishing generated output.
• TypeScript Configuration: For optimal performance, ensure skipLibCheck is enabled in your tsconfig.json. Without it, TypeScript will attempt to type-check the large declaration sidecar, negating the performance benefits.