@fuzionx/framework 0.1.42 → 0.1.44

package/lib/database/MongoModel.js

@@ -1,232 +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 {}
-    }
-}
+/**
+ * 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

@@ -1,37 +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,
-            },
-        };
-    }
-}
+/**
+ * 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

@@ -1,29 +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';
-}
+/**
+ * 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';
+}