@fuzionx/framework 0.1.2

package/lib/core/AutoLoader.js

@@ -0,0 +1,162 @@
+/**
+ * AutoLoader — 앱 디렉토리 자동 스캔 + 등록
+ *
+ * Application.boot() 시 호출.
+ * models/, services/, middleware/ 등 자동 로드.
+ *
+ * @see docs/framework/04-bootstrap-lifecycle.md
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * 디렉토리에서 .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 - 프로젝트 루트
+     */
+    constructor(app, baseDir) {
+        this.app = app;
+        this.baseDir = baseDir;
+    }
+
+    /**
+     * 전체 스캔 + 등록 실행
+     */
+    async load() {
+        await this.loadModels();
+        await this.loadServices();
+        await this.loadMiddleware();
+        await this.loadEvents();
+        await this.loadJobs();
+        await this.loadWsHandlers();
+        await this.loadRoutes();
+    }
+
+    /** models/*.js → ModelRegistry */
+    async loadModels() {
+        const files = await scanDir(path.join(this.baseDir, 'models'));
+        for (const file of files) {
+            const mod = await import(file);
+            const ModelClass = mod.default;
+            if (!ModelClass) continue;
+            const name = extractName(file);
+            if (this.app.db) {
+                this.app.db.register(name, ModelClass);
+            }
+        }
+    }
+
+    /** services/*.js → DI register */
+    async loadServices() {
+        const files = await scanDir(path.join(this.baseDir, 'services'));
+        for (const file of files) {
+            const mod = await import(file);
+            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() {
+        if (!this.app._middlewareRegistry) {
+            this.app._middlewareRegistry = new Map();
+        }
+        const files = await scanDir(path.join(this.baseDir, 'middleware'));
+        for (const file of files) {
+            const mod = await import(file);
+            const MwClass = mod.default;
+            if (!MwClass) continue;
+            const mwName = MwClass.name || extractName(file, 'Middleware').toLowerCase();
+            this.app._middlewareRegistry.set(mwName, MwClass);
+        }
+    }
+
+    /** events/*.js → EventBus.on() */
+    async loadEvents() {
+        const files = await scanDir(path.join(this.baseDir, 'events'));
+        for (const file of files) {
+            const mod = await import(file);
+            // events/*.js 는 export default (app) => { app.on('...', handler) }
+            if (typeof mod.default === 'function') {
+                mod.default(this.app);
+            }
+        }
+    }
+
+    /** jobs/*.js → Scheduler + Queue */
+    async loadJobs() {
+        const files = await scanDir(path.join(this.baseDir, 'jobs'));
+        for (const file of files) {
+            const mod = await import(file);
+            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() {
+        if (!this.app._wsHandlers) {
+            this.app._wsHandlers = new Map();
+        }
+        const files = await scanDir(path.join(this.baseDir, 'ws'));
+        for (const file of files) {
+            const mod = await import(file);
+            const HandlerClass = mod.default;
+            if (!HandlerClass) continue;
+            const ns = HandlerClass.namespace || '/';
+            this.app._wsHandlers.set(ns, HandlerClass);
+        }
+    }
+
+    /** routes/*.js → Router.load() */
+    async loadRoutes() {
+        const files = await scanDir(path.join(this.baseDir, 'routes'));
+        if (!this.app._router) return;
+        for (const file of files) {
+            const mod = await import(file);
+            if (typeof mod.default === 'function') {
+                this.app._router.load(mod.default);
+            }
+        }
+    }
+}
+
+export { scanDir, extractName };

package/lib/core/Base.js

@@ -0,0 +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; }
+}

package/lib/core/Config.js

@@ -0,0 +1,122 @@
+/**
+ * Config — 통합 설정 접근
+ *
+ * fuzionx.yaml의 3개 섹션(bridge, database, app)을 통합 관리.
+ * dot-notation으로 접근: config.get('app.auth.secret')
+ *
+ * .env 자동 로드 + ${VAR:default} 환경변수 치환.
+ *
+ * @see docs/framework/17-config.md
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+
+export default class Config {
+    /**
+     * @param {object} raw - 파싱된 YAML 객체 전체
+     *   raw.bridge  — Bridge(Rust)가 파싱한 bridge: 섹션
+     *   raw.database — JS가 파싱한 database: 섹션
+     *   raw.app      — JS가 파싱한 app: 섹션
+     */
+    constructor(raw = {}) {
+        this.bridge = raw.bridge || {};
+        this.database = raw.database || {};
+        this.app = raw.app || {};
+        this._raw = raw;
+        this._cache = new Map();
+    }
+
+    /**
+     * .env 파일 로드 (17-config.md)
+     * 부트 시 자동 호출. 이미 설정된 환경변수는 덮어쓰지 않음.
+     * @param {string} [baseDir='.']
+     */
+    loadEnv(baseDir = '.') {
+        const envPath = path.resolve(baseDir, '.env');
+        if (!existsSync(envPath)) return;
+
+        try {
+            const content = readFileSync(envPath, 'utf-8');
+            for (const line of content.split('\n')) {
+                const trimmed = line.trim();
+                if (!trimmed || trimmed.startsWith('#')) continue;
+                const eqIdx = trimmed.indexOf('=');
+                if (eqIdx === -1) continue;
+                const key = trimmed.slice(0, eqIdx).trim();
+                let value = trimmed.slice(eqIdx + 1).trim();
+                // .env 인용부호 제거 ("value" → value, 'value' → value)
+                value = value.replace(/^(['"])(.*)\1$/, '$2');
+                // 시스템 환경변수 우선 (17-config.md)
+                if (!(key in process.env)) {
+                    process.env[key] = value;
+                }
+            }
+        } catch {} // .env 읽기 실패 시 무시
+    }
+
+    /**
+     * YAML 객체의 ${VAR} / ${VAR:default} 패턴 치환 (17-config.md)
+     * @param {object} obj
+     * @returns {object}
+     */
+    static resolveEnvVars(obj) {
+        if (typeof obj === 'string') {
+            return obj.replace(/\$\{(\w+)(?::([^}]*))?\}/g, (_, varName, defaultVal) => {
+                const envVal = process.env[varName];
+                if (envVal !== undefined) return envVal;
+                if (defaultVal !== undefined) return defaultVal;
+                throw new Error(`Required environment variable '${varName}' is not set`);
+            });
+        }
+        if (Array.isArray(obj)) return obj.map(item => Config.resolveEnvVars(item));
+        if (obj !== null && typeof obj === 'object') {
+            const result = {};
+            for (const [key, value] of Object.entries(obj)) {
+                result[key] = Config.resolveEnvVars(value);
+            }
+            return result;
+        }
+        return obj;
+    }
+
+    /**
+     * dot-notation으로 설정값 접근
+     * @param {string} path - 'app.auth.secret', 'database.main.host' 등
+     * @param {*} [defaultValue] - 키가 없을 때 반환값
+     * @returns {*}
+     */
+    get(path, defaultValue = undefined) {
+        if (this._cache.has(path)) return this._cache.get(path);
+
+        const parts = path.split('.');
+        let current = this._raw;
+
+        for (const part of parts) {
+            if (current == null || typeof current !== 'object') {
+                return defaultValue;
+            }
+            current = current[part];
+        }
+
+        if (current === undefined) return defaultValue;
+        this._cache.set(path, current);
+        return current;
+    }
+
+    /**
+     * 설정값 존재 여부
+     * @param {string} path
+     * @returns {boolean}
+     */
+    has(path) {
+        return this.get(path) !== undefined;
+    }
+
+    /**
+     * 전체 설정 반환 (읽기 전용)
+     * @returns {object}
+     */
+    all() {
+        return this._raw;
+    }
+}