@fuzionx/framework 0.1.2

package/lib/database/Model.js

@@ -0,0 +1,247 @@
+/**
+ * Model — 데이터베이스 테이블/컬렉션 추상화
+ *
+ * @see docs/framework/02-database-orm.md
+ * @see docs/framework/class-design.mm.md (Model)
+ */
+import QueryBuilder from './QueryBuilder.js';
+import { ServiceError } from '../core/AppError.js';
+
+export default class Model {
+    // ── Static 멤버 (서브클래스에서 오버라이드) ──
+    static table = '';         // 테이블명 / 컬렉션명
+    static primaryKey = 'id';  // 기본키
+    static connection = 'main'; // DB 연결명
+    static timestamps = true;  // created_at, updated_at 자동
+    static softDelete = false; // deleted_at 소프트 삭제
+    static hidden = [];        // JSON 직렬화 시 제외 필드
+    static columns = {};       // SQL 스키마 정의 (fx db:sync 용)
+    static indexes = [];       // 인덱스 정의 [{ columns: ['role'], unique? }]
+    static schema = {};        // MongoDB 스키마
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  인스턴스 (레코드 래퍼)
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    constructor(attributes = {}) {
+        this._attributes = { ...attributes };
+        this._original = { ...attributes };
+        // 속성을 인스턴스 프로퍼티로도 노출 (backward compat)
+        Object.assign(this, attributes);
+    }
+
+    /** 속성 접근 */
+    get(key) { return key ? this._attributes[key] : { ...this._attributes }; }
+    set(key, value) { this._attributes[key] = value; }
+
+    /**
+     * 뮤테이터용 내부 설정 (02-database-orm.md)
+     * set password(v) { this._set('password', app.hash.argon2(v)); }
+     */
+    _set(key, value) {
+        this._attributes[key] = value;
+        this[key] = value;
+    }
+
+    /**
+     * 인스턴스 수정 — DB update + 로컬 반영
+     * @param {object} data
+     * @returns {Promise<this>}
+     */
+    async update(data) {
+        Object.assign(this._attributes, data);
+        // Model 서브클래스(Maria/Postgre/Mongo)에서 오버라이드하여 실제 DB 쿼리 실행
+        return this;
+    }
+
+    /**
+     * 인스턴스 삭제
+     * softDelete가 true면 deleted_at 설정, 아니면 실제 삭제.
+     * @returns {Promise<void>}
+     */
+    async delete() {
+        if (this.constructor.softDelete) {
+            const now = new Date().toISOString();
+            this._attributes.deleted_at = now;
+            this.deleted_at = now;
+            await this.update({ deleted_at: now });
+            return;
+        }
+        // 서브클래스에서 오버라이드하여 실제 DB 삭제
+    }
+
+    /**
+     * 소프트 삭제 복원 — deleted_at = null
+     * @returns {Promise<this>}
+     */
+    async restore() {
+        this._attributes.deleted_at = null;
+        this.deleted_at = null;
+        await this.update({ deleted_at: null });
+        return this;
+    }
+
+    /**
+     * 강제 삭제 — softDelete 무시하고 실제 삭제
+     * @returns {Promise<void>}
+     */
+    async forceDelete() {
+        // 서브클래스에서 오버라이드하여 실제 DB 삭제
+    }
+
+    /**
+     * JSON 직렬화 — hidden 필드 제외
+     * @returns {object}
+     */
+    toJSON() {
+        const obj = { ...this._attributes };
+        const hidden = this.constructor.hidden || [];
+        for (const key of hidden) {
+            delete obj[key];
+        }
+        return obj;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  관계 (스텁 — 서브클래스에서 오버라이드)
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /** 1:N 관계 */
+    hasMany(model, fk) {
+        return { type: 'hasMany', model, fk: fk || `${this.constructor.table.replace(/s$/, '')}_id` };
+    }
+
+    /** N:1 관계 */
+    belongsTo(model, fk) {
+        return { type: 'belongsTo', model, fk: fk || `${model.toLowerCase()}_id` };
+    }
+
+    /** 1:1 관계 */
+    hasOne(model, fk) {
+        return { type: 'hasOne', model, fk: fk || `${this.constructor.table.replace(/s$/, '')}_id` };
+    }
+
+    /** N:N 관계 */
+    belongsToMany(model, pivot) {
+        return { type: 'belongsToMany', model, pivot };
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  Static 메서드 (쿼리 진입점)
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /** 쿼리 빌더 시작 */
+    static query() {
+        return new QueryBuilder(this);
+    }
+
+    /** where 체이닝 시작 */
+    static where(key, op, value) {
+        return this.query().where(key, op, value);
+    }
+
+    /** limit 체이닝 시작 */
+    static limit(n) {
+        return this.query().limit(n);
+    }
+
+    /** 관계 eager-load 진입점 */
+    static with(...relations) {
+        return this.query().with(...relations);
+    }
+
+    /** 페이지네이션 진입점 */
+    static paginate(page, perPage) {
+        return this.query().paginate(page, perPage);
+    }
+
+    /**
+     * ID로 조회
+     * @param {*} id
+     * @returns {Promise<Model|null>}
+     */
+    static async find(id) {
+        return this.query().where(this.primaryKey, id).first();
+    }
+
+    /**
+     * ID로 조회 (없으면 404 에러)
+     * @param {*} id
+     * @returns {Promise<Model>}
+     */
+    static async findOrFail(id) {
+        const result = await this.find(id);
+        if (!result) {
+            throw new ServiceError(`${this.name} not found`, 404);
+        }
+        return result;
+    }
+
+    /**
+     * 전체 조회
+     * @returns {Promise<Array>}
+     */
+    static async all() {
+        return this.query().get();
+    }
+
+    /** all() alias */
+    static async findAll() {
+        return this.all();
+    }
+
+    /**
+     * 여러 ID 조회
+     * @param {Array} ids
+     * @returns {Promise<Array>}
+     */
+    static async findMany(ids) {
+        return this.query().whereIn(this.primaryKey, ids).get();
+    }
+
+    /**
+     * 카운트
+     * @param {object} [where] - 간단 조건
+     * @returns {Promise<number>}
+     */
+    static async count(where) {
+        let qb = this.query();
+        if (where) {
+            for (const [key, value] of Object.entries(where)) {
+                qb = qb.where(key, value);
+            }
+        }
+        return qb.count();
+    }
+
+    /**
+     * 생성
+     * @param {object} data
+     * @returns {Promise<Model>}
+     */
+    static async create(data) {
+        // Model 서브클래스에서 오버라이드하여 실제 DB insert
+        const instance = new this({ ...data, [this.primaryKey]: Date.now() });
+        return instance;
+    }
+
+    /**
+     * Raw 쿼리 (DB 고유 기능)
+     * @param {string|Array} query - SQL 문자열 또는 MongoDB pipeline
+     * @param {Array} [bindings] - SQL 바인딩
+     * @returns {Promise<Array>}
+     */
+    static async raw(query, bindings) {
+        // 서브클래스에서 오버라이드 (Knex.raw / Mongoose.aggregate)
+        return [];
+    }
+
+    /**
+     * 네이티브 드라이버 접근
+     * @returns {object} - Knex 인스턴스 | Mongoose 인스턴스
+     */
+    static nativeConnection() {
+        // 서브클래스에서 오버라이드
+        return null;
+    }
+}

package/lib/database/ModelRegistry.js

@@ -0,0 +1,72 @@
+/**
+ * ModelRegistry — Proxy 기반 db.User 접근
+ *
+ * app.db.User → ModelRegistry에서 'User' 모델 반환.
+ * Proxy로 동적 프로퍼티 접근 지원.
+ *
+ * @see docs/framework/class-design.mm.md (ModelRegistry)
+ */
+export default class ModelRegistry {
+    constructor() {
+        this._models = new Map();
+        this._knex = null;
+        this._mongoConnections = null;
+
+        // Proxy로 동적 접근 지원 (db.User → _models.get('User'))
+        return new Proxy(this, {
+            get(target, prop) {
+                // 내부 메서드/프로퍼티는 직접 접근
+                if (prop in target || typeof prop === 'symbol') {
+                    return target[prop];
+                }
+                // 모델 이름으로 접근
+                if (target._models.has(prop)) {
+                    return target._models.get(prop);
+                }
+                return undefined;
+            },
+        });
+    }
+
+    /**
+     * 모델 등록
+     * @param {string} name - 모델 이름 (e.g. 'User')
+     * @param {typeof import('./Model.js').default} ModelClass
+     */
+    register(name, ModelClass) {
+        this._models.set(name, ModelClass);
+    }
+
+    /**
+     * 모델 조회
+     * @param {string} name
+     * @returns {typeof import('./Model.js').default}
+     */
+    get(name) {
+        return this._models.get(name);
+    }
+
+    /**
+     * 등록된 모델 이름 목록
+     * @returns {string[]}
+     */
+    names() {
+        return [...this._models.keys()];
+    }
+
+    /**
+     * Knex 연결 설정 (SQL)
+     * @param {object} knex
+     */
+    setKnex(knex) {
+        this._knex = knex;
+    }
+
+    /**
+     * MongoDB 연결 설정
+     * @param {object} connections
+     */
+    setMongoConnections(connections) {
+        this._mongoConnections = connections;
+    }
+}

package/lib/database/MongoModel.js

@@ -0,0 +1,232 @@
+/**
+ * MongoModel — MongoDB 모델 서브클래스
+ *
+ * Mongoose 기반. SqlModel과 별도 계층.
+ * MongoDB 전용 API (aggregate, populate 등)를 별도 구현.
+ *
+ * @see docs/framework/02-database-orm.md
+ *
+ * @example
+ * import { MongoModel } from '@fuzionx/framework';
+ *
+ * export default class AccessLog extends MongoModel {
+ *     static table = 'access_logs';
+ *     static connection = 'mongo';
+ *     static timestamps = true;
+ *     static schema = {
+ *         level:   { type: 'string', required: true },
+ *         message: { type: 'string' },
+ *         meta:    { type: 'object' },
+ *     };
+ * }
+ */
+import Model from './Model.js';
+import QueryBuilder from './QueryBuilder.js';
+
+export default class MongoModel extends Model {
+    static driver = 'mongodb';
+    static connection = 'mongo';
+
+    /** @type {import('./ConnectionManager.js').default|null} */
+    static _connectionManager = null;
+
+    /**
+     * ConnectionManager를 MongoModel에 주입
+     * @param {import('./ConnectionManager.js').default} cm
+     */
+    static setConnectionManager(cm) {
+        MongoModel._connectionManager = cm;
+    }
+
+    /**
+     * DB 연결 가져오기
+     * @returns {object}
+     */
+    static getConnection() {
+        if (!MongoModel._connectionManager) {
+            throw new Error('DB not initialized. Ensure Application.boot() has been called.');
+        }
+        return MongoModel._connectionManager.get(this.connection);
+    }
+
+    /**
+     * Mongoose 모델 가져오기 (lazy 생성)
+     * @returns {import('mongoose').Model}
+     */
+    static _getMongooseModel() {
+        if (this._mongooseModel) return this._mongooseModel;
+
+        const conn = this.getConnection();
+        if (!conn.mongoose) {
+            throw new Error('MongoDB requires mongoose. Install: npm install mongoose');
+        }
+
+        // schema 정의 → Mongoose 모델 생성
+        const schemaFields = {};
+        for (const [key, def] of Object.entries(this.schema || {})) {
+            const mongoType = this._toMongooseType(def.type);
+            schemaFields[key] = {
+                type: mongoType,
+                required: def.required || false,
+                default: def.default,
+            };
+        }
+
+        const options = { collection: this.table };
+        if (this.timestamps) {
+            options.timestamps = { createdAt: 'created_at', updatedAt: 'updated_at' };
+        }
+
+        const schema = new conn.mongoose.Schema(schemaFields, options);
+        this._mongooseModel = conn.mongoose.model(this.name, schema);
+        return this._mongooseModel;
+    }
+
+    /**
+     * FuzionX 타입 → Mongoose 타입 변환
+     * @private
+     */
+    static _toMongooseType(type) {
+        const mongoose = this.getConnection().mongoose;
+        if (!mongoose) return String;
+
+        const map = {
+            'string': String,
+            'integer': Number,
+            'bigInteger': Number,
+            'float': Number,
+            'decimal': Number,
+            'boolean': Boolean,
+            'date': Date,
+            'datetime': Date,
+            'timestamp': Date,
+            'object': Object,
+            'json': Object,
+            'array': Array,
+            'binary': Buffer,
+        };
+        return map[type] || String;
+    }
+
+    /**
+     * 레코드 생성
+     * @param {object} data
+     * @returns {Promise<MongoModel>}
+     */
+    static async create(data) {
+        try {
+            const MongooseModel = this._getMongooseModel();
+            const doc = await MongooseModel.create(data);
+            return new this(doc.toObject());
+        } catch {
+            // Mongoose 미설치 → stub
+            return new this({ ...data, _id: Date.now().toString(36) });
+        }
+    }
+
+    /**
+     * ID로 조회
+     * @param {*} id
+     * @returns {Promise<MongoModel|null>}
+     */
+    static async find(id) {
+        try {
+            const MongooseModel = this._getMongooseModel();
+            const doc = await MongooseModel.findById(id);
+            return doc ? new this(doc.toObject()) : null;
+        } catch {
+            return null;
+        }
+    }
+
+    /**
+     * 전체 조회
+     * @returns {Promise<Array>}
+     */
+    static async all() {
+        try {
+            const MongooseModel = this._getMongooseModel();
+            const docs = await MongooseModel.find({});
+            return docs.map(d => new this(d.toObject()));
+        } catch {
+            return [];
+        }
+    }
+
+    static async findAll() { return this.all(); }
+
+    /**
+     * Raw aggregation pipeline
+     * @param {Array} pipeline
+     * @returns {Promise<Array>}
+     */
+    static async raw(pipeline) {
+        try {
+            const MongooseModel = this._getMongooseModel();
+            return MongooseModel.aggregate(pipeline);
+        } catch {
+            return [];
+        }
+    }
+
+    /**
+     * 네이티브 Mongoose 접근
+     * @returns {object|null}
+     */
+    static nativeConnection() {
+        try {
+            return this.getConnection().mongoose;
+        } catch {
+            return null;
+        }
+    }
+
+    // ━━━━━━━━━━ 인스턴스 메서드 ━━━━━━━━━━
+
+    /**
+     * 인스턴스 수정
+     * @param {object} data
+     * @returns {Promise<this>}
+     */
+    async update(data) {
+        Object.assign(this._attributes, data);
+        Object.assign(this, data);
+
+        const id = this._attributes._id || this._attributes[this.constructor.primaryKey];
+        if (!id) return this;
+
+        try {
+            const MongooseModel = this.constructor._getMongooseModel();
+            await MongooseModel.updateOne({ _id: id }, { $set: data });
+        } catch {}
+
+        return this;
+    }
+
+    /**
+     * 삭제
+     */
+    async delete() {
+        if (this.constructor.softDelete) {
+            const now = new Date().toISOString();
+            this._attributes.deleted_at = now;
+            this.deleted_at = now;
+            await this.update({ deleted_at: now });
+            return;
+        }
+        await this.forceDelete();
+    }
+
+    /**
+     * 실제 삭제
+     */
+    async forceDelete() {
+        const id = this._attributes._id || this._attributes[this.constructor.primaryKey];
+        if (!id) return;
+
+        try {
+            const MongooseModel = this.constructor._getMongooseModel();
+            await MongooseModel.deleteOne({ _id: id });
+        } catch {}
+    }
+}

package/lib/database/Pagination.js

@@ -0,0 +1,37 @@
+/**
+ * Pagination — 페이지네이션 결과 객체
+ *
+ * @see docs/framework/class-design.mm.md (Pagination)
+ */
+export default class Pagination {
+    /**
+     * @param {Array} data - 현재 페이지 데이터
+     * @param {number} total - 전체 레코드 수
+     * @param {number} page - 현재 페이지
+     * @param {number} perPage - 페이지당 수
+     */
+    constructor(data, total, page, perPage) {
+        this.data = data;
+        this.total = total;
+        this.page = page;
+        this.perPage = perPage;
+        this.lastPage = Math.ceil(total / perPage) || 1;
+        this.hasMore = page < this.lastPage;
+    }
+
+    /**
+     * JSON 직렬화 형태
+     */
+    toJSON() {
+        return {
+            data: this.data,
+            meta: {
+                total: this.total,
+                page: this.page,
+                perPage: this.perPage,
+                lastPage: this.lastPage,
+                hasMore: this.hasMore,
+            },
+        };
+    }
+}

package/lib/database/PostgreModel.js

@@ -0,0 +1,29 @@
+/**
+ * PostgreModel — PostgreSQL 모델 서브클래스
+ *
+ * Knex + pg 기반.
+ * SqlModel의 공통 SQL 로직을 상속하며,
+ * PostgreSQL 고유 기능(JSONB, ARRAY, CTE 등)은 raw()로 접근.
+ *
+ * @see docs/framework/02-database-orm.md
+ *
+ * @example
+ * import { PostgreModel } from '@fuzionx/framework';
+ *
+ * export default class Analytics extends PostgreModel {
+ *     static table = 'analytics';
+ *     static connection = 'analytics_db';
+ *     static columns = {
+ *         id:       { type: 'increments' },
+ *         event:    { type: 'string', length: 100 },
+ *         meta:     { type: 'json' },
+ *         created:  { type: 'timestamp' },
+ *     };
+ * }
+ */
+import SqlModel from './SqlModel.js';
+
+export default class PostgreModel extends SqlModel {
+    static driver = 'postgres';
+    static connection = 'main';
+}