Standard approach

Using the standard and recommended approach, which has been available since Nest.js 4, Nest.js will automatically serialize the JavaScript object or array returned from the handler method to JSON and send it in the response body. If a string is returned, Nest.js will just send the string without serializing it to JSON.

The default response status code is 200, expect for POST requests, which uses 201. The response code for can easily be changed for a handler method by using the @HttpCode(...) decorator. For example:

@HttpCode(204)
@Post()
create() {
  // This handler will return a 204 status response
}

Express approach

An alternate approach to generating responses in Nest.js is to use a response object directly. You can ask Nest.js to inject a response object into a handler method using the @Res() decorator. Nest.js uses express response objects].

You can rewrite the response handler seen earlier using a response object as shown here.

import { Controller, Get, Res } from '@nestjs/common';
import { Response } from 'express';

@Controller('entries')
export class EntryController {
    @Get()
    index(@Res() res: Response) {
        const entries: Entry[] = this.entriesService.findAll();
        return res.status(HttpStatus.OK).json(entries);
    }
}

The express response object is used directly to serialize the entries array to JSON and send a 200 status code response.

The typings for the Response object come from express. Add the @types/express package to your devDependencies in package.json to use these typings.

Async/await

Nest.js has support for async request handler functions.

In our example application, the entriesService.findAll() function actually returns a Promise<Entry[]>. Using async and await, this function could be written as follows.

import { Controller, Get } from '@nestjs/common';

@Controller('entries')
export class EntryController {
    @Get()
    async index(): Promise<Entry[]> {
        const entries: Entry[] = await this.entryService.findAll();
        return entries;
    }

Async functions have to return promises, but using the async/await pattern in modern JavaScript, the handler function can appear to be synchronous. Next, we’ll resolve the returned promise and generate the response.

Promise

Similarly, you can also just return a promise from a handler function directly without using async/await.

import { Controller, Get } from '@nestjs/common';

@Controller('entries')
export class EntryController {
    @Get()
    index(): Promise<Entry[]> {
        const entriesPromise: Promise<Entry[]> = this.entryService.findAll();
        return entriesPromise;
    }

Observables

Nest.js request handlers can also return RxJS Observables.

For example, if entryService.findAll() were to return an Observable of entries instead of a Promise, the following would be completely valid.

import { Controller, Get } from '@nestjs/common';

@Controller('entries')
export class EntryController {
    @Get()
    index(): Observable<Entry[]> {
        const entriesPromise: Observable<Entry[]> = this.entryService.findAll();
        return entriesPromise;
    }

There is no recommended way to write asynchronous request handlers. Use whichever method you are most comfortable with.

HttpException

If an exception thrown from a request handler is a HttpException, the global exception filter will transform it to the a JSON response.

For example, you can throw an HttpException from the create() handler function if the body is not valid as shown.

import { Body, Controller, HttpException, HttpStatus, Post } from '@nestjs/common';

@Controller('entries')
export class EntryController {
    @Post()
    create(@Body() entry: Entry) {
        if (!entry) throw new HttpException('Bad request', HttpStatus.BAD_REQUEST);
        this.entryService.create(entry);
    }
}

If this exception is thrown, the response would look like this:

{
    "statusCode": 400,
    "message": "Bad request"
}

You can also completely override the response body by passing an object to the HttpException constructor as follows.

import { Body, Controller, HttpException, HttpStatus, Post } from '@nestjs/common';

@Controller('entries')
export class EntryController {
    @Post()
    create(@Body() entry: Entry) {
        if (!entry) throw new HttpException({ status: HttpStatus.BAD_REQUEST, error: 'Entry required' });
        this.entryService.create(entry);
    }
}

If this exception is thrown, the response would look like this:

{
    "statusCode": 400,
    "error": "Entry required"
}

Unrecognized exceptions

If the exception is not recognized, meaning it is not HttpException or a class that inherits from HttpException, then the client will receive the JSON response below.

{
    "statusCode": 500,
    "message": "Internal server error"
}