typed error handling

Author: ajaishankar

README.md

@@ -68,6 +68,37 @@ const { status, data: pets } = await findPetsByStatus({
 console.log(pets[0])
 ```
 
+### Typed Error Handling
+
+A non-ok fetch response throws a generic `ApiError`
+
+But an Openapi document can declare a different response type for each status code, or a default error response type
+
+These can be accessed via a `discriminated union` on status, as in code snippet below
+
+```ts
+const findPetsByStatus = fetcher.path('/pet/findByStatus').method('get').create()
+const addPet = fetcher.path('/pet').method('post').create()
+
+try {
+  await findPetsByStatus({ ... })
+  await addPet({ ... })
+} catch(e) {
+  // check which operation threw the exception
+  if (e instanceof addPet.Error) {
+    // get discriminated union { status, data } 
+    const error = e.getActualType()
+    if (error.status === 400) {
+      error.data.validationErrors // only available for a 400 response
+    } else if (error.status === 500) {
+      error.data.errorMessage // only available for a 500 response
+    } else {
+      ...
+    }
+  }
+}
+```
+
 ### Middleware
 
 Middlewares can be used to pre and post process fetch operations (log api calls, add auth headers etc)

package.json

@@ -1,7 +1,7 @@
 {
   "name": "openapi-typescript-fetch",
   "description": "A typed fetch client for openapi-typescript",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "engines": {
     "node": ">= 12.0.0",
     "npm": ">= 7.0.0"

src/fetcher.ts

@@ -7,8 +7,12 @@ import {
   FetchConfig,
   Method,
   Middleware,
+  OpArgType,
   OpenapiPaths,
+  OpErrorType,
   Request,
+  _TypedFetch,
+  TypedFetch,
 } from './types'
 
 const sendBody = (method: Method) =>
@@ -185,6 +189,34 @@ async function fetchUrl<R>(request: Request) {
   return response as ApiResponse<R>
 }
 
+function createFetch<OP>(fetch: _TypedFetch<OP>): TypedFetch<OP> {
+  const fun = async (payload: OpArgType<OP>, init?: RequestInit) => {
+    try {
+      return await fetch(payload, init)
+    } catch (err) {
+      if (err instanceof ApiError) {
+        throw new fun.Error(err)
+      }
+      throw err
+    }
+  }
+
+  fun.Error = class extends ApiError {
+    constructor(error: ApiError) {
+      super(error)
+      Object.setPrototypeOf(this, new.target.prototype)
+    }
+    getActualType() {
+      return {
+        status: this.status,
+        data: this.data,
+      } as OpErrorType<OP>
+    }
+  }
+
+  return fun
+}
+
 function fetcher<Paths>() {
   let baseUrl = ''
   let defaultInit: RequestInit = {}
@@ -201,16 +233,18 @@ function fetcher<Paths>() {
     use: (mw: Middleware) => middlewares.push(mw),
     path: <P extends keyof Paths>(path: P) => ({
       method: <M extends keyof Paths[P]>(method: M) => ({
-        create: ((queryParams?: Record<string, true | 1>) => (payload, init) =>
-          fetchUrl({
-            baseUrl: baseUrl || '',
-            path: path as string,
-            method: method as Method,
-            queryParams: Object.keys(queryParams || {}),
-            payload,
-            init: mergeRequestInit(defaultInit, init),
-            fetch,
-          })) as CreateFetch<M, Paths[P][M]>,
+        create: ((queryParams?: Record<string, true | 1>) =>
+          createFetch((payload, init) =>
+            fetchUrl({
+              baseUrl: baseUrl || '',
+              path: path as string,
+              method: method as Method,
+              queryParams: Object.keys(queryParams || {}),
+              payload,
+              init: mergeRequestInit(defaultInit, init),
+              fetch,
+            }),
+          )) as CreateFetch<M, Paths[P][M]>,
       }),
     }),
   }

src/index.ts

@@ -4,8 +4,10 @@ import type {
   ApiResponse,
   FetchArgType,
   FetchReturnType,
+  FetchErrorType,
   Middleware,
   OpArgType,
+  OpErrorType,
   OpDefaultReturnType,
   OpReturnType,
 } from './types'
@@ -14,10 +16,12 @@ import { ApiError } from './types'
 
 export type {
   OpArgType,
+  OpErrorType,
   OpDefaultReturnType,
   OpReturnType,
   FetchArgType,
   FetchReturnType,
+  FetchErrorType,
   ApiResponse,
   Middleware,
 }

src/types.ts

@@ -29,31 +29,51 @@ export type OpArgType<OP> = OP extends {
   ? P & Q & (B extends Record<string, unknown> ? B[keyof B] : unknown) & RB
   : Record<string, never>
 
-export type OpDefaultReturnType<OP> = OP extends {
-  responses: {
-    default: infer D
-  }
+type OpResponseTypes<OP> = OP extends {
+  responses: infer R
 }
-  ? D extends { schema: infer S }
-    ? S
-    : D extends { content: { 'application/json': infer C } } // openapi 3
-    ? C
-    : D
+  ? {
+      [S in keyof R]: R[S] extends { schema?: infer S } // openapi 2
+        ? S
+        : R[S] extends { content: { 'application/json': infer C } } // openapi 3
+        ? C
+        : S extends 'default'
+        ? R[S]
+        : unknown
+    }
+  : never
+
+type _OpReturnType<T> = 200 extends keyof T
+  ? T[200]
+  : 'default' extends keyof T
+  ? T['default']
   : unknown
 
-export type OpReturnType<OP> = OP extends {
-  responses: {
-    200: {
-      schema?: infer R
-      // openapi 3
-      content?: {
-        'application/json': infer C
-      }
-    }
+export type OpReturnType<OP> = _OpReturnType<OpResponseTypes<OP>>
+
+type _OpDefaultReturnType<T> = 'default' extends keyof T
+  ? T['default']
+  : unknown
+
+export type OpDefaultReturnType<OP> = _OpDefaultReturnType<OpResponseTypes<OP>>
+
+// private symbol to prevent narrowing on "default" error status
+const never: unique symbol = Symbol()
+
+type _OpErrorType<T> = {
+  [S in Exclude<keyof T, 200>]: {
+    status: S extends 'default' ? typeof never : S
+    data: T[S]
   }
-}
-  ? R & C
-  : OpDefaultReturnType<OP>
+}[Exclude<keyof T, 200>]
+
+type Coalesce<T, D> = [T] extends [never] ? D : T
+
+// coalesce default error type to unknown
+export type OpErrorType<OP> = Coalesce<
+  _OpErrorType<OpResponseTypes<OP>>,
+  unknown
+>
 
 export type CustomRequestInit = Omit<RequestInit, 'headers'> & {
   readonly headers: Headers
@@ -64,18 +84,32 @@ export type Fetch = (
   init: CustomRequestInit,
 ) => Promise<ApiResponse>
 
-export type TypedFetch<R, A> = (
-  arg: A,
+export type _TypedFetch<OP> = (
+  arg: OpArgType<OP>,
   init?: RequestInit,
-) => Promise<ApiResponse<R>>
+) => Promise<ApiResponse<OpReturnType<OP>>>
+
+export type TypedFetch<OP> = _TypedFetch<OP> & {
+  Error: new (error: ApiError) => ApiError & {
+    getActualType: () => OpErrorType<OP>
+  }
+}
+
+export type FetchArgType<F> = F extends TypedFetch<infer OP>
+  ? OpArgType<OP>
+  : never
 
-export type FetchArgType<F> = F extends TypedFetch<any, infer A> ? A : never
+export type FetchReturnType<F> = F extends TypedFetch<infer OP>
+  ? OpReturnType<OP>
+  : never
 
-export type FetchReturnType<F> = F extends TypedFetch<infer R, any> ? R : never
+export type FetchErrorType<F> = F extends TypedFetch<infer OP>
+  ? OpErrorType<OP>
+  : never
 
 type _CreateFetch<OP, Q = never> = [Q] extends [never]
-  ? () => TypedFetch<OpReturnType<OP>, OpArgType<OP>>
-  : (query: Q) => TypedFetch<OpReturnType<OP>, OpArgType<OP>>
+  ? () => TypedFetch<OP>
+  : (query: Q) => TypedFetch<OP>
 
 export type CreateFetch<M, OP> = M extends 'post' | 'put' | 'patch' | 'delete'
   ? OP extends { parameters: { query: infer Q } }
@@ -121,7 +155,7 @@ export class ApiError extends Error {
   readonly statusText: string
   readonly data: any
 
-  constructor(response: ApiResponse) {
+  constructor(response: Omit<ApiResponse, 'ok'>) {
     super(response.statusText)
     Object.setPrototypeOf(this, new.target.prototype)
 

test/fetch.test.ts

@@ -85,13 +85,16 @@ describe('fetch', () => {
   })
 
   it('GET /error', async () => {
-    expect.assertions(1)
+    expect.assertions(3)
 
-    const fun = fetcher.path('/error').method('get').create()
+    const fun = fetcher.path('/error/{status}').method('get').create()
 
     try {
-      await fun({})
+      await fun({ status: 400 })
     } catch (err) {
+      expect(err instanceof ApiError).toBe(true)
+      expect(err instanceof fun.Error).toBe(true)
+
       if (err instanceof ApiError) {
         expect(err).toMatchObject({
           status: 400,
@@ -103,25 +106,63 @@ describe('fetch', () => {
   })
 
   it('GET /error (json body)', async () => {
+    const fun = fetcher.path('/error/{status}').method('get').create()
+
+    const errors = {
+      badRequest: false,
+      internalServer: false,
+      other: false,
+    }
+
+    const handleError = (e: any) => {
+      if (e instanceof fun.Error) {
+        const error = e.getActualType()
+        // discriminated union
+        if (error.status === 400) {
+          errors.badRequest = error.data.badRequest
+        } else if (error.status === 500) {
+          errors.internalServer = error.data.internalServer
+        } else {
+          errors.other = error.data.message === 'unknown error'
+        }
+      }
+    }
+
+    for (const status of [400, 500, 503]) {
+      try {
+        await fun({ status, detail: true })
+      } catch (e) {
+        handleError(e)
+      }
+    }
+
+    expect(errors).toEqual({
+      badRequest: true,
+      internalServer: true,
+      other: true,
+    })
+  })
+
+  it('network error', async () => {
     expect.assertions(1)
 
-    const fun = fetcher.path('/error').method('get').create()
+    const fun = fetcher.path('/networkerror').method('get').create()
 
     try {
-      await fun({ detail: true })
+      await fun({})
     } catch (e) {
-      if (e instanceof ApiError) {
-        expect(e).toMatchObject({
-          status: 400,
-          statusText: 'Bad Request',
-          data: {
-            message: 'Really Bad Request',
-          },
-        })
-      }
+      expect(e).not.toBeInstanceOf(ApiError)
     }
   })
 
+  it('operation specific error type', () => {
+    const one = fetcher.path('/query/{a}/{b}').method('get').create()
+    const two = fetcher.path('/body/{id}').method('post').create()
+
+    expect(new one.Error({} as any)).not.toBeInstanceOf(two.Error)
+    expect(new two.Error({} as any)).not.toBeInstanceOf(one.Error)
+  })
+
   it('override init', async () => {
     const fun = fetcher.path('/query/{a}/{b}').method('get').create()