@hodfords/nestjs-exception NPM

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 };
    }
}