WIP

Author: drwpow

.changeset/cool-steaks-lay.md

@@ -0,0 +1,5 @@
+---
+"openapi-fetch": minor
+---
+
+Add middleware support

docs/data/contributors.json

@@ -18,17 +18,28 @@ description: openapi-fetch Project Goals, comparisons, and more
 
 ## Differences
 
+### vs. Axios
+
+[Axios](https://axios-http.com) doesn’t automatically typecheck against your OpenAPI schema. Further, there’s no easy way to do that. Axios does have more features than openapi-fetch such as request/responce interception and cancellation.
+
+### vs. tRPC
+
+[tRPC](https://trpc.io/) is meant for projects where both the backend and frontend are written in TypeScript (Node.js). openapi-fetch is universal, and can work with any backend that follows an OpenAPI 3.x schema.
+
 ### vs. openapi-typescript-fetch
 
-This library is identical in purpose to [openapi-typescript-fetch](https://github.com/ajaishankar/openapi-typescript-fetch), but has the following differences:
+[openapi-typescript-fetch](https://github.com/ajaishankar/openapi-typescript-fetch) predates openapi-fetch, and is nearly identical in purpos, but differs mostly in syntax (so it’s more of an opinionated choice):
 
 - This library has a built-in `error` type for `3xx`/`4xx`/`5xx` errors whereas openapi-typescript-fetch throws exceptions (requiring you to wrap things in `try/catch`)
 - This library has a more terse syntax (`get(…)`) wheras openapi-typescript-fetch requires chaining (`.path(…).method(…).create()`)
-- openapi-typescript-fetch supports middleware whereas this library doesn’t
 
 ### vs. openapi-typescript-codegen
 
-This library is quite different from [openapi-typescript-codegen](https://github.com/ferdikoomen/openapi-typescript-codegen)
+[openapi-typescript-codegen](https://github.com/ferdikoomen/openapi-typescript-codegen) is a codegen library, which is fundamentally different from openapi-fetch’s “no codegen” approach. openapi-fetch uses static TypeScript typechecking that all happens at build time with no client weight and no performance hit to runtime. Traditional codegen generates hundreds (if not thousands) of different functions that all take up client weight and slow down runtime.
+
+### vs. Swagger Codegen
+
+Swagger Codegen is the original codegen project for Swagger/OpenAPI, and has the same problems of other codgen approaches of size bloat and runtime performance problems. Further, Swagger Codegen require the Java runtime to work, whereas openapi-typescript/openapi-fetch don’t as native Node.js projects.
 
 ## Contributors
 

docs/openapi-fetch/about.md

@@ -37,6 +37,7 @@ client.get("/my-url", options);
 | `bodySerializer`  | BodySerializer                                                    | (optional) Provide a [bodySerializer](#bodyserializer)                                                                                                                                                                            |
 | `parseAs`         | `"json"` \| `"text"` \| `"arrayBuffer"` \| `"blob"` \| `"stream"` | (optional) Parse the response using [a built-in instance method](https://developer.mozilla.org/en-US/docs/Web/API/Response#instance_methods) (default: `"json"`). `"stream"` skips parsing altogether and returns the raw stream. |
 | `fetch`           | `fetch`                                                           | Fetch instance used for requests (default: fetch from `createClient`)                                                                                                                                                             |
+| `middleware`      | `Middleware[]`                                                    | [See docs](#middleware)                                                                                                                                                                                                           |
 | (Fetch options)   |                                                                   | Any valid fetch option (`headers`, `mode`, `cache`, `signal`, …) ([docs](https://developer.mozilla.org/en-US/docs/Web/API/fetch#options))                                                                                         |
 
 ## querySerializer
@@ -150,3 +151,100 @@ openapi-fetch supports path serialization as [outlined in the 3.1 spec](https://
 | `/users/{.id*}`   | label (exploded)     | `/users/.5`        | `/users/.3.4.5`          | `/users/.role=admin.firstName=Alex`                  |
 | `/users/{;id}`    | matrix               | `/users/;id=5`     | `/users/;id=3,4,5`       | `/users/;id=role,admin,firstName,Alex`               |
 | `/users/{;id*}`   | matrix (exploded)    | `/users/;id=5`     | `/users/;id=3;id=4;id=5` | `/users/;role=admin;firstName=Alex`                  |
+
+## Middleware
+
+As of `0.9.0` this library supports lightweight middleware. Middleware allows you to modify either the request, response, or both for all fetches.
+
+You can declare middleware as an array of functions on [createClient](#create-client). Each middleware function will be **called twice**—once for the request, then again for the response. On request, they’ll be called in array order. On response, they’ll be called in reverse-array order. That way the first middleware gets the first “dibs” on request, and the final control over responses.
+
+Within your middleware function, you’ll either need to check for `req` (request) or `res` (response) to handle each pass appropriately:
+
+```ts
+createClient({
+  middleware: [
+    async function myMiddleware({
+      req, // request (undefined for responses)
+      res, // response (undefined for requests)
+      options, // all options passed to openapi-fetch
+    }) {
+      if (req) {
+        return new Request(req.url, {
+          ...req,
+          headers: { ...req.headers, foo: "bar" },
+        });
+      } else if (res) {
+        return new Response({
+          ...res,
+          status: 200,
+        });
+      }
+    },
+  ],
+});
+```
+
+### Request pass
+
+The request pass of each middleware provides `req` that’s a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) instance, but has 2 additional properties:
+
+| Name         |   Type   | Description                                                      |
+| :----------- | :------: | :--------------------------------------------------------------- |
+| `schemaPath` | `string` | The OpenAPI pathname called (e.g. `/projects/{project_id}`)      |
+| `params`     | `Object` | The [params](#fetch-options) fetch option provided by the client |
+
+### Response pass
+
+The response pass returns a standard [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) instance with no modifications.
+
+### Skipping middleware
+
+If you want to skip the middleware under certain conditions, just `return` as early as possible:
+
+```ts
+async function myMiddleware({ req }) {
+  if (req.schemaPath !== "/projects/{project_id}") {
+    return;
+  }
+
+  // …
+}
+```
+
+This will leave the request/response unmodified, and pass things off to the next middleware handler (if any). There’s no internal callback or observer library needed.
+
+### Handling statefulness
+
+When using middleware, it’s important to remember 2 things:
+
+- **Create new instances** when modifying (e.g. `new Response()`)
+- **Clone bodies** before accessing (e.g. `res.clone().json()`)
+
+This is to account for the fact responses are [stateful](https://developer.mozilla.org/en-US/docs/Web/API/Response/bodyUsed), and if the stream is consumed in middleware [the client will throw an error](https://developer.mozilla.org/en-US/docs/Web/API/Response/clone).
+
+<!-- prettier-ignore -->
+```ts
+async function myMiddleware({ req, res }) {
+  // Example 1: modifying request
+  if (req) {
+    res.headers.foo = "bar"; // [!code --]
+    return new Request(req.url, { // [!code ++]
+      ...req, // [!code ++]
+      headers: { ...req.headers, foo: "bar" }, // [!code ++]
+    }); // [!code ++]
+  }
+
+  // Example 2: accessing response
+  if (res) {
+    const data = await res.json(); // [!code --]
+    const data = await res.clone().json(); // [!code ++]
+  }
+}
+```
+
+### Other notes
+
+- `querySerializer()` runs _before_ middleware
+  - This is to save middleware from having to do annoying URL formatting. But remember middleware can access `req.params`
+- `bodySerializer()` runs _after_ middleware
+  - There is some overlap with `bodySerializer()` and middleware. Probably best to use one or the other; not both together.

docs/openapi-fetch/api.md

@@ -182,6 +182,11 @@ async function main() {
             lastFetch: new Date().getTime(),
           };
           upsert(contributors[repo], userData);
+          // write after every update (so failures are resumable)
+          fs.writeFileSync(
+            new URL("../data/contributors.json", import.meta.url),
+            JSON.stringify(contributors),
+          );
           console.log(`Updated old contributor data for ${username}`); // eslint-disable-line no-console
           fs.writeFileSync(
             new URL("../data/contributors.json", import.meta.url),
@@ -193,10 +198,6 @@ async function main() {
       }
     }),
   );
-  fs.writeFileSync(
-    new URL("../data/contributors.json", import.meta.url),
-    JSON.stringify(contributors),
-  );
 }
 
 main();

docs/scripts/update-contributors.js

@@ -23,6 +23,8 @@ export interface ClientOptions extends Omit<RequestInit, "headers"> {
   querySerializer?: QuerySerializer<unknown> | QuerySerializerOptions;
   /** global bodySerializer */
   bodySerializer?: BodySerializer<unknown>;
+  /** middlewares */
+  middleware?: Middleware[];
   headers?: HeadersOptions;
 }
 
@@ -130,6 +132,43 @@ export type RequestOptions<T> = ParamsOption<T> &
     fetch?: ClientOptions["fetch"];
   };
 
+export type MergedOptions<T = unknown> = {
+  baseUrl: string;
+  parseAs: ParseAs;
+  querySerializer: QuerySerializer<T>;
+  bodySerializer: BodySerializer<T>;
+  fetch: typeof globalThis.fetch;
+};
+
+export type MiddlewareRequestPayload = {
+  type: "request";
+  req: Request & {
+    /** The original OpenAPI schema path (including curly braces) */
+    schemaPath: string;
+    /** OpenAPI parameters as provided from openapi-fetch */
+    params: {
+      query?: Record<string, unknown>;
+      header?: Record<string, unknown>;
+      path?: Record<string, unknown>;
+      cookie?: Record<string, unknown>;
+    };
+  };
+  res?: never;
+  options: readonly MergedOptions;
+};
+export type MiddlewareResponsePayload = {
+  type: "response";
+  req?: never;
+  res: Response;
+  options: readonly MergedOptions;
+};
+export type MiddlewarePayload =
+  | MiddlewareRequestPayload
+  | MiddlewareResponsePayload;
+export type Middleware = (
+  payload: MiddlewarePayload,
+) => Promise<Request | Response | undefined> | Promise<void>;
+
 export type ClientMethod<Paths extends {}, M> = <
   P extends PathsWithMethod<Paths, M>,
   I extends MaybeOptionalInit<Paths[P], M>,

packages/openapi-fetch/src/index.d.ts

@@ -14,6 +14,7 @@ export default function createClient(clientOptions) {
     fetch: baseFetch = globalThis.fetch,
     querySerializer: globalQuerySerializer,
     bodySerializer: globalBodySerializer,
+    middleware,
     ...baseOptions
   } = clientOptions ?? {};
   let baseUrl = baseOptions.baseUrl ?? "";
@@ -27,10 +28,9 @@ export default function createClient(clientOptions) {
    * @param {import('./index.js').FetchOptions<T>} fetchOptions
    */
   async function coreFetch(url, fetchOptions) {
-    const {
+    let {
       fetch = baseFetch,
       headers,
-      body: requestBody,
       params = {},
       parseAs = "json",
       querySerializer: requestQuerySerializer,
@@ -54,37 +54,83 @@ export default function createClient(clientOptions) {
             });
     }
 
-    // URL
-    const finalURL = createFinalURL(url, {
-      baseUrl,
-      params,
-      querySerializer,
-    });
-    const finalHeaders = mergeHeaders(
-      DEFAULT_HEADERS,
-      clientOptions?.headers,
-      headers,
-      params.header,
+    let request = new Request(
+      createFinalURL(url, { baseUrl, params, querySerializer }),
+      {
+        redirect: "follow",
+        ...baseOptions,
+        ...init,
+        headers: mergeHeaders(
+          DEFAULT_HEADERS,
+          clientOptions?.headers,
+          headers,
+          params.header,
+        ),
+      },
     );
 
-    // fetch!
-    /** @type {RequestInit} */
-    const requestInit = {
-      redirect: "follow",
-      ...baseOptions,
-      ...init,
-      headers: finalHeaders,
+    // middleware (request)
+    const mergedOptions = {
+      baseUrl,
+      fetch,
+      parseAs,
+      querySerializer,
+      bodySerializer,
     };
-
-    if (requestBody) {
-      requestInit.body = bodySerializer(requestBody);
+    if (Array.isArray(middleware)) {
+      for (const m of middleware) {
+        const req = new Request(request.url, request);
+        req.schemaPath = url; // (re)attach original URL
+        req.params = params; // (re)attach params
+        const result = await m({
+          type: "request",
+          req,
+          options: Object.freeze({ ...mergedOptions }),
+        });
+        if (result) {
+          if (!(result instanceof Request)) {
+            throw new Error(
+              `Middleware must return new Request() when modifying the request`,
+            );
+          }
+          request = result;
+        }
+      }
     }
+
+    // fetch!
+    // if (init.body) {
+    //   request = new Request(request.url, {
+    //     ...request,
+    //     body: bodySerializer(init.body),
+    //   });
+    // }
     // remove `Content-Type` if serialized body is FormData; browser will correctly set Content-Type & boundary expression
-    if (requestInit.body instanceof FormData) {
-      finalHeaders.delete("Content-Type");
-    }
+    // if (request.body instanceof FormData) {
+    //   request.headers.delete("Content-Type");
+    // }
 
-    const response = await fetch(finalURL, requestInit);
+    let response = await fetch(request);
+
+    // middleware (response)
+    if (Array.isArray(middleware)) {
+      // execute in reverse-array order (first priority gets last transform)
+      for (let i = middleware.length - 1; i >= 0; i--) {
+        const result = await middleware[i]({
+          type: "response",
+          res: response,
+          options: Object.freeze({ ...mergedOptions }),
+        });
+        if (result) {
+          if (!(result instanceof Response)) {
+            throw new Error(
+              `Middleware must return new Response() when modifying the response`,
+            );
+          }
+          response = result;
+        }
+      }
+    }
 
     // handle empty content
     // note: we return `{}` because we want user truthy checks for `.data` or `.error` to succeed