@fuzionx/framework 0.1.39 → 0.1.42

package/lib/database/SqlModel.js

@@ -1,257 +1,257 @@
-/**
- * SqlModel — SQL 공통 로직 (SQLite / MariaDB / PostgreSQL 공유)
- *
- * Knex-style 쿼리 빌딩을 공통화한 중간 클래스.
- * SQLiteModel, MariaModel, PostgreModel이 이 클래스를 상속.
- *
- * @see docs/framework/02-database-orm.md
- */
-import Model from './Model.js';
-import SqlQueryBuilder from './SqlQueryBuilder.js';
-
-/**
- * DB 드라이버에 맞는 datetime 문자열 반환
- * MySQL/MariaDB: 'YYYY-MM-DD HH:MM:SS.SSS' (T/Z 제거, 밀리초 유지 — DATETIME(3) 지원)
- * SQLite/PostgreSQL: ISO 8601
- */
-function dbNow(conn) {
-    if (conn?.type === 'knex' && (conn.driver === 'mariadb' || conn.driver === 'mysql')) {
-        return new Date().toISOString().replace('T', ' ').replace('Z', '');
-    }
-    return new Date().toISOString();
-}
-
-export default class SqlModel extends Model {
-    /** @type {string} DB 드라이버 — 서브클래스에서 오버라이드 */
-    static driver = 'sql';
-
-    /**
-     * ConnectionManager 인스턴스 (Application에서 주입)
-     * @type {import('./ConnectionManager.js').default|null}
-     */
-    static _connectionManager = null;
-
-    /**
-     * ConnectionManager를 모든 SqlModel 서브클래스에 주입
-     * @param {import('./ConnectionManager.js').default} cm
-     */
-    static setConnectionManager(cm) {
-        SqlModel._connectionManager = cm;
-    }
-
-    /**
-     * DB 연결 가져오기
-     * @returns {object} connection object
-     */
-    static getConnection() {
-        if (!SqlModel._connectionManager) {
-            throw new Error(
-                `DB not initialized. Ensure Application.boot() has been called and database is configured.`
-            );
-        }
-        return SqlModel._connectionManager.get(this.connection);
-    }
-
-    /** 쿼리 빌더 시작 — SQL 전용 */
-    static query() {
-        return new SqlQueryBuilder(this);
-    }
-
-    /** where 체이닝 시작 */
-    static where(key, op, value) {
-        return this.query().where(key, op, value);
-    }
-
-    /** limit 체이닝 */
-    static limit(n) {
-        return this.query().limit(n);
-    }
-
-    /** with 체이닝 */
-    static with(...relations) {
-        return this.query().with(...relations);
-    }
-
-    /** 페이지네이션 */
-    static paginate(page, perPage) {
-        return this.query().paginate(page, perPage);
-    }
-
-    /**
-     * 레코드 생성
-     * @param {object} data
-     * @returns {Promise<Model>}
-     */
-    static async create(data) {
-        const conn = this.getConnection();
-        const insertData = { ...data };
-
-        // timestamps 자동 관리
-        if (this.timestamps) {
-            const now = dbNow(conn);
-            if (!insertData.created_at) insertData.created_at = now;
-            if (!insertData.updated_at) insertData.updated_at = now;
-        }
-
-        if (conn.type === 'sqlite' && conn.db) {
-            const columns = Object.keys(insertData).map(c => SqlQueryBuilder._sanitizeName(c));
-            const placeholders = columns.map(() => '?').join(', ');
-            const safeTable = SqlQueryBuilder._sanitizeName(this.table);
-            const sql = `INSERT INTO ${safeTable} (${columns.join(', ')}) VALUES (${placeholders})`;
-            const result = conn.db.prepare(sql).run(...Object.values(insertData));
-            const id = result.lastInsertRowid;
-            return new this({ ...insertData, [this.primaryKey]: Number(id) });
-        }
-
-        if (conn.type === 'knex' && conn.db) {
-            // MySQL: insert returns [insertId], PostgreSQL: needs .returning()
-            if (conn.driver === 'postgres') {
-                const [row] = await conn.db(this.table).insert(insertData).returning(this.primaryKey);
-                const id = typeof row === 'object' ? row[this.primaryKey] : row;
-                return new this({ ...insertData, [this.primaryKey]: id });
-            } else {
-                const [id] = await conn.db(this.table).insert(insertData);
-                return new this({ ...insertData, [this.primaryKey]: id });
-            }
-        }
-
-        // Stub: no DB connection
-        return new this({ ...insertData, [this.primaryKey]: Date.now() });
-    }
-
-    /**
-     * ID로 조회
-     * @param {*} id
-     * @returns {Promise<Model|null>}
-     */
-    static async find(id) {
-        return this.query().where(this.primaryKey, id).first();
-    }
-
-    /**
-     * 전체 조회
-     * @returns {Promise<Array>}
-     */
-    static async all() {
-        return this.query().get();
-    }
-
-    static async findAll() { return this.all(); }
-
-    /**
-     * 여러 ID 조회
-     * @param {Array} ids
-     */
-    static async findMany(ids) {
-        return this.query().whereIn(this.primaryKey, ids).get();
-    }
-
-    /**
-     * Raw SQL 실행
-     * @param {string} sql
-     * @param {Array} [bindings]
-     * @returns {Promise<Array>}
-     */
-    static async raw(sql, bindings = []) {
-        const conn = this.getConnection();
-
-        if (conn.type === 'sqlite' && conn.db) {
-            return conn.db.prepare(sql).all(...bindings);
-        }
-
-        if (conn.type === 'knex' && conn.db) {
-            const result = await conn.db.raw(sql, bindings);
-            // MySQL: [[rows], fields], PostgreSQL: { rows: [...] }
-            if (Array.isArray(result)) {
-                return Array.isArray(result[0]) ? result[0] : result;
-            }
-            return result.rows || [];
-        }
-
-        return [];
-    }
-
-    /**
-     * 네이티브 드라이버 접근
-     * @returns {object}
-     */
-    static nativeConnection() {
-        const conn = this.getConnection();
-        if (conn.type === 'sqlite') return conn.db;
-        if (conn.type === 'knex') return conn.db;
-        return null;
-    }
-
-    // ━━━━━━━━━━ 인스턴스 메서드 ━━━━━━━━━━
-
-    /**
-     * 인스턴스 수정
-     * @param {object} data
-     * @returns {Promise<this>}
-     */
-    async update(data) {
-        Object.assign(this._attributes, data);
-        Object.assign(this, data);
-
-        if (this.constructor.timestamps && !data.updated_at) {
-            const conn = this.constructor.getConnection();
-            const now = dbNow(conn);
-            this._attributes.updated_at = now;
-            this.updated_at = now;
-            data.updated_at = now;
-        }
-
-        const pk = this.constructor.primaryKey;
-        const id = this._attributes[pk];
-        if (id == null) return this;
-
-        const conn = this.constructor.getConnection();
-
-        if (conn.type === 'sqlite' && conn.db) {
-            const columns = Object.keys(data).map(c => SqlQueryBuilder._sanitizeName(c));
-            const pk = SqlQueryBuilder._sanitizeName(this.constructor.primaryKey);
-            const safeTable = SqlQueryBuilder._sanitizeName(this.constructor.table);
-            const sets = columns.map(c => `${c} = ?`).join(', ');
-            const sql = `UPDATE ${safeTable} SET ${sets} WHERE ${pk} = ?`;
-            conn.db.prepare(sql).run(...Object.values(data), id);
-        } else if (conn.type === 'knex' && conn.db) {
-            await conn.db(this.constructor.table).where(pk, id).update(data);
-        }
-
-        return this;
-    }
-
-    /**
-     * 삭제 — softDelete 지원
-     */
-    async delete() {
-        if (this.constructor.softDelete) {
-            const conn = this.constructor.getConnection();
-            const now = dbNow(conn);
-            this._attributes.deleted_at = now;
-            this.deleted_at = now;
-            await this.update({ deleted_at: now });
-            return;
-        }
-        await this.forceDelete();
-    }
-
-    /**
-     * 실제 삭제 (softDelete 무시)
-     */
-    async forceDelete() {
-        const pk = this.constructor.primaryKey;
-        const id = this._attributes[pk];
-        if (id == null) return;
-
-        const conn = this.constructor.getConnection();
-
-        if (conn.type === 'sqlite' && conn.db) {
-            const safeTable = SqlQueryBuilder._sanitizeName(this.constructor.table);
-            const safePk = SqlQueryBuilder._sanitizeName(pk);
-            conn.db.prepare(`DELETE FROM ${safeTable} WHERE ${safePk} = ?`).run(id);
-        } else if (conn.type === 'knex' && conn.db) {
-            await conn.db(this.constructor.table).where(pk, id).delete();
-        }
-    }
-}
+/**
+ * SqlModel — SQL 공통 로직 (SQLite / MariaDB / PostgreSQL 공유)
+ *
+ * Knex-style 쿼리 빌딩을 공통화한 중간 클래스.
+ * SQLiteModel, MariaModel, PostgreModel이 이 클래스를 상속.
+ *
+ * @see docs/framework/02-database-orm.md
+ */
+import Model from './Model.js';
+import SqlQueryBuilder from './SqlQueryBuilder.js';
+
+/**
+ * DB 드라이버에 맞는 datetime 문자열 반환
+ * MySQL/MariaDB: 'YYYY-MM-DD HH:MM:SS.SSS' (T/Z 제거, 밀리초 유지 — DATETIME(3) 지원)
+ * SQLite/PostgreSQL: ISO 8601
+ */
+function dbNow(conn) {
+    if (conn?.type === 'knex' && (conn.driver === 'mariadb' || conn.driver === 'mysql')) {
+        return new Date().toISOString().replace('T', ' ').replace('Z', '');
+    }
+    return new Date().toISOString();
+}
+
+export default class SqlModel extends Model {
+    /** @type {string} DB 드라이버 — 서브클래스에서 오버라이드 */
+    static driver = 'sql';
+
+    /**
+     * ConnectionManager 인스턴스 (Application에서 주입)
+     * @type {import('./ConnectionManager.js').default|null}
+     */
+    static _connectionManager = null;
+
+    /**
+     * ConnectionManager를 모든 SqlModel 서브클래스에 주입
+     * @param {import('./ConnectionManager.js').default} cm
+     */
+    static setConnectionManager(cm) {
+        SqlModel._connectionManager = cm;
+    }
+
+    /**
+     * DB 연결 가져오기
+     * @returns {object} connection object
+     */
+    static getConnection() {
+        if (!SqlModel._connectionManager) {
+            throw new Error(
+                `DB not initialized. Ensure Application.boot() has been called and database is configured.`
+            );
+        }
+        return SqlModel._connectionManager.get(this.connection);
+    }
+
+    /** 쿼리 빌더 시작 — SQL 전용 */
+    static query() {
+        return new SqlQueryBuilder(this);
+    }
+
+    /** where 체이닝 시작 */
+    static where(key, op, value) {
+        return this.query().where(key, op, value);
+    }
+
+    /** limit 체이닝 */
+    static limit(n) {
+        return this.query().limit(n);
+    }
+
+    /** with 체이닝 */
+    static with(...relations) {
+        return this.query().with(...relations);
+    }
+
+    /** 페이지네이션 */
+    static paginate(page, perPage) {
+        return this.query().paginate(page, perPage);
+    }
+
+    /**
+     * 레코드 생성
+     * @param {object} data
+     * @returns {Promise<Model>}
+     */
+    static async create(data) {
+        const conn = this.getConnection();
+        const insertData = { ...data };
+
+        // timestamps 자동 관리
+        if (this.timestamps) {
+            const now = dbNow(conn);
+            if (!insertData.created_at) insertData.created_at = now;
+            if (!insertData.updated_at) insertData.updated_at = now;
+        }
+
+        if (conn.type === 'sqlite' && conn.db) {
+            const columns = Object.keys(insertData).map(c => SqlQueryBuilder._sanitizeName(c));
+            const placeholders = columns.map(() => '?').join(', ');
+            const safeTable = SqlQueryBuilder._sanitizeName(this.table);
+            const sql = `INSERT INTO ${safeTable} (${columns.join(', ')}) VALUES (${placeholders})`;
+            const result = conn.db.prepare(sql).run(...Object.values(insertData));
+            const id = result.lastInsertRowid;
+            return new this({ ...insertData, [this.primaryKey]: Number(id) });
+        }
+
+        if (conn.type === 'knex' && conn.db) {
+            // MySQL: insert returns [insertId], PostgreSQL: needs .returning()
+            if (conn.driver === 'postgres') {
+                const [row] = await conn.db(this.table).insert(insertData).returning(this.primaryKey);
+                const id = typeof row === 'object' ? row[this.primaryKey] : row;
+                return new this({ ...insertData, [this.primaryKey]: id });
+            } else {
+                const [id] = await conn.db(this.table).insert(insertData);
+                return new this({ ...insertData, [this.primaryKey]: id });
+            }
+        }
+
+        // Stub: no DB connection
+        return new this({ ...insertData, [this.primaryKey]: Date.now() });
+    }
+
+    /**
+     * ID로 조회
+     * @param {*} id
+     * @returns {Promise<Model|null>}
+     */
+    static async find(id) {
+        return this.query().where(this.primaryKey, id).first();
+    }
+
+    /**
+     * 전체 조회
+     * @returns {Promise<Array>}
+     */
+    static async all() {
+        return this.query().get();
+    }
+
+    static async findAll() { return this.all(); }
+
+    /**
+     * 여러 ID 조회
+     * @param {Array} ids
+     */
+    static async findMany(ids) {
+        return this.query().whereIn(this.primaryKey, ids).get();
+    }
+
+    /**
+     * Raw SQL 실행
+     * @param {string} sql
+     * @param {Array} [bindings]
+     * @returns {Promise<Array>}
+     */
+    static async raw(sql, bindings = []) {
+        const conn = this.getConnection();
+
+        if (conn.type === 'sqlite' && conn.db) {
+            return conn.db.prepare(sql).all(...bindings);
+        }
+
+        if (conn.type === 'knex' && conn.db) {
+            const result = await conn.db.raw(sql, bindings);
+            // MySQL: [[rows], fields], PostgreSQL: { rows: [...] }
+            if (Array.isArray(result)) {
+                return Array.isArray(result[0]) ? result[0] : result;
+            }
+            return result.rows || [];
+        }
+
+        return [];
+    }
+
+    /**
+     * 네이티브 드라이버 접근
+     * @returns {object}
+     */
+    static nativeConnection() {
+        const conn = this.getConnection();
+        if (conn.type === 'sqlite') return conn.db;
+        if (conn.type === 'knex') return conn.db;
+        return null;
+    }
+
+    // ━━━━━━━━━━ 인스턴스 메서드 ━━━━━━━━━━
+
+    /**
+     * 인스턴스 수정
+     * @param {object} data
+     * @returns {Promise<this>}
+     */
+    async update(data) {
+        Object.assign(this._attributes, data);
+        Object.assign(this, data);
+
+        if (this.constructor.timestamps && !data.updated_at) {
+            const conn = this.constructor.getConnection();
+            const now = dbNow(conn);
+            this._attributes.updated_at = now;
+            this.updated_at = now;
+            data.updated_at = now;
+        }
+
+        const pk = this.constructor.primaryKey;
+        const id = this._attributes[pk];
+        if (id == null) return this;
+
+        const conn = this.constructor.getConnection();
+
+        if (conn.type === 'sqlite' && conn.db) {
+            const columns = Object.keys(data).map(c => SqlQueryBuilder._sanitizeName(c));
+            const pk = SqlQueryBuilder._sanitizeName(this.constructor.primaryKey);
+            const safeTable = SqlQueryBuilder._sanitizeName(this.constructor.table);
+            const sets = columns.map(c => `${c} = ?`).join(', ');
+            const sql = `UPDATE ${safeTable} SET ${sets} WHERE ${pk} = ?`;
+            conn.db.prepare(sql).run(...Object.values(data), id);
+        } else if (conn.type === 'knex' && conn.db) {
+            await conn.db(this.constructor.table).where(pk, id).update(data);
+        }
+
+        return this;
+    }
+
+    /**
+     * 삭제 — softDelete 지원
+     */
+    async delete() {
+        if (this.constructor.softDelete) {
+            const conn = this.constructor.getConnection();
+            const now = dbNow(conn);
+            this._attributes.deleted_at = now;
+            this.deleted_at = now;
+            await this.update({ deleted_at: now });
+            return;
+        }
+        await this.forceDelete();
+    }
+
+    /**
+     * 실제 삭제 (softDelete 무시)
+     */
+    async forceDelete() {
+        const pk = this.constructor.primaryKey;
+        const id = this._attributes[pk];
+        if (id == null) return;
+
+        const conn = this.constructor.getConnection();
+
+        if (conn.type === 'sqlite' && conn.db) {
+            const safeTable = SqlQueryBuilder._sanitizeName(this.constructor.table);
+            const safePk = SqlQueryBuilder._sanitizeName(pk);
+            conn.db.prepare(`DELETE FROM ${safeTable} WHERE ${safePk} = ?`).run(id);
+        } else if (conn.type === 'knex' && conn.db) {
+            await conn.db(this.constructor.table).where(pk, id).delete();
+        }
+    }
+}