feat: only-pay-what-you-use alternative

Author: gzm0

docs/openapi-fetch/api.md

@@ -40,6 +40,43 @@ client.GET("/my-url", options);
 | `middleware`      | `Middleware[]`                                                    | [See docs](/openapi-fetch/middleware-auth)                                                                                                                                                                                        |
 | (Fetch options)   |                                                                   | Any valid fetch option (`headers`, `mode`, `cache`, `signal`, …) ([docs](https://developer.mozilla.org/en-US/docs/Web/API/fetch#options))                                                                                         |
 
+## wrapAsPathBasedClient
+
+**wrapAsPathBasedClient** wraps the result of `createClient()` to return a [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)-based client that allows path-indexed calls:
+
+```ts
+const client = createClient<paths>(clientOptions);
+const pathBasedClient = wrapAsPathBasedClient(client);
+
+pathBasedClient["/my-url"].GET(fetchOptions);
+```
+
+The `fetchOptions` are the same than for the base client.
+
+A path based client can lead to better type inference but comes at a runtime cost due to the use of a Proxy.
+
+**createPathBasedClient** is a convenience method combining `createClient` and `wrapAsPathBasedClient` if you only want to use the path based call style:
+
+```ts
+const client = createPathBasedClient<paths>(clientOptions);
+
+client["/my-url"].GET(fetchOptions);
+```
+
+Note that it does not allow you to attach middlewares. If you need middlewares, you need to use the full form:
+
+```ts
+const client = createClient<paths>(clientOptions);
+
+client.use(...);
+
+const pathBasedClient = wrapAsPathBasedClient(client);
+
+client.use(...); // the client reference is shared, so the middlewares will propagate.
+
+pathBasedClient["/my-url"].GET(fetchOptions);
+```
+
 ## querySerializer
 
 OpenAPI supports [different ways of serializing objects and arrays](https://swagger.io/docs/specification/serialization/#query) for parameters (strings, numbers, and booleans—primitives—always behave the same way). By default, this library serializes arrays using `style: "form", explode: true`, and objects using `style: "deepObject", explode: true`, but you can customize that behavior with the `querySerializer` option (either on `createClient()` to control every request, or on individual requests for just one).

docs/openapi-fetch/index.md

@@ -171,16 +171,22 @@ const { data, error, response } = await client.GET("/url");
 
 ### Path-property style
 
-Alternatively to passing the path as parameter, you can select it as a property on the client:
+If you prefer selecting the path as a property, you can create a path based client:
 
 ```ts
+import { createPathBasedClient } from "openapi-fetch";
+import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript
+
+const client = createPathBasedClient<paths>({ baseUrl: "https://myapi.dev/v1" });
+
 client["/blogposts/{post_id}"].GET({
   params: { post_id: "my-post" },
   query: { version: 2 },
 });
 ```
 
-This is strictly equivalent to `.GET("/blogposts/{post_id}", { ... } )`.
+Note that this has performance implications and does not allow to attach middlewares directly.
+See [`wrapAsPathBasedClient`](/openapi-fetch/api#wrapAsPathBasedClient) for more.
 
 ## Support
 

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

@@ -179,7 +179,7 @@ export type ClientForPath<PathInfo extends Record<HttpMethod, {}>, Media extends
   ) => Promise<FetchResponse<PathInfo[Method], Init, Media>>;
 };
 
-export type Client<Paths extends Record<string, Record<HttpMethod, {}>>, Media extends MediaType = MediaType> = {
+export interface Client<Paths extends {}, Media extends MediaType = MediaType> {
   /** Call a GET endpoint */
   GET: ClientMethod<Paths, "get", Media>;
   /** Call a PUT endpoint */
@@ -200,14 +200,27 @@ export type Client<Paths extends Record<string, Record<HttpMethod, {}>>, Media e
   use(...middleware: Middleware[]): void;
   /** Unregister middleware */
   eject(...middleware: Middleware[]): void;
-} & {
-  [Path in keyof Paths]: ClientForPath<Paths[Path], Media>;
-};
+}
 
 export default function createClient<Paths extends {}, Media extends MediaType = MediaType>(
   clientOptions?: ClientOptions,
 ): Client<Paths, Media>;
 
+export type PathBasedClient<
+  Paths extends Record<string, Record<HttpMethod, {}>>,
+  Media extends MediaType = MediaType,
+> = {
+  [Path in keyof Paths]: ClientForPath<Paths[Path], Media>;
+};
+
+export declare function wrapAsPathBasedClient<Paths extends {}, Media extends MediaType = MediaType>(
+  client: Client<Paths, Media>,
+): PathBasedClient<Paths, Media>;
+
+export declare function createPathBasedClient<Paths extends {}, Media extends MediaType = MediaType>(
+  clientOptions?: ClientOptions,
+): PathBasedClient<Paths, Media>;
+
 /** Serialize primitive params to string */
 export declare function serializePrimitiveParam(
   name: string,

packages/openapi-fetch/src/index.js

@@ -176,15 +176,39 @@ export default function createClient(clientOptions) {
     return { error, response };
   }
 
-  const methods = ["GET", "PUT", "POST", "DELETE", "OPTIONS", "HEAD", "PATCH", "TRACE"];
-
-  const methodMembers = Object.fromEntries(
-    methods.map((method) => [method, (url, init) => coreFetch(url, { ...init, method })]),
-  );
-
-  const coreClient = {
-    ...methodMembers,
-
+  return {
+    /** Call a GET endpoint */
+    async GET(url, init) {
+      return coreFetch(url, { ...init, method: "GET" });
+    },
+    /** Call a PUT endpoint */
+    async PUT(url, init) {
+      return coreFetch(url, { ...init, method: "PUT" });
+    },
+    /** Call a POST endpoint */
+    async POST(url, init) {
+      return coreFetch(url, { ...init, method: "POST" });
+    },
+    /** Call a DELETE endpoint */
+    async DELETE(url, init) {
+      return coreFetch(url, { ...init, method: "DELETE" });
+    },
+    /** Call a OPTIONS endpoint */
+    async OPTIONS(url, init) {
+      return coreFetch(url, { ...init, method: "OPTIONS" });
+    },
+    /** Call a HEAD endpoint */
+    async HEAD(url, init) {
+      return coreFetch(url, { ...init, method: "HEAD" });
+    },
+    /** Call a PATCH endpoint */
+    async PATCH(url, init) {
+      return coreFetch(url, { ...init, method: "PATCH" });
+    },
+    /** Call a TRACE endpoint */
+    async TRACE(url, init) {
+      return coreFetch(url, { ...init, method: "TRACE" });
+    },
     /** Register middleware */
     use(...middleware) {
       for (const m of middleware) {
@@ -207,19 +231,60 @@ export default function createClient(clientOptions) {
       }
     },
   };
+}
 
-  const handler = {
-    get: (coreClient, property) => {
-      if (property in coreClient) {
-        return coreClient[property];
-      }
+class UrlCallForwarder {
+  constructor(client, url) {
+    this.client = client;
+    this.url = url;
+  }
 
-      // Assume the property is an URL.
-      return Object.fromEntries(methods.map((method) => [method, (init) => coreFetch(property, { ...init, method })]));
-    },
-  };
+  GET(init) {
+    return this.client.GET(this.url, init);
+  }
+  PUT(init) {
+    return this.client.PUT(this.url, init);
+  }
+  POST(init) {
+    return this.client.POST(this.url, init);
+  }
+  DELETE(init) {
+    return this.client.DELETE(this.url, init);
+  }
+  OPTIONS(init) {
+    return this.client.OPTIONS(this.url, init);
+  }
+  HEAD(init) {
+    return this.client.HEAD(this.url, init);
+  }
+  PATCH(init) {
+    return this.client.PATCH(this.url, init);
+  }
+  TRACE(init) {
+    return this.client.TRACE(this.url, init);
+  }
+}
 
-  return new Proxy(coreClient, handler);
+const clientProxyHandler = {
+  // Assume the property is an URL.
+  get: (coreClient, url) => new UrlCallForwarder(coreClient, url),
+};
+
+/**
+ * Wrap openapi-fetch client to support a path based API.
+ * @type {import("./index.js").wrapAsPathBasedClient}
+ */
+export function wrapAsPathBasedClient(coreClient) {
+  return new Proxy(coreClient, clientProxyHandler);
+}
+
+/**
+ * Convenience method to an openapi-fetch path based client.
+ * Strictly equivalent to `wrapAsPathBasedClient(createClient(...))`.
+ * @type {import("./index.js").createPathBasedClient}
+ */
+export function createPathBasedClient(clientOptions) {
+  return wrapAsPathBasedClient(createClient(clientOptions));
 }
 
 // utils

packages/openapi-fetch/test/index.test.ts

@@ -4,6 +4,7 @@ import createClient, {
   type Middleware,
   type MiddlewareCallbackParams,
   type QuerySerializerOptions,
+  createPathBasedClient,
 } from "../src/index.js";
 import { server, baseUrl, useMockRequestHandler, toAbsoluteURL } from "./fixtures/mock-server.js";
 import type { paths } from "./fixtures/api.js";
@@ -21,6 +22,19 @@ afterEach(() => server.resetHandlers());
 afterAll(() => server.close());
 
 describe("client", () => {
+  it("generates all proper functions", () => {
+    const client = createClient<paths>();
+
+    expect(client).toHaveProperty("GET");
+    expect(client).toHaveProperty("PUT");
+    expect(client).toHaveProperty("POST");
+    expect(client).toHaveProperty("DELETE");
+    expect(client).toHaveProperty("OPTIONS");
+    expect(client).toHaveProperty("HEAD");
+    expect(client).toHaveProperty("PATCH");
+    expect(client).toHaveProperty("TRACE");
+  });
+
   describe("TypeScript checks", () => {
     it("marks data or error as undefined, but never both", async () => {
       const client = createClient<paths>({
@@ -1858,9 +1872,10 @@ describe("client", () => {
     });
   });
 
-  describe("URL as property style call", () => {
+  describe("path based client", () => {
     it("performs a call without params", async () => {
-      const client = createClient<paths>({ baseUrl });
+      const client = createPathBasedClient<paths>({ baseUrl });
+
       const { getRequest } = useMockRequestHandler({
         baseUrl,
         method: "get",
@@ -1871,13 +1886,23 @@ describe("client", () => {
     });
 
     it("performs a call with params", async () => {
-      const client = createClient<paths>({ baseUrl });
+      const client = createPathBasedClient<paths>({ baseUrl });
       const { getRequestUrl } = useMockRequestHandler({
         baseUrl,
         method: "get",
         path: "/blogposts/:post_id",
         status: 200,
-        body: { message: "OK" },
+        body: { title: "Blog post title" },
+      });
+
+      // Wrong method
+      // @ts-expect-error
+      await client["/blogposts/{post_id}"].POST({
+        params: {
+          // Unknown property `path`.
+          // @ts-expect-error
+          path: { post_id: "1234" },
+        },
       });
 
       await client["/blogposts/{post_id}"].GET({
@@ -1886,10 +1911,74 @@ describe("client", () => {
         params: { path: { post_id: 1234 } },
       });
 
-      await client["/blogposts/{post_id}"].GET({
+      const { data, error } = await client["/blogposts/{post_id}"].GET({
         params: { path: { post_id: "1234" } },
       });
+
       expect(getRequestUrl().pathname).toBe("/blogposts/1234");
+
+      // Check typing of data.
+      if (error) {
+        // Fail, but we need the if above for type inference.
+        expect(error).toBeUndefined();
+      } else {
+        // @ts-expect-error
+        data.not_a_blogpost_property;
+        // Check typing of result value.
+        expect(data.title).toBe("Blog post title");
+      }
+    });
+
+    it("performs a POST call", async () => {
+      const client = createPathBasedClient<paths>({ baseUrl });
+      const { getRequest } = useMockRequestHandler({
+        baseUrl,
+        method: "post",
+        path: "/anyMethod",
+      });
+      await client["/anyMethod"].POST();
+      expect(getRequest().method).toBe("POST");
+    });
+
+    it("performs a PUT call with a request body", async () => {
+      const mockData = { status: "success" };
+
+      const client = createPathBasedClient<paths>({ baseUrl });
+      const { getRequestUrl } = useMockRequestHandler({
+        baseUrl,
+        method: "put",
+        path: "/blogposts",
+        status: 201,
+        body: mockData,
+      });
+
+      await client["/blogposts"].PUT({
+        body: {
+          title: "New Post",
+          body: "<p>Best post yet</p>",
+          // Should be a number, not a Date.
+          // @ts-expect-error
+          publish_date: new Date("2023-03-31T12:00:00Z"),
+        },
+      });
+
+      const { data, error, response } = await client["/blogposts"].PUT({
+        body: {
+          title: "New Post",
+          body: "<p>Best post yet</p>",
+          publish_date: new Date("2023-03-31T12:00:00Z").getTime(),
+        },
+      });
+
+      // assert correct URL was called
+      expect(getRequestUrl().pathname).toBe("/blogposts");
+
+      // assert correct data was returned
+      expect(data).toEqual(mockData);
+      expect(response.status).toBe(201);
+
+      // assert error is empty
+      expect(error).toBeUndefined();
     });
   });
 });