@fuzionx/framework 0.1.39 → 0.1.42

package/lib/database/SqlQueryBuilder.js

@@ -1,332 +1,332 @@
-/**
- * SqlQueryBuilder — SQL 쿼리 빌더 (SQLite / MariaDB / PostgreSQL 공통)
- *
- * QueryBuilder를 상속하여 터미널 메서드(get/count/update/delete)에서
- * 실제 SQL을 생성하고 실행합니다.
- *
- * @see docs/framework/02-database-orm.md
- */
-import QueryBuilder from './QueryBuilder.js';
-import Pagination from './Pagination.js';
-
-export default class SqlQueryBuilder extends QueryBuilder {
-    constructor(model) {
-        super(model);
-    }
-
-    /**
-     * SQL 식별자(컬럼명/테이블명) 유효성 검증 — SQL Injection 방지
-     * @param {string} name
-     * @returns {string}
-     * @private
-     */
-    static _sanitizeName(name) {
-        if (typeof name !== 'string' || !/^[\w.]+$/.test(name)) {
-            throw new Error(`Invalid SQL identifier: '${name}'`);
-        }
-        return name;
-    }
-
-    /**
-     * 결과 조회 — 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 safeTable = SqlQueryBuilder._sanitizeName(this._model.table);
-            const sql = `DELETE FROM ${safeTable}${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 new Pagination(data, total, page, 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.map(c => SqlQueryBuilder._sanitizeName(c)).join(', ') : '*');
-
-        const safeTable = SqlQueryBuilder._sanitizeName(this._model.table);
-
-        let sql = `SELECT ${selectColumns} FROM ${safeTable}${whereClause}`;
-
-        // ORDER BY
-        if (this._orders.length > 0 && mode !== 'count') {
-            const orderParts = this._orders.map(o => `${SqlQueryBuilder._sanitizeName(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 safeKey = SqlQueryBuilder._sanitizeName(w.key);
-            let expr;
-
-            if (w.op === 'IN') {
-                const placeholders = w.value.map(() => '?').join(', ');
-                expr = `${safeKey} IN (${placeholders})`;
-                params.push(...w.value);
-            } else if (w.op === 'IS NULL') {
-                expr = `${safeKey} IS NULL`;
-            } else if (w.op === 'IS NOT NULL') {
-                expr = `${safeKey} IS NOT NULL`;
-            } else {
-                expr = `${safeKey} ${w.op} ?`;
-                params.push(w.value);
-            }
-
-            if (w.type === 'or' && parts.length > 0) {
-                // OR 조건: 이전 항목과 괄호로 그룹핑
-                const prev = parts.pop();
-                // 이전 항목이 이미 괄호 그룹이면 내부에 추가
-                if (prev.startsWith('(') && prev.endsWith(')')) {
-                    parts.push(`${prev.slice(0, -1)} OR ${expr})`);
-                } else {
-                    parts.push(`(${prev} OR ${expr})`);
-                }
-            } else {
-                parts.push(expr);
-            }
-        }
-
-        const whereClause = parts.length > 0 ? ` WHERE ${parts.join(' AND ')}` : '';
-        return { whereClause, whereParams: params };
-    }
-
-    /**
-     * SQL UPDATE문 생성
-     * @private
-     */
-    _buildUpdateSql(data) {
-        const { whereClause, whereParams } = this._buildWhereSql();
-        const columns = Object.keys(data);
-        const sets = columns.map(c => `${SqlQueryBuilder._sanitizeName(c)} = ?`).join(', ');
-        const sql = `UPDATE ${SqlQueryBuilder._sanitizeName(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;
-    }
-}
+/**
+ * SqlQueryBuilder — SQL 쿼리 빌더 (SQLite / MariaDB / PostgreSQL 공통)
+ *
+ * QueryBuilder를 상속하여 터미널 메서드(get/count/update/delete)에서
+ * 실제 SQL을 생성하고 실행합니다.
+ *
+ * @see docs/framework/02-database-orm.md
+ */
+import QueryBuilder from './QueryBuilder.js';
+import Pagination from './Pagination.js';
+
+export default class SqlQueryBuilder extends QueryBuilder {
+    constructor(model) {
+        super(model);
+    }
+
+    /**
+     * SQL 식별자(컬럼명/테이블명) 유효성 검증 — SQL Injection 방지
+     * @param {string} name
+     * @returns {string}
+     * @private
+     */
+    static _sanitizeName(name) {
+        if (typeof name !== 'string' || !/^[\w.]+$/.test(name)) {
+            throw new Error(`Invalid SQL identifier: '${name}'`);
+        }
+        return name;
+    }
+
+    /**
+     * 결과 조회 — 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 safeTable = SqlQueryBuilder._sanitizeName(this._model.table);
+            const sql = `DELETE FROM ${safeTable}${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 new Pagination(data, total, page, 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.map(c => SqlQueryBuilder._sanitizeName(c)).join(', ') : '*');
+
+        const safeTable = SqlQueryBuilder._sanitizeName(this._model.table);
+
+        let sql = `SELECT ${selectColumns} FROM ${safeTable}${whereClause}`;
+
+        // ORDER BY
+        if (this._orders.length > 0 && mode !== 'count') {
+            const orderParts = this._orders.map(o => `${SqlQueryBuilder._sanitizeName(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 safeKey = SqlQueryBuilder._sanitizeName(w.key);
+            let expr;
+
+            if (w.op === 'IN') {
+                const placeholders = w.value.map(() => '?').join(', ');
+                expr = `${safeKey} IN (${placeholders})`;
+                params.push(...w.value);
+            } else if (w.op === 'IS NULL') {
+                expr = `${safeKey} IS NULL`;
+            } else if (w.op === 'IS NOT NULL') {
+                expr = `${safeKey} IS NOT NULL`;
+            } else {
+                expr = `${safeKey} ${w.op} ?`;
+                params.push(w.value);
+            }
+
+            if (w.type === 'or' && parts.length > 0) {
+                // OR 조건: 이전 항목과 괄호로 그룹핑
+                const prev = parts.pop();
+                // 이전 항목이 이미 괄호 그룹이면 내부에 추가
+                if (prev.startsWith('(') && prev.endsWith(')')) {
+                    parts.push(`${prev.slice(0, -1)} OR ${expr})`);
+                } else {
+                    parts.push(`(${prev} OR ${expr})`);
+                }
+            } else {
+                parts.push(expr);
+            }
+        }
+
+        const whereClause = parts.length > 0 ? ` WHERE ${parts.join(' AND ')}` : '';
+        return { whereClause, whereParams: params };
+    }
+
+    /**
+     * SQL UPDATE문 생성
+     * @private
+     */
+    _buildUpdateSql(data) {
+        const { whereClause, whereParams } = this._buildWhereSql();
+        const columns = Object.keys(data);
+        const sets = columns.map(c => `${SqlQueryBuilder._sanitizeName(c)} = ?`).join(', ');
+        const sql = `UPDATE ${SqlQueryBuilder._sanitizeName(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;
+    }
+}