nestjs-response-wrapper

A NestJS package that globally standardizes HTTP responses with consistent success and error formats.

Installation

npm install nestjs-response-wrapper

This package has the following peer dependencies:

npm install @nestjs/common @nestjs/core rxjs

Features

• Global Response Interceptor: Wraps all successful REST responses in a consistent format
• Global Exception Filter: Catches and transforms all thrown errors into a standardized format
• Configurable: Customize timestamp inclusion, custom formatters, excluded routes, and error logging
• TypeScript Support: Full TypeScript support with type definitions
• NestJS v10+ Compatible: Works with NestJS v10 and above
• Global Module: Automatically available across all modules without explicit imports

Usage

Basic Usage

Import ResponseWrapperModule in your root module:

import { Module } from '@nestjs/common';
import { ResponseWrapperModule } from 'nestjs-response-wrapper';

@Module({
  imports: [ResponseWrapperModule.forRoot()],
})
export class AppModule {}

Advanced Configuration

import { Module } from '@nestjs/common';
import { ResponseWrapperModule } from 'nestjs-response-wrapper';

@Module({
  imports: [
    ResponseWrapperModule.forRoot({
      includeTimestamp: true,
      excludeRoutes: ['/health', '/health*'],
      logErrors: true,
      customSuccessFormatter: (data) => ({
        success: true,
        data,
        timestamp: new Date().toISOString(),
      }),
      customErrorFormatter: (error) => ({
        message: error instanceof Error ? error.message : 'Unknown error',
        code: 'ERROR_CODE',
      }),
    }),
  ],
})
export class AppModule {}

Response Formats

Success Response

{
  "success": true,
  "data": <original_response>,
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Error Response

{
  "success": false,
  "error": "Error message",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Options

Option	Type	Default	Description
includeTimestamp	boolean	true	Include ISO timestamp in responses
customSuccessFormatter	function	undefined	Custom formatter for success responses
customErrorFormatter	function	undefined	Custom formatter for error responses
excludeRoutes	string[]	[]	Routes to exclude from wrapping
logErrors	boolean	false	Enable error logging

Route Exclusion

The excludeRoutes option supports exact matches and wildcards:

ResponseWrapperModule.forRoot({
  excludeRoutes: [
    '/health',        // Exact match
    '/health*',       // Prefix match (wildcard)
  ],
})

TypeScript Types

The package exports the following types:

import {
  ApiResponse,
  ApiErrorResponse,
  ResponseWrapperOptions,
} from 'nestjs-response-wrapper';

License

MIT