feat(server): Change the nest integration to support Nest features that were competing with Orpc

Author: Mathiasduc

packages/nest/README.md

@@ -68,6 +68,34 @@ You can find the full documentation [here](https://orpc.unnoq.com).
 
 Deeply integrate oRPC with [NestJS](https://nestjs.com/). Read the [documentation](https://orpc.unnoq.com/docs/openapi/integrations/implement-contract-in-nest) for more information.
 
+### Error Handling
+
+oRPC provides an optional `ORPCExceptionFilter` that catches `ORPCError` instances and converts them to standardized oRPC error responses. You can choose to:
+
+1. **Use the built-in filter** for standard oRPC error responses
+2. **Handle ORPCError in your own custom exception filters** for custom error formatting
+3. **Let NestJS default error handling take over**
+
+```ts
+import { ORPCExceptionFilter } from '@orpc/nest'
+
+// Option 1: Register globally in your app
+app.useGlobalFilters(new ORPCExceptionFilter())
+
+// Option 2: Register as a provider in your module
+@Module({
+  providers: [
+    {
+      provide: APP_FILTER,
+      useClass: ORPCExceptionFilter,
+    },
+  ],
+})
+export class AppModule {}
+```
+
+**Note:** All errors thrown in oRPC handlers (including decoding/encoding errors) are now allowed to bubble up to NestJS exception filters. This gives you full control over error handling while maintaining compatibility with NestJS's exception filter system.
+
 ### Implement Contract
 
 An overview of how to implement an [oRPC contract](https://orpc.unnoq.com/docs/contract-first/define-contract) in NestJS.

packages/nest/src/filters/orpc-exception.filter.ts

@@ -0,0 +1,64 @@
+import type { ArgumentsHost, ExceptionFilter } from '@nestjs/common'
+import type { Response } from 'express'
+import type { FastifyReply } from 'fastify'
+import { Catch, Injectable } from '@nestjs/common'
+import { StandardBracketNotationSerializer, StandardOpenAPIJsonSerializer, StandardOpenAPISerializer } from '@orpc/openapi-client/standard'
+import { StandardOpenAPICodec } from '@orpc/openapi/standard'
+import { ORPCError } from '@orpc/server'
+import * as StandardServerFastify from '@orpc/standard-server-fastify'
+import * as StandardServerNode from '@orpc/standard-server-node'
+
+const codec = new StandardOpenAPICodec(
+  new StandardOpenAPISerializer(
+    new StandardOpenAPIJsonSerializer(),
+    new StandardBracketNotationSerializer(),
+  ),
+)
+
+/**
+ * Global exception filter that catches ORPCError instances and converts them
+ * to standardized oRPC error responses.
+ *
+ * This filter is optional - you can choose to:
+ * 1. Use this filter to get standard oRPC error responses
+ * 2. Handle ORPCError in your own custom exception filters
+ * 3. Let NestJS default error handling take over
+ *
+ * @example
+ * ```typescript
+ * // Register globally in your app
+ * app.useGlobalFilters(new ORPCExceptionFilter())
+ *
+ * // Or register as a provider
+ * @Module({
+ *   providers: [
+ *     {
+ *       provide: APP_FILTER,
+ *       useClass: ORPCExceptionFilter,
+ *     },
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+@Catch(ORPCError)
+@Injectable()
+export class ORPCExceptionFilter implements ExceptionFilter {
+  constructor(
+    private config: StandardServerNode.SendStandardResponseOptions | undefined,
+  ) {}
+
+  async catch(exception: ORPCError<any, any>, host: ArgumentsHost) {
+    const ctx = host.switchToHttp()
+    const res = ctx.getResponse<Response | FastifyReply>()
+    const standardResponse = codec.encodeError(exception)
+    // Send the response directly with proper status and headers
+    const isFastify = 'raw' in res
+    if (isFastify) {
+      await StandardServerFastify.sendStandardResponse(res as FastifyReply, standardResponse, this.config)
+    }
+    else {
+      await StandardServerNode.sendStandardResponse(res as Response, standardResponse, this.config)
+    }
+  }
+}

packages/nest/src/implement.test.ts

@@ -3,19 +3,21 @@ import type { Request } from 'express'
 import type { FastifyReply } from 'fastify'
 import FastifyCookie from '@fastify/cookie'
 import { Controller, Req, Res } from '@nestjs/common'
-import { REQUEST } from '@nestjs/core'
+import { APP_FILTER, REQUEST } from '@nestjs/core'
 import { FastifyAdapter } from '@nestjs/platform-fastify'
 import { Test } from '@nestjs/testing'
 import { oc, ORPCError } from '@orpc/contract'
 import { implement, lazy } from '@orpc/server'
 import * as StandardServerNode from '@orpc/standard-server-node'
 import supertest from 'supertest'
 import { expect, it, vi } from 'vitest'
-import * as z from 'zod'
+import { z } from 'zod'
+import { ORPCExceptionFilter } from './filters/orpc-exception.filter'
 import { Implement } from './implement'
 import { ORPCModule } from './module'
 
 const sendStandardResponseSpy = vi.spyOn(StandardServerNode, 'sendStandardResponse')
+const setStandardResponseSpy = vi.spyOn(StandardServerNode, 'setStandardResponse')
 
 beforeEach(() => {
   vi.clearAllMocks()
@@ -134,6 +136,14 @@ describe('@Implement', async () => {
   ] as const)('type: $1', async (Controller, _) => {
     const moduleRef = await Test.createTestingModule({
       controllers: [Controller],
+      // The pong test throw errors and need this filter to match the
+      // expected behaviour.
+      providers: [
+        {
+          provide: APP_FILTER,
+          useClass: ORPCExceptionFilter,
+        },
+      ],
     }).compile()
 
     const app = moduleRef.createNestApplication()
@@ -186,6 +196,7 @@ describe('@Implement', async () => {
           name: 'world',
         },
       }))
+      expect(sendStandardResponseSpy).toHaveBeenCalledTimes(1)
 
       expect(req).toBeDefined()
       expect(req!.method).toEqual('GET')
@@ -369,6 +380,7 @@ describe('@Implement', async () => {
     }).compile()
 
     const app = moduleRef.createNestApplication()
+    app.useGlobalFilters(new ORPCExceptionFilter())
     await app.init()
 
     const httpServer = app.getHttpServer()
@@ -411,8 +423,8 @@ describe('@Implement', async () => {
     expect(res.body).toEqual('pong')
 
     expect(interceptor).toHaveBeenCalledTimes(1)
-    expect(sendStandardResponseSpy).toHaveBeenCalledTimes(1)
-    expect(sendStandardResponseSpy).toHaveBeenCalledWith(expect.anything(), expect.anything(), expect.objectContaining({
+    expect(setStandardResponseSpy).toHaveBeenCalledTimes(1)
+    expect(setStandardResponseSpy).toHaveBeenCalledWith(expect.anything(), expect.anything(), expect.objectContaining({
       eventIteratorKeepAliveComment: '__TEST__',
     }))
   })
@@ -459,8 +471,8 @@ describe('@Implement', async () => {
         }),
       }),
     }))
-    expect(sendStandardResponseSpy).toHaveBeenCalledTimes(1)
-    expect(sendStandardResponseSpy).toHaveBeenCalledWith(expect.anything(), expect.anything(), expect.objectContaining({
+    expect(setStandardResponseSpy).toHaveBeenCalledTimes(1)
+    expect(setStandardResponseSpy).toHaveBeenCalledWith(expect.anything(), expect.anything(), expect.objectContaining({
       eventIteratorKeepAliveComment: '__TEST__',
     }))
   })

packages/nest/src/implement.ts

@@ -9,7 +9,6 @@ import type { FastifyReply, FastifyRequest } from 'fastify'
 import type { Observable } from 'rxjs'
 import type { ORPCModuleConfig } from './module'
 import { applyDecorators, Delete, Get, Head, Inject, Injectable, Optional, Patch, Post, Put, UseInterceptors } from '@nestjs/common'
-import { toORPCError } from '@orpc/client'
 import { fallbackContractConfig, isContractProcedure } from '@orpc/contract'
 import { StandardBracketNotationSerializer, StandardOpenAPIJsonSerializer, StandardOpenAPISerializer } from '@orpc/openapi-client/standard'
 import { StandardOpenAPICodec } from '@orpc/openapi/standard'
@@ -124,40 +123,63 @@ export class ImplementInterceptor implements NestInterceptor {
           ? StandardServerFastify.toStandardLazyRequest(req, res as FastifyReply)
           : StandardServerNode.toStandardLazyRequest(req, res as Response)
 
-        const standardResponse: StandardResponse = await (async () => {
-          let isDecoding = false
+        // Pass the original NestJS request as context
+        const contextWithRequest = {
+          ...(this.config?.context || {}),
+          request: req,
+          response: res,
+        }
 
+        const client = createProcedureClient(procedure, {
+          ...this.config,
+          context: contextWithRequest,
+        })
+        const standardResponse: StandardResponse = await (async (): Promise<StandardResponse> => {
+        // Decode input - catch only non-ORPC decoding errors and convert to ORPCError
+          let input: Awaited<ReturnType<typeof codec.decode>>
           try {
-            const client = createProcedureClient(procedure, this.config)
-
-            isDecoding = true
-            const input = await codec.decode(standardRequest, flattenParams(req.params as NestParams), procedure)
-            isDecoding = false
+            input = await codec.decode(standardRequest, flattenParams(req.params as NestParams), procedure)
+          }
+          catch (e: any) {
+            let error: ORPCError<any, any> = e
+            // Malformed request - wrap in ORPCError and let exception filters handle it
+            if (!(e instanceof ORPCError)) {
+              error = new ORPCError('BAD_REQUEST', {
+                message: `Malformed request. Ensure the request body is properly formatted and the 'Content-Type' header is set correctly.`,
+                cause: e,
+              })
+            }
+            return codec.encodeError(error)
+          }
 
-            const output = await client(input, {
-              signal: standardRequest.signal,
-              lastEventId: flattenHeader(standardRequest.headers['last-event-id']),
-            })
+          // Execute handler - let all errors bubble up to NestJS exception filters
+          const output = await client(input, {
+            signal: standardRequest.signal,
+            lastEventId: flattenHeader(standardRequest.headers['last-event-id']),
+          })
 
+          // Encode output - catch only non-ORPC encoding errors and convert to ORPCError
+          try {
             return codec.encode(output, procedure)
           }
-          catch (e) {
-            const error = isDecoding && !(e instanceof ORPCError)
-              ? new ORPCError('BAD_REQUEST', {
-                  message: `Malformed request. Ensure the request body is properly formatted and the 'Content-Type' header is set correctly.`,
-                  cause: e,
-                })
-              : toORPCError(e)
-
+          catch (e: any) {
+            let error: ORPCError<any, any> = e
+            // Encoding error means our handler returned invalid data
+            if (!(e instanceof ORPCError)) {
+              error = new ORPCError('INTERNAL_SERVER_ERROR', {
+                message: `Failed to encode response. The handler may have returned data that doesn't match the contract output schema.`,
+                cause: e,
+              })
+            }
             return codec.encodeError(error)
           }
         })()
-
+        // Set status and headers
         if ('raw' in res) {
-          await StandardServerFastify.sendStandardResponse(res, standardResponse, this.config)
+          return StandardServerFastify.setStandardResponse(res as FastifyReply, standardResponse, this.config)
         }
         else {
-          await StandardServerNode.sendStandardResponse(res, standardResponse, this.config)
+          return StandardServerNode.setStandardResponse(res as Response, standardResponse, this.config)
         }
       }),
     )

packages/nest/src/index.ts

@@ -1,3 +1,4 @@
+export * from './filters/orpc-exception.filter'
 export * from './implement'
 export { Implement as Impl } from './implement'
 export * from './module'