@fuzionx/framework 0.1.43 → 0.1.44

package/lib/core/Config.js

@@ -1,331 +1,331 @@
-/**
- * Config — 통합 설정 접근
- *
- * fuzionx.yaml의 3개 섹션(bridge, database, app)을 통합 관리.
- * dot-notation으로 접근: config.get('app.auth.secret')
- *
- * .env 자동 로드 + ${VAR:default} 환경변수 치환.
- * YAML 파일 직접 파싱 지원 (외부 의존 없이 내장 파서 사용).
- *
- * @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();
-    }
-
-    /**
-     * YAML 파일에서 설정 로드.
-     * configPath가 지정된 경우 Application 생성자에서 호출.
-     * bridge 섹션은 Rust에서 파싱하므로 JS 쪽은 database/app/themes 등을 로드.
-     * @param {string} configPath - 절대 경로
-     */
-    loadYaml(configPath) {
-        if (!existsSync(configPath)) return;
-
-        try {
-            const content = readFileSync(configPath, 'utf-8');
-            const raw = Config.parseYaml(content);
-            const parsed = Config.resolveEnvVars(raw);
-
-            // _raw에 병합 (기존 opts.config 우선)
-            for (const [key, value] of Object.entries(parsed)) {
-                if (this._raw[key] === undefined) {
-                    this._raw[key] = value;
-                }
-            }
-
-            // 섹션 별칭 갱신
-            if (!Object.keys(this.bridge).length && parsed.bridge) this.bridge = parsed.bridge;
-            if (!Object.keys(this.database).length && parsed.database) this.database = parsed.database;
-            if (!Object.keys(this.app).length && parsed.app) this.app = parsed.app;
-
-            // 캐시 초기화
-            this._cache.clear();
-        } catch (err) {
-            console.error(`[Config] YAML 파일 로드 실패 (${configPath}):`, err.message);
-        }
-    }
-
-    /**
-     * 간이 YAML 파서 — 외부 의존 없이 fuzionx.yaml 구조 파싱.
-     * 지원: 중첩 객체, 문자열, 숫자, boolean, 배열(인라인/블록), 인용 문자열.
-     * Windows(\r\n) / Unix(\n) 줄바꿈 모두 지원.
-     * @param {string} content
-     * @returns {object}
-     */
-    static parseYaml(content) {
-        const result = {};
-        // Windows \r\n → \n 정규화 (정규식 $, . 호환)
-        const lines = content.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n');
-        // stack: { indent, obj, lastKey? }
-        const stack = [{ indent: -1, obj: result }];
-
-        for (const rawLine of lines) {
-            // 인용부호 바깥의 # 주석만 제거 (문자열 안의 # 보존)
-            const line = Config._stripInlineComment(rawLine);
-            if (!line.trim()) continue;
-
-            const indent = line.search(/\S/);
-
-            // ── YAML 블록 배열 항목: "- value" 또는 "- key: value" ──
-            const listMatch = line.match(/^(\s*)-\s+(.+)$/);
-            if (listMatch) {
-                const listIndent = listMatch[1].length;
-
-                // 스택에서 현재 indent보다 깊은 레벨 제거 (배열은 유지)
-                while (stack.length > 1) {
-                    const top = stack[stack.length - 1];
-                    if (Array.isArray(top.obj) && top.indent === listIndent) break;
-                    if (top.indent >= listIndent) {
-                        stack.pop();
-                    } else {
-                        break;
-                    }
-                }
-
-                // 부모 찾기 — 배열이면 직접 사용, 아니면 lastKey를 배열로 변환
-                const top = stack[stack.length - 1];
-                let arr;
-                if (Array.isArray(top.obj)) {
-                    arr = top.obj;
-                } else {
-                    // lastKey 탐색: 현재 top → 상위 스택 순서로 찾기
-                    // (빈 값 키 origins: → {} 가 스택에 있으면 lastKey=undefined,
-                    //  이 경우 부모의 lastKey가 "origins")
-                    let foundIdx = -1;
-                    let foundKey = null;
-                    let foundObj = null;
-                    for (let si = stack.length - 1; si >= 0; si--) {
-                        if (stack[si].lastKey !== undefined) {
-                            foundIdx = si;
-                            foundKey = stack[si].lastKey;
-                            foundObj = stack[si].obj;
-                            // 배열이 아닌 빈 객체가 이 키 아래 있으면 그게 배열로 바뀌어야 함
-                            const target = Array.isArray(foundObj)
-                                ? foundObj[foundObj.length - 1]
-                                : foundObj;
-                            if (target && typeof target[foundKey] !== undefined) {
-                                foundObj = target;
-                            }
-                            break;
-                        }
-                    }
-                    if (foundKey === null) continue;
-                    if (!Array.isArray(foundObj[foundKey])) {
-                        foundObj[foundKey] = [];
-                    }
-                    arr = foundObj[foundKey];
-                    // 기존 빈 객체 스택 제거 후 배열로 교체
-                    while (stack.length > foundIdx + 1) stack.pop();
-                    stack.push({ indent: listIndent, obj: arr });
-                }
-
-                const itemContent = listMatch[2].trim();
-                // "- key: value" 형태인지 확인
-                const kvMatch = itemContent.match(/^(?:(["'])([^"']+)\1|([-\w.]+))\s*:\s*(.+)$/);
-                if (kvMatch) {
-                    const k = kvMatch[2] || kvMatch[3];
-                    const v = Config._parseYamlValue(kvMatch[4].trim());
-                    const obj = { [k]: v };
-                    arr.push(obj);
-                    stack.push({ indent: listIndent + 2, obj, lastKey: k });
-                } else {
-                    arr.push(Config._parseYamlValue(itemContent));
-                }
-                continue;
-            }
-
-            // ── 키: 값 파싱 ──
-            // 키: unquoted ([-\w.]+) 또는 quoted ("..." / '...')
-            const match = line.match(/^(\s*)(?:(["'])([^"']+)\2|([-\w.]+))\s*:\s*(.*)$/);
-            if (!match) continue;
-
-            const key = match[3] || match[4]; // quoted key (그룹3) 또는 unquoted key (그룹4)
-            const rawValue = match[5];
-
-            // 스택에서 현재 indent보다 깊거나 같은 레벨 제거
-            while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
-                stack.pop();
-            }
-
-            const top = stack[stack.length - 1];
-            // 배열 안의 마지막 객체에 키 추가 (- key: value 후속 키)
-            const target = Array.isArray(top.obj) ? top.obj[top.obj.length - 1] : top.obj;
-            const value = rawValue.trim();
-
-            if (!value) {
-                // 하위 객체 시작
-                target[key] = {};
-                stack.push({ indent, obj: target[key], lastKey: undefined });
-                // lastKey를 부모에 설정 (배열 전환 시 필요)
-                const parentIdx = stack.length - 2;
-                if (parentIdx >= 0) {
-                    stack[parentIdx].lastKey = key;
-                }
-            } else {
-                // 값 파싱
-                target[key] = Config._parseYamlValue(value);
-                top.lastKey = key;
-            }
-        }
-
-        return result;
-    }
-
-    /**
-     * 인라인 주석 제거 — 인용부호 안의 # 보존
-     * @param {string} line
-     * @returns {string}
-     * @private
-     */
-    static _stripInlineComment(line) {
-        let inSingle = false;
-        let inDouble = false;
-        for (let i = 0; i < line.length; i++) {
-            const ch = line[i];
-            if (ch === "'" && !inDouble) inSingle = !inSingle;
-            else if (ch === '"' && !inSingle) inDouble = !inDouble;
-            else if (ch === '#' && !inSingle && !inDouble) {
-                return line.slice(0, i);
-            }
-        }
-        return line;
-    }
-
-    /**
-     * YAML 값 파싱 (문자열, 숫자, boolean, 배열)
-     * @private
-     */
-    static _parseYamlValue(raw) {
-        // 인용 문자열
-        const quoted = raw.match(/^(['"])(.*)\1$/);
-        if (quoted) return quoted[2];
-
-        // boolean
-        if (raw === 'true') return true;
-        if (raw === 'false') return false;
-        if (raw === 'null' || raw === '~') return null;
-
-        // 인라인 배열 [a, b, c]
-        if (raw.startsWith('[') && raw.endsWith(']')) {
-            const inner = raw.slice(1, -1).trim();
-            if (!inner) return [];
-            return inner.split(',').map(s => Config._parseYamlValue(s.trim()));
-        }
-
-        // 숫자
-        const num = Number(raw);
-        if (!isNaN(num) && raw !== '') return num;
-
-        // 기본: 문자열
-        return raw;
-    }
-
-    /**
-     * .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;
-    }
-}
+/**
+ * Config — 통합 설정 접근
+ *
+ * fuzionx.yaml의 3개 섹션(bridge, database, app)을 통합 관리.
+ * dot-notation으로 접근: config.get('app.auth.secret')
+ *
+ * .env 자동 로드 + ${VAR:default} 환경변수 치환.
+ * YAML 파일 직접 파싱 지원 (외부 의존 없이 내장 파서 사용).
+ *
+ * @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();
+    }
+
+    /**
+     * YAML 파일에서 설정 로드.
+     * configPath가 지정된 경우 Application 생성자에서 호출.
+     * bridge 섹션은 Rust에서 파싱하므로 JS 쪽은 database/app/themes 등을 로드.
+     * @param {string} configPath - 절대 경로
+     */
+    loadYaml(configPath) {
+        if (!existsSync(configPath)) return;
+
+        try {
+            const content = readFileSync(configPath, 'utf-8');
+            const raw = Config.parseYaml(content);
+            const parsed = Config.resolveEnvVars(raw);
+
+            // _raw에 병합 (기존 opts.config 우선)
+            for (const [key, value] of Object.entries(parsed)) {
+                if (this._raw[key] === undefined) {
+                    this._raw[key] = value;
+                }
+            }
+
+            // 섹션 별칭 갱신
+            if (!Object.keys(this.bridge).length && parsed.bridge) this.bridge = parsed.bridge;
+            if (!Object.keys(this.database).length && parsed.database) this.database = parsed.database;
+            if (!Object.keys(this.app).length && parsed.app) this.app = parsed.app;
+
+            // 캐시 초기화
+            this._cache.clear();
+        } catch (err) {
+            console.error(`[Config] YAML 파일 로드 실패 (${configPath}):`, err.message);
+        }
+    }
+
+    /**
+     * 간이 YAML 파서 — 외부 의존 없이 fuzionx.yaml 구조 파싱.
+     * 지원: 중첩 객체, 문자열, 숫자, boolean, 배열(인라인/블록), 인용 문자열.
+     * Windows(\r\n) / Unix(\n) 줄바꿈 모두 지원.
+     * @param {string} content
+     * @returns {object}
+     */
+    static parseYaml(content) {
+        const result = {};
+        // Windows \r\n → \n 정규화 (정규식 $, . 호환)
+        const lines = content.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n');
+        // stack: { indent, obj, lastKey? }
+        const stack = [{ indent: -1, obj: result }];
+
+        for (const rawLine of lines) {
+            // 인용부호 바깥의 # 주석만 제거 (문자열 안의 # 보존)
+            const line = Config._stripInlineComment(rawLine);
+            if (!line.trim()) continue;
+
+            const indent = line.search(/\S/);
+
+            // ── YAML 블록 배열 항목: "- value" 또는 "- key: value" ──
+            const listMatch = line.match(/^(\s*)-\s+(.+)$/);
+            if (listMatch) {
+                const listIndent = listMatch[1].length;
+
+                // 스택에서 현재 indent보다 깊은 레벨 제거 (배열은 유지)
+                while (stack.length > 1) {
+                    const top = stack[stack.length - 1];
+                    if (Array.isArray(top.obj) && top.indent === listIndent) break;
+                    if (top.indent >= listIndent) {
+                        stack.pop();
+                    } else {
+                        break;
+                    }
+                }
+
+                // 부모 찾기 — 배열이면 직접 사용, 아니면 lastKey를 배열로 변환
+                const top = stack[stack.length - 1];
+                let arr;
+                if (Array.isArray(top.obj)) {
+                    arr = top.obj;
+                } else {
+                    // lastKey 탐색: 현재 top → 상위 스택 순서로 찾기
+                    // (빈 값 키 origins: → {} 가 스택에 있으면 lastKey=undefined,
+                    //  이 경우 부모의 lastKey가 "origins")
+                    let foundIdx = -1;
+                    let foundKey = null;
+                    let foundObj = null;
+                    for (let si = stack.length - 1; si >= 0; si--) {
+                        if (stack[si].lastKey !== undefined) {
+                            foundIdx = si;
+                            foundKey = stack[si].lastKey;
+                            foundObj = stack[si].obj;
+                            // 배열이 아닌 빈 객체가 이 키 아래 있으면 그게 배열로 바뀌어야 함
+                            const target = Array.isArray(foundObj)
+                                ? foundObj[foundObj.length - 1]
+                                : foundObj;
+                            if (target && typeof target[foundKey] !== undefined) {
+                                foundObj = target;
+                            }
+                            break;
+                        }
+                    }
+                    if (foundKey === null) continue;
+                    if (!Array.isArray(foundObj[foundKey])) {
+                        foundObj[foundKey] = [];
+                    }
+                    arr = foundObj[foundKey];
+                    // 기존 빈 객체 스택 제거 후 배열로 교체
+                    while (stack.length > foundIdx + 1) stack.pop();
+                    stack.push({ indent: listIndent, obj: arr });
+                }
+
+                const itemContent = listMatch[2].trim();
+                // "- key: value" 형태인지 확인
+                const kvMatch = itemContent.match(/^(?:(["'])([^"']+)\1|([-\w.]+))\s*:\s*(.+)$/);
+                if (kvMatch) {
+                    const k = kvMatch[2] || kvMatch[3];
+                    const v = Config._parseYamlValue(kvMatch[4].trim());
+                    const obj = { [k]: v };
+                    arr.push(obj);
+                    stack.push({ indent: listIndent + 2, obj, lastKey: k });
+                } else {
+                    arr.push(Config._parseYamlValue(itemContent));
+                }
+                continue;
+            }
+
+            // ── 키: 값 파싱 ──
+            // 키: unquoted ([-\w.]+) 또는 quoted ("..." / '...')
+            const match = line.match(/^(\s*)(?:(["'])([^"']+)\2|([-\w.]+))\s*:\s*(.*)$/);
+            if (!match) continue;
+
+            const key = match[3] || match[4]; // quoted key (그룹3) 또는 unquoted key (그룹4)
+            const rawValue = match[5];
+
+            // 스택에서 현재 indent보다 깊거나 같은 레벨 제거
+            while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
+                stack.pop();
+            }
+
+            const top = stack[stack.length - 1];
+            // 배열 안의 마지막 객체에 키 추가 (- key: value 후속 키)
+            const target = Array.isArray(top.obj) ? top.obj[top.obj.length - 1] : top.obj;
+            const value = rawValue.trim();
+
+            if (!value) {
+                // 하위 객체 시작
+                target[key] = {};
+                stack.push({ indent, obj: target[key], lastKey: undefined });
+                // lastKey를 부모에 설정 (배열 전환 시 필요)
+                const parentIdx = stack.length - 2;
+                if (parentIdx >= 0) {
+                    stack[parentIdx].lastKey = key;
+                }
+            } else {
+                // 값 파싱
+                target[key] = Config._parseYamlValue(value);
+                top.lastKey = key;
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * 인라인 주석 제거 — 인용부호 안의 # 보존
+     * @param {string} line
+     * @returns {string}
+     * @private
+     */
+    static _stripInlineComment(line) {
+        let inSingle = false;
+        let inDouble = false;
+        for (let i = 0; i < line.length; i++) {
+            const ch = line[i];
+            if (ch === "'" && !inDouble) inSingle = !inSingle;
+            else if (ch === '"' && !inSingle) inDouble = !inDouble;
+            else if (ch === '#' && !inSingle && !inDouble) {
+                return line.slice(0, i);
+            }
+        }
+        return line;
+    }
+
+    /**
+     * YAML 값 파싱 (문자열, 숫자, boolean, 배열)
+     * @private
+     */
+    static _parseYamlValue(raw) {
+        // 인용 문자열
+        const quoted = raw.match(/^(['"])(.*)\1$/);
+        if (quoted) return quoted[2];
+
+        // boolean
+        if (raw === 'true') return true;
+        if (raw === 'false') return false;
+        if (raw === 'null' || raw === '~') return null;
+
+        // 인라인 배열 [a, b, c]
+        if (raw.startsWith('[') && raw.endsWith(']')) {
+            const inner = raw.slice(1, -1).trim();
+            if (!inner) return [];
+            return inner.split(',').map(s => Config._parseYamlValue(s.trim()));
+        }
+
+        // 숫자
+        const num = Number(raw);
+        if (!isNaN(num) && raw !== '') return num;
+
+        // 기본: 문자열
+        return raw;
+    }
+
+    /**
+     * .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;
+    }
+}