Skip to main content

@hodfords/nestjs-exception

Nest Logo

This repository contains a set of custom exception filters and exceptions designed for use in a NestJS application. It enhances error handling for HTTP-based and microservice-based (gRPC, Kafka) applications by providing more meaningful error responses and localization support.

Installation 🤖​

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

npm install @hodfords/nestjs-exception

Exception Classes​

Note: These exception classes only function when used alongside the HttpExceptionFilter or one of its child classes (GrpcExceptionFilter, KafkaExceptionFilter, etc.). Be sure to apply the appropriate filter in your application.

1. UuidException

This exception is used to handle invalid UUID formats in requests. It returns a 400 BAD_REQUEST status.

Parameters:

  • field: The name of the field that contains the invalid UUID. This value is passed to indicate which field caused the exception.

2. ValidateException

Handles specific validation errors related to a particular field. Returns a 422 UNPROCESSABLE_ENTITY status.

Parameters:

  • property: The field name that caused the validation error.
  • message: The detailed message for the validation error.
  • constraint: The validation constraint that was violated (e.g., notNull).
  • detail: Additional information for the validation error, if applicable.

Exception Filters​

  • HttpExceptionFilter: Handles various types of HTTP exceptions with localization support.

  • GrpcExceptionFilter: Handles exceptions for gRPC microservices, formatting errors for gRPC clients.

  • KafkaExceptionFilter: Manages exceptions in Kafka microservices, formatting errors for Kafka messaging.

  • ValidatorExceptionFilter: Catches validation errors (ValidateException), supporting nested object validation and localization.

Note on Translation: These filters, especially HttpExceptionFilter and ValidatorExceptionFilter, rely on a translation service to provide localized error messages. Ensure that your application has translation support enabled (e.g., using @hodfords/nestjs-cls-translation). The filters use translation keys defined in your language files to dynamically translate error messages based on the request's language.

Example of usage​

To use the exception classes and filters in your NestJS application, follow these steps:

1. Applying the HttpExceptionFilter​

Global Application:

import { HttpExceptionFilter } from '@hodfords/nestjs-exception';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
    const app = await NestFactory.create(AppModule);
    app.useGlobalFilters(new HttpExceptionFilter());
    await app.listen(3000);
}
bootstrap();

Controller-Level Application:

import { Controller, UseFilters } from '@nestjs/common';
import { HttpExceptionFilter } from 'hodfords/nestjs-exception';

@Controller('users')
@UseFilters(HttpExceptionFilter)
export class UserController {}

2. Throwing a Custom Exception​

import { UuidException } from '@hodfords/nestjs-exception';

@Controller('users')
export class UserController {
    @Get(':id')
    getUser(@Param('id') id: string) {
        if (!isValidUUID(id)) {
            throw new UuidException('id'); // Translation key: 'error.field_malformed'
        }
        return { id };
    }
}

License​

This project is licensed under the MIT License