@ahhaohho/response-dto 1.4.0 → 2.0.0

package/ResponseDTO.js

@@ -1,69 +1,323 @@
+/**
+ * ResponseDTO 클래스 v2.0.0
+ * RFC 7807 (Problem Details for HTTP APIs) 표준을 점진적으로 도입하는 API 응답 클래스
+ *
+ * [하위 호환성 보장]
+ * - 기존 응답 구조 (type, status, data, message) 100% 유지
+ * - 에러 응답의 type은 기존대로 'client' 또는 'system' 유지
+ * - 새로운 RFC 7807 필드는 추가 필드로만 제공 (선택적 사용)
+ *
+ * [새로 추가된 필드] (에러 응답에만 해당)
+ * - title: 에러 제목 (예: 'Bad Request')
+ * - detail: 상세 설명 (message와 동일)
+ * - errorCode: 에러 코드 (예: 'BAD_REQUEST')
+ * - instance: 요청 경로 (선택적)
+ * - errors: 필드별 검증 오류 (선택적)
+ */
+
+// HTTP 상태 코드별 표준 제목
+const HTTP_STATUS_TITLES = {
+  200: 'OK',
+  201: 'Created',
+  204: 'No Content',
+  400: 'Bad Request',
+  401: 'Unauthorized',
+  403: 'Forbidden',
+  404: 'Not Found',
+  409: 'Conflict',
+  422: 'Validation Error',
+  429: 'Too Many Requests',
+  500: 'Internal Server Error',
+  503: 'Service Unavailable'
+};
+
+// 에러 코드 매핑
+const ERROR_CODES = {
+  400: 'BAD_REQUEST',
+  401: 'UNAUTHORIZED',
+  403: 'FORBIDDEN',
+  404: 'NOT_FOUND',
+  409: 'CONFLICT',
+  422: 'VALIDATION_ERROR',
+  429: 'TOO_MANY_REQUESTS',
+  500: 'INTERNAL_SERVER_ERROR',
+  503: 'SERVICE_UNAVAILABLE'
+};
+
+// 상태 코드에 따른 기존 type 값 (하위 호환)
+const LEGACY_TYPE = {
+  client: [400, 401, 403, 404, 409, 422, 429],
+  system: [500, 503]
+};
+
+function getLegacyType(status) {
+  if (LEGACY_TYPE.client.includes(status)) return 'client';
+  if (LEGACY_TYPE.system.includes(status)) return 'system';
+  if (status >= 400 && status < 500) return 'client';
+  if (status >= 500) return 'system';
+  return 'success';
+}
+
 class ResponseDTO {
-    constructor(type, status, data = null, message = null) {
-        this.type = type;
-        this.status = status;
-        this.data = data;
-        this.message = message;
-    }
-  
-    static success(data = null, message = null, type = 'success', status = 200) {
-        return new ResponseDTO(type, status, data, message);
-    }
-  
-    static created(data = null, message = null, type = 'success', status = 201) {
-        return new ResponseDTO(type, status, data, message);
-    }
-  
-    static noContent(message = null, type = 'success', status = 204) {
-        return new ResponseDTO(type, status, null, message);
-    }
-  
-    static badRequest(message, type = 'client', status = 400) {
-        return new ResponseDTO(type, status, null, message);
-    }
-  
-    static unauthorized(message, type = 'client', status = 401) {
-        return new ResponseDTO(type, status, null, message);
+  /**
+   * ResponseDTO 생성자
+   * @param {string|Object} typeOrOptions - 응답 유형 또는 옵션 객체
+   * @param {number} [status] - HTTP 상태 코드 (레거시 형태)
+   * @param {any} [data] - 응답 데이터 (레거시 형태)
+   * @param {string} [message] - 응답 메시지 (레거시 형태)
+   */
+  constructor(typeOrOptions, status, data, message) {
+    if (typeof typeOrOptions === 'string') {
+      // 레거시 생성자: new ResponseDTO('success', 200, data, message)
+      this.type = typeOrOptions;
+      this.status = status;
+      this.data = data ?? null;
+      this.message = message ?? null;
+    } else {
+      // 새 생성자: new ResponseDTO({ type, status, data, message, ... })
+      const options = typeOrOptions;
+      this.type = options.type;
+      this.status = options.status;
+      this.data = options.data ?? null;
+      this.message = options.message ?? null;
+      this.title = options.title ?? null;
+      this.detail = options.detail ?? null;
+      this.instance = options.instance ?? null;
+      this.errorCode = options.errorCode ?? null;
+      this.errors = options.errors ?? null;
     }
-  
-    static forbidden(message, type = 'client', status = 403) {
-        return new ResponseDTO(type, status, null, message);
-    }
-  
-    static notFound(message, type = 'client', status = 404) {
-        return new ResponseDTO(type, status, null, message);
-    }
-  
-    static conflict(message, type = 'client', status = 409) {
-        return new ResponseDTO(type, status, null, message);
-    }
-  
-    static validationError(message, type = 'client', status = 422) {
-        return new ResponseDTO(type, status, null, message);
-    }
-  
-    static systemError(message, type = 'system', status = 500) {
-        return new ResponseDTO(type, status, null, message);
-    }
-  
-    static serviceUnavailable(message, type = 'system', status = 503) {
-        return new ResponseDTO(type, status, null, message);
+  }
+
+  // ==================== 성공 응답 메서드 ====================
+
+  /**
+   * 상태 코드 200의 성공 응답
+   * @param {any} [data] - 응답 데이터
+   * @param {string} [message] - 성공 메시지
+   * @returns {ResponseDTO}
+   */
+  static success(data = null, message = null) {
+    return new ResponseDTO('success', 200, data, message);
+  }
+
+  /**
+   * 리소스 생성 성공 응답 (201)
+   * @param {any} [data] - 생성된 리소스 데이터
+   * @param {string} [message] - 성공 메시지
+   * @returns {ResponseDTO}
+   */
+  static created(data = null, message = null) {
+    return new ResponseDTO('success', 201, data, message);
+  }
+
+  /**
+   * 콘텐츠 없는 성공 응답 (204)
+   * @param {string} [message] - 성공 메시지
+   * @returns {ResponseDTO}
+   */
+  static noContent(message = null) {
+    return new ResponseDTO('success', 204, null, message);
+  }
+
+  // ==================== 에러 응답 메서드 ====================
+
+  /**
+   * 에러 응답 생성 헬퍼 (내부용)
+   * @private
+   */
+  static _createError(status, message, options = {}) {
+    const legacyType = getLegacyType(status);
+    const errorCode = options.errorCode || ERROR_CODES[status] || 'ERROR';
+
+    return new ResponseDTO({
+      type: legacyType,  // 하위 호환: 'client' 또는 'system' 유지
+      status,
+      data: null,
+      message,
+      // RFC 7807 추가 필드
+      title: HTTP_STATUS_TITLES[status] || 'Error',
+      detail: message,
+      errorCode,
+      instance: options.instance || null,
+      errors: options.errors || null
+    });
+  }
+
+  /**
+   * 잘못된 요청 (400)
+   * @param {string} message - 에러 메시지
+   * @param {Object} [options] - 추가 옵션
+   * @param {string} [options.instance] - 요청 경로
+   * @param {Array} [options.errors] - 필드별 오류
+   * @param {string} [options.errorCode] - 커스텀 에러 코드
+   * @returns {ResponseDTO}
+   */
+  static badRequest(message, options = {}) {
+    return ResponseDTO._createError(400, message, options);
+  }
+
+  /**
+   * 인증 필요 (401)
+   * @param {string} message - 에러 메시지
+   * @param {Object} [options] - 추가 옵션
+   * @returns {ResponseDTO}
+   */
+  static unauthorized(message, options = {}) {
+    return ResponseDTO._createError(401, message, options);
+  }
+
+  /**
+   * 권한 부족 (403)
+   * @param {string} message - 에러 메시지
+   * @param {Object} [options] - 추가 옵션
+   * @returns {ResponseDTO}
+   */
+  static forbidden(message, options = {}) {
+    return ResponseDTO._createError(403, message, options);
+  }
+
+  /**
+   * 리소스 없음 (404)
+   * @param {string} message - 에러 메시지
+   * @param {Object} [options] - 추가 옵션
+   * @returns {ResponseDTO}
+   */
+  static notFound(message, options = {}) {
+    return ResponseDTO._createError(404, message, options);
+  }
+
+  /**
+   * 충돌 (409)
+   * @param {string} message - 에러 메시지
+   * @param {Object} [options] - 추가 옵션
+   * @returns {ResponseDTO}
+   */
+  static conflict(message, options = {}) {
+    return ResponseDTO._createError(409, message, options);
+  }
+
+  /**
+   * 유효성 검사 오류 (422)
+   * @param {string} message - 에러 메시지
+   * @param {Object} [options] - 추가 옵션
+   * @param {Array<{field: string, message: string, rejected?: any}>} [options.errors] - 필드별 오류
+   * @returns {ResponseDTO}
+   */
+  static validationError(message, options = {}) {
+    return ResponseDTO._createError(422, message, options);
+  }
+
+  /**
+   * 요청 제한 초과 (429)
+   * @param {string} message - 에러 메시지
+   * @param {Object} [options] - 추가 옵션
+   * @returns {ResponseDTO}
+   */
+  static tooManyRequests(message, options = {}) {
+    return ResponseDTO._createError(429, message, options);
+  }
+
+  /**
+   * 서버 내부 오류 (500)
+   * @param {string} message - 에러 메시지
+   * @param {Object} [options] - 추가 옵션
+   * @returns {ResponseDTO}
+   */
+  static systemError(message, options = {}) {
+    return ResponseDTO._createError(500, message, options);
+  }
+
+  /**
+   * 서비스 불가 (503)
+   * @param {string} message - 에러 메시지
+   * @param {Object} [options] - 추가 옵션
+   * @returns {ResponseDTO}
+   */
+  static serviceUnavailable(message, options = {}) {
+    return ResponseDTO._createError(503, message, options);
+  }
+
+  // ==================== 유틸리티 메서드 ====================
+
+  /**
+   * 성공 응답인지 확인
+   * @returns {boolean}
+   */
+  isSuccess() {
+    return this.type === 'success' || this.status < 400;
+  }
+
+  /**
+   * 에러 응답인지 확인
+   * @returns {boolean}
+   */
+  isError() {
+    return !this.isSuccess();
+  }
+
+  /**
+   * 클라이언트 에러인지 확인 (4xx)
+   * @returns {boolean}
+   */
+  isClientError() {
+    return this.status >= 400 && this.status < 500;
+  }
+
+  /**
+   * 서버 에러인지 확인 (5xx)
+   * @returns {boolean}
+   */
+  isServerError() {
+    return this.status >= 500;
+  }
+
+  /**
+   * JSON 직렬화
+   *
+   * [하위 호환 보장]
+   * 기존 응답 구조를 100% 유지하고, 새 필드는 추가로만 포함됩니다.
+   *
+   * 성공 응답: { type: 'success', status, data, message }
+   * 에러 응답: { type: 'client'|'system', status, data: null, message, title?, detail?, errorCode?, instance?, errors? }
+   *
+   * @returns {Object}
+   */
+  toJSON() {
+    // 기본 응답 구조 (하위 호환 100%)
+    const response = {
+      type: this.type,
+      status: this.status,
+      data: this.data,
+      message: this.message
+    };
+
+    // 리다이렉트 처리 (기존 로직 유지)
+    if (this.type === 'redirect' && this.data?.redirect) {
+      response.redirect = this.data.redirect;
+      delete response.data;
     }
-  
-    toJSON() {
-        const response = {
-            type: this.type,
-            status: this.status,
-            data: this.data,
-            message: this.message,
-        };
-
-        // 리다이렉트의 경우 redirect 객체를 최상위로 이동
-        if (this.type === 'redirect' && this.data?.redirect) {
-            response.redirect = this.data.redirect;
-            delete response.data;
-        }
-
-        return response;
+
+    // 에러 응답인 경우 RFC 7807 필드 추가 (있는 경우에만)
+    if (this.isError()) {
+      if (this.title) {
+        response.title = this.title;
+      }
+      if (this.detail) {
+        response.detail = this.detail;
+      }
+      if (this.errorCode) {
+        response.errorCode = this.errorCode;
+      }
+      if (this.instance) {
+        response.instance = this.instance;
+      }
+      if (this.errors && this.errors.length > 0) {
+        response.errors = this.errors;
+      }
     }
+
+    return response;
+  }
 }
+
+module.exports = ResponseDTO;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahhaohho/response-dto",
-  "version": "1.4.0",
+  "version": "2.0.0",
   "description": "AhhaOhho API 응답을 위한 DTO 클래스",
   "main": "index.js",
   "scripts": {