The throwing middleware implementation available in the documentation is not working

[darkbasic]

Description

The documentation explains how to throw errors instead of returning them:

onResponse({ response }) {
  if (response.error) {
    throw new Error(response.error.message);
  }
}

Unfortunately it seems to be wrong because I get Property 'error' does not exist on type 'Response':

It's not just a matter of bad typings: the error prop just isn't there.

Reproduction

Copy-paste the throwing middleware snippet from the documentation and look for the typing error.

Expected result

The error should be available somewhere if we want to be able to throw it.

Checklist

• I’m willing to open a PR (see CONTRIBUTING.md)

[jo-m]

A better example could be

  onResponse({ response }) {
    if (!response.ok) {
      // Will produce error messages like "404 Not Found".
      throw new Error(`${response.status} ${response.statusText}`)
    }
  }

[drwpow]

Thank you for raising! Would love a small PR to update this

[darkbasic]

@drwpow @jo-m unfortunately this is still not satisfactory because data will remain an union with undefined, forcing you to check if error is not empty even if the error won't happen outside of the catch block:

[jo-m]

I think there is no way to achieve that via a middleware, because that would have to change the type signature of the client object.

So, you'd have to implement a wrapper around the client object which throws, and removes error from the type signature.

[darkbasic]

I agree and I think that the throwingMiddleware should be embedded in the openapi-fetch package, maybe via a configurable flag if you prefer to keep both behaviours.

For sure having to refactor this

await Promise.all(ids.map(async (id) => await apiClient.delete(deleteEndpoint + id)))

into this

await Promise.all(
  ids.map(
    async (zdhcId) =>
      await new Promise<number>((resolve, reject) => {
        client
          .DELETE('/ci/zdhc/{zdhcId}', {
            params: { path: { zdhcId } }
          })
          .then(({ error }) => {
            if (error != null) {
              console.error(error)
              reject(new Error(error.message))
            } else {
              resolve(zdhcId)
            }
          })
          .catch((error) => {
            console.error(error)
            reject(new Error(`Error while deleting zdhc ${zdhcId}`))
          })
      })
  )
)

is not pleasant and I would really love to have a throwing middleware with correct typings.

[jo-m]

1. Again, a middleware cannot do this because it cannot change the type signature.
2. If you want to submit a PR for a wrapper, this is probably a good starting point.

[darkbasic]

Again, a middleware cannot do this because it cannot change the type signature.

That's why I said it should be embedded in the codebase, otherwise you cannot change the type signature.

If you want to submit a PR for a wrapper, this is probably a good starting point.

The point is: will openapi-fetch accept such PR?

[jo-m]

@drwpow Would you accept a contribution like this:

import createClient, {
  Client,
  ClientMethod,
  ClientOptions,
  InitParam,
  MaybeOptionalInit,
  Middleware,
  ParseAsResponse,
} from "openapi-fetch"
import {
  HttpMethod,
  MediaType,
  PathsWithMethod,
  ResponseObjectMap,
  SuccessResponse,
} from "openapi-typescript-helpers"

type SuccessfulFetchResponse<
  T extends Record<string | number, any>,
  Options,
  Media extends MediaType,
> = {
  data: ParseAsResponse<SuccessResponse<ResponseObjectMap<T>, Media>, Options>
  response: Response
}

type ThrowingClientMethod<
  Paths extends Record<string, Record<HttpMethod, {}>>,
  Method extends HttpMethod,
  Media extends MediaType,
> = <
  Path extends PathsWithMethod<Paths, Method>,
  Init extends MaybeOptionalInit<Paths[Path], Method>,
>(
  url: Path,
  ...init: InitParam<Init>
) => Promise<SuccessfulFetchResponse<Paths[Path][Method], Init, Media>>

interface ThrowingClient<Paths extends {}, Media extends MediaType = MediaType> {
  GET: ThrowingClientMethod<Paths, "get", Media>
  PUT: ThrowingClientMethod<Paths, "put", Media>
  POST: ThrowingClientMethod<Paths, "post", Media>
  DELETE: ThrowingClientMethod<Paths, "delete", Media>
  OPTIONS: ThrowingClientMethod<Paths, "options", Media>
  HEAD: ThrowingClientMethod<Paths, "head", Media>
  PATCH: ThrowingClientMethod<Paths, "patch", Media>
  TRACE: ThrowingClientMethod<Paths, "trace", Media>
  use(...middleware: Middleware[]): void
  eject(...middleware: Middleware[]): void
}

export class APIError extends Error {
  public readonly method: HttpMethod
  public readonly response: Response
  public readonly errorPayload: any

  constructor(method: HttpMethod, response: Response, errorPayload: any) {
    super(`${method.toUpperCase()} ${response.url}: ${response.status} ${response.statusText}`)
    this.name = "APIError"
    this.method = method
    this.response = response
    this.errorPayload = errorPayload
  }
}

async function wrap<
  Paths extends Record<string, Record<HttpMethod, {}>>,
  Method extends HttpMethod,
  Media extends MediaType,
  Path extends PathsWithMethod<Paths, Method>,
  Init extends MaybeOptionalInit<Paths[Path], Method>,
>(
  client: Client<Paths, Media>,
  method: Method,
  url: Path,
  ...init: InitParam<Init>
): Promise<SuccessfulFetchResponse<Paths[Path][Method], Init, Media>> {
  const mth = method.toUpperCase() as Uppercase<typeof method>
  const fn = client[mth] as ClientMethod<Paths, typeof method, Media>
  // TODO: find a way to avoid as any.
  // Copied from https://github.com/openapi-ts/openapi-typescript/blob/455b73527c788918d665a3d607e8ac240a4e5e52/packages/openapi-react-query/src/index.ts#L117
  const { data, error, response } = await fn(url, ...(init as any))

  if (error) {
    throw new APIError(method, response, error)
  }

  if (!data) {
    throw new APIError(method, response, "No data and no error received")
  }

  return { data: data!, response }
}

// Like `createClient()` from "openapi-fetch", but the client will additionally
// throw an `APIError` on non-2XX responses.
//
// Usage example with complete error handling:
//
//     import createThrowingClient, { APIError } from "throwingClient"
//     import { paths } from "my-generated-client-package"
//
//     const client = createThrowingClient<paths>({ baseUrl: "/" })
//     try {
//       const { response, data } = await client.POST("/api/v1/auth/signin", {
//         body: {
//           username: "admin",
//           password: "REPLACEME",
//         },
//       })
//       console.log(response.status, data.token)
//     } catch (error: unknown) {
//       if (error instanceof APIError) {
//         console.error("=== APIError ===", error.message, error.errorPayload)
//       } else if (error instanceof Error) {
//         console.error("=== Fetch Error ===", error)
//       } else {
//         console.error("=== Unknown Error ===", error)
//       }
//     }
export default function createThrowingClient<Paths extends {}, Media extends MediaType = MediaType>(
  clientOptions?: ClientOptions,
): ThrowingClient<Paths, Media> {
  const client = createClient<Paths, Media>(clientOptions)

  return {
    GET: (url, ...init) => wrap(client, "get", url, ...init),
    PUT: (url, ...init) => wrap(client, "put", url, ...init),
    POST: (url, ...init) => wrap(client, "post", url, ...init),
    DELETE: (url, ...init) => wrap(client, "delete", url, ...init),
    OPTIONS: (url, ...init) => wrap(client, "options", url, ...init),
    HEAD: (url, ...init) => wrap(client, "head", url, ...init),
    PATCH: (url, ...init) => wrap(client, "patch", url, ...init),
    TRACE: (url, ...init) => wrap(client, "trace", url, ...init),
    use(...middleware: Middleware[]) {
      client.use(...middleware)
    },
    eject(...middleware: Middleware[]) {
      client.eject(...middleware)
    },
  }
}

With example usage:

import createThrowingClient, { APIError } from "throwingClient"
import { paths } from "my-generated-client-package"

const client = createThrowingClient<paths>({ baseUrl: "/" })
try {
  const { response, data } = await client.POST("/api/v1/user/login", {
    body: {
      username: "REPLACEME",
      password: "SUPERSECRET",
    },
  })
  console.log(response.status, data.token)
} catch (error: unknown) {
  if (error instanceof APIError) {
    console.error("=== APIError ===", error.message, error.errorPayload)
  } else if (error instanceof Error) {
    console.error("=== Fetch Error ===", error)
  } else {
    console.error("=== Unknown Error ===", error)
  }
}

This wraps the existing Client, does not break any existing code, and could easily coexist.

[darkbasic]

@jo-m I would make it an option of createClient instead of creating a separate createThrowingClient

[darkbasic]

Also we cannot simply throw a standard Error because we need to provide the additional properties returned by the server with the error response. So we need to create our own Error class and instantiate it.

Edit: nevermind I saw you created an APIError class so that's ok.

[jo-m]

@jo-m I would make it an option of createClient instead of creating a separate createThrowingClient

I do not think this is ergonomic and possible whilst keeping compile time type safety. Can you propose a type signature for createClient() that would work?

---

Also we cannot simply throw a standard Error because we need to provide the additional properties returned by the server with the error response. So we need to create our own Error class and instantiate it.

Yeah, there is APIError, but unfortunately the error property is of type any. I am not a TS/JS expert, but as far as I know, TS does not offer any typing for Errors and try/throw/catch, so there is no way to have some kind of APIError which contains the error response from your oapi spec in a type safe manner. Except if you'd pass in some user-supplied extractor method for the error message on every call, but that's not really in the spirit of this I think.