chore: improve interceptors

Author: mrlubos

docs/.vitepress/config/en.ts

@@ -77,7 +77,7 @@ export default defineConfig({
               },
               {
                 link: '/openapi-ts/clients/nuxt',
-                text: 'Nuxt <span data-soon>soon</span>',
+                text: 'Nuxt',
               },
               {
                 link: '/openapi-ts/clients/legacy',

docs/.vitepress/theme/Layout.vue

@@ -29,7 +29,7 @@ const { Layout } = DefaultTheme;
   background-color: var(--vp-c-bg);
   border-bottom: 1px solid var(--vp-c-divider);
   color: var(--vp-c-text-1);
-  column-gap: 1.5rem;
+  column-gap: 0.5rem;
   display: flex;
   font-size: var(--announcement-font-size);
   height: var(--announcement-height);

docs/openapi-ts/clients.md

@@ -28,7 +28,7 @@ Hey API natively supports the following clients.
 - [Fetch API](/openapi-ts/clients/fetch)
 - [Axios](/openapi-ts/clients/axios)
 - [Next.js](/openapi-ts/clients/next-js) <span data-soon>Soon</span>
-- [Nuxt](/openapi-ts/clients/nuxt) <span data-soon>Soon</span>
+- [Nuxt](/openapi-ts/clients/nuxt)
 - [Legacy](/openapi-ts/clients/legacy)
 
 Don't see your client? Let us know your interest by [opening an issue](https://github.com/hey-api/openapi-ts/issues).

docs/openapi-ts/clients/next-js.md

@@ -1,5 +1,5 @@
 ---
-title: Next.js
+title: Next.js client
 description: Next.js client for Hey API. Compatible with all our features.
 ---
 

docs/openapi-ts/clients/nuxt.md

@@ -1,14 +1,215 @@
 ---
-title: Nuxt
+title: Nuxt client
 description: Nuxt client for Hey API. Compatible with all our features.
 ---
 
-# Nuxt <span data-soon>soon</span>
+# Nuxt
 
 ::: warning
-This feature isn't in development yet. Help us prioritize it by voting on [GitHub](https://github.com/hey-api/openapi-ts/issues/998).
+Nuxt client is currently in beta. The interface might change before it becomes stable. We encourage you to leave feedback on [GitHub](https://github.com/hey-api/openapi-ts/issues).
 :::
 
 [Nuxt](https://nuxt.com/) is an open source framework that makes web development intuitive and powerful.
 
+## Installation
+
+Start by adding `@hey-api/client-nuxt` to your dependencies.
+
+::: code-group
+
+```sh [npm]
+npm install @hey-api/client-nuxt
+```
+
+```sh [pnpm]
+pnpm add @hey-api/client-nuxt
+```
+
+```sh [yarn]
+yarn add @hey-api/client-nuxt
+```
+
+```sh [bun]
+bun add @hey-api/client-nuxt
+```
+
+:::
+
+In your [configuration](/openapi-ts/get-started), set `client` to `@hey-api/client-nuxt` and you'll be ready to use the Nuxt client. :tada:
+
+::: code-group
+
+```js [config]
+export default {
+  client: '@hey-api/client-nuxt', // [!code ++]
+  input: 'path/to/openapi.json',
+  output: 'src/client',
+};
+```
+
+```sh [cli]
+npx @hey-api/openapi-ts \
+  -c @hey-api/client-nuxt \  # [!code ++]
+  -i path/to/openapi.json \
+  -o src/client
+```
+
+:::
+
+## Configuration
+
+If you're using SDKs, you will want to configure the internal client instance. You can do that with the `setConfig()` method. Call it at the beginning of your application.
+
+```js
+import { client } from 'client/sdk.gen';
+
+client.setConfig({
+  baseURL: 'https://example.com',
+});
+```
+
+If you aren't using SDKs, you can create your own client instance.
+
+```js
+import { createClient } from '@hey-api/client-nuxt';
+
+const client = createClient({
+  baseURL: 'https://example.com',
+});
+```
+
+## Interceptors
+
+Interceptors (middleware) can be used to modify requests before they're sent or responses before they're returned to your application. Nuxt provides interceptors through ofetch, please refer to their documentation on [$fetch](https://nuxt.com/docs/api/utils/dollarfetch).
+
+You can pass any Nuxt/ofetch arguments to the client instance.
+
+```js
+import { client } from 'client/sdk.gen';
+
+const result = await client.get({
+  composable: '$fetch',
+  onRequest: (context) => {
+    // do something
+  },
+  url: '/foo',
+});
+```
+
+## Customization
+
+The Nuxt client is built as a thin wrapper on top of Nuxt, extending its functionality to work with Hey API. If you're already familiar with Nuxt, customizing your client will feel like working directly with Nuxt. You can customize requests in three ways – through SDKs, per client, or per request.
+
+### SDKs
+
+This is the most common requirement. The generated SDKs consume an internal client instance, so you will want to configure that.
+
+```js
+import { client } from 'client/sdk.gen';
+
+client.setConfig({
+  baseURL: 'https://example.com',
+});
+```
+
+You can pass any Nuxt configuration option to `setConfig()`, and even your own `$fetch` implementation.
+
+### Client
+
+If you need to create a client pointing to a different domain, you can create your own client instance.
+
+```js
+import { createClient } from '@hey-api/client-nuxt';
+
+const myClient = createClient({
+  baseURL: 'https://example.com',
+});
+```
+
+You can then pass this instance to any SDK function through the `client` option. This will override the internal instance.
+
+```js
+const response = await getFoo({
+  client: myClient,
+});
+```
+
+### Request
+
+Alternatively, you can pass the Nuxt configuration options to each SDK function. This is useful if you don't want to create a client instance for one-off use cases.
+
+```js
+const response = await getFoo({
+  baseURL: 'https://example.com', // <-- override internal configuration
+});
+```
+
+## Auth
+
+The SDKs include auth mechanisms for every endpoint. You will want to configure the `auth` field to pass the right token for each request. The `auth` field can be a string or a function returning a string representing the token. The returned value will be attached only to requests that require auth.
+
+```js
+import { client } from 'client/sdk.gen';
+
+client.setConfig({
+  auth: () => '<my_token>', // [!code ++]
+  baseURL: 'https://example.com',
+});
+```
+
+If you're not using SDKs or generating auth, using interceptors is a common approach to configuring auth for each request.
+
+```js
+import { client } from 'client/sdk.gen';
+
+client.setConfig({
+  onRequest: ({ options }) => {
+    options.headers.set('Authorization', 'Bearer <my_token>'); // [!code ++]
+  },
+});
+```
+
+## Build URL
+
+If you need to access the compiled URL, you can use the `buildUrl()` method. It's loosely typed by default to accept almost any value; in practice, you will want to pass a type hint.
+
+```ts
+type FooData = {
+  path: {
+    fooId: number;
+  };
+  query?: {
+    bar?: string;
+  };
+  url: '/foo/{fooId}';
+};
+
+const url = client.buildUrl<FooData>({
+  path: {
+    fooId: 1,
+  },
+  query: {
+    bar: 'baz',
+  },
+  url: '/foo/{fooId}',
+});
+console.log(url); // prints '/foo/1?bar=baz'
+```
+
+## Bundling
+
+Sometimes, you may not want to declare client packages as a dependency. This scenario is common if you're using Hey API to generate output that is repackaged and published for other consumers under your own brand. For such cases, our clients support bundling through the `client.bundle` configuration option.
+
+```js
+export default {
+  client: {
+    bundle: true, // [!code ++]
+    name: '@hey-api/client-nuxt',
+  },
+  input: 'path/to/openapi.json',
+  output: 'src/client',
+};
+```
+
+<!--@include: ../../examples.md-->
 <!--@include: ../../sponsors.md-->

examples/openapi-ts-nuxt/app.vue

@@ -13,6 +13,12 @@ client.setConfig({
   headers: {
     Authorization: 'Bearer <token_from_service_client>',
   },
+  onRequest: () => {
+    console.log('onRequest: global');
+  },
+  onResponse: () => {
+    console.log('onResponse: global');
+  },
 });
 </script>
 

examples/openapi-ts-nuxt/components/home.vue

@@ -123,6 +123,16 @@ watch(lazyFetch.data, (newPet) => {
 async function handleFetch() {
   const result = await getPetById({
     composable: '$fetch',
+    onRequest: [
+      () => {
+        console.log('onRequest: local');
+      },
+    ],
+    onResponse: [
+      () => {
+        console.log('onResponse: local');
+      },
+    ],
     path: {
       petId,
     },

packages/client-nuxt/src/index.ts

@@ -12,6 +12,7 @@ import {
   createConfig,
   mergeConfigs,
   mergeHeaders,
+  mergeInterceptors,
   setAuthParams,
   unwrapRefs,
 } from './utils';
@@ -37,49 +38,45 @@ export const createClient = (config: Config = {}): Client => {
       ...options,
       $fetch: options.$fetch ?? _config.$fetch ?? $fetch,
       headers: mergeHeaders(_config.headers, options.headers),
+      onRequest: mergeInterceptors(_config.onRequest, options.onRequest),
+      onResponse: mergeInterceptors(_config.onResponse, options.onResponse),
     };
 
     const { responseTransformer, responseValidator, security } = opts;
     if (security) {
-      const _onRequest = opts.onRequest;
       // auth must happen in interceptors otherwise we'd need to require
       // asyncContext enabled
       // https://nuxt.com/docs/guide/going-further/experimental-features#asynccontext
-      opts.onRequest = async (context) => {
-        const { options } = context;
-
-        await setAuthParams({
-          auth: opts.auth,
-          headers: options.headers,
-          query: options.query,
-          security,
-        });
-
-        if (typeof _onRequest === 'function') {
-          await _onRequest(context);
-        }
-      };
+      opts.onRequest = [
+        async ({ options }) => {
+          await setAuthParams({
+            auth: opts.auth,
+            headers: options.headers,
+            query: options.query,
+            security,
+          });
+        },
+        ...opts.onRequest,
+      ];
     }
 
     if (responseTransformer || responseValidator) {
-      const _onResponse = opts.onResponse;
-      opts.onResponse = async (context) => {
-        const { options, response } = context;
+      opts.onResponse = [
+        ...opts.onResponse,
+        async ({ options, response }) => {
+          if (options.responseType && options.responseType !== 'json') {
+            return;
+          }
 
-        if (!options.responseType || options.responseType === 'json') {
           if (responseValidator) {
             await responseValidator(response._data);
           }
 
           if (responseTransformer) {
             response._data = await responseTransformer(response._data);
           }
-        }
-
-        if (typeof _onResponse === 'function') {
-          await _onResponse(context);
-        }
-      };
+        },
+      ];
     }
 
     if (opts.body && opts.bodySerializer) {

packages/client-nuxt/src/utils.ts

@@ -19,6 +19,8 @@ type ArraySeparatorStyle = ArrayStyle | MatrixStyle;
 type ObjectStyle = 'form' | 'deepObject';
 type ObjectSeparatorStyle = ObjectStyle | MatrixStyle;
 
+type MaybeArray<T> = T | T[];
+
 export type QuerySerializer = (
   query: Parameters<Client['buildUrl']>[0]['query'],
 ) => string;
@@ -474,6 +476,16 @@ export const mergeHeaders = (
   return mergedHeaders;
 };
 
+export const mergeInterceptors = <T>(...args: Array<MaybeArray<T>>): Array<T> =>
+  args.reduce<Array<T>>((acc, item) => {
+    if (typeof item === 'function') {
+      acc.push(item);
+    } else if (Array.isArray(item)) {
+      return acc.concat(item);
+    }
+    return acc;
+  }, []);
+
 const serializeFormDataPair = (data: FormData, key: string, value: unknown) => {
   if (typeof value === 'string' || value instanceof Blob) {
     data.append(key, value);