@fuzionx/framework 0.1.2

package/lib/database/QueryBuilder.js

@@ -0,0 +1,172 @@
+/**
+ * QueryBuilder — SQL/MongoDB 쿼리 빌더 (체이닝)
+ *
+ * @see docs/framework/02-database-orm.md
+ * @see docs/framework/class-design.mm.md (QueryBuilder)
+ */
+export default class QueryBuilder {
+    constructor(model) {
+        this._model = model;
+        this._wheres = [];
+        this._orders = [];
+        this._limit = null;
+        this._offset = null;
+        this._selects = null;
+        this._withs = [];
+        // softDelete 자동 적용
+        this._softDelete = model?.softDelete || false;
+        this._withTrashed = false;
+        this._onlyTrashed = false;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  체이닝 메서드
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    where(key, op, value) {
+        if (value === undefined) { value = op; op = '='; }
+        this._wheres.push({ key, op, value, type: 'and' });
+        return this;
+    }
+
+    /** OR 조건 */
+    orWhere(key, op, value) {
+        if (value === undefined) { value = op; op = '='; }
+        this._wheres.push({ key, op, value, type: 'or' });
+        return this;
+    }
+
+    /** IN 조건 */
+    whereIn(key, values) {
+        this._wheres.push({ key, op: 'IN', value: values, type: 'and' });
+        return this;
+    }
+
+    /** NOT NULL 조건 */
+    whereNotNull(key) {
+        this._wheres.push({ key, op: 'IS NOT NULL', value: null, type: 'and' });
+        return this;
+    }
+
+    /** NULL 조건 */
+    whereNull(key) {
+        this._wheres.push({ key, op: 'IS NULL', value: null, type: 'and' });
+        return this;
+    }
+
+    orderBy(column, direction = 'asc') {
+        this._orders.push({ column, direction });
+        return this;
+    }
+
+    limit(n) { this._limit = n; return this; }
+    offset(n) { this._offset = n; return this; }
+
+    select(...columns) {
+        this._selects = columns.flat();
+        return this;
+    }
+
+    with(...relations) {
+        this._withs.push(...relations.flat());
+        return this;
+    }
+
+    /** softDelete 포함 (삭제된 레코드도 조회) */
+    withTrashed() {
+        this._withTrashed = true;
+        return this;
+    }
+
+    /** softDelete만 조회 (삭제된 레코드만) */
+    onlyTrashed() {
+        this._onlyTrashed = true;
+        return this;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  터미널 메서드
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /**
+     * 페이지네이션
+     * @param {number} page
+     * @param {number} perPage
+     * @returns {Promise<Pagination>}
+     */
+    async paginate(page = 1, perPage = 20) {
+        // Model 서브클래스에서 오버라이드하여 실제 DB 쿼리 실행
+        return {
+            data: [],
+            page,
+            perPage,
+            total: 0,
+            lastPage: 0,
+            _query: this._buildQuery(),
+        };
+    }
+
+    /**
+     * 전체 결과 반환
+     * @returns {Promise<Array>}
+     */
+    async get() {
+        // 서브클래스에서 오버라이드
+        return [];
+    }
+
+    /**
+     * 단일 결과
+     * @returns {Promise<object|null>}
+     */
+    async first() {
+        this._limit = 1;
+        const results = await this.get();
+        return results[0] || null;
+    }
+
+    /**
+     * 결과 수
+     * @returns {Promise<number>}
+     */
+    async count() {
+        // 서브클래스에서 오버라이드
+        return 0;
+    }
+
+    /**
+     * 조건부 수정
+     * @param {object} data
+     * @returns {Promise<number>} 수정된 행 수
+     */
+    async update(data) {
+        // 서브클래스에서 오버라이드
+        return 0;
+    }
+
+    /**
+     * 조건부 삭제
+     * @returns {Promise<number>} 삭제된 행 수
+     */
+    async delete() {
+        // 서브클래스에서 오버라이드
+        return 0;
+    }
+
+    /**
+     * 빌드된 쿼리 파라미터 (디버깅/테스트용)
+     */
+    _buildQuery() {
+        return {
+            wheres: this._wheres,
+            orders: this._orders,
+            limit: this._limit,
+            offset: this._offset,
+            selects: this._selects,
+            withs: this._withs,
+            softDelete: this._softDelete,
+            withTrashed: this._withTrashed,
+            onlyTrashed: this._onlyTrashed,
+        };
+    }
+}

package/lib/database/SQLiteModel.js

@@ -0,0 +1,27 @@
+/**
+ * SQLiteModel — SQLite 모델 서브클래스 (기본 드라이버)
+ *
+ * better-sqlite3 기반 동기 API.
+ * 개발 환경에서 별도 DB 서버 없이 즉시 사용 가능.
+ *
+ * @see docs/framework/02-database-orm.md
+ *
+ * @example
+ * import { SQLiteModel } from '@fuzionx/framework';
+ *
+ * export default class User extends SQLiteModel {
+ *     static table = 'users';
+ *     static timestamps = true;
+ *     static columns = {
+ *         id:    { type: 'increments' },
+ *         name:  { type: 'string', length: 100 },
+ *         email: { type: 'string', length: 150, unique: true },
+ *     };
+ * }
+ */
+import SqlModel from './SqlModel.js';
+
+export default class SQLiteModel extends SqlModel {
+    static driver = 'sqlite';
+    static connection = 'main';
+}

package/lib/database/SqlModel.js

@@ -0,0 +1,252 @@
+/**
+ * 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);
+            const placeholders = columns.map(() => '?').join(', ');
+            const sql = `INSERT INTO ${this.table} (${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);
+            const sets = columns.map(c => `${c} = ?`).join(', ');
+            const sql = `UPDATE ${this.constructor.table} 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) {
+            conn.db.prepare(`DELETE FROM ${this.constructor.table} WHERE ${pk} = ?`).run(id);
+        } else if (conn.type === 'knex' && conn.db) {
+            await conn.db(this.constructor.table).where(pk, id).delete();
+        }
+    }
+}