@fuzionx/framework 0.1.2

package/lib/database/SqlQueryBuilder.js

@@ -0,0 +1,309 @@
+/**
+ * SqlQueryBuilder — SQL 쿼리 빌더 (SQLite / MariaDB / PostgreSQL 공통)
+ *
+ * QueryBuilder를 상속하여 터미널 메서드(get/count/update/delete)에서
+ * 실제 SQL을 생성하고 실행합니다.
+ *
+ * @see docs/framework/02-database-orm.md
+ */
+import QueryBuilder from './QueryBuilder.js';
+
+export default class SqlQueryBuilder extends QueryBuilder {
+    constructor(model) {
+        super(model);
+    }
+
+    /**
+     * 결과 조회 — SQL SELECT 실행
+     * @returns {Promise<Array<import('./Model.js').default>>}
+     */
+    async get() {
+        const conn = this._model.getConnection();
+
+        if (conn.type === 'sqlite' && conn.db) {
+            return this._executeSqlite(conn.db, 'select');
+        }
+
+        if (conn.type === 'knex' && conn.db) {
+            return this._executeKnex(conn.db, 'select');
+        }
+
+        // Stub: no connection
+        return [];
+    }
+
+    /**
+     * 단일 결과
+     * @returns {Promise<object|null>}
+     */
+    async first() {
+        this._limit = 1;
+        const results = await this.get();
+        return results[0] || null;
+    }
+
+    /**
+     * 카운트
+     * @returns {Promise<number>}
+     */
+    async count() {
+        const conn = this._model.getConnection();
+
+        if (conn.type === 'sqlite' && conn.db) {
+            const rows = this._executeSqlite(conn.db, 'count');
+            return rows[0]?.cnt ?? 0;
+        }
+
+        if (conn.type === 'knex' && conn.db) {
+            let query = conn.db(this._model.table);
+            query = this._applyWheres(query);
+            query = this._applySoftDelete(query);
+            const [result] = await query.count('* as cnt');
+            // PostgreSQL returns string, MySQL returns number; key can vary
+            const cnt = result?.cnt ?? result?.['count(*)'] ?? result?.count ?? 0;
+            return Number(cnt);
+        }
+
+        return 0;
+    }
+
+    /**
+     * 조건부 수정
+     * @param {object} data
+     * @returns {Promise<number>} 수정된 행 수
+     */
+    async update(data) {
+        if (this._model.timestamps && !data.updated_at) {
+            const conn = this._model.getConnection();
+            const isMysql = conn?.type === 'knex' && (conn.driver === 'mariadb' || conn.driver === 'mysql');
+            data.updated_at = isMysql
+                ? new Date().toISOString().replace('T', ' ').replace('Z', '')
+                : new Date().toISOString();
+        }
+
+        const conn = this._model.getConnection();
+
+        if (conn.type === 'sqlite' && conn.db) {
+            const { sql, params } = this._buildUpdateSql(data);
+            const result = conn.db.prepare(sql).run(...params);
+            return result.changes;
+        }
+
+        if (conn.type === 'knex' && conn.db) {
+            let query = conn.db(this._model.table);
+            query = this._applyWheres(query);
+            query = this._applySoftDelete(query);
+            return query.update(data);
+        }
+
+        return 0;
+    }
+
+    /**
+     * 조건부 삭제
+     * @returns {Promise<number>}
+     */
+    async delete() {
+        const conn = this._model.getConnection();
+
+        // softDelete → UPDATE deleted_at
+        if (this._softDelete) {
+            const isMysql = conn?.type === 'knex' && (conn.driver === 'mariadb' || conn.driver === 'mysql');
+            const now = isMysql
+                ? new Date().toISOString().replace('T', ' ').replace('Z', '')
+                : new Date().toISOString();
+            return this.update({ deleted_at: now });
+        }
+
+        if (conn.type === 'sqlite' && conn.db) {
+            const { whereClause, whereParams } = this._buildWhereSql();
+            const sql = `DELETE FROM ${this._model.table}${whereClause}`;
+            const result = conn.db.prepare(sql).run(...whereParams);
+            return result.changes;
+        }
+
+        if (conn.type === 'knex' && conn.db) {
+            let query = conn.db(this._model.table);
+            query = this._applyWheres(query);
+            return query.delete();
+        }
+
+        return 0;
+    }
+
+    /**
+     * 페이지네이션
+     * @param {number} page
+     * @param {number} perPage
+     */
+    async paginate(page = 1, perPage = 20) {
+        const total = await this.count();
+        this._limit = perPage;
+        this._offset = (page - 1) * perPage;
+        const data = await this.get();
+        return {
+            data,
+            page,
+            perPage,
+            total,
+            lastPage: Math.ceil(total / perPage),
+        };
+    }
+
+    // ━━━━━━━━━━ SQLite 실행 ━━━━━━━━━━
+
+    /**
+     * SQLite SELECT / COUNT 실행
+     * @private
+     */
+    _executeSqlite(db, mode = 'select') {
+        const { whereClause, whereParams } = this._buildWhereSql();
+
+        const selectColumns = mode === 'count'
+            ? 'COUNT(*) as cnt'
+            : (this._selects ? this._selects.join(', ') : '*');
+
+        let sql = `SELECT ${selectColumns} FROM ${this._model.table}${whereClause}`;
+
+        // ORDER BY
+        if (this._orders.length > 0 && mode !== 'count') {
+            const orderParts = this._orders.map(o => `${o.column} ${o.direction.toUpperCase()}`);
+            sql += ` ORDER BY ${orderParts.join(', ')}`;
+        }
+
+        // LIMIT / OFFSET
+        if (this._limit != null && mode !== 'count') {
+            sql += ` LIMIT ${this._limit}`;
+        }
+        if (this._offset != null && mode !== 'count') {
+            sql += ` OFFSET ${this._offset}`;
+        }
+
+        const rows = db.prepare(sql).all(...whereParams);
+
+        if (mode === 'count') return rows;
+        return rows.map(row => new this._model(row));
+    }
+
+    /**
+     * SQL WHERE절 생성
+     * @private
+     * @returns {{ whereClause: string, whereParams: Array }}
+     */
+    _buildWhereSql() {
+        const parts = [];
+        const params = [];
+
+        // softDelete 자동 필터
+        if (this._softDelete && !this._withTrashed) {
+            if (this._onlyTrashed) {
+                parts.push('deleted_at IS NOT NULL');
+            } else {
+                parts.push('deleted_at IS NULL');
+            }
+        }
+
+        for (const w of this._wheres) {
+            const prefix = parts.length > 0
+                ? (w.type === 'or' ? ' OR ' : ' AND ')
+                : '';
+
+            if (w.op === 'IN') {
+                const placeholders = w.value.map(() => '?').join(', ');
+                parts.push(`${prefix}${w.key} IN (${placeholders})`);
+                params.push(...w.value);
+            } else if (w.op === 'IS NULL') {
+                parts.push(`${prefix}${w.key} IS NULL`);
+            } else if (w.op === 'IS NOT NULL') {
+                parts.push(`${prefix}${w.key} IS NOT NULL`);
+            } else {
+                parts.push(`${prefix}${w.key} ${w.op} ?`);
+                params.push(w.value);
+            }
+        }
+
+        const whereClause = parts.length > 0 ? ` WHERE ${parts.join('')}` : '';
+        return { whereClause, whereParams: params };
+    }
+
+    /**
+     * SQL UPDATE문 생성
+     * @private
+     */
+    _buildUpdateSql(data) {
+        const { whereClause, whereParams } = this._buildWhereSql();
+        const columns = Object.keys(data);
+        const sets = columns.map(c => `${c} = ?`).join(', ');
+        const sql = `UPDATE ${this._model.table} SET ${sets}${whereClause}`;
+        const params = [...Object.values(data), ...whereParams];
+        return { sql, params };
+    }
+
+    // ━━━━━━━━━━ Knex 실행 ━━━━━━━━━━
+
+    /**
+     * Knex SELECT 실행
+     * @private
+     */
+    async _executeKnex(knex, mode = 'select') {
+        let query = knex(this._model.table);
+
+        // SELECT columns
+        if (this._selects) {
+            query = query.select(...this._selects);
+        }
+
+        // WHERE
+        query = this._applyWheres(query);
+
+        // softDelete
+        query = this._applySoftDelete(query);
+
+        // ORDER BY
+        for (const o of this._orders) {
+            query = query.orderBy(o.column, o.direction);
+        }
+
+        // LIMIT / OFFSET
+        if (this._limit != null) query = query.limit(this._limit);
+        if (this._offset != null) query = query.offset(this._offset);
+
+        const rows = await query;
+        return rows.map(row => new this._model(row));
+    }
+
+    /**
+     * Knex에 WHERE 조건 적용
+     * @private
+     */
+    _applyWheres(query) {
+        for (const w of this._wheres) {
+            const method = w.type === 'or' ? 'orWhere' : 'where';
+            if (w.op === 'IN') {
+                query = query.whereIn(w.key, w.value);
+            } else if (w.op === 'IS NULL') {
+                query = query.whereNull(w.key);
+            } else if (w.op === 'IS NOT NULL') {
+                query = query.whereNotNull(w.key);
+            } else {
+                query = query[method](w.key, w.op, w.value);
+            }
+        }
+        return query;
+    }
+
+    /**
+     * softDelete 필터 적용
+     * @private
+     */
+    _applySoftDelete(query) {
+        if (this._softDelete && !this._withTrashed) {
+            if (this._onlyTrashed) {
+                query = query.whereNotNull('deleted_at');
+            } else {
+                query = query.whereNull('deleted_at');
+            }
+        }
+        return query;
+    }
+}

package/lib/helpers/CryptoHelper.js

@@ -0,0 +1,48 @@
+/**
+ * CryptoHelper — Bridge crypto N-API 래퍼
+ *
+ * @see docs/framework/19-utilities.md — "1. Crypto (app.crypto)"
+ * @see packages/fuzionx/lib/crypto.js (Core 래퍼)
+ */
+import { randomUUID, createHash as nodeCreateHash, createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+
+export default class CryptoHelper {
+    constructor(bridge) { this._bridge = bridge; }
+
+    uuid() {
+        if (this._bridge?.cryptoUuid) return this._bridge.cryptoUuid();
+        return randomUUID();
+    }
+
+    md5(input) {
+        if (this._bridge?.cryptoMd5) return this._bridge.cryptoMd5(input);
+        return nodeCreateHash('md5').update(input).digest('hex');
+    }
+
+    sha256(input) {
+        if (this._bridge?.cryptoSha256) return this._bridge.cryptoSha256(input);
+        return nodeCreateHash('sha256').update(input).digest('hex');
+    }
+
+    encrypt(key, plaintext) {
+        if (this._bridge?.cryptoEncryptAes) return this._bridge.cryptoEncryptAes(key, plaintext);
+        const keyBuf = Buffer.from(key.padEnd(32, '0').slice(0, 32));
+        const iv = randomBytes(12);
+        const cipher = createCipheriv('aes-256-gcm', keyBuf, iv);
+        let encrypted = cipher.update(plaintext, 'utf-8', 'base64');
+        encrypted += cipher.final('base64');
+        const tag = cipher.getAuthTag().toString('base64');
+        return `${iv.toString('base64')}.${encrypted}.${tag}`;
+    }
+
+    decrypt(key, ciphertext) {
+        if (this._bridge?.cryptoDecryptAes) return this._bridge.cryptoDecryptAes(key, ciphertext);
+        const [ivB64, encB64, tagB64] = ciphertext.split('.');
+        const keyBuf = Buffer.from(key.padEnd(32, '0').slice(0, 32));
+        const decipher = createDecipheriv('aes-256-gcm', keyBuf, Buffer.from(ivB64, 'base64'));
+        decipher.setAuthTag(Buffer.from(tagB64, 'base64'));
+        let decrypted = decipher.update(encB64, 'base64', 'utf-8');
+        decrypted += decipher.final('utf-8');
+        return decrypted;
+    }
+}

package/lib/helpers/FileHelper.js

@@ -0,0 +1,61 @@
+/**
+ * FileHelper — Bridge file N-API 래퍼
+ *
+ * @see docs/framework/19-utilities.md — "4. File (app.file)"
+ * @see packages/fuzionx/lib/file.js (Core 래퍼)
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export default class FileHelper {
+    constructor(bridge) { this._bridge = bridge; }
+
+    async move(src, dst) {
+        if (this._bridge?.fileMoveFile) return this._bridge.fileMoveFile(src, dst);
+        await fs.mkdir(path.dirname(dst), { recursive: true });
+        await fs.rename(src, dst).catch(async () => {
+            await fs.copyFile(src, dst);
+            await fs.unlink(src);
+        });
+    }
+
+    async copy(src, dst) {
+        if (this._bridge?.fileCopyFile) return this._bridge.fileCopyFile(src, dst);
+        await fs.mkdir(path.dirname(dst), { recursive: true });
+        await fs.copyFile(src, dst);
+        const stat = await fs.stat(dst);
+        return stat.size;
+    }
+
+    async ensureDir(dirPath) {
+        if (this._bridge?.fileEnsureDir) return this._bridge.fileEnsureDir(dirPath);
+        await fs.mkdir(dirPath, { recursive: true });
+    }
+
+    async size(filePath) {
+        if (this._bridge?.fileSize) return this._bridge.fileSize(filePath);
+        const stat = await fs.stat(filePath);
+        return stat.size;
+    }
+
+    async exists(filePath) {
+        if (this._bridge?.fileExists) return this._bridge.fileExists(filePath);
+        try { await fs.access(filePath); return true; } catch { return false; }
+    }
+
+    async remove(filePath) {
+        if (this._bridge?.fileRemove) return this._bridge.fileRemove(filePath);
+        await fs.unlink(filePath);
+    }
+
+    tempPath(prefix = 'fx') {
+        if (this._bridge?.fileTempPath) return this._bridge.fileTempPath(prefix);
+        return path.join('/tmp', `${prefix}-${randomUUID()}`);
+    }
+
+    extension(filePath) {
+        const ext = path.extname(filePath).slice(1).toLowerCase();
+        return ext || null;
+    }
+}

package/lib/helpers/HashHelper.js

@@ -0,0 +1,39 @@
+/**
+ * HashHelper — Bridge hash N-API 래퍼
+ *
+ * @see docs/framework/19-utilities.md — "2. Hash (app.hash)"
+ * @see packages/fuzionx/lib/hash.js (Core 래퍼)
+ */
+import { randomUUID, createHash as nodeCreateHash } from 'node:crypto';
+
+export default class HashHelper {
+    constructor(bridge) { this._bridge = bridge; }
+
+    /** ⚠️ JS 폴백: SHA-256 기반 유사 구현 (테스트 전용, 프로덕션은 Bridge 필수) */
+    bcrypt(password, cost = 12) {
+        if (this._bridge?.hashBcrypt) return this._bridge.hashBcrypt(password, cost);
+        const salt = randomUUID().replace(/-/g, '').slice(0, 22);
+        return `$2b$${cost}$${salt}${nodeCreateHash('sha256').update(password + salt).digest('hex')}`;
+    }
+
+    bcryptVerify(password, hash) {
+        if (this._bridge?.hashBcryptVerify) return this._bridge.hashBcryptVerify(password, hash);
+        const salt = hash.slice(7, 29);
+        const expected = `$2b$12$${salt}${nodeCreateHash('sha256').update(password + salt).digest('hex')}`;
+        return hash === expected;
+    }
+
+    argon2(password) {
+        if (this._bridge?.hashArgon2) return this._bridge.hashArgon2(password);
+        const salt = randomUUID().replace(/-/g, '');
+        return `$argon2id$v=19$m=65536,t=3,p=4$${salt}$${nodeCreateHash('sha256').update(password + salt).digest('hex')}`;
+    }
+
+    argon2Verify(password, hash) {
+        if (this._bridge?.hashArgon2Verify) return this._bridge.hashArgon2Verify(password, hash);
+        const parts = hash.split('$');
+        const salt = parts[4] || '';
+        const expected = nodeCreateHash('sha256').update(password + salt).digest('hex');
+        return parts[5] === expected;
+    }
+}

package/lib/helpers/I18nHelper.js

@@ -0,0 +1,170 @@
+/**
+ * I18nHelper — Bridge i18n N-API 위임 + JS 폴백
+ *
+ * Bridge의 i18NTranslate(locale, key) 직접 호출.
+ * Bridge 없으면 JS 파일 기반 폴백.
+ *
+ * @see docs/framework/18-i18n.md
+ * @see packages/fuzionx/lib/i18n.js (Core 래퍼 참조)
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+export default class I18nHelper {
+    /**
+     * @param {object} [opts]
+     * @param {string} [opts.defaultLocale='ko']
+     * @param {string} [opts.fallback='en']
+     * @param {string} [opts.dir='./locales']
+     * @param {object} [opts.bridge] - Bridge N-API 인스턴스
+     */
+    constructor(opts = {}) {
+        this.defaultLocale = opts.defaultLocale || 'ko';
+        this.fallback = opts.fallback || 'en';
+        this.dir = opts.dir || './locales';
+        this._bridge = opts.bridge || null;
+        this._messages = new Map(); // locale → { flat key: value }
+        this._loaded = false;
+    }
+
+    /**
+     * 번역 파일 로드 (JS 폴백용)
+     */
+    async load() {
+        if (this._loaded) return;
+        try {
+            const entries = await fs.readdir(this.dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isFile()) continue;
+                const ext = path.extname(entry.name);
+                if (ext !== '.yaml' && ext !== '.yml' && ext !== '.json') continue;
+                const locale = path.basename(entry.name, ext);
+                const content = await fs.readFile(path.join(this.dir, entry.name), 'utf-8');
+                const data = ext === '.json' ? JSON.parse(content) : this._parseSimpleYaml(content);
+                this._messages.set(locale, this._flatten(data));
+            }
+        } catch {} // locales/ 없으면 무시
+        this._loaded = true;
+    }
+
+    /**
+     * 번역 키 조회
+     *
+     * Bridge가 있으면 bridge.i18NTranslate(locale, key) 호출.
+     * Bridge 없으면 JS 메시지 맵에서 조회.
+     *
+     * @param {string} locale
+     * @param {string} key - dot-notation (e.g. 'auth.login_required')
+     * @param {object} [vars] - 치환 변수 + { default? }
+     * @returns {string}
+     */
+    translate(locale, key, vars = {}) {
+        // ── Bridge N-API 위임 ──
+        // Core i18n.js 참조: bridge.i18NTranslate(locale, key)
+        if (this._bridge && typeof this._bridge.i18NTranslate === 'function') {
+            try {
+                const result = this._bridge.i18NTranslate(locale, key);
+                if (result != null) return this._substitute(result, vars);
+            } catch {} // Bridge 실패 시 JS 폴백
+        }
+
+        // ── JS 폴백 ──
+        const messages = this._messages.get(locale)
+            || this._messages.get(this.fallback)
+            || this._messages.get(this.defaultLocale);
+        if (!messages) return vars.default || key;
+
+        const value = messages[key];
+        if (value == null) return vars.default || key;
+
+        return this._substitute(value, vars);
+    }
+
+    /**
+     * 전체 locale 데이터 반환 (뷰 주입용)
+     * @param {string} locale
+     * @returns {object}
+     */
+    all(locale) {
+        // Bridge: i18NGetLocales() 는 locale 목록만 반환, 전체 데이터 API 없음
+        const messages = this._messages.get(locale) || this._messages.get(this.defaultLocale);
+        if (!messages) return {};
+        return { ...messages };
+    }
+
+    /** getAll alias (ctx.t.all() 호환) */
+    getAll(locale) { return this.all(locale); }
+
+    /**
+     * 사용 가능한 locale 목록
+     * @returns {string[]}
+     */
+    locales() {
+        if (this._bridge && typeof this._bridge.i18NGetLocales === 'function') {
+            try { return this._bridge.i18NGetLocales(); } catch {}
+        }
+        return [...this._messages.keys()];
+    }
+
+    /**
+     * 누락 키 업데이트 (dev 모드)
+     * @param {string} key
+     * @param {string} value
+     */
+    updateMissing(key, value) {
+        if (this._bridge && typeof this._bridge.i18NUpdateMissingKey === 'function') {
+            try { this._bridge.i18NUpdateMissingKey(key, value); } catch {}
+        }
+    }
+
+    /** {field} → value 치환 */
+    _substitute(template, vars) {
+        if (!vars || typeof template !== 'string') return template;
+        return template.replace(/\{(\w+)\}/g, (_, key) => {
+            if (key === 'locale' || key === 'default') return `{${key}}`; // 예약어
+            return vars[key] !== undefined ? String(vars[key]) : `{${key}}`;
+        });
+    }
+
+    /** YAML 간단 파서 (중첩 키 → dot-notation flat map) */
+    _parseSimpleYaml(content) {
+        const result = {};
+        const lines = content.split('\n');
+        const stack = [];
+
+        for (const line of lines) {
+            if (!line.trim() || line.trim().startsWith('#')) continue;
+
+            const indent = line.search(/\S/);
+            const match = line.match(/^(\s*)(\w[\w.]*)\s*:\s*(.*)$/);
+            if (!match) continue;
+
+            const [, , key, rawValue] = match;
+            const level = Math.floor(indent / 2);
+
+            while (stack.length > level) stack.pop();
+            stack[level] = key;
+
+            const value = rawValue.replace(/^["']|["']$/g, '').trim();
+            if (value) {
+                const fullKey = stack.filter(Boolean).join('.');
+                result[fullKey] = value;
+            }
+        }
+        return result;
+    }
+
+    /** 중첩 객체 → flat dot-notation */
+    _flatten(obj, prefix = '') {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            const fullKey = prefix ? `${prefix}.${key}` : key;
+            if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                Object.assign(result, this._flatten(value, fullKey));
+            } else {
+                result[fullKey] = String(value);
+            }
+        }
+        return result;
+    }
+}