@fuzionx/framework 0.1.39 → 0.1.41

package/lib/helpers/Logger.js

@@ -1,108 +1,108 @@
-/**
- * Logger — Bridge tracing 통합 로거
- *
- * Bridge(Rust) logInfo/logWarn/logError/logDebug N-API에 위임.
- * Bridge 없으면 JS console 폴백.
- *
- * @see docs/framework/13-logging.md
- * @see packages/fuzionx/lib/logger.js (Core 래퍼 참조)
- */
-import { format } from 'node:util';
-
-export default class Logger {
-    /**
-     * @param {object} [opts]
-     * @param {string} [opts.level='info'] - 최소 출력 레벨
-     * @param {object} [opts.bridge] - Bridge N-API 인스턴스
-     * @param {boolean} [opts.json=false] - JSON 포맷 (Bridge 없을 때)
-     * @param {string} [opts.prefix='app'] - Bridge target 이름
-     */
-    constructor(opts = {}) {
-        this.level = opts.level || 'info';
-        this._bridge = opts.bridge || null;
-        this._json = opts.json || false;
-        this._prefix = opts.prefix || 'app';
-        this._levels = { error: 0, warn: 1, info: 2, debug: 3 };
-        this._minLevel = this._levels[this.level] ?? 2;
-    }
-
-    /**
-     * @param {string} message
-     * @param {object} [context]
-     */
-    error(message, context) { this._log('error', message, context); }
-    warn(message, context) { this._log('warn', message, context); }
-    info(message, context) { this._log('info', message, context); }
-    debug(message, context) { this._log('debug', message, context); }
-
-    /**
-     * 자식 로거 생성 (prefix 상속)
-     * @param {string} prefix
-     * @returns {Logger}
-     */
-    child(prefix) {
-        return new Logger({
-            level: this.level,
-            bridge: this._bridge,
-            json: this._json,
-            prefix: this._prefix ? `${this._prefix}:${prefix}` : prefix,
-        });
-    }
-
-    /** @private */
-    _log(level, message, context) {
-        if (this._levels[level] > this._minLevel) return;
-
-        // Error 객체면 전체 스택 포함
-        const isErr = message instanceof Error;
-        const text = isErr ? (message.stack || `${message}`) : `${message}`;
-
-        // ── Bridge N-API 위임 (context 결합은 Bridge 경로에서만) ──
-        if (this._bridge) {
-            // Bridge는 단일 문자열만 받으므로 여기서만 concat
-            const msg = context ? `${text} ${JSON.stringify(context)}` : text;
-            try {
-                if (level === 'info' && typeof this._bridge.logInfo === 'function') {
-                    this._bridge.logInfo(this._prefix, msg);
-                    return;
-                }
-                if (level === 'warn' && typeof this._bridge.logWarn === 'function') {
-                    this._bridge.logWarn(this._prefix, msg);
-                    return;
-                }
-                if (level === 'error' && typeof this._bridge.logError === 'function') {
-                    this._bridge.logError(this._prefix, msg);
-                    return;
-                }
-                if (level === 'debug' && typeof this._bridge.logDebug === 'function') {
-                    this._bridge.logDebug(this._prefix, msg);
-                    return;
-                }
-            } catch {} // Bridge 호출 실패 시 JS 폴백
-        }
-
-        // ── JS 폴백 ──
-        const timestamp = new Date().toISOString();
-
-        if (this._json) {
-            const entry = {
-                timestamp,
-                level,
-                target: this._prefix,
-                message: text,
-                ...(context || {}),
-            };
-            console[level === 'debug' ? 'log' : level](JSON.stringify(entry));
-        } else {
-            const levelTag = level.toUpperCase().padEnd(5);
-            const fullMsg = context
-                ? `${timestamp}  ${levelTag}  [${this._prefix}] ${text}`
-                : `${timestamp}  ${levelTag}  [${this._prefix}] ${text}`;
-            if (context && Object.keys(context).length > 0) {
-                console[level === 'debug' ? 'log' : level](fullMsg, context);
-            } else {
-                console[level === 'debug' ? 'log' : level](fullMsg);
-            }
-        }
-    }
-}
+/**
+ * Logger — Bridge tracing 통합 로거
+ *
+ * Bridge(Rust) logInfo/logWarn/logError/logDebug N-API에 위임.
+ * Bridge 없으면 JS console 폴백.
+ *
+ * @see docs/framework/13-logging.md
+ * @see packages/fuzionx/lib/logger.js (Core 래퍼 참조)
+ */
+import { format } from 'node:util';
+
+export default class Logger {
+    /**
+     * @param {object} [opts]
+     * @param {string} [opts.level='info'] - 최소 출력 레벨
+     * @param {object} [opts.bridge] - Bridge N-API 인스턴스
+     * @param {boolean} [opts.json=false] - JSON 포맷 (Bridge 없을 때)
+     * @param {string} [opts.prefix='app'] - Bridge target 이름
+     */
+    constructor(opts = {}) {
+        this.level = opts.level || 'info';
+        this._bridge = opts.bridge || null;
+        this._json = opts.json || false;
+        this._prefix = opts.prefix || 'app';
+        this._levels = { error: 0, warn: 1, info: 2, debug: 3 };
+        this._minLevel = this._levels[this.level] ?? 2;
+    }
+
+    /**
+     * @param {string} message
+     * @param {object} [context]
+     */
+    error(message, context) { this._log('error', message, context); }
+    warn(message, context) { this._log('warn', message, context); }
+    info(message, context) { this._log('info', message, context); }
+    debug(message, context) { this._log('debug', message, context); }
+
+    /**
+     * 자식 로거 생성 (prefix 상속)
+     * @param {string} prefix
+     * @returns {Logger}
+     */
+    child(prefix) {
+        return new Logger({
+            level: this.level,
+            bridge: this._bridge,
+            json: this._json,
+            prefix: this._prefix ? `${this._prefix}:${prefix}` : prefix,
+        });
+    }
+
+    /** @private */
+    _log(level, message, context) {
+        if (this._levels[level] > this._minLevel) return;
+
+        // Error 객체면 전체 스택 포함
+        const isErr = message instanceof Error;
+        const text = isErr ? (message.stack || `${message}`) : `${message}`;
+
+        // ── Bridge N-API 위임 (context 결합은 Bridge 경로에서만) ──
+        if (this._bridge) {
+            // Bridge는 단일 문자열만 받으므로 여기서만 concat
+            const msg = context ? `${text} ${JSON.stringify(context)}` : text;
+            try {
+                if (level === 'info' && typeof this._bridge.logInfo === 'function') {
+                    this._bridge.logInfo(this._prefix, msg);
+                    return;
+                }
+                if (level === 'warn' && typeof this._bridge.logWarn === 'function') {
+                    this._bridge.logWarn(this._prefix, msg);
+                    return;
+                }
+                if (level === 'error' && typeof this._bridge.logError === 'function') {
+                    this._bridge.logError(this._prefix, msg);
+                    return;
+                }
+                if (level === 'debug' && typeof this._bridge.logDebug === 'function') {
+                    this._bridge.logDebug(this._prefix, msg);
+                    return;
+                }
+            } catch {} // Bridge 호출 실패 시 JS 폴백
+        }
+
+        // ── JS 폴백 ──
+        const timestamp = new Date().toISOString();
+
+        if (this._json) {
+            const entry = {
+                timestamp,
+                level,
+                target: this._prefix,
+                message: text,
+                ...(context || {}),
+            };
+            console[level === 'debug' ? 'log' : level](JSON.stringify(entry));
+        } else {
+            const levelTag = level.toUpperCase().padEnd(5);
+            const fullMsg = context
+                ? `${timestamp}  ${levelTag}  [${this._prefix}] ${text}`
+                : `${timestamp}  ${levelTag}  [${this._prefix}] ${text}`;
+            if (context && Object.keys(context).length > 0) {
+                console[level === 'debug' ? 'log' : level](fullMsg, context);
+            } else {
+                console[level === 'debug' ? 'log' : level](fullMsg);
+            }
+        }
+    }
+}

package/lib/helpers/MediaHelper.js

@@ -1,84 +1,84 @@
-/**
- * MediaHelper — Bridge media N-API 래퍼
- *
- * @see docs/framework/19-utilities.md — "3. Media (app.media)"
- * @see packages/fuzionx/lib/media.js (Core 래퍼)
- */
-export default class MediaHelper {
-    constructor(bridge) { this._bridge = bridge; }
-
-    resize(input, output, width, height, format = 'webp', quality = 80) {
-        if (this._bridge?.mediaResize) return this._bridge.mediaResize(input, output, width, height, format, quality);
-        throw new Error('Media operations require Bridge (Rust). Install @fuzionx/bridge.');
-    }
-
-    resizeMultiple(input, outputDir, baseName, specs) {
-        if (this._bridge?.mediaResizeMultiple) return this._bridge.mediaResizeMultiple(input, outputDir, baseName, JSON.stringify(specs));
-        throw new Error('Media operations require Bridge (Rust).');
-    }
-
-    imageInfo(filePath) {
-        if (this._bridge?.mediaGetImageInfo) return this._bridge.mediaGetImageInfo(filePath);
-        throw new Error('Image info requires Bridge (Rust).');
-    }
-
-    toWebp(input, output, quality = 80) {
-        return this.resize(input, output, 0, 0, 'webp', quality);
-    }
-
-    videoThumbnail(input, output, atSeconds = 1, width = 640, format = 'jpeg') {
-        if (this._bridge?.mediaVideoThumbnail) return this._bridge.mediaVideoThumbnail(input, output, atSeconds, width, format);
-        throw new Error('Video operations require ffmpeg + Bridge.');
-    }
-
-    videoInfo(filePath) {
-        if (this._bridge?.mediaVideoInfo) return this._bridge.mediaVideoInfo(filePath);
-        throw new Error('Video info requires ffprobe + Bridge.');
-    }
-
-    /**
-     * 이미지에 워터마크를 합성한다.
-     * @param {string} targetPath - 대상 이미지 경로
-     * @param {string} watermarkPath - 워터마크 이미지 경로
-     * @param {number} [opacity=50] - 불투명도 (0-100)
-     * @param {string} [format] - 출력 포맷 (기본: 원본 확장자)
-     * @param {number} [quality=90] - 출력 품질
-     */
-    applyWatermark(targetPath, watermarkPath, opacity = 50, format, quality = 90) {
-        if (this._bridge?.mediaApplyWatermark) {
-            return this._bridge.mediaApplyWatermark(targetPath, watermarkPath, opacity, format, quality);
-        }
-        throw new Error('Watermark requires Bridge (Rust).');
-    }
-
-    /**
-     * 비디오에서 N초 간격으로 다중 썸네일을 추출한다.
-     * @param {string} inputPath - 비디오 경로
-     * @param {string} outputDir - 출력 디렉토리
-     * @param {number} [interval=5] - 초 간격
-     * @param {number} [width=320] - 썸네일 가로 크기
-     * @param {string} [format='jpeg'] - 포맷
-     * @returns {string[]} 생성된 파일 경로 목록
-     */
-    videoThumbnails(inputPath, outputDir, interval = 5, width = 320, format = 'jpeg') {
-        if (this._bridge?.mediaVideoThumbnails) {
-            return this._bridge.mediaVideoThumbnails(inputPath, outputDir, interval, width, format);
-        }
-        throw new Error('Video thumbnails requires ffmpeg + Bridge.');
-    }
-
-    /**
-     * 썸네일 목록을 스프라이트 시트(그리드)로 합성한다.
-     * @param {string[]} thumbPaths - 썸네일 경로 목록
-     * @param {string} outputPath - 출력 스프라이트 시트 경로
-     * @param {number} [cols=10] - 그리드 열 수
-     * @param {number} [thumbWidth=160] - 각 썸네일 가로
-     * @param {number} [thumbHeight=0] - 각 썸네일 세로 (0=자동)
-     */
-    videoPreviewSheet(thumbPaths, outputPath, cols = 10, thumbWidth = 160, thumbHeight = 0) {
-        if (this._bridge?.mediaVideoPreviewSheet) {
-            return this._bridge.mediaVideoPreviewSheet(thumbPaths, outputPath, cols, thumbWidth, thumbHeight);
-        }
-        throw new Error('Preview sheet requires Bridge (Rust).');
-    }
-}
+/**
+ * MediaHelper — Bridge media N-API 래퍼
+ *
+ * @see docs/framework/19-utilities.md — "3. Media (app.media)"
+ * @see packages/fuzionx/lib/media.js (Core 래퍼)
+ */
+export default class MediaHelper {
+    constructor(bridge) { this._bridge = bridge; }
+
+    resize(input, output, width, height, format = 'webp', quality = 80) {
+        if (this._bridge?.mediaResize) return this._bridge.mediaResize(input, output, width, height, format, quality);
+        throw new Error('Media operations require Bridge (Rust). Install @fuzionx/bridge.');
+    }
+
+    resizeMultiple(input, outputDir, baseName, specs) {
+        if (this._bridge?.mediaResizeMultiple) return this._bridge.mediaResizeMultiple(input, outputDir, baseName, JSON.stringify(specs));
+        throw new Error('Media operations require Bridge (Rust).');
+    }
+
+    imageInfo(filePath) {
+        if (this._bridge?.mediaGetImageInfo) return this._bridge.mediaGetImageInfo(filePath);
+        throw new Error('Image info requires Bridge (Rust).');
+    }
+
+    toWebp(input, output, quality = 80) {
+        return this.resize(input, output, 0, 0, 'webp', quality);
+    }
+
+    videoThumbnail(input, output, atSeconds = 1, width = 640, format = 'jpeg') {
+        if (this._bridge?.mediaVideoThumbnail) return this._bridge.mediaVideoThumbnail(input, output, atSeconds, width, format);
+        throw new Error('Video operations require ffmpeg + Bridge.');
+    }
+
+    videoInfo(filePath) {
+        if (this._bridge?.mediaVideoInfo) return this._bridge.mediaVideoInfo(filePath);
+        throw new Error('Video info requires ffprobe + Bridge.');
+    }
+
+    /**
+     * 이미지에 워터마크를 합성한다.
+     * @param {string} targetPath - 대상 이미지 경로
+     * @param {string} watermarkPath - 워터마크 이미지 경로
+     * @param {number} [opacity=50] - 불투명도 (0-100)
+     * @param {string} [format] - 출력 포맷 (기본: 원본 확장자)
+     * @param {number} [quality=90] - 출력 품질
+     */
+    applyWatermark(targetPath, watermarkPath, opacity = 50, format, quality = 90) {
+        if (this._bridge?.mediaApplyWatermark) {
+            return this._bridge.mediaApplyWatermark(targetPath, watermarkPath, opacity, format, quality);
+        }
+        throw new Error('Watermark requires Bridge (Rust).');
+    }
+
+    /**
+     * 비디오에서 N초 간격으로 다중 썸네일을 추출한다.
+     * @param {string} inputPath - 비디오 경로
+     * @param {string} outputDir - 출력 디렉토리
+     * @param {number} [interval=5] - 초 간격
+     * @param {number} [width=320] - 썸네일 가로 크기
+     * @param {string} [format='jpeg'] - 포맷
+     * @returns {string[]} 생성된 파일 경로 목록
+     */
+    videoThumbnails(inputPath, outputDir, interval = 5, width = 320, format = 'jpeg') {
+        if (this._bridge?.mediaVideoThumbnails) {
+            return this._bridge.mediaVideoThumbnails(inputPath, outputDir, interval, width, format);
+        }
+        throw new Error('Video thumbnails requires ffmpeg + Bridge.');
+    }
+
+    /**
+     * 썸네일 목록을 스프라이트 시트(그리드)로 합성한다.
+     * @param {string[]} thumbPaths - 썸네일 경로 목록
+     * @param {string} outputPath - 출력 스프라이트 시트 경로
+     * @param {number} [cols=10] - 그리드 열 수
+     * @param {number} [thumbWidth=160] - 각 썸네일 가로
+     * @param {number} [thumbHeight=0] - 각 썸네일 세로 (0=자동)
+     */
+    videoPreviewSheet(thumbPaths, outputPath, cols = 10, thumbWidth = 160, thumbHeight = 0) {
+        if (this._bridge?.mediaVideoPreviewSheet) {
+            return this._bridge.mediaVideoPreviewSheet(thumbPaths, outputPath, cols, thumbWidth, thumbHeight);
+        }
+        throw new Error('Preview sheet requires Bridge (Rust).');
+    }
+}

package/lib/http/Controller.js

@@ -1,34 +1,34 @@
-/**
- * Controller — HTTP 요청 핸들러 기본 클래스
- *
- * 싱글톤: 부트 시 1회 생성. 핸들러 메서드는 ctx만으로 동작.
- *
- * @see docs/framework/01-routing-controllers.md
- * @see docs/framework/class-design.mm.md (Controller)
- */
-import Base from '../core/Base.js';
-
-export default class Controller extends Base {
-    /** @type {string[]} 이 컨트롤러 전체에 적용할 미들웨어 */
-    static middleware = [];
-
-    /**
-     * 프레임워크 내부 — 컨트롤러 스캔 시 프로토타입 메서드를 static 레퍼런스로 자동 등록
-     * @param {typeof Controller} ControllerClass
-     */
-    static register(ControllerClass) {
-        const proto = ControllerClass.prototype;
-        const baseNames = new Set(Object.getOwnPropertyNames(Base.prototype));
-        for (const method of Object.getOwnPropertyNames(proto)) {
-            if (method === 'constructor') continue;
-            // Base 메서드/getter 전체 스킵 (service, emit, dispatch, ws, crypto, i18n)
-            if (baseNames.has(method)) continue;
-
-            ControllerClass[method] = {
-                __handler__: true,
-                controller: ControllerClass,
-                method,
-            };
-        }
-    }
-}
+/**
+ * Controller — HTTP 요청 핸들러 기본 클래스
+ *
+ * 싱글톤: 부트 시 1회 생성. 핸들러 메서드는 ctx만으로 동작.
+ *
+ * @see docs/framework/01-routing-controllers.md
+ * @see docs/framework/class-design.mm.md (Controller)
+ */
+import Base from '../core/Base.js';
+
+export default class Controller extends Base {
+    /** @type {string[]} 이 컨트롤러 전체에 적용할 미들웨어 */
+    static middleware = [];
+
+    /**
+     * 프레임워크 내부 — 컨트롤러 스캔 시 프로토타입 메서드를 static 레퍼런스로 자동 등록
+     * @param {typeof Controller} ControllerClass
+     */
+    static register(ControllerClass) {
+        const proto = ControllerClass.prototype;
+        const baseNames = new Set(Object.getOwnPropertyNames(Base.prototype));
+        for (const method of Object.getOwnPropertyNames(proto)) {
+            if (method === 'constructor') continue;
+            // Base 메서드/getter 전체 스킵 (service, emit, dispatch, ws, crypto, i18n)
+            if (baseNames.has(method)) continue;
+
+            ControllerClass[method] = {
+                __handler__: true,
+                controller: ControllerClass,
+                method,
+            };
+        }
+    }
+}