♻️ refactor: Enhanced type-safety, modular helper functions

- Refactored blancLogger code by separating inline logic into dedicated helper functions for module name formatting, message formatting, and log level transformation.
- Improved type-safety by explicitly defining types and refining interfaces.
- Added concise, official one-line comments to all logging-related functions and classes for clarity.
- Implemented YAML configuration override for logging settings by merging default configurations with user-provided settings.

Author: yooseungmo

.npmignore

@@ -1,9 +1,6 @@
 # 소스 코드
 src/
 
-# Rollup 설정 파일 등 빌드 스크립트
-rollup.config.js
-
 # tsconfig 파일들 (필요에 따라)
 tsconfig.json
 tsconfig.*.json

README.md

@@ -118,7 +118,7 @@ logs/
 | **SQL 구문 하이라이팅 (SQL Syntax Highlighting)** | - SQL 쿼리의 키워드, 값, 테이블명을 색상 강조 및 들여쓰기로 구분<br>- 파라미터 값 컨텍스트 인식 강조 |
 | **쿼리 성능 분석 (Query Analysis)** | - SQL 성능 저하 유발 패턴 자동 감지 (`SELECT *`, `JOIN 조건 누락` 등) |
 | **에러 진단 및 스택 추적 (Error Diagnostics)** | - 에러 발생 시 다중 스택 레이어와 추가 메타데이터를 포함하여 상세한 에러 로그 기록 |
-| **성능 모니터링 (Performance Monitoring)** | - HTTP 요청 처리 시간 및 `Slow Query`(예: 100ms) 경고 로그 생성<br>- 실행 계획(Explain Plan) 리포트 시각화  |
+| **성능 모니터링 (Performance Monitoring)** | - HTTP 요청 처리 시간 및 `Slow Query`(예: 500ms) 경고 로그 생성<br>- 실행 계획(Explain Plan) 리포트 시각화  |
 | **커스터마이징 (Customization)** | - `logger-config.yaml`파일을 통해 로그 저장 경로, 로그 레벨, 파일 크기, 회전 주기 등을 쉽게 조정 가능 |
 
 ---
@@ -130,8 +130,8 @@ logs/
 
 ```yaml
 LOG_DIR: logs            # 로그 파일 저장 경로 (기본: 프로젝트 루트/logs)
-CONSOLE_LOG_LEVEL: info  # 콘솔 출력 로그 레벨 (debug, info, warn, error)
-FILE_LOG_LEVEL: error    # 파일 출력 로그 레벨
+CONSOLE_LOG_LEVEL: info  # 콘솔 출력 로그 레벨 (debug, verbose, info, warn, error)
+FILE_LOG_LEVEL: error    # 파일 출력 로그 레벨 (debug, verbose, info, warn, error)
 ROTATION_DAYS: 30d       # 로그 파일 보관 기간 (예: 30일)
 MAX_FILE_SIZE: 20m       # 단일 파일 최대 크기 (예: 20MB)
 
@@ -203,7 +203,7 @@ export class LoggingInterceptor implements NestInterceptor {
       tap(() => {
         const delay = Date.now() - startTime;
         const delayStr =
-          delay > 100 ? chalk.bold.red(`${delay}ms 🚨`) : chalk.magenta(`${delay}ms`);
+          delay > 500 ? chalk.bold.red(`${delay}ms 🚨`) : chalk.magenta(`${delay}ms`);
         const message = `Request processed: ${chalk.yellow(req.method)} ${chalk.green(
           decodedUrl,
         )} ${delayStr}`;
@@ -233,7 +233,7 @@ export class AppModule {}
 ```
 
 > **Console Output Log Example**         
-> _(응답 시간 초과 시 (예: 100ms)강조)_
+> _- 응답 시간 (예: 500ms) 초과 시 강조_
 
 <p align="left">
   <img src="https://github.com/user-attachments/assets/315ac55c-7f06-44b6-a4bb-66a465186dd3" alt="blanc-logger-output-log" width="600">
@@ -258,45 +258,53 @@ import {
 import { blancLogger } from 'blanc-logger';
 import { Request, Response } from 'express';
 
+interface ExceptionResponse {
+  status: number;
+  message: string;
+  stack?: string;
+}
+
+/** 예외 객체를 처리하여 상태, 메시지, 스택을 반환하는 함수 */
+const handleException = (exception: unknown, _request: Request): ExceptionResponse => {
+  if (exception instanceof HttpException) {
+    const status = exception.getStatus();
+    const res = exception.getResponse();
+    const message =
+      typeof res === 'object' && res !== null
+        ? (res as any).message ?? exception.message
+        : exception.message;
+    return {
+      status,
+      message: `HTTP Exception: ${message}`,
+      stack: exception instanceof Error ? exception.stack : '',
+    };
+  }
+  if (exception instanceof Error) {
+    const status = new InternalServerErrorException().getStatus();
+    return {
+      status,
+      message: `Unhandled exception: ${exception.message}`,
+      stack: exception.stack,
+    };
+  }
+  return { status: 500, message: 'Unknown error' };
+};
+
 @Catch()
 export class GlobalExceptionFilter implements ExceptionFilter {
   catch(exception: unknown, host: ArgumentsHost): void {
     const ctx = host.switchToHttp();
     const response = ctx.getResponse<Response>();
     const request = ctx.getRequest<Request>();
-    const moduleName = (request as any).moduleName || 'Global';
-
-    let status: number;
-    let message: string;
-
-    if (exception instanceof HttpException) {
-      status = exception.getStatus();
-      const resObj = exception.getResponse();
-      message =
-        typeof resObj === 'object' && resObj !== null
-          ? (resObj as any).message || exception.message
-          : exception.message;
-      blancLogger.error(`HTTP Exception: ${message}`, {
-        moduleName,
-        path: request.url,
-        stack: exception instanceof Error ? exception.stack : '',
-      });
-    } else if (exception instanceof Error) {
-      status = new InternalServerErrorException().getStatus();
-      message = 'Internal Server Error';
-      blancLogger.error(`Unhandled exception: ${exception.message}`, {
-        moduleName,
-        path: request.url,
-        stack: exception.stack,
-      });
-    } else {
-      status = 500;
-      message = 'Unknown error';
-      blancLogger.error(`Unknown exception: ${JSON.stringify(exception)}`, {
-        moduleName,
-        path: request.url,
-      });
-    }
+
+    const moduleName = (request as any)?.moduleName ?? 'Global';
+    const { status, message, stack } = handleException(exception, request);
+
+    blancLogger.error(message, {
+      moduleName,
+      path: request.url,
+      stack,
+    });
 
     response.status(status).json({
       statusCode: status,
@@ -306,6 +314,7 @@ export class GlobalExceptionFilter implements ExceptionFilter {
     });
   }
 }
+
 ```
 
 > **전역 필터로 적용하려면 AppModule에 아래와 같이 등록합니다**

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "blanc-logger",
-  "version": "1.0.9",
-  "description": "Advanced Winston logger for NestJS & TypeORM with structured logging (npm package).",
+  "version": "1.1.0",
+  "description": "Advanced Winston logger for NestJS & TypeORM with structured logging.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [

package.json

@@ -1,11 +1,13 @@
 import * as chalk from 'chalk';
 
+/** 주어진 텍스트의 각 줄에 지정된 공백 수만큼 들여쓰기를 적용 */
 export const indent = (text: string, spaces: number = 4): string =>
   text
     .split('\n')
     .map((line) => ' '.repeat(spaces) + line)
     .join('\n');
 
+/** SQL 쿼리 문자열의 키워드, 숫자, 문자열 및 식별자에 색상 포맷을 적용하여 하이라이트 */
 export const sqlHighlighter = (sql: string): string => {
   const keywords = [
     'SELECT',
@@ -50,9 +52,11 @@ export const sqlHighlighter = (sql: string): string => {
     .join('');
 };
 
+/** SQL 쿼리의 파라미터 배열을 JSON 문자열로 변환하여 색상 포맷을 적용 */
 export const formatParameters = (params: unknown[]): string =>
   params.length > 0 ? chalk.hex('#2E8B57')(JSON.stringify(params)) : '';
 
+/** SQL 쿼리를 분석하여 성능 이슈가 발생할 수 있는 부분에 대한 경고 메시지를 반환 */
 export const addQueryAnalysis = (query: string): string => {
   const warnings: string[] = [];
   const simplified = query.toLowerCase().replace(/\s+/g, ' ');
@@ -66,4 +70,4 @@ export const addQueryAnalysis = (query: string): string => {
     warnings.push(chalk.magentaBright('🚨 Leading % in LIKE can cause full table scan'));
   }
   return warnings.join('\n');
-};
+};

src/helper/sql-formatter.ts

@@ -1,5 +1,6 @@
 import { v4 as uuidv4, v5 as uuidv5 } from 'uuid';
 
+/** 입력 문자열을 기반으로 UUID를 생성하며, 입력이 없을 경우 랜덤 UUID를 사용하고 하이픈을 제거 */
 export const generateUUID = (from?: string): string => {
   const uid = from ?? uuidv4();
   return uuidv5(uid, uuidv5.DNS).replace(/-/g, '');

src/helper/uuid.ts

@@ -1,4 +1,3 @@
-// blanc-logger.ts
 import * as chalk from 'chalk';
 import { WinstonModule } from 'nest-winston';
 import * as util from 'util';
@@ -8,7 +7,6 @@ import { generateUUID } from '../helper/uuid';
 import { LOGGING_CONFIG } from './logger.config';
 
 const { LOG_DIR, CONSOLE_LOG_LEVEL, FILE_LOG_LEVEL, ROTATION_DAYS, MAX_FILE_SIZE } = LOGGING_CONFIG;
-
 const MAX_OBJECT_DEPTH = 5;
 const MAX_OBJECT_WIDTH = 120;
 
@@ -20,6 +18,7 @@ export interface CustomTransformableInfo extends winston.Logform.TransformableIn
   context?: { moduleName?: string } | string;
 }
 
+/** util.inspect의 사전 정의된 옵션을 사용하여 객체를 문자열로 포맷팅 */
 const deepInspector = (obj: unknown): string =>
   util.inspect(obj, {
     colors: true,
@@ -29,6 +28,7 @@ const deepInspector = (obj: unknown): string =>
     sorted: true,
   });
 
+/** 로그 레벨에 해당하는 이모지를 매핑 */
 const emojiMap: Record<string, string> = {
   error: '🚨',
   warn: '⚠️',
@@ -37,6 +37,7 @@ const emojiMap: Record<string, string> = {
   debug: '🐛',
 };
 
+/** 로그 레벨에 해당하는 chalk 색상 함수를 매핑 */
 const levelColorMap: Record<string, (text: string) => string> = {
   error: chalk.hex('#FF6B6B'),
   warn: chalk.hex('#FFD93D'),
@@ -45,23 +46,21 @@ const levelColorMap: Record<string, (text: string) => string> = {
   verbose: chalk.hex('#6BCB77'),
 };
 
-const moduleHierarchyFormat = winston.format(
-  (info: CustomTransformableInfo): CustomTransformableInfo => {
-    if (typeof info.moduleName === 'string') {
-      info.moduleName = info.moduleName
-        .split('/')
-        .map((part: string) => chalk.cyan(part))
-        .join(chalk.dim(' → '));
-    }
-    return info;
-  },
-);
+/** 모듈 경로를 색상이 적용된 계층적 문자열로 변환 */
+const moduleHierarchyTransform = (info: CustomTransformableInfo): CustomTransformableInfo => {
+  info.moduleName =
+    info.moduleName?.split('/')?.map((part: string) => chalk.cyan(part))?.join(chalk.dim(' → ')) ??
+    info.moduleName;
+  return info;
+};
 
+/** 파일 로그에 대한 타임스탬프와 JSON 포맷을 결합 */
 const fileLogFormat = winston.format.combine(
   winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
-  winston.format.json(),
+  winston.format.json()
 );
 
+/** 로그 파일 순환을 위한 DailyRotateFile 전송 객체를 생성 */
 const createDailyRotateFileTransport = (filename: string, level: string): DailyRotateFile =>
   new DailyRotateFile({
     dirname: LOG_DIR,
@@ -74,52 +73,52 @@ const createDailyRotateFileTransport = (filename: string, level: string): DailyR
     format: fileLogFormat,
   });
 
-const addMetaData = winston.format((info: CustomTransformableInfo): CustomTransformableInfo => {
-  if (!info.logId) {
-    info.logId = generateUUID();
-  }
+/** 로그 메타데이터에 고유한 logId가 없으면 추가 */
+const addMetaDataTransform = (info: CustomTransformableInfo): CustomTransformableInfo => {
+  info.logId ??= generateUUID();
+  return info;
+};
+
+/** 제공된 moduleName 또는 context 속성을 사용하여 모듈 이름을 포맷팅 */
+const formatModuleName = (info: CustomTransformableInfo): string => {
+  const moduleName =
+    info.moduleName ?? (typeof info.context === 'object' ? info.context?.moduleName : info.context);
+  return moduleName ? `[${moduleName}]` : '';
+};
+
+/** 로그 메시지를 포맷팅하며, 객체인 경우 deepInspector를 사용하여 포맷팅 */
+const formatMessage = (info: CustomTransformableInfo): string => {
+  const message = info.stack || info.message;
+  return typeof message === 'object' ? deepInspector(message) : String(message);
+};
+
+/** 이모지를 추가하고 대문자로 변환하여 로그 레벨을 변환 */
+const transformLogLevel = (info: CustomTransformableInfo): CustomTransformableInfo => {
+  info.rawLevel = info.level;
+  info.level = `${emojiMap[info.level] || ''} ${info.level.toUpperCase()}`.padEnd(5);
   return info;
-});
+};
 
+/** 다양한 포맷팅 함수를 결합하여 최종 콘솔 로그 포맷을 생성 */
 const customConsoleFormat = winston.format.combine(
-  addMetaData(),
+  winston.format(addMetaDataTransform)(),
   winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
-  moduleHierarchyFormat(),
-  winston.format((info: CustomTransformableInfo): CustomTransformableInfo => {
-    info.rawLevel = info.level;
-    info.level = `${emojiMap[info.level] || ''} ${info.level.toUpperCase()}`.padEnd(5);
-    return info;
-  })(),
+  winston.format(moduleHierarchyTransform)(),
+  winston.format(transformLogLevel)(),
   winston.format.printf((info: CustomTransformableInfo): string => {
     const colorFunc =
       levelColorMap[info.rawLevel ?? ''] || ((text: string): string => chalk.bold.white(text));
     const coloredLevel = colorFunc(info.level);
     const simpleLogId = info.logId ? chalk.hex('#00008B')(`[${info.logId.substring(0, 8)}]`) : '';
-    let moduleName: string | undefined;
-    if (!info.moduleName && info.context) {
-      if (
-        typeof info.context === 'object' &&
-        info.context !== null &&
-        'moduleName' in info.context
-      ) {
-        moduleName = (info.context as { moduleName?: string }).moduleName;
-      } else if (typeof info.context === 'string') {
-        moduleName = info.context;
-      }
-    } else {
-      moduleName = info.moduleName;
-    }
-    const moduleStr = moduleName ? `[${moduleName}]` : '';
-    let message: unknown = info.stack || info.message;
-    if (typeof message === 'object') {
-      message = deepInspector(message);
-    }
-    return `${simpleLogId} ${chalk.dim(
-      info.timestamp,
-    )} ${coloredLevel} ${moduleStr} - ${chalk.blueBright(message as string)}`;
-  }),
+    const moduleStr = formatModuleName(info);
+    const messageStr = formatMessage(info);
+    return `${simpleLogId} ${chalk.dim(info.timestamp)} ${coloredLevel} ${moduleStr} - ${chalk.blueBright(
+      messageStr
+    )}`;
+  })
 );
 
+/** 구성된 전송 및 포맷을 사용하여 WinstonModule로 blancLogger를 생성 */
 export const blancLogger = WinstonModule.createLogger({
   transports: [
     new winston.transports.Console({
@@ -133,4 +132,4 @@ export const blancLogger = WinstonModule.createLogger({
   ],
   exceptionHandlers: [createDailyRotateFileTransport('exceptions', 'error')],
   rejectionHandlers: [createDailyRotateFileTransport('rejections', 'error')],
-});
+});

src/logger/blanc-logger.ts

@@ -1,6 +1,7 @@
 import { LoggerService } from '@nestjs/common';
 import { blancLogger } from './blanc-logger';
 
+/** Nest의 LoggerService를 대체하여 blancLogger를 통해 로그를 기록하는 커스텀 로거 */
 export const customBlancLogger: LoggerService = {
   log: (message: unknown, context?: string): void =>
     blancLogger.log('info', message, { moduleName: context }),