feat(client, server): make plugin execution order configurable (#344)

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

- **New Features**
  - Expanded public APIs to expose new composite plugin handlers.
- Introduced configurable ordering properties to manage plugin execution
priority.

- **Bug Fixes**
  - Removed outdated interfaces to simplify plugin handling.

- **Refactor**
- Streamlined plugin initialization by consolidating individual
initializations into unified composite handlers.

- **Tests**
- Added automated tests to validate the initialization process and
execution order of the composite plugins.
  - Introduced backward compatibility tests for plugin interfaces.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: unnoq

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

@@ -1,4 +1,5 @@
 export * from './link'
+export * from './plugin'
 export * from './rpc-json-serializer'
 export * from './rpc-link'
 export * from './rpc-link-codec'

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

@@ -3,13 +3,10 @@ import type { StandardLazyResponse, StandardRequest } from '@orpc/standard-serve
 import type { ClientContext, ClientLink, ClientOptions } from '../../types'
 import type { StandardLinkClient, StandardLinkCodec } from './types'
 import { intercept, toArray } from '@orpc/shared'
+import { CompositeStandardLinkPlugin, type StandardLinkPlugin } from './plugin'
 
 export class InvalidEventIteratorRetryResponse extends Error { }
 
-export interface StandardLinkPlugin<T extends ClientContext> {
-  init?(options: StandardLinkOptions<T>): void
-}
-
 export interface StandardLinkInterceptorOptions<T extends ClientContext> extends ClientOptions<T> {
   path: readonly string[]
   input: unknown
@@ -34,9 +31,9 @@ export class StandardLink<T extends ClientContext> implements ClientLink<T> {
     public readonly sender: StandardLinkClient<T>,
     options: StandardLinkOptions<T> = {},
   ) {
-    for (const plugin of toArray(options.plugins)) {
-      plugin.init?.(options)
-    }
+    const plugin = new CompositeStandardLinkPlugin(options.plugins)
+
+    plugin.init(options)
 
     this.interceptors = toArray(options.interceptors)
     this.clientInterceptors = toArray(options.clientInterceptors)

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

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

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

@@ -0,0 +1,21 @@
+import type { ClientContext } from '../../types'
+import type { StandardLinkOptions } from './link'
+
+export interface StandardLinkPlugin<T extends ClientContext> {
+  order?: number
+  init?(options: StandardLinkOptions<T>): void
+}
+
+export class CompositeStandardLinkPlugin<T extends ClientContext, TPlugin extends StandardLinkPlugin<T>> implements StandardLinkPlugin<T> {
+  protected readonly plugins: TPlugin[]
+
+  constructor(plugins: readonly TPlugin[] = []) {
+    this.plugins = [...plugins].sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
+  }
+
+  init(options: StandardLinkOptions<T>): void {
+    for (const plugin of this.plugins) {
+      plugin.init?.(options)
+    }
+  }
+}

packages/client/src/plugins/batch.ts

@@ -76,6 +76,8 @@ export class BatchLinkPlugin<T extends ClientContext> implements StandardLinkPlu
     ][]
   >
 
+  order = 5_000_000
+
   constructor(options: BatchLinkPluginOptions<T>) {
     this.groups = options.groups
     this.pending = new Map()

packages/server/src/adapters/fetch/body-limit-plugin.ts

@@ -1,5 +1,6 @@
 import type { Context } from '../../context'
-import type { FetchHandlerOptions, FetchHandlerPlugin } from './handler'
+import type { FetchHandlerOptions } from './handler'
+import type { FetchHandlerPlugin } from './plugin'
 import { ORPCError } from '@orpc/client'
 
 export interface BodyLimitPluginOptions {

packages/server/src/adapters/fetch/handler.test-d.ts

@@ -1,12 +1,4 @@
-import type { StandardHandlerPlugin } from '../standard'
-import type { FetchHandler, FetchHandlerPlugin } from './handler'
-
-describe('FetchHandlerPlugin', () => {
-  it('backward compatibility', () => {
-    expectTypeOf<FetchHandlerPlugin<{ a: string }>>().toMatchTypeOf<StandardHandlerPlugin<{ a: string }>>()
-    expectTypeOf<StandardHandlerPlugin<{ a: string }>>().toMatchTypeOf<FetchHandlerPlugin<{ a: string }>>()
-  })
-})
+import type { FetchHandler } from './handler'
 
 describe('FetchHandler', () => {
   it('optional context when all context is optional', () => {

packages/server/src/adapters/fetch/handler.ts

@@ -1,17 +1,15 @@
 import type { Interceptor, MaybeOptionalOptions, ThrowableError } from '@orpc/shared'
 import type { Context } from '../../context'
-import type { StandardHandleOptions, StandardHandler, StandardHandlerPlugin } from '../standard'
+import type { StandardHandleOptions, StandardHandler } from '../standard'
 import type { FriendlyStandardHandleOptions } from '../standard/utils'
+import type { FetchHandlerPlugin } from './plugin'
 import { intercept, resolveMaybeOptionalOptions, toArray } from '@orpc/shared'
 import { toFetchResponse, type ToFetchResponseOptions, toStandardLazyRequest } from '@orpc/standard-server-fetch'
 import { resolveFriendlyStandardHandleOptions } from '../standard/utils'
+import { CompositeFetchHandlerPlugin } from './plugin'
 
 export type FetchHandleResult = { matched: true, response: Response } | { matched: false, response: undefined }
 
-export interface FetchHandlerPlugin<T extends Context> extends StandardHandlerPlugin<T> {
-  initRuntimeAdapter?(options: FetchHandlerOptions<T>): void
-}
-
 export interface FetchHandlerInterceptorOptions<T extends Context> extends StandardHandleOptions<T> {
   request: Request
   toFetchResponseOptions: ToFetchResponseOptions
@@ -31,9 +29,9 @@ export class FetchHandler<T extends Context> {
     private readonly standardHandler: StandardHandler<T>,
     options: NoInfer<FetchHandlerOptions<T>> = {},
   ) {
-    for (const plugin of toArray(options.plugins)) {
-      plugin.initRuntimeAdapter?.(options)
-    }
+    const plugin = new CompositeFetchHandlerPlugin(options.plugins)
+
+    plugin.initRuntimeAdapter(options)
 
     this.adapterInterceptors = toArray(options.adapterInterceptors)
     this.toFetchResponseOptions = options

packages/server/src/adapters/fetch/index.ts

@@ -1,3 +1,4 @@
 export * from './body-limit-plugin'
 export * from './handler'
+export * from './plugin'
 export * from './rpc-handler'

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

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

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

@@ -0,0 +1,37 @@
+import type { FetchHandlerPlugin } from './plugin'
+import { CompositeFetchHandlerPlugin } from './plugin'
+
+describe('compositeFetchHandlerPlugin', () => {
+  it('forward initRuntimeAdapter and sort plugins', () => {
+    const plugin1 = {
+      initRuntimeAdapter: vi.fn(),
+      order: 1,
+    } satisfies FetchHandlerPlugin<any>
+    const plugin2 = {
+      initRuntimeAdapter: vi.fn(),
+    } satisfies FetchHandlerPlugin<any>
+    const plugin3 = {
+      initRuntimeAdapter: vi.fn(),
+      order: -1,
+    } satisfies FetchHandlerPlugin<any>
+
+    const compositePlugin = new CompositeFetchHandlerPlugin([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/server/src/adapters/fetch/plugin.ts

@@ -0,0 +1,16 @@
+import type { Context } from '../../context'
+import type { FetchHandlerOptions } from './handler'
+import { CompositeStandardHandlerPlugin, type StandardHandlerPlugin } from '../standard'
+
+export interface FetchHandlerPlugin<T extends Context> extends StandardHandlerPlugin<T> {
+  initRuntimeAdapter?(options: FetchHandlerOptions<T>): void
+}
+
+export class CompositeFetchHandlerPlugin<T extends Context, TPlugin extends FetchHandlerPlugin<T>>
+  extends CompositeStandardHandlerPlugin<T, TPlugin> implements FetchHandlerPlugin<T> {
+  initRuntimeAdapter(options: FetchHandlerOptions<T>): void {
+    for (const plugin of this.plugins) {
+      plugin.initRuntimeAdapter?.(options)
+    }
+  }
+}

packages/server/src/adapters/node/body-limit-plugin.ts

@@ -1,5 +1,6 @@
 import type { Context } from '../../context'
-import type { NodeHttpHandlerOptions, NodeHttpHandlerPlugin } from './handler'
+import type { NodeHttpHandlerOptions } from './handler'
+import type { NodeHttpHandlerPlugin } from './plugin'
 import { ORPCError } from '@orpc/client'
 
 export interface BodyLimitPluginOptions {

packages/server/src/adapters/node/handler.test-d.ts

@@ -1,13 +1,5 @@
 import type { IncomingMessage, ServerResponse } from 'node:http'
-import type { StandardHandlerPlugin } from '../standard'
-import type { NodeHttpHandler, NodeHttpHandlerPlugin } from './handler'
-
-describe('NodeHttpHandlerPlugin', () => {
-  it('backward compatibility', () => {
-    expectTypeOf<NodeHttpHandlerPlugin<{ a: string }>>().toMatchTypeOf<StandardHandlerPlugin<{ a: string }>>()
-    expectTypeOf<StandardHandlerPlugin<{ a: string }>>().toMatchTypeOf<NodeHttpHandlerPlugin<{ a: string }>>()
-  })
-})
+import type { NodeHttpHandler } from './handler'
 
 describe('NodeHttpHandler', () => {
   it('optional context when all context is optional', () => {

packages/server/src/adapters/node/handler.ts

@@ -1,17 +1,14 @@
 import type { Interceptor, MaybeOptionalOptions, ThrowableError } from '@orpc/shared'
 import type { NodeHttpRequest, NodeHttpResponse, SendStandardResponseOptions } from '@orpc/standard-server-node'
 import type { Context } from '../../context'
-import type { StandardHandleOptions, StandardHandler, StandardHandlerPlugin } from '../standard'
+import type { StandardHandleOptions, StandardHandler } from '../standard'
 import { intercept, resolveMaybeOptionalOptions, toArray } from '@orpc/shared'
 import { sendStandardResponse, toStandardLazyRequest } from '@orpc/standard-server-node'
 import { type FriendlyStandardHandleOptions, resolveFriendlyStandardHandleOptions } from '../standard/utils'
+import { CompositeNodeHttpHandlerPlugin, type NodeHttpHandlerPlugin } from './plugin'
 
 export type NodeHttpHandleResult = { matched: true } | { matched: false }
 
-export interface NodeHttpHandlerPlugin<T extends Context> extends StandardHandlerPlugin<T> {
-  initRuntimeAdapter?(options: NodeHttpHandlerOptions<T>): void
-}
-
 export interface NodeHttpHandlerInterceptorOptions<T extends Context> extends StandardHandleOptions<T> {
   request: NodeHttpRequest
   response: NodeHttpResponse
@@ -32,9 +29,9 @@ export class NodeHttpHandler<T extends Context> implements NodeHttpHandler<T> {
     private readonly standardHandler: StandardHandler<T>,
       options: NoInfer<NodeHttpHandlerOptions<T>> = {},
   ) {
-    for (const plugin of toArray(options.plugins)) {
-      plugin.initRuntimeAdapter?.(options)
-    }
+    const plugin = new CompositeNodeHttpHandlerPlugin(options.plugins)
+
+    plugin.initRuntimeAdapter(options)
 
     this.adapterInterceptors = toArray(options.adapterInterceptors)
     this.sendStandardResponseOptions = options

packages/server/src/adapters/node/index.ts

@@ -1,3 +1,4 @@
 export * from './body-limit-plugin'
 export * from './handler'
+export * from './plugin'
 export * from './rpc-handler'

packages/server/src/adapters/node/plugin.test-d.ts

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

packages/server/src/adapters/node/plugin.test.ts

@@ -0,0 +1,37 @@
+import type { NodeHttpHandlerPlugin } from './plugin'
+import { CompositeNodeHttpHandlerPlugin } from './plugin'
+
+describe('compositeNodeHttpHandlerPlugin', () => {
+  it('forward initRuntimeAdapter and sort plugins', () => {
+    const plugin1 = {
+      initRuntimeAdapter: vi.fn(),
+      order: 1,
+    } satisfies NodeHttpHandlerPlugin<any>
+    const plugin2 = {
+      initRuntimeAdapter: vi.fn(),
+    } satisfies NodeHttpHandlerPlugin<any>
+    const plugin3 = {
+      initRuntimeAdapter: vi.fn(),
+      order: -1,
+    } satisfies NodeHttpHandlerPlugin<any>
+
+    const compositePlugin = new CompositeNodeHttpHandlerPlugin([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/server/src/adapters/node/plugin.ts

@@ -0,0 +1,17 @@
+import type { Context } from '../../context'
+import type { StandardHandlerPlugin } from '../standard'
+import type { NodeHttpHandlerOptions } from './handler'
+import { CompositeStandardHandlerPlugin } from '../standard'
+
+export interface NodeHttpHandlerPlugin<T extends Context> extends StandardHandlerPlugin<T> {
+  initRuntimeAdapter?(options: NodeHttpHandlerOptions<T>): void
+}
+
+export class CompositeNodeHttpHandlerPlugin<T extends Context, TPlugin extends NodeHttpHandlerPlugin<T>>
+  extends CompositeStandardHandlerPlugin<T, TPlugin> implements NodeHttpHandlerPlugin<T> {
+  initRuntimeAdapter(options: NodeHttpHandlerOptions<T>): void {
+    for (const plugin of this.plugins) {
+      plugin.initRuntimeAdapter?.(options)
+    }
+  }
+}

packages/server/src/adapters/standard/handler.ts

@@ -9,6 +9,7 @@ import type { StandardCodec, StandardMatcher } from './types'
 import { ORPCError, toORPCError } from '@orpc/client'
 import { intercept, toArray } from '@orpc/shared'
 import { createProcedureClient } from '../../procedure-client'
+import { CompositeStandardHandlerPlugin, type StandardHandlerPlugin } from './plugin'
 
 export interface StandardHandleOptions<T extends Context> {
   prefix?: HTTPPath
@@ -17,10 +18,6 @@ export interface StandardHandleOptions<T extends Context> {
 
 export type StandardHandleResult = { matched: true, response: StandardResponse } | { matched: false, response: undefined }
 
-export interface StandardHandlerPlugin<TContext extends Context> {
-  init?(options: StandardHandlerOptions<TContext>): void
-}
-
 export interface StandardHandlerInterceptorOptions<T extends Context> extends StandardHandleOptions<T> {
   request: StandardLazyRequest
 }
@@ -60,9 +57,9 @@ export class StandardHandler<T extends Context> {
     private readonly codec: StandardCodec,
     options: NoInfer<StandardHandlerOptions<T>>,
   ) {
-    for (const plugin of toArray(options.plugins)) {
-      plugin.init?.(options)
-    }
+    const plugins = new CompositeStandardHandlerPlugin(options.plugins)
+
+    plugins.init(options)
 
     this.interceptors = toArray(options.interceptors)
     this.clientInterceptors = toArray(options.clientInterceptors)

packages/server/src/adapters/standard/index.ts

@@ -1,4 +1,5 @@
 export * from './handler'
+export * from './plugin'
 export * from './rpc-codec'
 export * from './rpc-handler'
 export * from './rpc-matcher'