@hodfords/nestjs-response

Nestjs-Response is a simple yet powerful library for managing API responses in a NestJS application. It provides decorators to handle response models, allowing easy integration with Swagger for API documentation and validation.

Installation 🤖

To begin using it, we first install the required dependencies.

npm install @hodfords/nestjs-response

Interceptor Setup 🚀

• Global Interceptor (Recommended):

Global interceptors are applied across the entire application. To set up a global interceptor, you can register it in the providers array in your module.

import { APP_INTERCEPTOR } from '@nestjs/core';
import { ResponseInterceptor } from '@hodfords/nestjs-response';

@Module({
    providers: [
        {
            provide: APP_INTERCEPTOR,
            useClass: ResponseInterceptor
        }
    ]
})
export class AppModule {}

• Interceptor with Decorator:

For microservices or specific scenarios, use the @UseInterceptors decorator to apply interceptors at the controller or method level. However, it's generally recommended to use global interceptors.

import { Controller } from '@nestjs/common';
import { UseResponseInterceptor } from '@hodfords/nestjs-response';

@Controller()
@UseResponseInterceptor()
export class AppController {}

Usage 🚀

@ResponseModel()

Use the @ResponseModel decorator when an API return single response type.

Parameter:

• responseClass: The class that defines the response model.
• isArray (optional): Set to true if the response is an array of responseClass. Defaults to false.
• isAllowEmpty (optional): Set to true if the response can be empty. Defaults to false.

Example of usage:

import { ResponseModel } from '@hodfords/nestjs-response';
import { Get } from '@nestjs/common';
import { IsNotEmpty, IsString } from 'class-validator';

class UserResponse {
    @IsNotEmpty()
    @IsString()
    name: string;
}

export class UserController {
    @Get()
    @ResponseModel(UserResponse, true)
    getAllUser() {
        return [{ name: 'John' }];
    }
}

@ResponseModels()

Use the @ResponseModels decorator when an API might return multiple response types.

Parameter:

• ...responseClasses: A list of response classes or arrays of response classes.

Example of usage:

import { ResponseModels } from '@hodfords/nestjs-response';
import { Controller, Get, Param } from '@nestjs/common';
import { UserResponse } from './responses/user.response';
import { UserPaginationResponse } from './responses/user-pagination.response';

@Controller()
export class AppController {
    @Get('list-models/:type')
    @ResponseModels(Number, [Number], UserPaginationResponse, [UserResponse], undefined, null)
    getModels(@Param('type') type: string) {
        if (type == 'undefined') {
            return undefined;
        }
        if (type == 'pagination') {
            return {
                items: [{ name: 'John' }, { name: 'Daniel' }],
                total: 2,
                lastPage: 1,
                perPage: 10,
                currentPage: 1
            };
        }
        if (type == 'multiple') {
            return [{ name: 'John' }, { name: 'Daniel' }];
        }
        if (type == 'list-number') {
            return [123, 456];
        }
        if (type == 'number') {
            return 456;
        }
        return null;
    }
}

Exception Handling

When the response data does not match the expected model, a validation exception will be raised. This ensures that the API returns data conforming to the defined structure.

Example Case: If a property is expected to be a string, but a number is returned, a validation error will occur.

import { ResponseModel } from '@hodfords/nestjs-response';
import { Get } from '@nestjs/common';
import { IsString } from 'class-validator';

class UserResponse {
    @IsString()
    name: string;
}

export class UserController {
    @Get()
    @ResponseModel(UserResponse)
    getUser() {
        return { name: 123 }; // Error: name must be a number ...
    }
}

License

This project is licensed under the MIT License