feat: add response validation functionality to express, next and nest (#121)

* feat: run `zod` validation on response interceptor

* refactor: get app router from request context and throw server error

* feat: make response parsing opt-in

* feat: infer proper types for `initNestServer`

* cleanup some code and add tests

* feat: response validation for express and next

* docs: add docs for response validation

* chore: changeset

* fix: failing tests

* refactor: use @TsRest for everything, deprecate @Api

* fix: unused import

---------

Co-authored-by: Youssef Gaber <1728215+Gabrola@users.noreply.github.com>

Author: lukemorales

.changeset/silent-foxes-rescue.md

@@ -0,0 +1,9 @@
+---
+'@ts-rest/core': minor
+'@ts-rest/express': minor
+'@ts-rest/nest': minor
+'@ts-rest/next': minor
+---
+
+- Added server-side response validation feature
+- Deprecated `@Api` decorator, use `@TsRest` instead

apps/docs/docs/core/form-data.mdx

@@ -113,7 +113,7 @@ With Nest this is a pretty simple implementation, due to the extensible Decorato
 // nest
 @Controller()
 export class AppController implements NestControllerInterface<typeof c> {
-  @Api(s.route.updateUserAvatar)
+  @TsRest(s.route.updateUserAvatar)
   @UseInterceptors(FileInterceptor('avatar'))
   async updateUserAvatar(
     @TsRestRequest() { params: { id } }: RequestShapes['updateUserAvatar'],

apps/docs/docs/express.md

@@ -26,3 +26,13 @@ To handle JSON query parameters, you can use the `jsonQuery` option.
 ```typescript
 createExpressEndpoints(router, completeRouter, app, { jsonQuery: true });
 ```
+
+### Response Validation
+
+To enable response parsing and validation, you can use the `validateResponses` option.
+If there is a corresponding response Zod schema defined in the contract for the returned status code, the response will be parsed and validated.
+If validation fails a `ResponseValidationError` will be thrown causing a 500 response to be returned.
+
+```typescript
+createExpressEndpoints(router, completeRouter, app, { validateResponses: true });
+```

apps/docs/docs/nest.md

@@ -4,10 +4,10 @@ As opposed to the Express implementation, where we can infer types from a functi
 
 ```typescript
 import {
-  Api,
   nestControllerContract,
   NestControllerInterface,
   NestRequestShapes,
+  TsRest,
   TsRestRequest,
 } from '@ts-rest/nest';
 
@@ -18,7 +18,7 @@ type RequestShapes = NestRequestShapes<typeof c>;
 export class PostController implements NestControllerInterface<typeof c> {
   constructor(private readonly postService: PostService) {}
 
-  @Api(c.getPost)
+  @TsRest(c.getPost)
   async getPost(@TsRestRequest() { params: { id } }: RequestShapes['getPost']) {
     const post = await this.postService.getPost(id);
 
@@ -37,38 +37,56 @@ To implement a nested contract, you can simply call `nestControllerContract(cont
 
 Having the controller class implement `NestControllerInterface` ensures that your controller implements all the routes defined in the contract. In addition, it ensures the type safety of the responses returned.
 
-The `@Api` decorator takes the route, defines the path and method for the controller route.
+The `@TsRest` decorator takes the route, defines the path and method for the controller route and also configures ts-rest options.
 
 The `@TsRestRequest` decorator takes the contract route defined in the `@Api` decorator, and returns the parsed and validated (if using Zod) request params, query and body.
 
 As Typescript cannot infer class method parameter types from an implemented interface, we need to explicitly define the type for the request parameter using the `NestRequestShapes` type. 
 
-## JSON Query Parameters
+## Configuration
+
+To configure certain ts-rest options you can use the `@TsRest` decorator on either your Controller or use the existing `@Api` decorator.
+
+### JSON Query Parameters
 
-To handle JSON query parameters, you can use the `@JsonQuery()` decorator on either your Controller classes or individual endpoint methods.
+To handle JSON query parameters, pass the `jsonQuery` option to the `@TsRest` decorator on your entire controller.
 
 ```typescript
 @Controller()
-@JsonQuery()
+@TsRest({ jsonQuery: true })
 export class PostController implements NestControllerInterface<typeof c> {}
 ```
 
-The method decorator can be useful to override the controller's behaviour on a per-endpoint basis.
+You can also use the method decorator to override or configure options for a specific route.
 
 ```typescript
 @Controller()
-@JsonQuery()
+@TsRest({ jsonQuery: true })
 export class PostController implements NestControllerInterface<typeof c> {
   constructor(private readonly postService: PostService) {}
 
-  @Api(s.route.getPost)
-  @JsonQuery(false)
+  @TsRest(s.route.getPost, { jsonQuery: false })
   async getPost(@TsRestRequest() { params: { id } }: RequestShapes['getPost']) {
     // ...
   }
 }
 ```
 
+### Response Validation
+
+You can enable response validation by passing the `validateResponses` option to the `@TsRest()` decorator.
+This will enable response parsing and validation for a returned status code, if there is a corresponding response Zod schema defined in the contract.
+This is useful for ensuring absolute safety that your controller is returning the correct response types as well as stripping any extra properties.
+
+```typescript
+@Controller()
+@TsRest({ validateResponses: true })
+export class PostController implements NestControllerInterface<typeof c> {}
+```
+
+If validation fails a `ResponseValidationError` will be thrown causing a 500 response to be returned.
+You can catch this error and handle it as you wish by using a [NestJS exception filter](https://docs.nestjs.com/exception-filters).
+
 ## Explicit Response Type Safety
 
 In cases where you do not want to implement `NestControllerInterface`.
@@ -91,7 +109,7 @@ type ResponseShapes = NestResponseShapes<typeof c>;
 export class PostController {
   constructor(private readonly postService: PostService) {}
 
-  @Api(c.getPost)
+  @TsRest(c.getPost)
   async getPost(
     @TsRestRequest() { params: { id } }: RequestShapes['getPost']
   ): Promise<ResponseShapes['getPost']> {

apps/docs/docs/next.md

@@ -38,6 +38,34 @@ To handle JSON query parameters, you can use the `jsonQuery` option.
 export default createNextRouter(api, router, { jsonQuery: true });
 ```
 
+### Response Validation
+
+To enable response parsing and validation, you can use the `validateResponses` option.
+If there is a corresponding response Zod schema defined in the contract for the returned status code, the response will be parsed and validated.
+If validation fails a `ResponseValidationError` will be thrown causing a 500 response to be returned.
+
+```typescript
+export default createNextRouter(api, router, { validateResponses: true });
+```
+
+### Error Handling
+
+You can create a global error handler to handle any thrown errors by using the `errorHandler` option.
+This includes response validation errors.
+
+```typescript
+export default createNextRouter(api, router, {
+  responseValidation: true,
+  errorHandler: (error: unknown, req: NextApiRequest, res: NextApiResponse) => {
+    if (error instanceof ResponseValidationError) {
+      console.log(error.cause);
+      return res.status(500).json({ message: 'Internal Server Error' });
+    }
+  },
+});
+```
+
+
 ## Future Work
 
 As this pattern doesn't support a lambda per endpoint, it is planned to provide a helper utility to allow individual endpoints to be created.

apps/docs/docs/quickstart.mdx

@@ -111,14 +111,14 @@ type RequestShapes = NestRequestShapes<typeof c>;
 export class PostController implements NestControllerInterface<typeof c> {
   constructor(private readonly postService: PostService) {}
 
-  @Api(c.getPost)
+  @TsRest(c.getPost)
   async getPost(@TsRestRequest() { params: { id } }: RequestShapes['getPost']) {
     const post = await this.postService.getPost(id);
 
     return { status: 200 as const, body: post };
   }
 
-  @Api(c.createPost)
+  @TsRest(c.createPost)
   async createPost(@TsRestRequest() { body }: RequestShapes['createPost']) {
     const post = await this.postService.createPost({
       title: body.title,

apps/example-express/src/main.ts

@@ -1,9 +1,11 @@
 import * as express from 'express';
+import { initContract, ResponseValidationError } from '@ts-rest/core';
 import { apiBlog, contractTs } from '@ts-rest/example-contracts';
 import { createExpressEndpoints, initServer } from '@ts-rest/express';
+import { generateOpenApi } from '@ts-rest/open-api';
 import * as bodyParser from 'body-parser';
+import { Request, Response, NextFunction } from 'express';
 import { serve, setup } from 'swagger-ui-express';
-import { generateOpenApi } from '@ts-rest/open-api';
 import { mockPostFixtureFactory } from './fixtures';
 import cors = require('cors');
 import { tsRouter } from './ts-router';
@@ -78,6 +80,13 @@ const completedRouter = s.router(apiBlog, {
   },
 });
 
+const validateResponseContact = initContract().router({
+  testPathParams: {
+    ...apiBlog.testPathParams,
+    path: '/validate-response/:id/:name',
+  },
+});
+
 const openapi = generateOpenApi(apiBlog, {
   info: { title: 'Play API', version: '0.1' },
 });
@@ -95,6 +104,30 @@ app.get('/test', (req, res) => {
 
 createExpressEndpoints(apiBlog, completedRouter, app);
 createExpressEndpoints(contractTs, tsRouter, app, { jsonQuery: true });
+createExpressEndpoints(
+  validateResponseContact,
+  s.router(validateResponseContact, {
+    testPathParams: async ({ params, query }) => {
+      return {
+        status: 200,
+        body: {
+          ...params,
+          ...query,
+        },
+      };
+    },
+  }),
+  app,
+  { responseValidation: true }
+);
+
+app.use((err: any, req: Request, res: Response, next: NextFunction) => {
+  if (err instanceof ResponseValidationError) {
+    console.error(err.cause);
+  }
+
+  next(err);
+});
 
 const port = process.env.port || 3333;
 const server = app.listen(port, () => {

apps/example-express/src/tests/posts-response-validation.spec.ts

@@ -0,0 +1,24 @@
+import * as supertest from 'supertest';
+import app from '../main';
+
+const superTestApp = supertest(app);
+
+describe('Posts Endpoints w/ Response Validation', () => {
+  it('should include default value and removes extra field', async () => {
+    const res = await superTestApp.get('/validate-response/123/name?field=foo');
+
+    expect(res.status).toStrictEqual(200);
+    expect(res.body).toStrictEqual({
+      id: 123,
+      name: 'name',
+      defaultValue: 'hello world',
+    });
+  });
+
+  it('fails with invalid field', async () => {
+    const res = await superTestApp.get('/validate-response/2000/name');
+
+    expect(res.status).toStrictEqual(500);
+    expect(res.body).toStrictEqual({});
+  });
+});

apps/example-microservice/users-service/src/app/app.controller.ts

@@ -1,11 +1,11 @@
 import { Controller, UploadedFile, UseInterceptors } from '@nestjs/common';
 import { usersApi } from '@ts-rest/example-microservice/util-users-api';
 import {
-  Api,
   TsRestRequest,
   nestControllerContract,
   NestControllerInterface,
   NestRequestShapes,
+  TsRest,
 } from '@ts-rest/nest';
 import { AppService } from './app.service';
 import { FileInterceptor } from '@nestjs/platform-express';
@@ -18,7 +18,7 @@ type RequestShapes = NestRequestShapes<typeof c>;
 export class AppController implements NestControllerInterface<typeof c> {
   constructor(private readonly appService: AppService) {}
 
-  @Api(c.getUser)
+  @TsRest(c.getUser)
   async getUser(@TsRestRequest() { params: { id } }: RequestShapes['getUser']) {
     return {
       status: 200 as const,
@@ -30,7 +30,7 @@ export class AppController implements NestControllerInterface<typeof c> {
     };
   }
 
-  @Api(c.updateUserAvatar)
+  @TsRest(c.updateUserAvatar)
   @UseInterceptors(FileInterceptor('avatar'))
   async updateUserAvatar(
     @TsRestRequest() { params: { id } }: RequestShapes['updateUserAvatar'],

apps/example-nest/src/app/post-json-query.controller.ts

@@ -1,9 +1,8 @@
 import { Controller } from '@nestjs/common';
 import { apiBlog } from '@ts-rest/example-contracts';
 import {
-  Api,
   TsRestRequest,
-  JsonQuery,
+  TsRest,
   nestControllerContract,
   NestControllerInterface,
   NestRequestShapes,
@@ -24,14 +23,14 @@ const c = nestControllerContract({
 });
 type RequestShapes = NestRequestShapes<typeof c>;
 
-@JsonQuery()
+@TsRest({ jsonQuery: true })
 @Controller()
 export class PostJsonQueryController
   implements NestControllerInterface<typeof c>
 {
   constructor(private readonly postService: PostService) {}
 
-  @Api(c.getPosts)
+  @TsRest(c.getPosts)
   async getPosts(
     @TsRestRequest()
     { query: { take, skip, search } }: RequestShapes['getPosts']