wip: fix response.error/status inference

Author: astahmer

ERROR_HANDLING.md

@@ -16,7 +16,7 @@ export type get_GetUserById = {
   response: { id: string; name: string };  // Success response (2xx)
   responses: {
     200: { id: string; name: string };     // Success
-    401: { error: string; code: number };  // Unauthorized  
+    401: { error: string; code: number };  // Unauthorized
     404: { message: string };              // Not Found
     500: { error: string };                // Server Error
   };
@@ -68,11 +68,11 @@ const api = createApiClient(fetch);
 
 async function getUser(id: string) {
   const result = await api.getSafe("/users/{id}", { path: { id } });
-  
+
   if (result.ok) {
     return result.data; // Typed as success response
   }
-  
+
   // Handle specific error cases
   switch (result.status) {
     case 401:
@@ -92,13 +92,13 @@ async function getUser(id: string) {
 ```typescript
 async function handleApiCall<T>(apiCall: () => Promise<T>) {
   const result = await apiCall();
-  
+
   if (result.ok) {
     return { success: true, data: result.data };
   }
-  
-  return { 
-    success: false, 
+
+  return {
+    success: false,
     error: {
       status: result.status,
       message: getErrorMessage(result.error),

error-handling-example.ts

@@ -0,0 +1,82 @@
+// Example: How to use the type-safe error handling
+
+// This is what the generated types would look like:
+type GetUserByIdEndpoint = {
+  method: "GET";
+  path: "/users/{id}";
+  requestFormat: "json";
+  parameters: {
+    path: { id: string };
+  };
+  response: { id: string; name: string };
+  responses: {
+    200: { id: string; name: string };
+    401: { error: string; code: number };
+    404: { message: string };
+    500: { error: string };
+  };
+};
+
+// The SafeApiResponse type creates a discriminated union:
+type SafeApiResponse<TEndpoint> = TEndpoint extends { response: infer TSuccess; responses: infer TResponses }
+  ? TResponses extends Record<string, unknown>
+    ? ApiResponse<TSuccess, TResponses>
+    : { ok: true; status: number; data: TSuccess }
+  : TEndpoint extends { response: infer TSuccess }
+    ? { ok: true; status: number; data: TSuccess }
+    : never;
+
+type ApiResponse<TSuccess, TErrors extends Record<string, unknown> = {}> = {
+  ok: true;
+  status: number;
+  data: TSuccess;
+} | {
+  [K in keyof TErrors]: {
+    ok: false;
+    status: K extends string ? (K extends `${number}` ? number : never) : never;
+    error: TErrors[K];
+  }
+}[keyof TErrors];
+
+// Example usage:
+async function handleUserRequest(api: any, userId: string) {
+  // Using the safe method for type-safe error handling
+  const result = await api.getSafe("/users/{id}", { path: { id: userId } });
+
+  if (result.ok) {
+    // TypeScript knows result.data is { id: string; name: string }
+    console.log(`User found: ${result.data.name} (ID: ${result.data.id})`);
+    return result.data;
+  } else {
+    // TypeScript knows this is an error case
+    if (result.status === 401) {
+      // TypeScript knows result.error is { error: string; code: number }
+      console.error(`Authentication failed: ${result.error.error} (Code: ${result.error.code})`);
+      throw new Error("Unauthorized");
+    } else if (result.status === 404) {
+      // TypeScript knows result.error is { message: string }
+      console.error(`User not found: ${result.error.message}`);
+      return null;
+    } else if (result.status === 500) {
+      // TypeScript knows result.error is { error: string }
+      console.error(`Server error: ${result.error.error}`);
+      throw new Error("Server error");
+    }
+  }
+}
+
+// Alternative: Using traditional try/catch with status code checking
+async function handleUserRequestTraditional(api: any, userId: string) {
+  try {
+    // Using the regular method - only gets success response type
+    const user = await api.get("/users/{id}", { path: { id: userId } });
+    console.log(`User found: ${user.name} (ID: ${user.id})`);
+    return user;
+  } catch (error) {
+    // No type safety here - error is unknown
+    console.error("Request failed:", error);
+    throw error;
+  }
+}
+
+export { handleUserRequest, handleUserRequestTraditional };

packages/typed-openapi/src/generator.ts

@@ -316,17 +316,19 @@ export type Endpoint<TConfig extends DefaultEndpoint = DefaultEndpoint> = {
 export type Fetcher = (method: Method, url: string, parameters?: EndpointParameters | undefined) => Promise<Response>;
 
 // Error handling types
-export type ApiResponse<TSuccess, TErrors extends Record<string, unknown> = {}> = {
-  ok: true;
-  status: number;
-  data: TSuccess;
-} | {
-  [K in keyof TErrors]: {
-    ok: false;
-    status: K extends string ? (K extends \`\${number}\` ? number : never) : never;
-    error: TErrors[K];
-  }
-}[keyof TErrors];
+export type ApiResponse<TSuccess, TErrors extends Record<string, unknown> = {}> =
+  | {
+      ok: true;
+      status: number;
+      data: TSuccess;
+    }
+  | {
+      [K in keyof TErrors]: {
+        ok: false;
+        status: K extends \`\${infer StatusCode extends number}\` ? StatusCode : never;
+        error: TErrors[K];
+      };
+    }[keyof TErrors];
 
 export type SafeApiResponse<TEndpoint> = TEndpoint extends { response: infer TSuccess; responses: infer TResponses }
   ? TResponses extends Record<string, unknown>
@@ -382,7 +384,7 @@ export class ApiClient {
       .with("zod", "yup", () => infer(`TEndpoint["response"]`))
       .with("arktype", "io-ts", "typebox", "valibot", () => infer(`TEndpoint`) + `["response"]`)
       .otherwise(() => `TEndpoint["response"]`)}>;
-    
+
     ${method}<Path extends keyof ${capitalizedMethod}Endpoints, TEndpoint extends ${capitalizedMethod}Endpoints[Path]>(
       path: Path,
       options: { withResponse: true },
@@ -391,7 +393,7 @@ export class ApiClient {
         .with("arktype", "io-ts", "typebox", "valibot", () => infer(`TEndpoint`) + `["parameters"]`)
         .otherwise(() => `TEndpoint["parameters"]`)}>
     ): Promise<SafeApiResponse<TEndpoint>>;
-    
+
     ${method}<Path extends keyof ${capitalizedMethod}Endpoints, TEndpoint extends ${capitalizedMethod}Endpoints[Path]>(
       path: Path,
       optionsOrParams?: { withResponse?: boolean } | ${match(ctx.runtime)
@@ -402,7 +404,7 @@ export class ApiClient {
     ): Promise<any> {
       const hasWithResponse = optionsOrParams && typeof optionsOrParams === 'object' && 'withResponse' in optionsOrParams;
       const requestParams = hasWithResponse ? params[0] : optionsOrParams;
-      
+
       if (hasWithResponse && optionsOrParams.withResponse) {
         return this.fetcher("${method}", this.baseUrl + path, requestParams)
           .then(async (response) => {
@@ -472,7 +474,7 @@ export function createApiClient(fetcher: Fetcher, baseUrl?: string) {
  api.get("/users").then((users) => console.log(users));
  api.post("/users", { body: { name: "John" } }).then((user) => console.log(user));
  api.put("/users/:id", { path: { id: 1 }, body: { name: "John" } }).then((user) => console.log(user));
- 
+
  // With error handling
  const result = await api.get("/users/{id}", { withResponse: true }, { path: { id: "123" } });
  if (result.ok) {

packages/typed-openapi/src/map-openapi-endpoints.ts

@@ -125,11 +125,11 @@ export const mapOpenApiEndpoints = (doc: OpenAPIObject) => {
       // Match the first 2xx-3xx response found, or fallback to default one otherwise
       let responseObject: ResponseObject | undefined;
       const allResponses: Record<string, AnyBox> = {};
-      
+
       Object.entries(operation.responses ?? {}).map(([status, responseOrRef]) => {
         const statusCode = Number(status);
         const responseObj = refs.unwrap<ResponseObject>(responseOrRef);
-        
+
         // Collect all responses for error handling
         const content = responseObj?.content;
         if (content) {
@@ -147,13 +147,13 @@ export const mapOpenApiEndpoints = (doc: OpenAPIObject) => {
           // If no content defined, use unknown type
           allResponses[status] = openApiSchemaToTs({ schema: {}, ctx });
         }
-        
+
         // Keep the current logic for the main response (first 2xx-3xx)
         if (statusCode >= 200 && statusCode < 300 && !responseObject) {
           responseObject = responseObj;
         }
       });
-      
+
       if (!responseObject && operation.responses?.default) {
         responseObject = refs.unwrap(operation.responses.default);
         // Also add default to all responses if not already covered
@@ -170,7 +170,7 @@ export const mapOpenApiEndpoints = (doc: OpenAPIObject) => {
           }
         }
       }
-      
+
       // Set the responses collection
       if (Object.keys(allResponses).length > 0) {
         endpoint.responses = allResponses;

packages/typed-openapi/tests/generator.test.ts

@@ -335,7 +335,7 @@ describe("generator", () => {
         | {
             [K in keyof TErrors]: {
               ok: false;
-              status: K extends string ? (K extends \`\${number}\` ? number : never) : never;
+              status: K extends \`\${infer StatusCode extends number}\` ? StatusCode : never;
               error: TErrors[K];
             };
           }[keyof TErrors];
@@ -558,7 +558,7 @@ describe("generator", () => {
        api.get("/users").then((users) => console.log(users));
        api.post("/users", { body: { name: "John" } }).then((user) => console.log(user));
        api.put("/users/:id", { path: { id: 1 }, body: { name: "John" } }).then((user) => console.log(user));
-       
+
        // With error handling
        const result = await api.get("/users/{id}", { withResponse: true }, { path: { id: "123" } });
        if (result.ok) {
@@ -920,7 +920,7 @@ describe("generator", () => {
         | {
             [K in keyof TErrors]: {
               ok: false;
-              status: K extends string ? (K extends \`\${number}\` ? number : never) : never;
+              status: K extends \`\${infer StatusCode extends number}\` ? StatusCode : never;
               error: TErrors[K];
             };
           }[keyof TErrors];
@@ -1032,7 +1032,7 @@ describe("generator", () => {
        api.get("/users").then((users) => console.log(users));
        api.post("/users", { body: { name: "John" } }).then((user) => console.log(user));
        api.put("/users/:id", { path: { id: 1 }, body: { name: "John" } }).then((user) => console.log(user));
-       
+
        // With error handling
        const result = await api.get("/users/{id}", { withResponse: true }, { path: { id: "123" } });
        if (result.ok) {
@@ -1192,7 +1192,7 @@ describe("generator", () => {
         | {
             [K in keyof TErrors]: {
               ok: false;
-              status: K extends string ? (K extends \`\${number}\` ? number : never) : never;
+              status: K extends \`\${infer StatusCode extends number}\` ? StatusCode : never;
               error: TErrors[K];
             };
           }[keyof TErrors];
@@ -1304,7 +1304,7 @@ describe("generator", () => {
        api.get("/users").then((users) => console.log(users));
        api.post("/users", { body: { name: "John" } }).then((user) => console.log(user));
        api.put("/users/:id", { path: { id: 1 }, body: { name: "John" } }).then((user) => console.log(user));
-       
+
        // With error handling
        const result = await api.get("/users/{id}", { withResponse: true }, { path: { id: "123" } });
        if (result.ok) {
@@ -1322,18 +1322,18 @@ describe("generator", () => {
   test("error schemas", async ({ expect }) => {
     const openApiDoc = (await SwaggerParser.parse("./tests/samples/error-schemas.yaml")) as OpenAPIObject;
     const generated = await prettify(generateFile(mapOpenApiEndpoints(openApiDoc)));
-    
+
     // Verify error schemas are generated
     expect(generated).toContain("export type AuthError");
     expect(generated).toContain("export type NotFoundError");
     expect(generated).toContain("export type ValidationError");
     expect(generated).toContain("export type ForbiddenError");
     expect(generated).toContain("export type ServerError");
-    
+
     // Verify error responses are included in endpoint types
     expect(generated).toContain('responses: { 200: Schemas.User; 401: Schemas.AuthError; 404: Schemas.NotFoundError; 500: Schemas.ServerError }');
     expect(generated).toContain('responses: { 201: Schemas.Post; 400: Schemas.ValidationError; 403: Schemas.ForbiddenError }');
-    
+
     // Verify specific error schema structure
     expect(generated).toContain("error: string");
     expect(generated).toContain("code: number");

packages/typed-openapi/tests/map-openapi-endpoints.test.ts

@@ -3117,7 +3117,7 @@ describe("map-openapi-endpoints", () => {
   test("error schemas", async ({ expect }) => {
     const openApiDoc = (await SwaggerParser.parse("./tests/samples/error-schemas.yaml")) as OpenAPIObject;
     const result = mapOpenApiEndpoints(openApiDoc);
-    
+
     // Find the getUserById endpoint
     const getUserEndpoint = result.endpointList.find(e => e.meta.alias === "get_GetUserById");
     expect(getUserEndpoint).toBeDefined();
@@ -3165,7 +3165,7 @@ describe("map-openapi-endpoints", () => {
     // Verify that error schemas are properly resolved
     const authErrorBox = result.refs.getInfosByRef("#/components/schemas/AuthError");
     expect(authErrorBox?.name).toBe("AuthError");
-    
+
     const validationErrorBox = result.refs.getInfosByRef("#/components/schemas/ValidationError");
     expect(validationErrorBox?.name).toBe("ValidationError");
   });

packages/typed-openapi/tests/samples/error-schemas.yaml

@@ -77,7 +77,7 @@ components:
         email:
           type: string
       required: [id, name, email]
-    
+
     Post:
       type: object
       properties:
@@ -90,7 +90,7 @@ components:
         authorId:
           type: string
       required: [id, title, content, authorId]
-    
+
     PostInput:
       type: object
       properties:
@@ -99,7 +99,7 @@ components:
         content:
           type: string
       required: [title, content]
-    
+
     AuthError:
       type: object
       properties:
@@ -110,7 +110,7 @@ components:
         timestamp:
           type: string
       required: [error, code]
-    
+
     NotFoundError:
       type: object
       properties:
@@ -119,7 +119,7 @@ components:
         resource:
           type: string
       required: [message, resource]
-    
+
     ValidationError:
       type: object
       properties:
@@ -130,7 +130,7 @@ components:
         value:
           type: string
       required: [message, field]
-    
+
     ForbiddenError:
       type: object
       properties:
@@ -139,7 +139,7 @@ components:
         reason:
           type: string
       required: [error, reason]
-    
+
     ServerError:
       type: object
       properties:

packages/typed-openapi/tests/snapshots/docker.openapi.client.ts

@@ -2593,7 +2593,7 @@ export type ApiResponse<TSuccess, TErrors extends Record<string, unknown> = {}>
   | {
       [K in keyof TErrors]: {
         ok: false;
-        status: K extends string ? (K extends `${number}` ? number : never) : never;
+        status: K extends `${infer StatusCode extends number}` ? StatusCode : never;
         error: TErrors[K];
       };
     }[keyof TErrors];