feat(client, server)!: Adapter-Level Plugin Interception (#292)

Plugins now have the ability to intercept and modify requests and
responses directly at the adapter level

### `Event Iterator Keep Alive`

We move configs for `Event Iterator Keep Alive` from `.handle` to
`handler options` (define when creating handler)

### Rename internal APIs

- `HandlerPlugin` -> `StandardHandlerPlugin`
- `ClientOptions` -> `FriendlyClientOptions`
- `ClientOptionsOut` -> `ClientOptions`
- `ClientPlugin` -> `StandardLinkPlugin`
- `StandardHandleOptions` -> `FriendlyStandardHandleOptions`

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

## Summary by CodeRabbit

- **Documentation**
- Clarified API descriptions, including keep-alive behavior and headers
for improved clarity.

- **Refactor**
- Streamlined internal handler implementations and standardized plugin
and configuration interfaces across client and server components.

- **Tests**
- Expanded test coverage for options resolution and plugin
initialization, while simplifying scenarios to focus on core
functionality.

- **Chores**
- Removed deprecated dependencies, updated package versions, and
consolidated module exports for a leaner codebase.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: dinwwwh

apps/content/docs/openapi/openapi-handler.md

@@ -99,10 +99,10 @@ To keep [Event Iterator](/docs/event-iterator) connections alive, `OpenAPIHandle
 
 - `eventIteratorKeepAliveEnabled` (default: `true`) – Enables or disables pings.
 - `eventIteratorKeepAliveInterval` (default: `5000`) – Time between pings (in milliseconds).
-- `eventIteratorKeepAliveComment` (default: `''`) – Custom content for ping messages.
+- `eventIteratorKeepAliveComment` (default: `''`) – Custom content for ping comments.
 
 ```ts
-const result = await handler.handle(request, {
+const handler = new OpenAPIHandler(router, {
   eventIteratorKeepAliveEnabled: true,
   eventIteratorKeepAliveInterval: 5000, // 5 seconds
   eventIteratorKeepAliveComment: '',

apps/content/docs/rpc-handler.md

@@ -72,7 +72,7 @@ export default async function fetch(request: Request) {
 }
 ```
 
-## Event-Iterator Keep Alive
+## Event Iterator Keep Alive
 
 To keep [Event Iterator](/docs/event-iterator) connections alive, `RPCHandler` periodically sends a ping comment to the client. You can configure this behavior using the following options:
 
@@ -81,7 +81,7 @@ To keep [Event Iterator](/docs/event-iterator) connections alive, `RPCHandler` p
 - `eventIteratorKeepAliveComment` (default: `''`) – Custom content for ping comments.
 
 ```ts
-const result = await handler.handle(request, {
+const handler = new RPCHandler(router, {
   eventIteratorKeepAliveEnabled: true,
   eventIteratorKeepAliveInterval: 5000, // 5 seconds
   eventIteratorKeepAliveComment: '',

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

@@ -1,14 +1,14 @@
 import type { StandardLazyResponse, StandardRequest } from '@orpc/standard-server'
 import type { ToFetchRequestOptions } from '@orpc/standard-server-fetch'
-import type { ClientContext, ClientOptionsOut } from '../../types'
+import type { ClientContext, ClientOptions } from '../../types'
 import type { StandardLinkClient } from '../standard'
 import { toFetchRequest, toStandardLazyResponse } from '@orpc/standard-server-fetch'
 
 export interface LinkFetchClientOptions<T extends ClientContext> extends ToFetchRequestOptions {
   fetch?: (
     request: Request,
     init: Record<never, never>,
-    options: ClientOptionsOut<T>,
+    options: ClientOptions<T>,
     path: readonly string[],
     input: unknown
   ) => Promise<Response>
@@ -23,7 +23,7 @@ export class LinkFetchClient<T extends ClientContext> implements StandardLinkCli
     this.toFetchRequestOptions = options
   }
 
-  async call(request: StandardRequest, options: ClientOptionsOut<T>, path: readonly string[], input: unknown): Promise<StandardLazyResponse> {
+  async call(request: StandardRequest, options: ClientOptions<T>, path: readonly string[], input: unknown): Promise<StandardLazyResponse> {
     const fetchRequest = toFetchRequest(request, this.toFetchRequestOptions)
 
     const fetchResponse = await this.fetch(fetchRequest, {}, options, path, input)

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

@@ -1,4 +1,4 @@
-import type { ClientContext, ClientLink, ClientOptionsOut } from '../../types'
+import type { ClientContext, ClientLink, ClientOptions } from '../../types'
 import type { StandardRPCLinkOptions } from '../standard'
 import type { LinkFetchClientOptions } from './link-fetch-client'
 import { StandardLink, StandardRPCJsonSerializer, StandardRPCLinkCodec, StandardRPCSerializer } from '../standard'
@@ -19,7 +19,7 @@ export class RPCLink<T extends ClientContext> implements ClientLink<T> {
     this.standardLink = new StandardLink(linkCodec, linkClient, options)
   }
 
-  async call(path: readonly string[], input: unknown, options: ClientOptionsOut<T>): Promise<unknown> {
+  async call(path: readonly string[], input: unknown, options: ClientOptions<T>): Promise<unknown> {
     return this.standardLink.call(path, input, options)
   }
 }

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

@@ -1,10 +1,10 @@
-import type { ClientContext, ClientOptionsOut } from '../../types'
+import type { ClientContext, ClientOptions } from '../../types'
 
 export interface FetchWithContext<TClientContext extends ClientContext> {
   (
     url: URL,
     init: RequestInit,
-    options: ClientOptionsOut<TClientContext>,
+    options: ClientOptions<TClientContext>,
     path: readonly string[],
     input: unknown,
   ): Promise<Response>

packages/client/src/adapters/standard/link.test.ts

@@ -52,4 +52,20 @@ describe('standardLink', () => {
       request: '__standard_request__',
     })
   })
+
+  it('plugins', () => {
+    const init = vi.fn()
+
+    const options = {
+      plugins: [
+        { init },
+      ],
+      interceptors: [vi.fn()],
+      clientInterceptors: [vi.fn()],
+    }
+    const link = new StandardLink(codec, client, options)
+
+    expect(init).toHaveBeenCalledOnce()
+    expect(init).toHaveBeenCalledWith(options)
+  })
 })

packages/client/src/adapters/standard/link.ts

@@ -1,16 +1,19 @@
 import type { Interceptor } from '@orpc/shared'
 import type { StandardLazyResponse, StandardRequest } from '@orpc/standard-server'
-import type { ClientContext, ClientLink, ClientOptionsOut } from '../../types'
+import type { ClientContext, ClientLink, ClientOptions } from '../../types'
 import type { StandardLinkClient, StandardLinkCodec } from './types'
-import { intercept } from '@orpc/shared'
-import { type ClientPlugin, CompositeClientPlugin } from '../../plugins'
+import { intercept, toArray } from '@orpc/shared'
 
 export class InvalidEventIteratorRetryResponse extends Error { }
 
+export interface StandardLinkPlugin<T extends ClientContext> {
+  init?(options: StandardLinkOptions<T>): void
+}
+
 export interface StandardLinkOptions<T extends ClientContext> {
-  interceptors?: Interceptor<{ path: readonly string[], input: unknown, options: ClientOptionsOut<T> }, unknown, unknown>[]
+  interceptors?: Interceptor<{ path: readonly string[], input: unknown, options: ClientOptions<T> }, unknown, unknown>[]
   clientInterceptors?: Interceptor<{ request: StandardRequest }, StandardLazyResponse, unknown>[]
-  plugins?: ClientPlugin<T>[]
+  plugins?: StandardLinkPlugin<T>[]
 }
 
 export class StandardLink<T extends ClientContext> implements ClientLink<T> {
@@ -22,23 +25,23 @@ export class StandardLink<T extends ClientContext> implements ClientLink<T> {
     public readonly sender: StandardLinkClient<T>,
     options: StandardLinkOptions<T> = {},
   ) {
-    const plugin = new CompositeClientPlugin(options.plugins)
-
-    plugin.init(options)
+    for (const plugin of toArray(options.plugins)) {
+      plugin.init?.(options)
+    }
 
-    this.interceptors = options.interceptors ?? []
-    this.clientInterceptors = options.clientInterceptors ?? []
+    this.interceptors = toArray(options.interceptors)
+    this.clientInterceptors = toArray(options.clientInterceptors)
   }
 
-  call(path: readonly string[], input: unknown, options: ClientOptionsOut<T>): Promise<unknown> {
+  call(path: readonly string[], input: unknown, options: ClientOptions<T>): Promise<unknown> {
     return intercept(this.interceptors, { path, input, options }, async ({ path, input, options }) => {
       const output = await this.#call(path, input, options)
 
       return output
     })
   }
 
-  async #call(path: readonly string[], input: unknown, options: ClientOptionsOut<T>): Promise<unknown> {
+  async #call(path: readonly string[], input: unknown, options: ClientOptions<T>): Promise<unknown> {
     const request = await this.codec.encode(path, input, options)
 
     const response = await intercept(

packages/client/src/adapters/standard/rpc-link-codec.ts

@@ -1,5 +1,5 @@
 import type { StandardHeaders, StandardLazyResponse, StandardRequest } from '@orpc/standard-server'
-import type { ClientContext, ClientOptionsOut } from '../../types'
+import type { ClientContext, ClientOptions } from '../../types'
 import type { StandardRPCSerializer } from './rpc-serializer'
 import type { StandardLinkCodec } from './types'
 import { isAsyncIteratorObject, stringifyJSON, trim, value, type Value } from '@orpc/shared'
@@ -12,7 +12,7 @@ export interface StandardRPCLinkCodecOptions<T extends ClientContext> {
    * Base url for all requests.
    */
   url: Value<string | URL, [
-    options: ClientOptionsOut<T>,
+    options: ClientOptions<T>,
     path: readonly string[],
     input: unknown,
   ]>
@@ -23,7 +23,7 @@ export interface StandardRPCLinkCodecOptions<T extends ClientContext> {
    * @default 2083
    */
   maxUrlLength?: Value<number, [
-    options: ClientOptionsOut<T>,
+    options: ClientOptions<T>,
     path: readonly string[],
     input: unknown,
   ]>
@@ -34,7 +34,7 @@ export interface StandardRPCLinkCodecOptions<T extends ClientContext> {
    * @default 'POST'
    */
   method?: Value<HTTPMethod, [
-    options: ClientOptionsOut<T>,
+    options: ClientOptions<T>,
     path: readonly string[],
     input: unknown,
   ]>
@@ -51,7 +51,7 @@ export interface StandardRPCLinkCodecOptions<T extends ClientContext> {
    * Inject headers to the request.
    */
   headers?: Value<StandardHeaders, [
-    options: ClientOptionsOut<T>,
+    options: ClientOptions<T>,
     path: readonly string[],
     input: unknown,
   ]>
@@ -75,7 +75,7 @@ export class StandardRPCLinkCodec<T extends ClientContext> implements StandardLi
     this.headers = options.headers ?? {}
   }
 
-  async encode(path: readonly string[], input: unknown, options: ClientOptionsOut<any>): Promise<StandardRequest> {
+  async encode(path: readonly string[], input: unknown, options: ClientOptions<T>): Promise<StandardRequest> {
     const expectedMethod = await value(this.expectedMethod, options, path, input)
     const headers = { ...await value(this.headers, options, path, input) }
     const baseUrl = await value(this.baseUrl, options, path, input)

packages/client/src/adapters/standard/types.ts

@@ -1,11 +1,11 @@
 import type { StandardLazyResponse, StandardRequest } from '@orpc/standard-server'
-import type { ClientContext, ClientOptionsOut } from '../../types'
+import type { ClientContext, ClientOptions } from '../../types'
 
 export interface StandardLinkCodec<T extends ClientContext> {
-  encode(path: readonly string[], input: unknown, options: ClientOptionsOut<any>): Promise<StandardRequest>
-  decode(response: StandardLazyResponse, options: ClientOptionsOut<T>, path: readonly string[], input: unknown): Promise<unknown>
+  encode(path: readonly string[], input: unknown, options: ClientOptions<T>): Promise<StandardRequest>
+  decode(response: StandardLazyResponse, options: ClientOptions<T>, path: readonly string[], input: unknown): Promise<unknown>
 }
 
 export interface StandardLinkClient<T extends ClientContext> {
-  call(request: StandardRequest, options: ClientOptionsOut<T>, path: readonly string[], input: unknown): Promise<StandardLazyResponse>
+  call(request: StandardRequest, options: ClientOptions<T>, path: readonly string[], input: unknown): Promise<StandardLazyResponse>
 }

packages/client/src/client.ts

@@ -1,4 +1,5 @@
-import type { Client, ClientLink, InferClientContext, NestedClient } from './types'
+import type { Client, ClientLink, FriendlyClientOptions, InferClientContext, NestedClient } from './types'
+import { resolveFriendlyClientOptions } from './utils'
 
 export interface createORPCClientOptions {
   /**
@@ -13,13 +14,10 @@ export function createORPCClient<T extends NestedClient<any>>(
 ): T {
   const path = options?.path ?? []
 
-  const procedureClient: Client<InferClientContext<T>, unknown, unknown, Error> = async (...[input, options]) => {
-    const optionsOut = {
-      ...options,
-      context: options?.context ?? {} as InferClientContext<T>, // options.context can be undefined when all field is optional
-    }
-
-    return await link.call(path, input, optionsOut)
+  const procedureClient: Client<InferClientContext<T>, unknown, unknown, Error> = async (
+    ...[input, options = {} as FriendlyClientOptions<InferClientContext<T>>]
+  ) => {
+    return await link.call(path, input, resolveFriendlyClientOptions(options))
   }
 
   const recursive = new Proxy(procedureClient, {