nestjs-exception-handler 4.2.0 → 4.4.0

package/README.md

@@ -3,17 +3,31 @@
 [![npm version](https://badge.fury.io/js/nestjs-exception-handler.svg)](https://badge.fury.io/js/nestjs-exception-handler)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A production-grade global exception handling system for NestJS applications that provides standardized error responses, supports Prisma errors, DTO validation, HTTP exceptions, and more.
+A production-grade global exception handling system for NestJS applications that provides **consistent global error response format** for all types of errors.
+
+## Why This Package Exists
+
+When building NestJS applications, error handling can become inconsistent across different scenarios:
+
+- ValidationPipe errors from class-validator
+- HttpException thrown manually
+- Prisma database errors
+- Unexpected internal server errors
+
+This package ensures **every error response follows the same standardized format**, making your API consistent and easier to consume by clients.
 
 ## Features
 
-- **Standardized Error Responses**: Consistent error format across your application
-- **Prisma Integration**: Built-in support for Prisma error codes (P2002, P2003, etc.)
-- **DTO Validation**: Automatic extraction of validation errors from class-validator
-- **HTTP Exception Support**: Handles all NestJS HTTP exceptions
+- **Standardized Error Responses**: Consistent error format across your entire application
+- **ValidationPipe Support**: Automatic extraction and normalization of class-validator errors
+- **Prisma Integration**: Built-in support for Prisma error codes (P2002, P2003, P2005, P2006, P2025)
+- **HttpException Handling**: Handles all NestJS HTTP exceptions with proper formatting
+- **404 Route Handling**: Converts unmatched routes to standardized format
+- **Unknown Error Handling**: Safe fallback for unexpected errors without leaking stack traces
 - **Extensible**: Plugin system for custom formatters
-- **Type Safe**: Full TypeScript support
-- **Production Ready**: Includes logging and stack trace control
+- **Type Safe**: Full TypeScript support with zero `any` types
+- **Production Ready**: Configurable logging and stack trace control
+- **NestJS v9 & v10 Compatible**: Works with both major versions
 
 ## Installation
 
@@ -21,204 +35,387 @@ A production-grade global exception handling system for NestJS applications that
 npm install nestjs-exception-handler
 ```
 
-## Quick Start
+Or with yarn:
 
-### 1. Import the module
+```bash
+yarn add nestjs-exception-handler
+```
 
-```typescript
-import { Module } from '@nestjs/common';
-import { ExceptionHandlerModule } from 'nestjs-exception-handler';
+## Quick Setup
 
-@Module({
-  imports: [ExceptionHandlerModule.forRoot()],
-})
-export class AppModule {}
-```
+### 1. Apply the Global Filter
 
-### 2. Apply the global filter
+The simplest way to use the package is to apply the global exception filter:
 
 ```typescript
 import { NestFactory } from '@nestjs/core';
 import { AppModule } from './app.module';
 import { GlobalExceptionFilter } from 'nestjs-exception-handler';
+import { ValidationPipe } from '@nestjs/common';
 
 async function bootstrap() {
   const app = await NestFactory.create(AppModule);
 
-  const filter = app.get(GlobalExceptionFilter);
-  app.useGlobalFilters(filter);
+  app.useGlobalPipes(
+    new ValidationPipe({
+      whitelist: true,
+      transform: true,
+    }),
+  );
+
+  app.useGlobalFilters(new GlobalExceptionFilter());
 
   await app.listen(3000);
 }
 bootstrap();
 ```
 
-## Configuration
+### 2. Using with Module Registration (Optional)
+
+For more control, you can use the module registration:
 
 ```typescript
-ExceptionHandlerModule.forRoot({
-  enableLogging: true, // Enable structured logging
-  hideStackTrace: true, // Hide stack traces in production
-});
+import { Module } from '@nestjs/common';
+import { ExceptionHandlerModule } from 'nestjs-exception-handler';
+
+@Module({
+  imports: [
+    ExceptionHandlerModule.forRoot({
+      enableLogging: true,
+      hideStackTrace: true,
+    }),
+  ],
+})
+export class AppModule {}
 ```
 
-## Standard Error Response Format
+## Error Response Format
 
-All responses follow this structure:
+Every error response follows this exact structure:
+
+```typescript
+interface ErrorResponse {
+  success: false;
+  message: string;
+  errorMessages: {
+    path: string;
+    message: string[];
+  }[];
+}
+```
+
+### Example Response
 
 ```json
 {
   "success": false,
-  "message": "Database error",
+  "message": "Bad Request Exception",
   "errorMessages": [
     {
-      "path": "email",
-      "message": "User with this email already exists"
+      "path": "http_error",
+      "message": ["email must be an email", "password must be longer than 8 characters"]
     }
   ]
 }
 ```
 
-## Supported Error Types
+## Validation Example
 
-### Prisma Errors
+When using ValidationPipe with class-validator, errors are automatically normalized:
 
-Handles all Prisma error types with automatic path extraction:
+```typescript
+// DTO
+import { IsEmail, IsString, MinLength } from 'class-validator';
 
-- `P2002` - Unique constraint violation
-- `P2003` - Foreign key constraint violation
-- `P2005` - Invalid value
-- `P2006` - Invalid format
-- `P2025` - Record not found
+export class CreateUserDto {
+  @IsEmail()
+  email: string;
+
+  @IsString()
+  @MinLength(8)
+  password: string;
+}
+```
 
-**Example:**
+**Response:**
 
 ```json
 {
-  "path": "email",
-  "message": "A record with this email already exists."
+  "success": false,
+  "message": "Bad Request Exception",
+  "errorMessages": [
+    {
+      "path": "http_error",
+      "message": ["email must be an email", "password must be longer than or equal to 8 characters"]
+    }
+  ]
 }
 ```
 
-### DTO Validation Errors
+## HttpException Example
 
-Automatically extracts validation errors from class-validator:
+Throwing HTTP exceptions manually:
 
 ```typescript
-// Example validation error
+throw new BadRequestException('User already exists');
+```
+
+**Response:**
+
+```json
 {
-  "path": "email",
-  "message": "email must be a valid email"
+  "success": false,
+  "message": "Bad Request Exception",
+  "errorMessages": [
+    {
+      "path": "http_error",
+      "message": ["User already exists"]
+    }
+  ]
 }
 ```
 
-### HTTP Exceptions
+Other supported HTTP exceptions:
 
-Handles all NestJS HTTP exceptions:
+- `NotFoundException` - Returns "Not Found Exception"
+- `UnauthorizedException` - Returns "Unauthorized Exception"
+- `ForbiddenException` - Returns "Forbidden Exception"
+- `ConflictException` - Returns "Conflict Exception"
+- And all other NestJS HTTP exceptions
 
-```typescript
-throw new BadRequestException('Invalid input');
-```
+## Prisma Error Example
 
-### Unknown Errors
+The package automatically handles common Prisma errors:
 
-Fallback handler returns generic error message.
+### P2002 - Unique Constraint Violation
 
-## Creating Custom Formatters
+```typescript
+// When trying to create a user with duplicate email
+```
 
-Extend the `ExceptionFormatter` interface to create custom formatters:
+**Response:**
 
-```typescript
-import { ExceptionFormatter, ErrorMessage } from 'nestjs-exception-handler';
+```json
+{
+  "success": false,
+  "message": "Database error",
+  "errorMessages": [
+    {
+      "path": "email",
+      "message": ["A record with this email already exists."]
+    }
+  ]
+}
+```
 
-export class CustomExceptionFormatter implements ExceptionFormatter {
-  supports(exception: unknown): boolean {
-    return exception instanceof CustomError;
-  }
+### P2003 - Foreign Key Constraint
 
-  format(exception: unknown): ErrorMessage[] {
-    const error = exception as CustomError;
-    return [{ path: error.field, message: error.message }];
-  }
+**Response:**
 
-  message(exception: unknown): string {
-    return 'Custom error occurred';
-  }
+```json
+{
+  "success": false,
+  "message": "Database error",
+  "errorMessages": [
+    {
+      "path": "userId",
+      "message": ["The referenced userId does not exist."]
+    }
+  ]
 }
 ```
 
-## API Reference
+### P2025 - Record Not Found
 
-### ExceptionHandlerModule
+**Response:**
 
-- `forRoot(config?)` - Register globally with optional configuration
-- `forFeature(config?)` - Register for specific modules
+```json
+{
+  "success": false,
+  "message": "Database error",
+  "errorMessages": [
+    {
+      "path": "record",
+      "message": ["The requested record does not exist."]
+    }
+  ]
+}
+```
 
-### ExceptionHandlerService
+## Unknown Error Example
 
-- `registerFormatter(formatter)` - Add custom formatter
-- `formatException(exception)` - Format exception to standardized response
-- `formatErrors(exception)` - Get error messages array
-- `getErrorMessage(exception)` - Get error message string
-- `getAllFormatters()` - Get registered formatters
+For unexpected errors:
 
-### GlobalExceptionFilter
+```json
+{
+  "success": false,
+  "message": "Internal Server Error",
+  "errorMessages": [
+    {
+      "path": "server",
+      "message": ["Something went wrong"]
+    }
+  ]
+}
+```
 
-- Catches all unhandled exceptions
-- Logs structured errors
-- Returns standardized responses
+Stack traces are never leaked in production (configurable).
 
-## Error Response Examples
+## 404 Route Not Found Example
 
-### Prisma Unique Constraint
+When a client requests a route that doesn't exist, the package automatically converts it to the standardized format:
 
 ```json
 {
   "success": false,
-  "message": "A record with this email already exists.",
+  "message": "Route Not Found",
   "errorMessages": [
     {
-      "path": "email",
-      "message": "A record with this email already exists."
+      "path": "route",
+      "message": ["Cannot GET /users/test"]
     }
   ]
 }
 ```
 
-### Validation Error
+The response includes:
+
+- The HTTP method (GET, POST, PATCH, DELETE, etc.)
+- The requested URL path
+
+### Examples for Different Methods
+
+**POST to non-existent route:**
 
 ```json
 {
   "success": false,
-  "message": "Validation failed",
+  "message": "Route Not Found",
   "errorMessages": [
     {
-      "path": "email",
-      "message": "email must be a valid email"
-    },
-    {
-      "path": "password",
-      "message": "password must be longer than 8 characters"
+      "path": "route",
+      "message": ["Cannot POST /api/user/test"]
     }
   ]
 }
 ```
 
-### HTTP Exception
+**DELETE on non-existent route:**
 
 ```json
 {
   "success": false,
-  "message": "Resource not found",
+  "message": "Route Not Found",
   "errorMessages": [
     {
-      "path": "unknown",
-      "message": "Resource not found"
+      "path": "route",
+      "message": ["Cannot DELETE /api/items/123"]
     }
   ]
 }
 ```
 
+## Best Practices
+
+### 1. Always Use Global ValidationPipe
+
+```typescript
+app.useGlobalPipes(
+  new ValidationPipe({
+    whitelist: true,
+    transform: true,
+    forbidNonWhitelisted: true,
+  }),
+);
+```
+
+### 2. Configure Based on Environment
+
+```typescript
+const config =
+  process.env.NODE_ENV === 'production'
+    ? { enableLogging: true, hideStackTrace: true }
+    : { enableLogging: true, hideStackTrace: false };
+
+app.useGlobalFilters(new GlobalExceptionFilter(config));
+```
+
+### 3. Create Custom Formatters
+
+Extend the package for custom error handling:
+
+```typescript
+import { ExceptionFormatter, ErrorMessage } from 'nestjs-exception-handler';
+
+export class CustomExceptionFormatter implements ExceptionFormatter {
+  supports(exception: unknown): boolean {
+    return exception instanceof CustomError;
+  }
+
+  format(exception: unknown): ErrorMessage[] {
+    const error = exception as CustomError;
+    return [
+      {
+        path: error.field,
+        message: [error.message],
+      },
+    ];
+  }
+
+  message(_exception: unknown): string {
+    return 'Custom error occurred';
+  }
+}
+```
+
+## API Reference
+
+### GlobalExceptionFilter
+
+```typescript
+// Constructor
+new GlobalExceptionFilter(service: ExceptionHandlerService, config?: ExceptionHandlerConfig)
+
+// Config options
+interface ExceptionHandlerConfig {
+  enableLogging?: boolean;  // Default: true
+  hideStackTrace?: boolean; // Default: false
+}
+```
+
+### ExceptionHandlerModule
+
+```typescript
+// Register globally
+ExceptionHandlerModule.forRoot(config?)
+
+// Register for specific feature
+ExceptionHandlerModule.forFeature(config?)
+```
+
+### ExceptionHandlerService
+
+```typescript
+// Register custom formatter
+service.registerFormatter(formatter: ExceptionFormatter)
+
+// Format exception
+service.formatException(exception: unknown): { errors: ErrorMessage[]; message: string }
+
+// Get all registered formatters
+service.getAllFormatters(): ExceptionFormatter[]
+```
+
+## Response Examples Summary
+
+| Error Type    | Example                                                 |
+| ------------- | ------------------------------------------------------- |
+| Validation    | `message: ["email must be an email"]`                   |
+| HttpException | `message: ["User already exists"]`                      |
+| Prisma P2002  | `message: ["A record with this email already exists."]` |
+| 404 Not Found | `message: ["Cannot GET /unknown-route"]`                |
+| Unknown       | `message: ["Something went wrong"]`                     |
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.

package/dist/index.d.mts

@@ -1,15 +1,14 @@
-import { PrismaClientKnownRequestError, PrismaClientValidationError, PrismaClientRustPanicError, PrismaClientInitializationError } from '@prisma/client/runtime/library';
 import { HttpException, ExceptionFilter, ArgumentsHost, DynamicModule } from '@nestjs/common';
+import { PrismaClientKnownRequestError, PrismaClientValidationError, PrismaClientRustPanicError, PrismaClientInitializationError } from '@prisma/client/runtime/library';
 
-interface IErrorMessage {
+interface ErrorMessage {
     path: string;
-    message: string;
+    message: string[];
 }
-type ErrorMessage = IErrorMessage;
-interface StandardErrorResponse {
+interface ErrorResponse {
     success: boolean;
     message: string;
-    errorMessages: IErrorMessage[];
+    errorMessages: ErrorMessage[];
 }
 
 interface ExceptionFormatter {
@@ -23,12 +22,17 @@ interface ExceptionHandlerConfig {
     hideStackTrace?: boolean;
 }
 
+declare class ValidationErrorFormatter {
+    formatValidationErrors(exception: HttpException): ErrorMessage[];
+    private formatNestedValidationErrors;
+}
+
 type PrismaError = PrismaClientKnownRequestError | PrismaClientValidationError | PrismaClientRustPanicError | PrismaClientInitializationError | unknown;
 declare class PrismaExceptionFormatter implements ExceptionFormatter {
     supports(exception: unknown): boolean;
-    format(exception: unknown): IErrorMessage[];
+    format(exception: unknown): ErrorMessage[];
     message(_exception: unknown): string;
-    formatError(exception: PrismaError): IErrorMessage[];
+    formatError(exception: PrismaError): ErrorMessage[];
     private formatPrismaError;
     private formatQueryError;
     private formatInitializationError;
@@ -36,27 +40,14 @@ declare class PrismaExceptionFormatter implements ExceptionFormatter {
 }
 
 declare class DtoValidationFormatter {
-    formatDtoValidationException(exception: HttpException): IErrorMessage[];
-}
-
-declare class OtherExceptionFormatter {
-    formatOtherError(exception: unknown): IErrorMessage[];
-}
-
-declare class GlobalExceptionFilter implements ExceptionFilter {
-    private readonly prismaExceptionFormatter;
-    private readonly dtoValidationFormatter;
-    private readonly otherValidationFormatter;
-    constructor(prismaExceptionFormatter: PrismaExceptionFormatter, dtoValidationFormatter: DtoValidationFormatter, otherValidationFormatter: OtherExceptionFormatter);
-    private readonly logger;
-    private getErrorMessage;
-    catch(exception: unknown, host: ArgumentsHost): void;
+    formatDtoValidationException(exception: HttpException): ErrorMessage[];
 }
 
 declare class ExceptionHandlerService {
     private formatters;
     private defaultFormatter;
     constructor();
+    private registerFormatters;
     registerFormatter(formatter: ExceptionFormatter): void;
     getFormatter(exception: unknown): ExceptionFormatter;
     formatException(exception: unknown): {
@@ -68,10 +59,26 @@ declare class ExceptionHandlerService {
     getAllFormatters(): ExceptionFormatter[];
 }
 
+declare class GlobalExceptionFilter implements ExceptionFilter {
+    private exceptionHandlerService?;
+    private readonly logger;
+    private config;
+    constructor(exceptionHandlerService?: ExceptionHandlerService | undefined, config?: ExceptionHandlerConfig);
+    private getService;
+    catch(exception: unknown, host: ArgumentsHost): void;
+    private getStatusCode;
+    private logError;
+}
+
 declare class ExceptionHandlerModule {
     static forRoot(config?: ExceptionHandlerConfig): DynamicModule;
     static forFeature(config?: ExceptionHandlerConfig): DynamicModule;
 }
 declare function initializeFormatters(service: ExceptionHandlerService): void;
 
-export { DtoValidationFormatter, ErrorMessage, ExceptionFormatter, ExceptionHandlerConfig, ExceptionHandlerModule, GlobalExceptionFilter, IErrorMessage, OtherExceptionFormatter, PrismaExceptionFormatter, StandardErrorResponse, initializeFormatters };
+declare class HttpErrorFormatter {
+    formatHttpException(exception: HttpException): ErrorMessage[];
+    getMessage(exception: HttpException): string;
+}
+
+export { DtoValidationFormatter, ErrorMessage, ErrorResponse, ExceptionFormatter, ExceptionHandlerConfig, ExceptionHandlerModule, ExceptionHandlerService, GlobalExceptionFilter, HttpErrorFormatter, PrismaExceptionFormatter, ValidationErrorFormatter, initializeFormatters };