import { InstallTabs } from '@site/src/components/InstallTabs';

# Nest 🆕

:::info
As part of `@ts-rest/nest` 3.26.0 we introduced the `single-handler` and `multi-handler` approach to Nest with ts-rest, for the legacy approach please see [here](/docs/nest/legacy/).

The old API will likely be deprecated in 4.0.0, so we recommend using the new API although there is no rush to migrate.
:::

## Installation

<InstallTabs packageName="@ts-rest/nest" />

## Approaches

Nest has always been a tricky framework to integrate with ts-rest, due to the way Nest handles routing and controllers. Nest normally uses large amounts of untyped decorators for each route, with ts-rest we introduce two new approaches to handle most of the heavy lifting for you.

### Single Handler Approach - Easy Migration and Flexibility ⚡️

We reccomend the single handler approach as it provides a 1-1 migration stategy for legacy controllers, you can swap one Nest route for one ts-rest route without affecting other routes in a Controller.

```typescript
import { TsRestHandler, tsRestHandler } from '@ts-rest/nest';
import { c } from './contract';

@Controller()
export class MyController {
  constructor(private readonly service: Service) {}

  @TsRestHandler(c.getPost)
  async getPost() {
    return tsRestHandler(c.getPost, async ({ params }) => {
      const post = await this.service.getPost(params.id);

      if (!post) {
        return { status: 404, body: null };
      }

      return { status: 200, body: post };
    });
  }

  @TsRestHandler(c.getPosts)
  async getPosts() {
    return tsRestHandler(c.getPosts, async () => {
      const posts = await this.service.getPosts();

      return { status: 200, body: posts };
    });
  }
}
```

:::note
Just like in regular Nest endpoints the names of the methods do not matter, you can name them whatever you like.
:::

You may be wondering why do we return `tsRestHandler` from this method, all this function does is return the second argument. The _only_ reason this exists is to provide you a fully typed `implementation` object which matches 1-1 with the way the `@ts-rest/next`, `@ts-rest/express` and `@ts-rest/fastify` packages work.

#### Benefits

- 1-1 migration strategy
- Able to not have a one to one relationship between your contract and controllers
  - You are able to implement one ts-rest contract across multiple controllers based on your domain.

### Multi Handler Approach - Ultimate Type Safety 🛡️

The multi handler approach is fantastic for those of you who tend towards a more functional approach to your code, or if you want to ensure that your controller methods are **always** returning the correct response types.

```typescript
import { TsRestHandler, tsRestHandler } from '@ts-rest/nest';
import { c } from './contract';

@Controller()
export class MyController {
  constructor(private readonly service: Service) {}

  @TsRestHandler(c)
  async handler() {
    return tsRestHandler(c, {
      getPost: async ({ params }) => {
        const post = await this.service.getPost(params.id);

        if (!post) {
          return { status: 404, body: null };
        }

        return { status: 200, body: post };
      },
      getPosts: async () => {
        const posts = await this.service.getPosts();

        return { status: 200, body: posts };
      },
    });
  }
}
```

The key difference here is you pass the entire contract (or a subset of a contract by defining a new contract or spreading multiple contracts) to the `@TsRestHandler` decorator and the `tsRestHandler` function.

:::caution

As of right now, for each route in a multi handler approach we instantiate the `@All` decorator for each route, this is _potentially_ problematic if you have the same route in multiple contracts (with different methods), as it will cause a conflict.

We're looking into ways to solve this, but right now this may be a Nest limitation.
:::

#### Benefits

- Less room for error, you are forced to implement all routes in a contract
- Less boilerplate
- Easier to move code between `@ts-rest/next`, `@ts-rest/express` and `@ts-rest/fastify` servers

## Using Nest Decorators

Despite using `@TsRestHandler` rather than `@Get` or `@Post` (etc.) you can still use all of the existing Nest decorators on your controller methods.

```typescript
import { TsRestHandler, tsRestHandler } from '@ts-rest/nest';

@Controller()
export class MyController {
  constructor(private readonly service: Service) {}

  @TsRestHandler(c.test)
  async myMethod(@Req() req: Request) {
    return tsRestHandler(c.test, async ({ params }) => {
      // ...

      console.log(req.headers);
      // ^ You can still use Nest decorators
    });
  }
}
```

In this example above we're using the `@Req` decorator to get access to the `Request` object, this is a great example of how you can use Nest decorators to get access to the underlying request/response objects.

This isn't limited to Param decorators, you can use any Nest decorator on your controllers as you would normally.

## Throwing Type-Safe Errors 🍀

Generally speaking you should try to return all errors as a response, so that you get the benefits of `ts-rest` typing in the contract (to let your consumers know what errors to expect).

However, sometimes it's much cleaner and simpler to throw an error rather than passing a response back to your handler - the problem is that you normally **loose all type safety** when you do this.

With `TsRestException` you can throw a Nest exception and it will be handled by the `tsRestHandler` function and returned as a fully typed response.

```typescript
throw new TsRestException(contract.test, {
  status: 400,
  body: { code: 'UserAlreadySignedUp', message: 'User has already signed up' },
});
```

This example above will provide you autocomplete for the given `status` within the `contract.test` responses contract.

:::caution

The only risk of doing it this way is that you throw the wrong exception for a given route, which can happen if you throw from a piece of code used by multiple routes. If you want to be 100% sure you are throwing the correct exception you should use the `tsRestHandler` function to return the response.

This can be somewhat mitigated if you share the error code schema between multiple routes, so that you can't throw the wrong error code.

:::

## 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, 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.

```typescript
import { TsRestHandler, tsRestHandler } from '@ts-rest/nest';

@Controller()
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 })
  async getPost() {
    return tsRestHandler(c.getPost, async () => {
      // ...
    });
  }
}
```

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

Currently any existing Nest global prefix, versioning, or controller prefixes will be ignored, please see https://github.com/ts-rest/ts-rest/issues/70 for more details.

If this feature is highly requested, we can investigate a solution.

We have added the ability to [prefix paths](/docs/core/#path-prefix), allowing more flexibility in defining your API endpoints. This can be used as a workaround for this functionality.
:::
