feat(client): adapter interceptor (#899)

LinkFetchClient, RPCLink, OpenAPILink, ... now support
`adapterInterceptors` option for intercept fetch request/response

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- New Features
- Plugin support for the fetch client with ordered runtime
initialization.
  - Adapter interceptors to customize request/response handling.
  - Client options expanded to accept plugins and interceptors.

- Refactor
  - Client constructor now accepts a single consolidated options object.
- Handler option shapes adjusted to reorganize and restrict where
plugins are provided.

- Tests
- Added unit and type tests for plugin composition and interceptor
execution.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: unnoq

apps/content/docs/advanced/superjson.md

@@ -83,7 +83,8 @@ import { StrictGetMethodPlugin } from '@orpc/server/plugins'
 import type { StandardHandlerOptions } from '@orpc/server/standard'
 import { StandardHandler, StandardRPCCodec, StandardRPCMatcher } from '@orpc/server/standard'
 
-export interface SuperJSONHandlerOptions<T extends Context> extends StandardHandlerOptions<T> {
+export interface SuperJSONHandlerOptions<T extends Context>
+  extends FetchHandlerOptions<T>, Omit<StandardHandlerOptions<T>, 'plugins'> {
   /**
    * Enable or disable the StrictGetMethodPlugin.
    *
@@ -93,7 +94,7 @@ export interface SuperJSONHandlerOptions<T extends Context> extends StandardHand
 }
 
 export class SuperJSONHandler<T extends Context> extends FetchHandler<T> {
-  constructor(router: Router<any, T>, options: NoInfer<FetchHandlerOptions<T> & SuperJSONHandlerOptions<T>> = {}) {
+  constructor(router: Router<any, T>, options: NoInfer<SuperJSONHandlerOptions<T>> = {}) {
     options.plugins ??= []
 
     const strictGetMethodPluginEnabled = options.strictGetMethodPluginEnabled ?? true
@@ -126,7 +127,9 @@ import type { LinkFetchClientOptions } from '@orpc/client/fetch'
 import { LinkFetchClient } from '@orpc/client/fetch'
 
 export interface SuperJSONLinkOptions<T extends ClientContext>
-  extends StandardLinkOptions<T>, StandardRPCLinkCodecOptions<T>, LinkFetchClientOptions<T> { }
+  extends LinkFetchClientOptions<T>,
+  Omit<StandardLinkOptions<T>, 'plugins'>,
+  StandardRPCLinkCodecOptions<T> { }
 
 export class SuperJSONLink<T extends ClientContext> extends StandardLink<T> {
   constructor(options: SuperJSONLinkOptions<T>) {

packages/client/src/adapters/fetch/link-fetch-client.test.ts

@@ -8,9 +8,15 @@ const toStandardLazyResponseSpy = vi.spyOn(StandardServerFetch, 'toStandardLazyR
 describe('linkFetchClient', () => {
   it('call', async () => {
     const fetch = vi.fn().mockResolvedValueOnce(new Response('body'))
-    const client = new LinkFetchClient({
+    const interceptor1 = vi.fn(({ next }) => next())
+    const interceptor2 = vi.fn(({ next }) => next())
+
+    const linkOptions = {
       fetch,
-    })
+      adapterInterceptors: [interceptor1, interceptor2],
+    }
+
+    const client = new LinkFetchClient(linkOptions)
 
     const standardRequest: StandardRequest = {
       url: new URL('http://localhost:300/example'),
@@ -31,7 +37,7 @@ describe('linkFetchClient', () => {
     const response = await client.call(standardRequest, options, ['example'], { body: true })
 
     expect(toFetchRequestSpy).toBeCalledTimes(1)
-    expect(toFetchRequestSpy).toBeCalledWith(standardRequest, { fetch })
+    expect(toFetchRequestSpy).toBeCalledWith(standardRequest, linkOptions)
 
     expect(response).toBe(toStandardLazyResponseSpy.mock.results[0]!.value)
     expect(toStandardLazyResponseSpy).toBeCalledTimes(1)
@@ -48,5 +54,39 @@ describe('linkFetchClient', () => {
       ['example'],
       { body: true },
     )
+
+    expect(interceptor1).toBeCalledTimes(1)
+    expect(interceptor2).toBeCalledTimes(1)
+    expect(interceptor1).toBeCalledWith(expect.objectContaining({
+      request: toFetchRequestSpy.mock.results[0]!.value,
+      ...options,
+      init: { redirect: 'manual' },
+      input: { body: true },
+      path: ['example'],
+    }))
+    expect(interceptor2).toBeCalledWith(expect.objectContaining({
+      request: toFetchRequestSpy.mock.results[0]!.value,
+      ...options,
+      init: { redirect: 'manual' },
+      input: { body: true },
+      path: ['example'],
+    }))
+  })
+
+  it('plugins', () => {
+    const initRuntimeAdapter = vi.fn()
+    const interceptor = vi.fn()
+
+    const linkOptions = {
+      plugins: [
+        { initRuntimeAdapter },
+      ],
+      adapterInterceptors: [interceptor],
+    }
+
+    const link = new LinkFetchClient(linkOptions)
+
+    expect(initRuntimeAdapter).toHaveBeenCalledOnce()
+    expect(initRuntimeAdapter).toHaveBeenCalledWith(linkOptions)
   })
 })

packages/client/src/adapters/fetch/link-fetch-client.ts

@@ -1,34 +1,59 @@
+import type { Interceptor } from '@orpc/shared'
 import type { StandardLazyResponse, StandardRequest } from '@orpc/standard-server'
 import type { ToFetchRequestOptions } from '@orpc/standard-server-fetch'
 import type { ClientContext, ClientOptions } from '../../types'
 import type { StandardLinkClient } from '../standard'
+import type { LinkFetchPlugin } from './plugin'
+import { intercept, toArray } from '@orpc/shared'
 import { toFetchRequest, toStandardLazyResponse } from '@orpc/standard-server-fetch'
+import { CompositeLinkFetchPlugin } from './plugin'
+
+export interface LinkFetchInterceptorOptions<T extends ClientContext> extends ClientOptions<T> {
+  request: Request
+  init: { redirect?: Request['redirect'] }
+  path: readonly string[]
+  input: unknown
+}
 
 export interface LinkFetchClientOptions<T extends ClientContext> extends ToFetchRequestOptions {
   fetch?: (
     request: Request,
-    init: { redirect?: Request['redirect'] },
+    init: LinkFetchInterceptorOptions<T>['init'],
     options: ClientOptions<T>,
     path: readonly string[],
     input: unknown,
   ) => Promise<Response>
+
+  adapterInterceptors?: Interceptor<LinkFetchInterceptorOptions<T>, Promise<Response>>[]
+
+  plugins?: LinkFetchPlugin<T>[]
 }
 
 export class LinkFetchClient<T extends ClientContext> implements StandardLinkClient<T> {
   private readonly fetch: Exclude<LinkFetchClientOptions<T>['fetch'], undefined>
   private readonly toFetchRequestOptions: ToFetchRequestOptions
+  private readonly adapterInterceptors: Exclude<LinkFetchClientOptions<T>['adapterInterceptors'], undefined>
 
   constructor(options: LinkFetchClientOptions<T>) {
-    this.fetch = options?.fetch ?? globalThis.fetch.bind(globalThis)
+    const plugin = new CompositeLinkFetchPlugin(options.plugins)
+
+    plugin.initRuntimeAdapter(options)
+
+    this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis)
     this.toFetchRequestOptions = options
+    this.adapterInterceptors = toArray(options.adapterInterceptors)
   }
 
-  async call(request: StandardRequest, options: ClientOptions<T>, path: readonly string[], input: unknown): Promise<StandardLazyResponse> {
-    const fetchRequest = toFetchRequest(request, this.toFetchRequestOptions)
+  async call(standardRequest: StandardRequest, options: ClientOptions<T>, path: readonly string[], input: unknown): Promise<StandardLazyResponse> {
+    const request = toFetchRequest(standardRequest, this.toFetchRequestOptions)
 
-    const fetchResponse = await this.fetch(fetchRequest, { redirect: 'manual' }, options, path, input)
+    const fetchResponse = await intercept(
+      this.adapterInterceptors,
+      { ...options, request, path, input, init: { redirect: 'manual' } },
+      ({ request, path, input, init, ...options }) => this.fetch(request, init, options, path, input),
+    )
 
-    const lazyResponse = toStandardLazyResponse(fetchResponse, { signal: fetchRequest.signal })
+    const lazyResponse = toStandardLazyResponse(fetchResponse, { signal: request.signal })
 
     return lazyResponse
   }

packages/client/src/adapters/fetch/plugin.test-d.ts

@@ -0,0 +1,9 @@
+import type { StandardLinkPlugin } from '../standard'
+import type { LinkFetchPlugin } from './plugin'
+
+describe('LinkFetchPlugin', () => {
+  it('backward compatibility', () => {
+    expectTypeOf<LinkFetchPlugin<{ a: string }>>().toExtend<StandardLinkPlugin<{ a: string }>>()
+    expectTypeOf<StandardLinkPlugin<{ a: string }>>().toExtend<LinkFetchPlugin<{ a: string }>>()
+  })
+})

packages/client/src/adapters/fetch/plugin.test.ts

@@ -0,0 +1,37 @@
+import type { LinkFetchPlugin } from './plugin'
+import { CompositeLinkFetchPlugin } from './plugin'
+
+describe('compositeLinkFetchPlugin', () => {
+  it('forward initRuntimeAdapter and sort plugins', () => {
+    const plugin1 = {
+      initRuntimeAdapter: vi.fn(),
+      order: 1,
+    } satisfies LinkFetchPlugin<any>
+    const plugin2 = {
+      initRuntimeAdapter: vi.fn(),
+    } satisfies LinkFetchPlugin<any>
+    const plugin3 = {
+      initRuntimeAdapter: vi.fn(),
+      order: -1,
+    } satisfies LinkFetchPlugin<any>
+
+    const compositePlugin = new CompositeLinkFetchPlugin([plugin1, plugin2, plugin3])
+
+    const interceptor = vi.fn()
+
+    const options = { adapterInterceptors: [interceptor] }
+
+    compositePlugin.initRuntimeAdapter(options)
+
+    expect(plugin1.initRuntimeAdapter).toHaveBeenCalledOnce()
+    expect(plugin2.initRuntimeAdapter).toHaveBeenCalledOnce()
+    expect(plugin3.initRuntimeAdapter).toHaveBeenCalledOnce()
+
+    expect(plugin1.initRuntimeAdapter.mock.calls[0]![0]).toBe(options)
+    expect(plugin2.initRuntimeAdapter.mock.calls[0]![0]).toBe(options)
+    expect(plugin3.initRuntimeAdapter.mock.calls[0]![0]).toBe(options)
+
+    expect(plugin3.initRuntimeAdapter).toHaveBeenCalledBefore(plugin2.initRuntimeAdapter)
+    expect(plugin2.initRuntimeAdapter).toHaveBeenCalledBefore(plugin1.initRuntimeAdapter)
+  })
+})

packages/client/src/adapters/fetch/plugin.ts

@@ -0,0 +1,17 @@
+import type { ClientContext } from '../../types'
+import type { StandardLinkPlugin } from '../standard'
+import type { LinkFetchClientOptions } from './link-fetch-client'
+import { CompositeStandardLinkPlugin } from '../standard'
+
+export interface LinkFetchPlugin<T extends ClientContext> extends StandardLinkPlugin<T> {
+  initRuntimeAdapter?(options: LinkFetchClientOptions<T>): void
+}
+
+export class CompositeLinkFetchPlugin<T extends ClientContext, TPlugin extends LinkFetchPlugin<T>>
+  extends CompositeStandardLinkPlugin<T, TPlugin> implements LinkFetchPlugin<T> {
+  initRuntimeAdapter(options: LinkFetchClientOptions<T>): void {
+    for (const plugin of this.plugins) {
+      plugin.initRuntimeAdapter?.(options)
+    }
+  }
+}

packages/client/src/adapters/fetch/rpc-link.ts

@@ -5,7 +5,7 @@ import { StandardRPCLink } from '../standard'
 import { LinkFetchClient } from './link-fetch-client'
 
 export interface RPCLinkOptions<T extends ClientContext>
-  extends StandardRPCLinkOptions<T>, LinkFetchClientOptions<T> {}
+  extends LinkFetchClientOptions<T>, Omit<StandardRPCLinkOptions<T>, 'plugins'> {}
 
 /**
  * The RPC Link communicates with the server using the RPC protocol.

packages/openapi-client/src/adapters/fetch/openapi-link.ts

@@ -6,7 +6,7 @@ import { LinkFetchClient } from '@orpc/client/fetch'
 import { StandardOpenAPILink } from '../standard'
 
 export interface OpenAPILinkOptions<T extends ClientContext>
-  extends StandardOpenAPILinkOptions<T>, LinkFetchClientOptions<T> { }
+  extends LinkFetchClientOptions<T>, Omit<StandardOpenAPILinkOptions<T>, 'plugins'> { }
 
 /**
  * The OpenAPI Link for fetch runtime communicates with the server that follow the OpenAPI specification.

packages/openapi/src/adapters/fetch/openapi-handler.ts

@@ -4,14 +4,17 @@ import type { StandardOpenAPIHandlerOptions } from '../standard'
 import { FetchHandler } from '@orpc/server/fetch'
 import { StandardOpenAPIHandler } from '../standard'
 
+export interface OpenAPIHandlerOptions<T extends Context> extends FetchHandlerOptions<T>, Omit<StandardOpenAPIHandlerOptions<T>, 'plugins'> {
+}
+
 /**
  * OpenAPI Handler for Fetch Server
  *
  * @see {@link https://orpc.unnoq.com/docs/openapi/openapi-handler OpenAPI Handler Docs}
  * @see {@link https://orpc.unnoq.com/docs/adapters/http HTTP Adapter Docs}
  */
 export class OpenAPIHandler<T extends Context> extends FetchHandler<T> {
-  constructor(router: Router<any, T>, options: NoInfer<StandardOpenAPIHandlerOptions<T> & FetchHandlerOptions<T>> = {}) {
+  constructor(router: Router<any, T>, options: NoInfer<OpenAPIHandlerOptions<T>> = {}) {
     super(new StandardOpenAPIHandler(router, options), options)
   }
 }

packages/openapi/src/adapters/node/openapi-handler.ts

@@ -4,14 +4,17 @@ import type { StandardOpenAPIHandlerOptions } from '../standard'
 import { NodeHttpHandler } from '@orpc/server/node'
 import { StandardOpenAPIHandler } from '../standard'
 
+export interface OpenAPIHandlerOptions<T extends Context> extends NodeHttpHandlerOptions<T>, Omit<StandardOpenAPIHandlerOptions<T>, 'plugins'> {
+}
+
 /**
  * OpenAPI Handler for Node Server
  *
  * @see {@link https://orpc.unnoq.com/docs/openapi/openapi-handler OpenAPI Handler Docs}
  * @see {@link https://orpc.unnoq.com/docs/adapters/http HTTP Adapter Docs}
  */
 export class OpenAPIHandler<T extends Context> extends NodeHttpHandler<T> {
-  constructor(router: Router<any, T>, options: NoInfer<StandardOpenAPIHandlerOptions<T> & NodeHttpHandlerOptions<T>> = {}) {
+  constructor(router: Router<any, T>, options: NoInfer<OpenAPIHandlerOptions<T>> = {}) {
     super(new StandardOpenAPIHandler(router, options), options)
   }
 }