@3xhaust/nest-response

NestJS 전용 응답 표준화 라이브러리입니다.

성공 응답과 예외 응답을 모두 아래와 동일한 외부 구조로 통일합니다.

{
  statusCode: number;
  data: T | null;
  message: string[];
  timestamp: string;
}

설계 규칙

• NestJS 전용
• message는 항상 string[]
• timestamp는 항상 ISO 문자열
• 성공/에러 응답은 동일한 외부 구조 사용
• data ?? null 규칙 사용 (0, false, "" 유지)
• 이미 최종 응답 형태면 다시 래핑하지 않음
• 기본 성공 메시지: ["Success"]
• 알 수 없는 에러 기본 메시지: ["Internal server error"]

설치

npm install @3xhaust/nest-response

빠른 시작

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { applyNestResponse } from '@3xhaust/nest-response';

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

bootstrap();

에러 디버깅이 필요하면 옵션으로 로그/메시지 노출 정책을 설정할 수 있습니다.

applyNestResponse(app, {
  allExceptionsFilter: {
    logUnknownErrors: true,
    exposeUnknownErrorMessages: process.env.NODE_ENV !== 'production',
  },
});

컨트롤러 예제

import { Controller, Get } from '@nestjs/common';
import { SuccessMessage } from '@3xhaust/nest-response';

@Controller('users')
export class UsersController {
  @Get()
  @SuccessMessage('Users fetched')
  findAll() {
    return [{ id: 1, name: 'lyu' }];
  }
}

응답 예시:

{
  "statusCode": 200,
  "data": [{ "id": 1, "name": "lyu" }],
  "message": ["Users fetched"],
  "timestamp": "2026-03-13T11:11:11.000Z"
}

전체 실행 예제

실행 가능한 샘플 앱은 examples/basic에 있습니다.

cd examples/basic
npm install
npm run start

API

ApiResponse<T>

interface ApiResponse<T> {
  statusCode: number;
  data: T | null;
  message: string[];
  timestamp: string;
}

SuccessMessage(...messages: string[])

성공 응답의 message를 지정하는 데코레이터입니다.

• 메서드 또는 컨트롤러 클래스에 적용 가능
• 설정 시 해당 메시지를 사용
• 미설정 시 기본값 ['Success'] 사용

TransformInterceptor

일반 성공 반환값을 표준 응답 형태로 변환합니다.

동작:

• 비표준 payload를 { statusCode, data: payload ?? null, message, timestamp }로 래핑
• @SuccessMessage(...) 메타데이터가 있으면 사용
• 없으면 기본 성공 메시지 사용
• 이미 ApiResponse 형태면 재래핑하지 않음 (timestamp 누락 시 보강)

AllExceptionsFilter

발생한 예외를 표준 응답 형태로 정규화합니다.

동작:

• 문자열 메시지 예외 -> string[]로 변환
• 배열 메시지 예외 -> 그대로 유지
• 알 수 없는 에러 -> 500, data: null, message: ["Internal server error"]
• 모든 에러 응답에 timestamp 포함
• 이미 표준 형태 예외 응답은 보존 (timestamp 없으면 자동 추가)

applyNestResponse(app)

전역으로 아래를 등록합니다.

• TransformInterceptor
• AllExceptionsFilter

시그니처:

applyNestResponse(app, {
  allExceptionsFilter?: {
    logUnknownErrors?: boolean; // default: true
    exposeUnknownErrorMessages?: boolean; // default: false
  };
});

• logUnknownErrors: 미분류 예외 및 5xx 예외를 서버 로그로 출력
• exposeUnknownErrorMessages: 미분류 예외의 원본 Error.message를 응답 메시지로 노출