feat: TypedResponseError + expose successStatusCodes/errorStatusCodes

Author: astahmer

.changeset/true-lemons-think.md

@@ -5,7 +5,10 @@
 Add comprehensive type-safe error handling and configurable status codes
 
 - **Type-safe error handling**: Added discriminated unions for API responses with `SafeApiResponse` and `TypedApiResponse` types that distinguish between success and error responses based on HTTP status codes
+- **TypedResponseError class**: Introduced `TypedResponseError` that extends the native Error class to include typed response data for easier error handling
+- Expose `successStatusCodes` and `errorStatusCodes` arrays on the generated API client instance for runtime access
 - **withResponse parameter**: Enhanced API clients to optionally return both the parsed data and the original Response object for advanced use cases
+- **throwOnStatusError option**: Added `throwOnStatusError` option to automatically throw `TypedResponseError` for error status codes, simplifying error handling in async/await patterns, defaulting to `true` (unless `withResponse` is set to true)
 - **TanStack Query integration**: Added complete TanStack Query client generation with:
   - Advanced mutation options supporting `withResponse` and `selectFn` parameters
   - Automatic error type inference based on OpenAPI error schemas instead of generic Error type

packages/typed-openapi/scripts.runtime.json

@@ -349,8 +349,11 @@ export type Endpoint<TConfig extends DefaultEndpoint = DefaultEndpoint> = {
 
 export type Fetcher = (method: Method, url: string, parameters?: EndpointParameters | undefined) => Promise<Response>;
 
-// Status code type for success responses
-export type SuccessStatusCode = ${statusCodeType};
+const successStatusCodes = [${ctx.successStatusCodes.join(",")}];
+type SuccessStatusCode = typeof successStatusCodes[number];
+
+const errorStatusCodes = [${ctx.errorStatusCodes.join(",")}];
+type ErrorStatusCode = typeof errorStatusCodes[number];
 
 // Error handling types
 /** @see https://developer.mozilla.org/en-US/docs/Web/API/Response */
@@ -406,9 +409,23 @@ type MaybeOptionalArg<T> = RequiredKeys<T> extends never ? [config?: T] : [confi
 `;
 
   const apiClient = `
+// <TypedResponseError>
+export class TypedResponseError extends Error {
+  response: ErrorResponse<unknown, ErrorStatusCode>;
+  status: number;
+  constructor(response: ErrorResponse<unknown, ErrorStatusCode>) {
+    super(\`HTTP \${response.status}: \${response.statusText}\`);
+    this.name = 'TypedResponseError';
+    this.response = response;
+    this.status = response.status;
+  }
+}
+// </TypedResponseError>
 // <ApiClient>
 export class ApiClient {
   baseUrl: string = "";
+  successStatusCodes = successStatusCodes;
+  errorStatusCodes = errorStatusCodes;
 
   constructor(public fetcher: Fetcher) {}
 
@@ -437,7 +454,7 @@ export class ApiClient {
       ...params: MaybeOptionalArg<${match(ctx.runtime)
         .with("zod", "yup", () => infer(`TEndpoint["parameters"]`))
         .with("arktype", "io-ts", "typebox", "valibot", () => infer(`TEndpoint`) + `["parameters"]`)
-        .otherwise(() => `TEndpoint["parameters"]`)} & { withResponse?: false }>
+        .otherwise(() => `TEndpoint["parameters"]`)} & { withResponse?: false; throwOnStatusError?: boolean }>
     ): Promise<${match(ctx.runtime)
       .with("zod", "yup", () => infer(`TEndpoint["response"]`))
       .with("arktype", "io-ts", "typebox", "valibot", () => infer(`TEndpoint`) + `["response"]`)
@@ -448,7 +465,7 @@ export class ApiClient {
       ...params: MaybeOptionalArg<${match(ctx.runtime)
         .with("zod", "yup", () => infer(`TEndpoint["parameters"]`))
         .with("arktype", "io-ts", "typebox", "valibot", () => infer(`TEndpoint`) + `["parameters"]`)
-        .otherwise(() => `TEndpoint["parameters"]`)} & { withResponse: true }>
+        .otherwise(() => `TEndpoint["parameters"]`)} & { withResponse: true; throwOnStatusError?: boolean }>
     ): Promise<SafeApiResponse<TEndpoint>>;
 
     ${method}<Path extends keyof ${capitalizedMethod}Endpoints, TEndpoint extends ${capitalizedMethod}Endpoints[Path]>(
@@ -457,27 +474,24 @@ export class ApiClient {
     ): Promise<any> {
       const requestParams = params[0];
       const withResponse = requestParams?.withResponse;
+      const { withResponse: _, throwOnStatusError = withResponse ? false : true, ...fetchParams } = requestParams || {};
+
+      const promise = this.fetcher("${method}", this.baseUrl + path, Object.keys(fetchParams).length ? requestParams : undefined)
+        .then(async (response) => {
+          const data = await this.parseResponse(response);
+          const typedResponse = Object.assign(response, {
+            data: data,
+            json: () => Promise.resolve(data)
+          }) as SafeApiResponse<TEndpoint>;
+
+          if (throwOnStatusError && errorStatusCodes.includes(response.status)) {
+            throw new TypedResponseError(typedResponse as never);
+          }
 
-      const { withResponse: _, ...fetchParams } = requestParams || {};
-
-      if (withResponse) {
-        // Don't count withResponse as params
-        return this.fetcher("${method}", this.baseUrl + path, Object.keys(fetchParams).length ? requestParams : undefined)
-          .then(async (response) => {
-            // Parse the response data
-            const data = await this.parseResponse(response);
-
-            // Override properties while keeping the original Response object
-            const typedResponse = Object.assign(response, {
-              data: data,
-              json: () => Promise.resolve(data)
-            });
-            return typedResponse;
-          });
-      }
+          return withResponse ? typedResponse : data;
+        });
 
-      return this.fetcher("${method}", this.baseUrl + path, requestParams)
-          .then(response => this.parseResponse(response))${match(ctx.runtime)
+        return promise ${match(ctx.runtime)
             .with("zod", "yup", () => `as Promise<${infer(`TEndpoint["response"]`)}>`)
             .with(
               "arktype",
@@ -486,7 +500,7 @@ export class ApiClient {
               "valibot",
               () => `as Promise<${infer(`TEndpoint`) + `["response"]`}>`,
             )
-            .otherwise(() => `as Promise<TEndpoint["response"]>`)};
+            .otherwise(() => `as Promise<TEndpoint["response"]>`)}
     }
     // </ApiClient.${method}>
     `
@@ -518,7 +532,7 @@ export class ApiClient {
         )
         .otherwise(() => `TEndpoint extends { parameters: infer Params } ? Params : never`)}>)
     : Promise<SafeApiResponse<TEndpoint>> {
-      return this.fetcher(method, this.baseUrl + (path as string), params[0] as EndpointParameters);
+      return this.fetcher(method, this.baseUrl + (path as string), params[0] as EndpointParameters) as Promise<SafeApiResponse<TEndpoint>>;
     }
     // </ApiClient.request>
 }

packages/typed-openapi/src/generator.ts

@@ -63,21 +63,12 @@ const fetcher: Fetcher = async (method, apiUrl, params) => {
     });
   }
 
-  const withResponse = params && typeof params === 'object' && 'withResponse' in params && params.withResponse;
   const response = await fetch(url, {
     method: method.toUpperCase(),
     ...(body && { body }),
     headers,
   });
 
-  if (!response.ok && !withResponse) {
-    // You can customize error handling here
-    const error = new Error(`HTTP ${response.status}: ${response.statusText}`);
-    (error as any).response = response;
-    (error as any).status = response.status;
-    throw error;
-  }
-
   return response;
 };
 

packages/typed-openapi/tests/api-client.example.ts

@@ -5,7 +5,7 @@ import { http, HttpResponse } from "msw";
 import { setupServer } from "msw/node";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { api } from "./api-client.example.js";
-import { createApiClient } from "../tmp/generated-client.ts";
+import { createApiClient, TypedResponseError } from "../tmp/generated-client.ts";
 
 // Mock handler for a real endpoint from petstore.yaml
 const mockPets = [
@@ -73,6 +73,11 @@ describe("Example API Client", () => {
     api.baseUrl = "http://localhost";
   });
 
+  it("has access to successStatusCodes and errorStatusCodes", async () => {
+    expect(api.successStatusCodes).toEqual([200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]);
+    expect(api.errorStatusCodes).toEqual([400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 418, 421, 422, 423, 424, 425, 426, 428, 429, 431, 451, 500, 501, 502, 503, 504, 505, 506, 507, 508, 510, 511]);
+  });
+
   it("should fetch /pet/findByStatus and receive mocked pets", async () => {
     const result = await api.get("/pet/findByStatus", { query: {} });
     expect(result).toEqual(mockPets);
@@ -169,21 +174,61 @@ describe("Example API Client", () => {
     });
 
     it("should handle error status codes as error in union (get /pet/findByStatus with error)", async () => {
-      // Simulate error (400) for status=pending
       const errorRes = await api.get("/pet/findByStatus", { query: { status: "pending" }, withResponse: true });
       expect(errorRes.ok).toBe(false);
       expect(errorRes.status).toBe(400);
       expect(errorRes.data).toEqual({ code: 400, message: expect.any(String) });
     });
 
     it("should support configurable status codes (simulate 201)", async () => {
-      // Simulate a 200 response for POST /pet (MSW handler returns 200)
       const res = await api.post("/pet", { body: { name: "Created", photoUrls: [] }, withResponse: true });
       expect([200, 201]).toContain(res.status);
       expect(res.ok).toBe(true);
       if (!res.ok) throw new Error("res.ok is false");
 
       expect(res.data.name).toBe("Created");
     });
+
+    it("should throw when throwOnStatusError is true with withResponse", async () => {
+      let err: unknown;
+      try {
+        await api.get("/pet/{petId}", { path: { petId: 9999 }, withResponse: true, throwOnStatusError: true });
+      } catch (e) {
+        err = e;
+      }
+
+      const error = err as TypedResponseError;
+      expect(error).toBeInstanceOf(TypedResponseError);
+      expect(error.message).toContain("404");
+      expect(error.status).toBe(404);
+      expect(error.response.data).toEqual({ code: 404, message: expect.any(String) });
+      expect(error.response).toBeDefined();
+    });
+
+    it("should not throw when throwOnStatusError is false with withResponse", async () => {
+      const res = await api.get("/pet/{petId}", {
+        path: { petId: 9999 },
+        withResponse: true,
+        throwOnStatusError: false,
+      });
+      expect(res.ok).toBe(false);
+      expect(res.status).toBe(404);
+      expect(res.data).toEqual({ code: 404, message: expect.any(String) });
+    });
+
+    it("should throw by default when withResponse is not set and error status", async () => {
+      let err: unknown;
+      try {
+        await api.get("/pet/{petId}", { path: { petId: 9999 } });
+      } catch (e) {
+        err = e as TypedResponseError;
+      }
+      const error = err as TypedResponseError;
+      expect(error).toBeInstanceOf(TypedResponseError);
+      expect(error.message).toContain("404");
+      expect(error.status).toBe(404);
+      expect(error.response.data).toEqual({ code: 404, message: expect.any(String) });
+      expect(error.response).toBeDefined();
+    });
   });
 });