feat: support client["/endpoint"].GET() style calls

Author: gzm0

.changeset/stale-donuts-smoke.md

@@ -0,0 +1,5 @@
+---
+"openapi-fetch": minor
+---
+
+Add support for `client["/endpoint"].GET()` style calls

docs/openapi-fetch/index.md

@@ -169,6 +169,19 @@ const { data, error, response } = await client.GET("/url");
 | `error`    | `5xx`, `4xx`, or `default` response if not OK; otherwise `undefined`                                                        |
 | `response` | [The original Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) which contains `status`, `headers`, etc. |
 
+### Path-property style
+
+Alternatively to passing the path as parameter, you can select it as a property on the client:
+
+```ts
+client["/blogposts/{post_id}"].GET({
+  params: { post_id: "my-post" },
+  query: { version: 2 },
+});
+```
+
+This is strictly equivalent to `.GET("/blogposts/{post_id}", { ... } )`.
+
 ## Support
 
 | Platform       | Support                                                                                                                                            |

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

@@ -156,18 +156,30 @@ export type MaybeOptionalInit<Params extends Record<HttpMethod, {}>, Location ex
   ? FetchOptions<FilterKeys<Params, Location>> | undefined
   : FetchOptions<FilterKeys<Params, Location>>;
 
+// The final init param to accept.
+// - Determines if the param is optional or not.
+// - Performs arbitrary [key: string] addition.
+// Note: the addition It MUST happen after all the inference happens (otherwise TS can’t infer if init is required or not).
+type InitParam<Init> = HasRequiredKeys<Init> extends never
+  ? [(Init & { [key: string]: unknown })?]
+  : [Init & { [key: string]: unknown }];
+
 export type ClientMethod<
   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: HasRequiredKeys<Init> extends never
-    ? [(Init & { [key: string]: unknown })?] // note: the arbitrary [key: string]: addition MUST happen here after all the inference happens (otherwise TS can’t infer if it’s required or not)
-    : [Init & { [key: string]: unknown }]
+  ...init: InitParam<Init>
 ) => Promise<FetchResponse<Paths[Path][Method], Init, Media>>;
 
-export interface Client<Paths extends {}, Media extends MediaType = MediaType> {
+export type ClientForPath<PathInfo extends Record<HttpMethod, {}>, Media extends MediaType> = {
+  [Method in keyof PathInfo as Uppercase<string & Method>]: <Init extends MaybeOptionalInit<PathInfo, Method>>(
+    ...init: InitParam<Init>
+  ) => Promise<FetchResponse<PathInfo[Method], Init, Media>>;
+};
+
+export type Client<Paths extends Record<string, Record<HttpMethod, {}>>, Media extends MediaType = MediaType> = {
   /** Call a GET endpoint */
   GET: ClientMethod<Paths, "get", Media>;
   /** Call a PUT endpoint */
@@ -188,7 +200,9 @@ export interface Client<Paths extends {}, Media extends MediaType = MediaType> {
   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,

packages/openapi-fetch/src/index.js

@@ -176,39 +176,15 @@ export default function createClient(clientOptions) {
     return { error, response };
   }
 
-  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" });
-    },
+  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,
+
     /** Register middleware */
     use(...middleware) {
       for (const m of middleware) {
@@ -231,6 +207,19 @@ export default function createClient(clientOptions) {
       }
     },
   };
+
+  const handler = {
+    get: (coreClient, property) => {
+      if (property in coreClient) {
+        return coreClient[property];
+      }
+
+      // Assume the property is an URL.
+      return Object.fromEntries(methods.map((method) => [method, (init) => coreFetch(property, { ...init, method })]));
+    },
+  };
+
+  return new Proxy(coreClient, handler);
 }
 
 // utils

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

@@ -21,19 +21,6 @@ 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>({
@@ -1843,6 +1830,41 @@ describe("client", () => {
       );
     });
   });
+
+  describe("URL as property style call", () => {
+    it("performs a call without params", async () => {
+      const client = createClient<paths>({ baseUrl });
+      const { getRequest } = useMockRequestHandler({
+        baseUrl,
+        method: "get",
+        path: "/anyMethod",
+      });
+      await client["/anyMethod"].GET();
+      expect(getRequest().method).toBe("GET");
+    });
+
+    it("performs a call with params", async () => {
+      const client = createClient<paths>({ baseUrl });
+      const { getRequestUrl } = useMockRequestHandler({
+        baseUrl,
+        method: "get",
+        path: "/blogposts/:post_id",
+        status: 200,
+        body: { message: "OK" },
+      });
+
+      await client["/blogposts/{post_id}"].GET({
+        // expect error on number instead of string.
+        // @ts-expect-error
+        params: { path: { post_id: 1234 } },
+      });
+
+      await client["/blogposts/{post_id}"].GET({
+        params: { path: { post_id: "1234" } },
+      });
+      expect(getRequestUrl().pathname).toBe("/blogposts/1234");
+    });
+  });
 });
 
 // test that the library behaves as expected inside commonly-used patterns