feat: add runtime hooks for API request and response handling

Author: mattmess1221

docs/guide/hooks.md

@@ -4,8 +4,28 @@ Some hooks are provided via nuxt's hookable system as a convenience. These hooks
 
 For more information on hooks, see the [nuxt documentation](https://nuxt.com/docs/guide/going-further/hooks).
 
-## Available hooks
+## Build hooks
+
+Register these hooks in `nuxt.config` or via a module.
 
 | Hook name            | Arguments          | Description
 | -------------------- | ------------------ | -----------
 | `api-party:resolve`  | `id, endpoint` | Called during module initialization for each configured endpoint. Can be used to modify the endpoint configuration.
+
+## Runtime Hooks
+
+Register these hooks with a client plugin.
+
+| Hook name            | Arguments  | Description
+| -------------------- | ---------- | -----------
+| `api-party:request`  | `ctx`      | Called before each request is made. Can be used to log or modify the request.
+| `api-party:response` | `ctx`      | Called after each request is made. Can be used to log or modify the response.
+
+## Nitro Runtime Hooks
+
+Register these hooks with a server plugin.
+
+| Hook name            | Arguments    | Description
+| -------------------- | ------------ | -----------
+| `api-party:request`  | `ctx, event` | Called before each request is made. Can be used to log or modify the request.
+| `api-party:response` | `ctx, event` | Called after each request is made. Can be used to log or modify the response.

src/module.ts

@@ -5,8 +5,10 @@ import { camelCase, pascalCase } from 'scule'
 import { createJiti } from 'jiti'
 import { addImportsSources, addServerHandler, addTemplate, createResolver, defineNuxtModule, useLogger } from '@nuxt/kit'
 import type { HookResult } from '@nuxt/schema'
+import type { H3Event } from 'h3'
 import type { OpenAPI3, OpenAPITSOptions } from 'openapi-typescript'
 import type { QueryObject } from 'ufo'
+import type { FetchContext } from 'ofetch'
 import { name } from '../package.json'
 import { generateDeclarationTypes } from './openapi'
 
@@ -91,6 +93,18 @@ declare module '@nuxt/schema' {
     'api-party:resolve': (id: string, endpoint: ApiEndpoint) => HookResult
   }
 }
+declare module '#app' {
+  interface RuntimeNuxtHooks {
+    'api-party:request': (options: FetchContext) => HookResult
+    'api-party:response': (options: FetchContext & { response: Response }) => HookResult
+  }
+}
+declare module 'nitropack' {
+  interface NitroRuntimeHooks {
+    'api-party:request': (options: FetchContext, event?: H3Event) => HookResult
+    'api-party:response': (options: FetchContext & { response: Response }, event?: H3Event) => HookResult
+  }
+}
 
 export default defineNuxtModule<ModuleOptions>({
   meta: {

src/runtime/composables/$api.ts

@@ -9,6 +9,7 @@ import type { ModuleOptions } from '../../module'
 import { CACHE_KEY_PREFIX } from '../constants'
 import type { EndpointFetchOptions } from '../types'
 import type { FetchResponseData, FilterMethods, MethodOption, ParamsOption, RequestBodyOption } from '../openapi'
+import { mergeFetchHooks } from '../hooks'
 import { useNuxtApp, useRequestHeaders, useRuntimeConfig } from '#imports'
 
 export interface SharedFetchOptions {
@@ -113,8 +114,18 @@ export function _$api<T = unknown>(
 
   const endpoint = (apiParty.endpoints || {})[endpointId]
 
+  const fetchHooks = mergeFetchHooks(fetchOptions, {
+    onRequest: async (ctx) => {
+      await nuxt.callHook('api-party:request', ctx)
+    },
+    onResponse: async (ctx) => {
+      await nuxt.callHook('api-party:response', ctx)
+    },
+  })
+
   const clientFetcher = () => globalThis.$fetch<T>(resolvePathParams(path, pathParams), {
     ...fetchOptions,
+    ...fetchHooks,
     baseURL: endpoint.url,
     method,
     query: {
@@ -132,6 +143,7 @@ export function _$api<T = unknown>(
   const serverFetcher = async () =>
     (await globalThis.$fetch<T>(joinURL('/api', apiParty.server.basePath!, endpointId), {
       ...fetchOptions,
+      ...fetchHooks,
       method: 'POST',
       body: {
         path: resolvePathParams(path, pathParams),

src/runtime/composables/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../.nuxt/tsconfig.json"
+}

src/runtime/composables/useApiData.ts

@@ -12,6 +12,7 @@ import { headersToObject, serializeMaybeEncodedBody } from '../utils'
 import { isFormData } from '../form-data'
 import type { EndpointFetchOptions } from '../types'
 import type { FetchResponseData, FetchResponseError, FilterMethods, ParamsOption, RequestBodyOption } from '../openapi'
+import { mergeFetchHooks } from '../hooks'
 import { useAsyncData, useRequestHeaders, useRuntimeConfig } from '#imports'
 
 type ComputedOptions<T> = {
@@ -56,17 +57,19 @@ export type SharedAsyncDataOptions<ResT, DataT = ResT> = Omit<AsyncDataOptions<R
 
 export type UseApiDataOptions<T> = Pick<
   ComputedOptions<NitroFetchOptions<string>>,
-  | 'onRequest'
-  | 'onRequestError'
-  | 'onResponse'
-  | 'onResponseError'
   | 'query'
   | 'headers'
   | 'method'
   | 'retry'
   | 'retryDelay'
   | 'retryStatusCodes'
   | 'timeout'
+> & Pick<
+  NitroFetchOptions<string>,
+  | 'onRequest'
+  | 'onRequestError'
+  | 'onResponse'
+  | 'onResponseError'
 > & {
   path?: MaybeRefOrGetter<Record<string, string>>
   body?: MaybeRef<string | Record<string, any> | FormData | null>
@@ -191,10 +194,20 @@ export function _useApiData<T = unknown>(
 
       let result: T | undefined
 
+      const fetchHooks = mergeFetchHooks(fetchOptions, {
+        onRequest: async (ctx) => {
+          await nuxt?.callHook('api-party:request', ctx)
+        },
+        onResponse: async (ctx) => {
+          await nuxt?.callHook('api-party:response', ctx)
+        },
+      })
+
       try {
         if (client) {
           result = (await globalThis.$fetch<T>(_path.value, {
             ..._fetchOptions,
+            ...fetchHooks,
             signal: controller.signal,
             baseURL: endpoint.url,
             method: _endpointFetchOptions.method,
@@ -215,6 +228,7 @@ export function _useApiData<T = unknown>(
             joinURL('/api', apiParty.server.basePath!, endpointId),
             {
               ..._fetchOptions,
+              ...fetchHooks,
               signal: controller.signal,
               method: 'POST',
               body: {

src/runtime/hooks.ts

@@ -0,0 +1,21 @@
+import type { FetchHooks } from 'ofetch'
+
+type Arrayify<T> = { [P in keyof T]-?: Extract<T[P], unknown[]> }
+type Hooks = Arrayify<Pick<FetchHooks, 'onRequest' | 'onResponse'>>
+
+export function mergeFetchHooks(...hooks: FetchHooks[]): Hooks {
+  const result: Hooks = {
+    onRequest: [],
+    onResponse: [],
+  }
+
+  hooks.forEach((hook) => {
+    for (const name of Object.keys(result) as (keyof Hooks)[]) {
+      if (hook) {
+        result[name].push(...(Array.isArray(hook) ? hook : [hook]))
+      }
+    }
+  })
+
+  return result
+}

src/runtime/server/$api.ts

@@ -2,7 +2,8 @@ import { headersToObject } from '../utils'
 import { resolvePathParams } from '../openapi'
 import type { ModuleOptions } from '../../module'
 import type { ApiClientFetchOptions } from '../composables/$api'
-import { useRuntimeConfig } from '#imports'
+import { mergeFetchHooks } from '../hooks'
+import { useNitroApp, useRuntimeConfig } from '#imports'
 
 export function _$api<T = unknown>(
   endpointId: string,
@@ -14,8 +15,18 @@ export function _$api<T = unknown>(
   const endpoints = apiParty.endpoints || {}
   const endpoint = endpoints[endpointId]
 
+  const nitro = useNitroApp()
+
   return globalThis.$fetch<T>(resolvePathParams(path, pathParams), {
     ...fetchOptions,
+    ...mergeFetchHooks(fetchOptions, {
+      onRequest: async (ctx) => {
+        await nitro.hooks.callHook('api-party:request', ctx)
+      },
+      onResponse: async (ctx) => {
+        await nitro.hooks.callHook('api-party:response', ctx)
+      },
+    }),
     baseURL: endpoint.url,
     query: {
       ...endpoint.query,

src/runtime/server/handler.ts

@@ -12,9 +12,10 @@ import {
 import { deserializeMaybeEncodedBody } from '../utils'
 import type { ModuleOptions } from '../../module'
 import type { EndpointFetchOptions } from '../types'
-import { useRuntimeConfig } from '#imports'
+import { useRuntimeConfig, useNitroApp } from '#imports'
 
 export default defineEventHandler(async (event) => {
+  const nitro = useNitroApp()
   const endpointId = getRouterParam(event, 'endpointId')!
   const apiParty = useRuntimeConfig().apiParty as Required<ModuleOptions>
   const endpoints = apiParty.endpoints || {}
@@ -79,6 +80,13 @@ export default defineEventHandler(async (event) => {
         ...(body && { body: await deserializeMaybeEncodedBody(body) }),
         responseType: 'arrayBuffer',
         ignoreResponseError: true,
+
+        onRequest: async (ctx) => {
+          await nitro.hooks.callHook('api-party:request', ctx, event)
+        },
+        onResponse: async (ctx) => {
+          await nitro.hooks.callHook('api-party:response', ctx, event)
+        },
       },
     )
 

src/runtime/server/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../.nuxt/tsconfig.server.json"
+}