feat(nest): add global configuration through nest module (#519)

Author: Gabrola

.changeset/unlucky-pets-attack.md

@@ -0,0 +1,5 @@
+---
+'@ts-rest/nest': minor
+---
+
+Add functionality to be able to set configuration options globally using `TsRestModule`

apps/docs/docs/nest/configuration.md

@@ -0,0 +1,80 @@
+# Configuration
+
+There are a number of configuration options that you can use to customize the behavior of `ts-rest` in your Nest application.
+
+## Configuration Options
+
+### jsonQuery
+
+#### Default value: `false`
+
+By default, all query parameters are encoded as strings, however, you can use the `jsonQuery` option to encode query parameters as typed JSON values.
+
+### validateResponses
+
+#### Default value: `false`
+
+You can enable response parsing and validation for defined response status codes, if there are 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.
+
+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).
+
+### Request Validation
+
+By default, `ts-rest` validates all request components - body, headers and query parameters.
+In case of validation errors, the server responds with a `ZodError` object in the response body and a status code of 400.
+You can disable the validation of these components if you wish to perform the validation manually or handle the error differently.
+
+#### Options
+
+- `validateRequestBody`
+- `validateRequestQuery`
+- `validateRequestHeaders`
+
+#### Default values: `true`
+
+```typescript
+import { TsRestHandler, tsRestHandler } from '@ts-rest/nest';
+
+@Controller()
+export class MyController {
+  constructor() {}
+
+  @TsRestHandler(c.getPost, {
+    validateRequestBody: false,
+    validateRequestQuery: false,
+    validateRequestHeaders: false
+  })
+  async getPost() {
+    return tsRestHandler(c.getPost, async ({ query, body }) => {
+      const isQueryValid = querySchema.safeParse(query);
+      console.log(isQueryValid) // => { success: false; error: ZodError }
+
+      const isBodyValid = bodySchema.safeParse(body);
+      console.log(isBodyValid) // => { success: true; data: {...} }
+    });
+  }
+}
+```
+
+## Global Configuration
+
+Configuring the different configuration options for each controller might get a bit cumbersome.
+To make it easier, you can set global options that will be used by all controllers in your Nest module, or globally across your application if you specify `isGlobal`.
+
+```typescript
+import { Module } from '@nestjs/common';
+import { TsRestModule } from '@ts-rest/nest';
+
+@Module({
+  imports: [
+    TsRestModule.register({
+      isGlobal: true,
+      jsonQuery: true,
+      validateResponses: true,
+    }),
+  ],
+})
+export class AppModule {}
+```

apps/docs/docs/nest/legacy.mdx

@@ -14,13 +14,17 @@ import { InstallTabs } from '@site/src/components/InstallTabs';
   }}
 />
 
+:::info
+
 As part of the [v3.26.0](https://github.com/ts-rest/ts-rest) we released the new `SingleHandler` and `MultiHandler` approaches to implementing your API contracts.
 
 We don't have any immediate plans to deprecate the old approach, but we do recommend using the new approach as it is more flexible and allows for more control over your API implementation.
 
 If we do make a v4 release, we will likely deprecate the old approach.
 
-::: ## Installation
+:::
+
+## Installation
 
 <InstallTabs packageName="@ts-rest/nest" />
 
@@ -71,19 +75,10 @@ As Typescript cannot infer class method parameter types from an implemented inte
 
 ## Configuration
 
-To configure certain ts-rest options you can use the `@TsRest` decorator on either your Controller or use the existing `@Api` decorator.
+To configure `ts-rest` options you can use the `@TsRest` decorator on either your controller or use the existing `@TsRest` decorator on your method.
+Controller options will be applied to all routes in the controller and will override any global options, and method options will override the controller options for that specific route.
 
-### JSON Query Parameters
-
-To handle JSON query parameters, pass the `jsonQuery` option to the `@TsRest` decorator on your entire controller.
-
-```typescript
-@Controller()
-@TsRest({ jsonQuery: true })
-export class PostController implements NestControllerInterface<typeof c> {}
-```
-
-You can also use the method decorator to override or configure options for a specific route.
+Check out the [configuration](/docs/nest/configuration/) section for more details on the different configuration options, or on how to configure options globally.
 
 ```typescript
 @Controller()
@@ -98,29 +93,13 @@ export class PostController implements NestControllerInterface<typeof c> {
 }
 ```
 
-### 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`.
 Say, if you were to implement a contract's non-nested routes across multiple controllers, or use different class method names than the ones defined in your contract, you can still ensure type safety of the responses by using the `NestResponseShapes` type.
 
 ```typescript
 import {
-  Api,
   nestControllerContract,
   NestRequestShapes,
   NestResponseShapes,

apps/docs/docs/nest/nest.mdx

@@ -167,125 +167,18 @@ This can be somewhat mitigated if you share the error code schema between multip
 
 ## Configuration
 
-To configure certain ts-rest options you can use the `@TsRest` decorator on either your Controller or use the existing `@Api` decorator.
+To configure `ts-rest` options you can use the `@TsRest` decorator on either your controller or use the existing `@TsRestHandler` decorator on your method.
+Controller options will be applied to all routes in the controller and will override any global options, and method options will override the controller options for that specific route.
 
-### JSON Query Parameters
-
-To handle JSON query parameters, pass the `jsonQuery` option to the `@TsRest` decorator on your entire controller.
-
-```typescript
-import { TsRest } from '@ts-rest/nest';
-
-@Controller()
-@TsRest({ jsonQuery: true })
-export class MyController {}
-```
-
-You can also use the method decorator to override or configure options for a specific route.
+Check out the [configuration](/docs/nest/configuration/) section for more details on the different configuration options, or on how to configure options globally.
 
 ```typescript
 import { TsRestHandler, tsRestHandler } from '@ts-rest/nest';
 
 @Controller()
+@TsRest({ jsonQuery: true })
 export class MyController {
-  constructor(private readonly service: Service) {}
-
-  @TsRestHandler(c.getPost, { jsonQuery: true })
-  async getPost() {
-    return tsRestHandler(c.getPost, async () => {
-      // ...
-    });
-  }
-}
-```
-
-### Request Validation
-By default, `ts-rest` validates all request components - body, headers and query parameters.
-In case of validation errors, the server responds with a `ZodError` object in the response body and a status code of 400.
-You can disable the validation of these components if you wish to perform the validation manually or handle the error differently.
-
-Using the `@TsRest()` decorator, you can configure request validation parameters for the entire controller:
-```typescript
-import { TsRest } from '@ts-rest/nest';
-
-@Controller()
-@TsRest({
-  validateRequestBody: false,
-  validateRequestQuery: false,
-  validateRequestHeaders: false
-})
-class MyController {}
-```
-
-You can also override controller decorator values for a specific route:
-
-```typescript
-import { TsRest } from '@ts-rest/nest';
-
-@Controller()
-@TsRest({
-  validateRequestBody: false,
-})
-class MyController {
-  @TsRest(contract.create, {
-    validateRequestBody: true
-  })
-  async create(@TsRestRequest() { body }) {
-    // body validated
-  }
-}
-```
-
-Or finally, using `@TsRestHandler()` for specific route:
-
-```typescript
-import { TsRestHandler, tsRestHandler } from '@ts-rest/nest';
-
-@Controller()
-export class MyController {
-  constructor() {}
-
-  @TsRestHandler(c.getPost, {
-    validateRequestBody: false,
-    validateRequestQuery: false,
-    validateRequestHeaders: false
-  })
-  async getPost() {
-    return tsRestHandler(c.getPost, async ({ query, body }) => {
-      const isQueryValid = querySchema.safeParse(query);
-      console.log(isQueryValid) // => { success: false; error: ZodError }
-
-      const isBodyValid = bodySchema.safeParse(body);
-      console.log(isBodyValid) // => { success: true; data: {...} }
-    });
-  }
-}
-```
-
-### 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
-import { TsRest } from '@ts-rest/nest';
-
-@Controller()
-@TsRest({ validateResponses: true })
-export class MyController {}
-```
-
-You can also use the method decorator to override or configure options for a specific route.
-
-```typescript
-import { TsRestHandler, tsRestHandler } from '@ts-rest/nest';
-
-@Controller()
-export class MyController {
-  constructor(private readonly service: Service) {}
-
-  @TsRestHandler(c.getPost, { validateResponses: true })
+  @TsRestHandler(c.getPost, { jsonQuery: false })
   async getPost() {
     return tsRestHandler(c.getPost, async () => {
       // ...
@@ -294,9 +187,6 @@ export class MyController {
 }
 ```
 
-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).
-
 ## Gotchas
 
 :::caution

apps/docs/sidebars.js

@@ -93,6 +93,7 @@ const sidebars = {
       items: [
         { type: 'doc', id: 'nest/nest' },
         { type: 'doc', id: 'nest/legacy' },
+        { type: 'doc', id: 'nest/configuration' },
       ],
     },
     {

libs/ts-rest/nest/src/index.ts

@@ -1,7 +1,8 @@
 export * from './lib/constants';
-export * from './lib/json-query.decorator';
 export * from './lib/ts-rest-nest';
 export * from './lib/ts-rest.decorator';
 export * from './lib/ts-rest.interceptor';
 export * from './lib/ts-rest-request.decorator';
 export * from './lib/ts-rest-nest-handler';
+export { TsRestModule } from './lib/ts-rest.module';
+export { TsRestOptions } from './lib/ts-rest-options';

libs/ts-rest/nest/src/lib/constants.ts

@@ -1,12 +1,2 @@
 export const TsRestAppRouteMetadataKey = Symbol('ts-rest-app-route');
-export const JsonQuerySymbol = Symbol('ts-rest-json-query');
-export const ValidateResponsesSymbol = Symbol('ts-rest-validate-responses');
-export const ValidateRequestHeadersSymbol = Symbol(
-  'ts-rest-validate-request-headers',
-);
-export const ValidateRequestQuerySymbol = Symbol(
-  'ts-rest-validate-request-query',
-);
-export const ValidateRequestBodySymbol = Symbol(
-  'ts-rest-validate-request-body',
-);
+export const TsRestOptionsMetadataKey = Symbol('ts-rest-options');