@fuzionx/framework 0.1.43 → 0.1.44

package/lib/database/Model.js

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

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