@fuzionx/framework 0.1.43 → 0.1.45

package/lib/core/AutoLoader.js

@@ -1,227 +1,227 @@
-/**
- * AutoLoader — 앱 디렉토리 자동 스캔 + 등록
- *
- * Application.boot() 시 호출.
- * multi-app 구조:
- *   mode='shared' → database/models, shared/events, shared/jobs, shared/workers
- *   mode='app'    → app/{name}/controllers, routes, services, middleware, ws
- *
- * @see docs/framework/04-bootstrap-lifecycle.md
- */
-import { promises as fs } from 'node:fs';
-import path from 'node:path';
-import { pathToFileURL } from 'node:url';
-
-/**
- * 디렉토리에서 .js 파일 목록 반환
- * @param {string} dir
- * @returns {Promise<string[]>}
- */
-async function scanDir(dir) {
-    try {
-        const entries = await fs.readdir(dir, { withFileTypes: true });
-        return entries
-            .filter(e => e.isFile() && e.name.endsWith('.js') && !e.name.startsWith('.'))
-            .map(e => path.join(dir, e.name));
-    } catch {
-        return []; // 디렉토리 없으면 빈 배열
-    }
-}
-
-/**
- * 파일명에서 PascalCase 이름 추출
- * 'UserController.js' → 'User'
- * 'User.js' → 'User'
- */
-function extractName(filePath, suffix = '') {
-    const base = path.basename(filePath, '.js');
-    return suffix && base.endsWith(suffix) ? base.slice(0, -suffix.length) : base;
-}
-
-export default class AutoLoader {
-    /**
-     * @param {import('./Application.js').default} app
-     * @param {string} baseDir - 프로젝트 루트 (shared) 또는 앱 디렉토리 (app)
-     * @param {object} [opts]
-     * @param {'shared'|'app'} [opts.mode='shared']
-     * @param {object} [opts.appContext] - 앱별 레지스트리 (mode='app' 시)
-     */
-    constructor(app, baseDir, opts = {}) {
-        this.app = app;
-        this.baseDir = baseDir;
-        this._mode = opts.mode || 'shared';
-        this._appContext = opts.appContext || null;
-    }
-
-    /**
-     * 모드에 따른 스캔 + 등록 실행
-     */
-    async load() {
-        if (this._mode === 'shared') {
-            await this.loadModels('database/models');
-            await this.loadEvents('shared/events');
-            await this.loadJobs('shared/jobs');
-            // workers는 WorkerPool._resolve()에서 shared/workers/ 경로로 자동 탐색
-        } else if (this._mode === 'app') {
-            await this.loadControllers();
-            await this.loadRoutes();
-            await this.loadServices();
-            await this.loadMiddleware();
-            await this.loadWsHandlers();
-        }
-    }
-
-    /** database/models/*.js → ModelRegistry (공유) */
-    async loadModels(subDir = 'models') {
-        const files = await scanDir(path.join(this.baseDir, subDir));
-        for (const file of files) {
-            const mod = await import(pathToFileURL(file).href);
-            const ModelClass = mod.default;
-            if (!ModelClass) continue;
-            const name = extractName(file);
-            if (this.app.db) {
-                this.app.db.register(name, ModelClass);
-            }
-        }
-    }
-
-    /**
-     * controllers/*.js → 앱별 컨트롤러 레지스트리 + __handler__ static 등록
-     *
-     * 문서 01-routing-controllers.md:
-     * 프로토타입 메서드를 static 레퍼런스로 자동 등록하여
-     * 라우트에서 UserController.index 형태로 사용 가능.
-     */
-    async loadControllers() {
-        const controllerDir = path.join(this.baseDir, 'controllers');
-        const files = await scanDir(controllerDir);
-        const registry = this._appContext?.controllers || this.app._controllers;
-        if (!registry) return;
-
-        for (const file of files) {
-            const mod = await import(pathToFileURL(file).href);
-            const ControllerClass = mod.default;
-            if (!ControllerClass) continue;
-
-            // __handler__ static 레퍼런스 자동 등록
-            AutoLoader.registerController(ControllerClass);
-
-            // 컨트롤러 이름 등록 (싱글톤 인스턴스는 boot 완료 후 생성)
-            const name = extractName(file, 'Controller');
-            registry.set(name, ControllerClass);
-        }
-    }
-
-    /**
-     * 컨트롤러 프로토타입 메서드를 static __handler__ 레퍼런스로 등록
-     * @param {Function} ControllerClass
-     */
-    static registerController(ControllerClass) {
-        const proto = ControllerClass.prototype;
-        // Base 프로토타입 메서드 스킵 (Controller.register와 동일 로직)
-        const baseNames = new Set(Object.getOwnPropertyNames(
-            Object.getPrototypeOf(proto) // Base.prototype (Controller extends Base)
-        ));
-        for (const method of Object.getOwnPropertyNames(proto)) {
-            if (method === 'constructor') continue;
-            if (baseNames.has(method)) continue;
-            if (typeof proto[method] !== 'function') continue;
-            // static property로 __handler__ 디스크립터 등록
-            ControllerClass[method] = {
-                __handler__: true,
-                controller: ControllerClass,
-                method,
-            };
-        }
-    }
-
-    /** services/*.js → DI register (앱별 네임스페이스) */
-    async loadServices() {
-        const files = await scanDir(path.join(this.baseDir, 'services'));
-        for (const file of files) {
-            const mod = await import(pathToFileURL(file).href);
-            const ServiceClass = mod.default;
-            if (!ServiceClass) continue;
-            const name = extractName(file, 'Service');
-            this.app.register(`${name}Service`, (app) => new ServiceClass(app));
-        }
-    }
-
-    /** middleware/*.js → 앱별 미들웨어 맵 */
-    async loadMiddleware() {
-        const registry = this._appContext?.middlewareRegistry || this.app._middlewareRegistry;
-        if (!registry) return;
-
-        const files = await scanDir(path.join(this.baseDir, 'middleware'));
-        for (const file of files) {
-            const mod = await import(pathToFileURL(file).href);
-            const MwClass = mod.default;
-            if (!MwClass) continue;
-            const mwName = MwClass.alias || extractName(file, 'Middleware').toLowerCase();
-            registry.set(mwName, MwClass);
-        }
-    }
-
-    /** shared/events/*.js → EventBus.on() (공유) */
-    async loadEvents(subDir = 'events') {
-        const files = await scanDir(path.join(this.baseDir, subDir));
-        for (const file of files) {
-            const mod = await import(pathToFileURL(file).href);
-            // events/*.js 는 export default (app) => { app.on('...', handler) }
-            if (typeof mod.default === 'function') {
-                mod.default(this.app);
-            }
-        }
-    }
-
-    /** shared/jobs/*.js → Scheduler + Queue (공유) */
-    async loadJobs(subDir = 'jobs') {
-        const files = await scanDir(path.join(this.baseDir, subDir));
-        for (const file of files) {
-            const mod = await import(pathToFileURL(file).href);
-            const JobClass = mod.default;
-            if (!JobClass) continue;
-
-            // schedule이 있으면 cron Job → Scheduler
-            if (JobClass.schedule && this.app._scheduler) {
-                this.app._scheduler.register(JobClass);
-            }
-            // queue이 있으면 Task → Queue
-            if (JobClass.queue && this.app._queue) {
-                const name = JobClass.name;
-                this.app._queue.register(name, JobClass);
-            }
-        }
-    }
-
-    /** ws/*.js → 앱별 WsHandler 등록 */
-    async loadWsHandlers() {
-        const registry = this._appContext?.wsHandlers || this.app._wsHandlers;
-        if (!registry) return;
-
-        const files = await scanDir(path.join(this.baseDir, 'ws'));
-        for (const file of files) {
-            const mod = await import(pathToFileURL(file).href);
-            const HandlerClass = mod.default;
-            if (!HandlerClass) continue;
-            const ns = HandlerClass.namespace || '/';
-            registry.set(ns, HandlerClass);
-        }
-    }
-
-    /** routes/*.js → 앱별 Router.load() */
-    async loadRoutes() {
-        const router = this._appContext?.router || this.app._router;
-        if (!router) return;
-
-        const files = await scanDir(path.join(this.baseDir, 'routes'));
-        for (const file of files) {
-            const mod = await import(pathToFileURL(file).href);
-            if (typeof mod.default === 'function') {
-                router.load(mod.default);
-            }
-        }
-    }
-}
-
-export { scanDir, extractName };
+/**
+ * AutoLoader — 앱 디렉토리 자동 스캔 + 등록
+ *
+ * Application.boot() 시 호출.
+ * multi-app 구조:
+ *   mode='shared' → database/models, shared/events, shared/jobs, shared/workers
+ *   mode='app'    → app/{name}/controllers, routes, services, middleware, ws
+ *
+ * @see docs/framework/04-bootstrap-lifecycle.md
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * 디렉토리에서 .js 파일 목록 반환
+ * @param {string} dir
+ * @returns {Promise<string[]>}
+ */
+async function scanDir(dir) {
+    try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        return entries
+            .filter(e => e.isFile() && e.name.endsWith('.js') && !e.name.startsWith('.'))
+            .map(e => path.join(dir, e.name));
+    } catch {
+        return []; // 디렉토리 없으면 빈 배열
+    }
+}
+
+/**
+ * 파일명에서 PascalCase 이름 추출
+ * 'UserController.js' → 'User'
+ * 'User.js' → 'User'
+ */
+function extractName(filePath, suffix = '') {
+    const base = path.basename(filePath, '.js');
+    return suffix && base.endsWith(suffix) ? base.slice(0, -suffix.length) : base;
+}
+
+export default class AutoLoader {
+    /**
+     * @param {import('./Application.js').default} app
+     * @param {string} baseDir - 프로젝트 루트 (shared) 또는 앱 디렉토리 (app)
+     * @param {object} [opts]
+     * @param {'shared'|'app'} [opts.mode='shared']
+     * @param {object} [opts.appContext] - 앱별 레지스트리 (mode='app' 시)
+     */
+    constructor(app, baseDir, opts = {}) {
+        this.app = app;
+        this.baseDir = baseDir;
+        this._mode = opts.mode || 'shared';
+        this._appContext = opts.appContext || null;
+    }
+
+    /**
+     * 모드에 따른 스캔 + 등록 실행
+     */
+    async load() {
+        if (this._mode === 'shared') {
+            await this.loadModels('database/models');
+            await this.loadEvents('shared/events');
+            await this.loadJobs('shared/jobs');
+            // workers는 WorkerPool._resolve()에서 shared/workers/ 경로로 자동 탐색
+        } else if (this._mode === 'app') {
+            await this.loadControllers();
+            await this.loadRoutes();
+            await this.loadServices();
+            await this.loadMiddleware();
+            await this.loadWsHandlers();
+        }
+    }
+
+    /** database/models/*.js → ModelRegistry (공유) */
+    async loadModels(subDir = 'models') {
+        const files = await scanDir(path.join(this.baseDir, subDir));
+        for (const file of files) {
+            const mod = await import(pathToFileURL(file).href);
+            const ModelClass = mod.default;
+            if (!ModelClass) continue;
+            const name = extractName(file);
+            if (this.app.db) {
+                this.app.db.register(name, ModelClass);
+            }
+        }
+    }
+
+    /**
+     * controllers/*.js → 앱별 컨트롤러 레지스트리 + __handler__ static 등록
+     *
+     * 문서 01-routing-controllers.md:
+     * 프로토타입 메서드를 static 레퍼런스로 자동 등록하여
+     * 라우트에서 UserController.index 형태로 사용 가능.
+     */
+    async loadControllers() {
+        const controllerDir = path.join(this.baseDir, 'controllers');
+        const files = await scanDir(controllerDir);
+        const registry = this._appContext?.controllers || this.app._controllers;
+        if (!registry) return;
+
+        for (const file of files) {
+            const mod = await import(pathToFileURL(file).href);
+            const ControllerClass = mod.default;
+            if (!ControllerClass) continue;
+
+            // __handler__ static 레퍼런스 자동 등록
+            AutoLoader.registerController(ControllerClass);
+
+            // 컨트롤러 이름 등록 (싱글톤 인스턴스는 boot 완료 후 생성)
+            const name = extractName(file, 'Controller');
+            registry.set(name, ControllerClass);
+        }
+    }
+
+    /**
+     * 컨트롤러 프로토타입 메서드를 static __handler__ 레퍼런스로 등록
+     * @param {Function} ControllerClass
+     */
+    static registerController(ControllerClass) {
+        const proto = ControllerClass.prototype;
+        // Base 프로토타입 메서드 스킵 (Controller.register와 동일 로직)
+        const baseNames = new Set(Object.getOwnPropertyNames(
+            Object.getPrototypeOf(proto) // Base.prototype (Controller extends Base)
+        ));
+        for (const method of Object.getOwnPropertyNames(proto)) {
+            if (method === 'constructor') continue;
+            if (baseNames.has(method)) continue;
+            if (typeof proto[method] !== 'function') continue;
+            // static property로 __handler__ 디스크립터 등록
+            ControllerClass[method] = {
+                __handler__: true,
+                controller: ControllerClass,
+                method,
+            };
+        }
+    }
+
+    /** services/*.js → DI register (앱별 네임스페이스) */
+    async loadServices() {
+        const files = await scanDir(path.join(this.baseDir, 'services'));
+        for (const file of files) {
+            const mod = await import(pathToFileURL(file).href);
+            const ServiceClass = mod.default;
+            if (!ServiceClass) continue;
+            const name = extractName(file, 'Service');
+            this.app.register(`${name}Service`, (app) => new ServiceClass(app));
+        }
+    }
+
+    /** middleware/*.js → 앱별 미들웨어 맵 */
+    async loadMiddleware() {
+        const registry = this._appContext?.middlewareRegistry || this.app._middlewareRegistry;
+        if (!registry) return;
+
+        const files = await scanDir(path.join(this.baseDir, 'middleware'));
+        for (const file of files) {
+            const mod = await import(pathToFileURL(file).href);
+            const MwClass = mod.default;
+            if (!MwClass) continue;
+            const mwName = MwClass.alias || extractName(file, 'Middleware').toLowerCase();
+            registry.set(mwName, MwClass);
+        }
+    }
+
+    /** shared/events/*.js → EventBus.on() (공유) */
+    async loadEvents(subDir = 'events') {
+        const files = await scanDir(path.join(this.baseDir, subDir));
+        for (const file of files) {
+            const mod = await import(pathToFileURL(file).href);
+            // events/*.js 는 export default (app) => { app.on('...', handler) }
+            if (typeof mod.default === 'function') {
+                mod.default(this.app);
+            }
+        }
+    }
+
+    /** shared/jobs/*.js → Scheduler + Queue (공유) */
+    async loadJobs(subDir = 'jobs') {
+        const files = await scanDir(path.join(this.baseDir, subDir));
+        for (const file of files) {
+            const mod = await import(pathToFileURL(file).href);
+            const JobClass = mod.default;
+            if (!JobClass) continue;
+
+            // schedule이 있으면 cron Job → Scheduler
+            if (JobClass.schedule && this.app._scheduler) {
+                this.app._scheduler.register(JobClass);
+            }
+            // queue이 있으면 Task → Queue
+            if (JobClass.queue && this.app._queue) {
+                const name = JobClass.name;
+                this.app._queue.register(name, JobClass);
+            }
+        }
+    }
+
+    /** ws/*.js → 앱별 WsHandler 등록 */
+    async loadWsHandlers() {
+        const registry = this._appContext?.wsHandlers || this.app._wsHandlers;
+        if (!registry) return;
+
+        const files = await scanDir(path.join(this.baseDir, 'ws'));
+        for (const file of files) {
+            const mod = await import(pathToFileURL(file).href);
+            const HandlerClass = mod.default;
+            if (!HandlerClass) continue;
+            const ns = HandlerClass.namespace || '/';
+            registry.set(ns, HandlerClass);
+        }
+    }
+
+    /** routes/*.js → 앱별 Router.load() */
+    async loadRoutes() {
+        const router = this._appContext?.router || this.app._router;
+        if (!router) return;
+
+        const files = await scanDir(path.join(this.baseDir, 'routes'));
+        for (const file of files) {
+            const mod = await import(pathToFileURL(file).href);
+            if (typeof mod.default === 'function') {
+                router.load(mod.default);
+            }
+        }
+    }
+}
+
+export { scanDir, extractName };

package/lib/core/Base.js

@@ -1,64 +1,64 @@
-/**
- * Base — 공통 기본 클래스
- *
- * Controller, Service, Middleware, Job, Task, WsHandler가 상속.
- * 생성자에서 app을 받아 바로가기 프로퍼티 설정.
- *
- * @see docs/framework/class-design.mm.md (DI 주입 맵)
- */
-export default class Base {
-    /**
-     * @param {import('./Application.js').default} app
-     */
-    constructor(app) {
-        /** @type {import('./Application.js').default} */
-        this.app = app;
-        /** @type {object} ModelRegistry */
-        this.db = app.db;
-        /** @type {import('./Config.js').default} */
-        this.config = app.config;
-        /** @type {object} Logger */
-        this.logger = app.logger;
-    }
-
-    /**
-     * 서비스 조회 (DI)
-     * @param {string} name
-     * @returns {*}
-     */
-    service(name) {
-        return this.app.make(name);
-    }
-
-    /**
-     * 이벤트 발행
-     * @param {string} event
-     * @param {*} [data]
-     * @param {object} [opts]
-     */
-    async emit(event, data, opts) {
-        await this.app.emit(event, data, opts);
-    }
-
-    /**
-     * 큐 Task 디스패치
-     * @param {string|Function} taskOrName
-     * @param {object} data
-     * @param {object} [opts]
-     */
-    dispatch(taskOrName, data, opts) {
-        this.app.dispatch(taskOrName, data, opts);
-    }
-
-    /** @returns {object} WebSocket 매니저 */
-    get ws() { return this.app.ws; }
-
-    /** @returns {import('../schedule/WorkerPool.js').default} */
-    get worker() { return this.app.worker; }
-
-    /** @returns {import('./CryptoHelper.js').default} */
-    get crypto() { return this.app.crypto; }
-
-    /** @returns {import('./I18nHelper.js').default} */
-    get i18n() { return this.app.i18n; }
-}
+/**
+ * Base — 공통 기본 클래스
+ *
+ * Controller, Service, Middleware, Job, Task, WsHandler가 상속.
+ * 생성자에서 app을 받아 바로가기 프로퍼티 설정.
+ *
+ * @see docs/framework/class-design.mm.md (DI 주입 맵)
+ */
+export default class Base {
+    /**
+     * @param {import('./Application.js').default} app
+     */
+    constructor(app) {
+        /** @type {import('./Application.js').default} */
+        this.app = app;
+        /** @type {object} ModelRegistry */
+        this.db = app.db;
+        /** @type {import('./Config.js').default} */
+        this.config = app.config;
+        /** @type {object} Logger */
+        this.logger = app.logger;
+    }
+
+    /**
+     * 서비스 조회 (DI)
+     * @param {string} name
+     * @returns {*}
+     */
+    service(name) {
+        return this.app.make(name);
+    }
+
+    /**
+     * 이벤트 발행
+     * @param {string} event
+     * @param {*} [data]
+     * @param {object} [opts]
+     */
+    async emit(event, data, opts) {
+        await this.app.emit(event, data, opts);
+    }
+
+    /**
+     * 큐 Task 디스패치
+     * @param {string|Function} taskOrName
+     * @param {object} data
+     * @param {object} [opts]
+     */
+    dispatch(taskOrName, data, opts) {
+        this.app.dispatch(taskOrName, data, opts);
+    }
+
+    /** @returns {object} WebSocket 매니저 */
+    get ws() { return this.app.ws; }
+
+    /** @returns {import('../schedule/WorkerPool.js').default} */
+    get worker() { return this.app.worker; }
+
+    /** @returns {import('./CryptoHelper.js').default} */
+    get crypto() { return this.app.crypto; }
+
+    /** @returns {import('./I18nHelper.js').default} */
+    get i18n() { return this.app.i18n; }
+}