feat: return Response object directly when using withResponse

Improves type-safe API error handling and response access

Refactors API client response typing to unify success and error data under a consistent interface.
Replaces separate error property with direct data access and ensures the Response object retains its methods.
Updates documentation with clearer examples for type-safe error handling and data access patterns.
Facilitates more ergonomic and predictable client usage, especially for error cases.

Author: astahmer

README.md

@@ -93,27 +93,34 @@ const user = await api.get("/users/{id}", {
   path: { id: "123" }
 }); // user is directly typed as User object
 
-// WithResponse: Full response details (for error handling)
+// WithResponse: Full Response object with typed ok/status and data
 const result = await api.get("/users/{id}", {
   path: { id: "123" },
   withResponse: true
 });
 
+// result is the actual Response object with typed ok/status overrides plus data access
 if (result.ok) {
-  // result.data is typed as the success response
-  console.log("User:", result.data.name);
-  // result.status is typed as success status codes (200, 201, etc.)
+  // Access data directly (already parsed)
+  const user = result.data; // Type: User
+  console.log("User:", user.name);
+
+  // Or use json() method for compatibility
+  const userFromJson = await result.json(); // Same as result.data
+  console.log("User from json():", userFromJson.name);
+
+  console.log("Status:", result.status); // Typed as success status codes
+  console.log("Headers:", result.headers); // Access to all Response properties
 } else {
-  // result.error is typed based on documented error responses
+  // Access error data directly
+  const error = result.data; // Type based on status code
   if (result.status === 404) {
-    console.log("User not found:", result.error.message);
+    console.log("User not found:", error.message);
   } else if (result.status === 401) {
-    console.log("Unauthorized:", result.error.details);
+    console.log("Unauthorized:", error.details);
   }
 }
-```
-
-### Success Response Type-Narrowing
+```### Success Response Type-Narrowing
 
 When endpoints have multiple success responses (200, 201, etc.), the type is automatically narrowed based on status:
 

packages/typed-openapi/API_CLIENT_EXAMPLES.md

@@ -151,3 +151,40 @@ if (!response.ok) {
   throw new ApiError(response.status, response.statusText, response);
 }
 ```
+
+## Error Handling with withResponse
+
+For type-safe error handling without exceptions, use the `withResponse: true` option:
+
+```typescript
+// Example with both data access methods
+const result = await api.get("/users/{id}", {
+  path: { id: "123" },
+  withResponse: true
+});
+
+if (result.ok) {
+  // Access data directly (already parsed)
+  const user = result.data; // Type: User
+  console.log("User:", user.name);
+
+  // Or use json() method for compatibility
+  const userFromJson = await result.json(); // Same as result.data
+  console.log("Same user:", userFromJson.name);
+
+  // Access other Response properties
+  console.log("Status:", result.status);
+  console.log("Headers:", result.headers.get("content-type"));
+} else {
+  // Handle errors with proper typing
+  const error = result.data; // Type based on status code
+
+  if (result.status === 404) {
+    console.error("Not found:", error.message);
+  } else if (result.status === 401) {
+    console.error("Unauthorized:", error.details);
+  } else {
+    console.error("Unknown error:", error);
+  }
+}
+```

packages/typed-openapi/src/generator.ts

@@ -343,47 +343,62 @@ export type StatusCode = ${statusCodeType};
 // Error handling types
 export type TypedApiResponse<TSuccess, TAllResponses extends Record<string | number, unknown> = {}> =
   (keyof TAllResponses extends never
-    ? {
+    ? Omit<Response, "ok" | "status" | "json"> & {
         ok: true;
         status: number;
         data: TSuccess;
+        json: () => Promise<TSuccess>;
       }
     : {
         [K in keyof TAllResponses]: K extends string
           ? K extends \`\${infer TStatusCode extends number}\`
             ? TStatusCode extends StatusCode
-              ? {
+              ? Omit<Response, "ok" | "status" | "json"> & {
                   ok: true;
                   status: TStatusCode;
-                  data: TAllResponses[K];
+                  data: TSuccess;
+                  json: () => Promise<TSuccess>;
                 }
-              : {
+              : Omit<Response, "ok" | "status" | "json"> & {
                   ok: false;
                   status: TStatusCode;
-                  error: TAllResponses[K];
+                  data: TAllResponses[K];
+                  json: () => Promise<TAllResponses[K]>;
                 }
             : never
           : K extends number
             ? K extends StatusCode
-              ? {
+              ? Omit<Response, "ok" | "status" | "json"> & {
                   ok: true;
                   status: K;
-                  data: TAllResponses[K];
+                  data: TSuccess;
+                  json: () => Promise<TSuccess>;
                 }
-              : {
+              : Omit<Response, "ok" | "status" | "json"> & {
                   ok: false;
                   status: K;
-                  error: TAllResponses[K];
+                  data: TAllResponses[K];
+                  json: () => Promise<TAllResponses[K]>;
                 }
             : never;
       }[keyof TAllResponses]);
 
 export type SafeApiResponse<TEndpoint> = TEndpoint extends { response: infer TSuccess; responses: infer TResponses }
   ? TResponses extends Record<string, unknown>
     ? TypedApiResponse<TSuccess, TResponses>
-    : { ok: true; status: number; data: TSuccess }
+    : Omit<Response, "ok" | "status" | "json"> & {
+        ok: true;
+        status: number;
+        data: TSuccess;
+        json: () => Promise<TSuccess>;
+      }
   : TEndpoint extends { response: infer TSuccess }
-    ? { ok: true; status: number; data: TSuccess }
+    ? Omit<Response, "ok" | "status" | "json"> & {
+        ok: true;
+        status: number;
+        data: TSuccess;
+        json: () => Promise<TSuccess>;
+      }
     : never;
 
 type RequiredKeys<T> = {
@@ -454,12 +469,17 @@ export class ApiClient {
       if (withResponse) {
         return this.fetcher("${method}", this.baseUrl + path, Object.keys(fetchParams).length ? fetchParams : undefined)
           .then(async (response) => {
+            // Parse the response data
             const data = await this.parseResponse(response);
-            if (response.ok) {
-              return { ok: true, status: response.status, data };
-            } else {
-              return { ok: false, status: response.status, error: data };
-            }
+
+            // Override properties while keeping the original Response object
+            const typedResponse = Object.assign(response, {
+              ok: response.ok,
+              status: response.status,
+              data: data,
+              json: () => Promise.resolve(data)
+            });
+            return typedResponse;
           });
       } else {
         return this.fetcher("${method}", this.baseUrl + path, requestParams)
@@ -530,9 +550,16 @@ export function createApiClient(fetcher: Fetcher, baseUrl?: string) {
  // With error handling
  const result = await api.get("/users/{id}", { path: { id: "123" }, withResponse: true });
  if (result.ok) {
-   console.log(result.data);
+   // Access data directly
+   const user = result.data;
+   console.log(user);
+
+   // Or use the json() method for compatibility
+   const userFromJson = await result.json();
+   console.log(userFromJson);
  } else {
-   console.error(\`Error \${result.status}:\`, result.error);
+   const error = result.data;
+   console.error(\`Error \${result.status}:\`, error);
  }
 */