monsqlize 1.0.2 → 1.0.5

package/lib/model/index.js

@@ -0,0 +1,756 @@
+/**
+ * Model 层 - 基于 collection 的增强封装
+ *
+ * 核心功能：
+ * 1. Schema 定义与验证（集成 schema-dsl）
+ * 2. 自定义方法扩展（instance + static）
+ * 3. 生命周期钩子（before/after）
+ * 4. 索引管理（自动创建）
+ * 5. 关系定义（hasOne/hasMany/belongsTo）
+ *
+ * @module lib/model
+ * @version 1.0.3
+ * @since 1.0.3
+ */
+
+// ========== 依赖导入 ==========
+let schemaDsl;
+try {
+    schemaDsl = require('schema-dsl');
+} catch (err) {
+    // schema-dsl 未安装时的友好提示
+    const installHint = `
+╔════════════════════════════════════════════════════════════════╗
+║  ⚠️  schema-dsl 未安装                                         ║
+║                                                                 ║
+║  Model 功能需要 schema-dsl 包支持                              ║
+║                                                                 ║
+║  安装方式：                                                     ║
+║  1. npm link（开发）：                                         ║
+║     cd path/to/schema-dsl && npm link                          ║
+║     cd path/to/monSQLize && npm link schema-dsl                ║
+║                                                                 ║
+║  2. npm 安装（生产）：                                         ║
+║     npm install schema-dsl                                      ║
+╚════════════════════════════════════════════════════════════════╝
+`;
+    console.error(installHint);
+    throw new Error('schema-dsl is required for Model functionality. Please install it first.');
+}
+
+const { dsl, validate } = schemaDsl;
+
+/**
+ * Model 基类
+ * 提供全局注册和实例化能力
+ */
+class Model {
+    /**
+     * 全局 Model 注册表
+     * @private
+     * @type {Map<string, Object>}
+     */
+    static _registry = new Map();
+
+    /**
+     * 定义并注册 Model
+     *
+     * @param {string} collectionName - 集合名称
+     * @param {Object} definition - Model 定义对象
+     * @param {Object} [definition.enums] - 枚举配置（可选）
+     * @param {Function|Object} definition.schema - Schema 定义（必需）
+     * @param {Function} [definition.methods] - 自定义方法（可选）
+     * @param {Function} [definition.hooks] - 生命周期钩子（可选）
+     * @param {Array} [definition.indexes] - 索引定义（可选）
+     * @param {Object} [definition.relations] - 关系定义（可选）
+     *
+     * @throws {Error} 集合名称无效
+     * @throws {Error} schema 未定义
+     * @throws {Error} Model 已存在
+     *
+     * @example
+     * Model.define('users', {
+     *   enums: {
+     *     role: 'admin|user'
+     *   },
+     *   schema: function(dsl) {
+     *     return dsl({
+     *       username: 'string:3-32!',
+     *       role: this.enums.role.default('user')
+     *     });
+     *   }
+     * });
+     */
+    static define(collectionName, definition) {
+        try {
+            // ========== 参数验证 ==========
+            if (!collectionName || typeof collectionName !== 'string' || collectionName.trim() === '') {
+                const err = new Error('Collection name must be a non-empty string.');
+                err.code = 'INVALID_COLLECTION_NAME';
+                throw err;
+            }
+
+            if (!definition || typeof definition !== 'object') {
+                const err = new Error('Model definition must be an object.');
+                err.code = 'INVALID_MODEL_DEFINITION';
+                throw err;
+            }
+
+            if (!definition.schema) {
+                const err = new Error('Model definition must include a schema property.');
+                err.code = 'MISSING_SCHEMA';
+                throw err;
+            }
+
+            if (typeof definition.schema !== 'function' && typeof definition.schema !== 'object') {
+                const err = new Error('Schema must be a function or object.');
+                err.code = 'INVALID_SCHEMA_TYPE';
+                throw err;
+            }
+
+            // ========== 检查重复注册 ==========
+            if (this._registry.has(collectionName)) {
+                const err = new Error(`Model '${collectionName}' is already defined.`);
+                err.code = 'MODEL_ALREADY_EXISTS';
+                throw err;
+            }
+
+            // ========== 解析 timestamps 配置 ==========
+            const timestampsConfig = this._parseTimestampsConfig(definition.options?.timestamps);
+            if (timestampsConfig) {
+                // 保存到内部 hooks 配置
+                if (!definition._internalHooks) {
+                    definition._internalHooks = {};
+                }
+                definition._internalHooks.timestamps = timestampsConfig;
+            }
+
+            // ========== 注册 Model ==========
+            this._registry.set(collectionName, {
+                collectionName,
+                definition
+            });
+
+        } catch (err) {
+            // 统一错误处理
+            if (!err.code) {
+                err.code = 'MODEL_DEFINE_ERROR';
+            }
+            throw err;
+        }
+    }
+
+    /**
+     * 解析 timestamps 配置
+     *
+     * @private
+     * @param {boolean|Object} config - timestamps 配置
+     * @returns {Object|null} 解析后的配置对象，包含 createdAt 和 updatedAt 字段名
+     *
+     * @example
+     * _parseTimestampsConfig(true)
+     * // => { createdAt: 'createdAt', updatedAt: 'updatedAt' }
+     *
+     * _parseTimestampsConfig({ createdAt: 'created_time', updatedAt: false })
+     * // => { createdAt: 'created_time' }
+     */
+    static _parseTimestampsConfig(config) {
+        if (!config) return null;
+
+        // 简单模式：timestamps: true
+        if (config === true) {
+            return {
+                createdAt: 'createdAt',
+                updatedAt: 'updatedAt'
+            };
+        }
+
+        // 对象模式
+        if (typeof config === 'object') {
+            const result = {};
+
+            // createdAt 配置
+            if (config.createdAt === true) {
+                result.createdAt = 'createdAt';
+            } else if (typeof config.createdAt === 'string') {
+                result.createdAt = config.createdAt;
+            }
+
+            // updatedAt 配置（默认启用）
+            if (config.updatedAt !== false) {
+                if (config.updatedAt === true || config.updatedAt === undefined) {
+                    result.updatedAt = 'updatedAt';
+                } else if (typeof config.updatedAt === 'string') {
+                    result.updatedAt = config.updatedAt;
+                }
+            }
+
+            return Object.keys(result).length > 0 ? result : null;
+        }
+
+        return null;
+    }
+
+    /**
+     * 获取已注册的 Model 定义
+     *
+     * @param {string} collectionName - 集合名称
+     * @returns {Object|undefined} Model 定义对象
+     *
+     * @example
+     * const userModelDef = Model.get('users');
+     */
+    static get(collectionName) {
+        return this._registry.get(collectionName);
+    }
+
+    /**
+     * 检查 Model 是否已注册
+     *
+     * @param {string} collectionName - 集合名称
+     * @returns {boolean}
+     *
+     * @example
+     * if (Model.has('users')) {
+     *   // Model 已注册
+     * }
+     */
+    static has(collectionName) {
+        return this._registry.has(collectionName);
+    }
+
+    /**
+     * 获取所有已注册的 Model 名称
+     *
+     * @returns {string[]} Model 名称数组
+     *
+     * @example
+     * const modelNames = Model.list();
+     * // ['users', 'posts', 'comments']
+     */
+    static list() {
+        return Array.from(this._registry.keys());
+    }
+
+    /**
+     * 清空所有已注册的 Model（主要用于测试）
+     *
+     * @private
+     */
+    static _clear() {
+        this._registry.clear();
+    }
+}
+
+/**
+ * ModelInstance - Model 实例类
+ * 继承 collection 的所有方法，并扩展 Model 特性
+ */
+class ModelInstance {
+    /**
+     * 创建 ModelInstance 实例
+     *
+     * @param {Object} collection - monSQLize collection 对象
+     * @param {Object} definition - Model 定义对象
+     * @param {Object} msq - monSQLize 实例
+     */
+    constructor(collection, definition, msq) {
+        this.collection = collection;
+        this.definition = definition;
+        this.msq = msq;
+
+        // ========== Schema 缓存优化 ==========
+        // 🚀 性能优化：编译 schema 并缓存，避免每次 validate 重新执行
+        this._schemaCache = null;
+        if (typeof definition.schema === 'function') {
+            try {
+                // 绑定 this 到 definition，支持访问 this.enums
+                this._schemaCache = definition.schema.call(definition, dsl);
+            } catch (err) {
+                // schema 函数执行失败时，保持为 null，在 validate 时重新尝试
+                this._schemaCache = null;
+            }
+        } else {
+            this._schemaCache = definition.schema;
+        }
+
+        // ========== 继承 collection 所有方法 ==========
+        // 将 collection 的所有方法代理到 ModelInstance
+        const collectionMethods = Object.getOwnPropertyNames(Object.getPrototypeOf(collection))
+            .concat(Object.keys(collection))
+            .filter(key => key !== 'constructor' && typeof collection[key] === 'function');
+
+        // 去重
+        const uniqueMethods = [...new Set(collectionMethods)];
+
+        uniqueMethods.forEach(method => {
+            if (!this[method]) {
+                this[method] = async (...args) => {
+                    // 🔧 incrementOne 特殊处理timestamps
+                    if (method === 'incrementOne' && this.definition._internalHooks?.timestamps?.updatedAt) {
+                        // 调用 _applyTimestampsToIncrementOne 处理
+                        args = this._applyTimestampsToIncrementOne(args);
+                    }
+
+                    // 🔧 Hook 拦截机制
+                    const result = await this._interceptWithHooks(method, args);
+
+                    // 🔧 实例方法注入：只在查询操作时注入（find/findOne/aggregate等）
+                    const opType = this._getOperationType(method);
+                    if (opType === 'find' && result) {
+                        this._injectInstanceMethods(result);
+                    }
+
+                    return result;
+                };
+            }
+        });
+
+        // ========== 扩展自定义方法 ==========
+        if (typeof definition.methods === 'function') {
+            const customMethods = definition.methods(this);
+
+            // 1. instance 方法 - 保存引用，用于注入到查询结果
+            this._instanceMethods = customMethods.instance || {};
+
+            // 2. static 方法 - 挂载到 ModelInstance 本身
+            if (customMethods.static && typeof customMethods.static === 'object') {
+                Object.keys(customMethods.static).forEach(methodName => {
+                    if (typeof customMethods.static[methodName] === 'function') {
+                        // 挂载到 this（ModelInstance 实例）
+                        this[methodName] = customMethods.static[methodName].bind(this);
+                    }
+                });
+            }
+
+            // 3. 警告未识别的键（帮助用户发现错误）
+            if (customMethods && typeof customMethods === 'object') {
+                const validKeys = ['instance', 'static'];
+                const unknownKeys = Object.keys(customMethods).filter(k => !validKeys.includes(k));
+                if (unknownKeys.length > 0 && this.msq && this.msq.logger) {
+                    this.msq.logger.warn(
+                        `[Model] methods 只支持 'instance' 和 'static' 两个分组。` +
+                        `发现未识别的键: ${unknownKeys.join(', ')}`
+                    );
+                }
+            }
+        } else {
+            this._instanceMethods = {};
+        }
+
+        // ========== 初始化 indexes 数组 ==========
+        // 注意：必须在 setupSoftDelete 之前初始化，因为 softDelete 可能添加 TTL 索引
+        this.indexes = definition.indexes || [];
+
+        // ========== 软删除功能 ==========
+        const { setupSoftDelete } = require('./features/soft-delete');
+        setupSoftDelete(this, definition.options?.softDelete);
+
+        // ========== 乐观锁版本控制功能 ==========
+        const { setupVersion } = require('./features/version');
+        setupVersion(this, definition.options?.version);
+
+        // ========== 自动创建索引 ==========
+        if (Array.isArray(this.indexes) && this.indexes.length > 0) {
+            // 延迟执行，避免阻塞初始化
+            setImmediate(() => {
+                this._createIndexes().catch(err => {
+                    // 索引创建失败仅记录警告，不中断流程
+                    if (this.msq && this.msq.logger) {
+                        this.msq.logger.warn(`[Model] Failed to create indexes for ${this.collection.collectionName}:`, err.message);
+                    }
+                });
+            });
+        }
+    }
+
+    /**
+     * 将实例方法注入到文档对象
+     *
+     * @private
+     * @param {Object|Array} result - 查询返回的结果（文档对象或数组）
+     */
+    _injectInstanceMethods(result) {
+        if (!this._instanceMethods || Object.keys(this._instanceMethods).length === 0) {
+            return;
+        }
+
+        // 处理数组结果（find 返回的）
+        if (Array.isArray(result)) {
+            result.forEach(doc => {
+                if (doc && typeof doc === 'object') {
+                    this._injectToDocument(doc);
+                }
+            });
+        }
+        // 处理单个文档（findOne 返回的）
+        else if (result && typeof result === 'object' && !Buffer.isBuffer(result)) {
+            this._injectToDocument(result);
+        }
+    }
+
+    /**
+     * 将实例方法注入到单个文档对象
+     *
+     * @private
+     * @param {Object} doc - 文档对象
+     */
+    _injectToDocument(doc) {
+        Object.keys(this._instanceMethods).forEach(methodName => {
+            if (typeof this._instanceMethods[methodName] === 'function') {
+                // 绑定 this 到文档对象
+                doc[methodName] = this._instanceMethods[methodName].bind(doc);
+            }
+        });
+    }
+
+    /**
+     * Hook 拦截机制
+     * 在方法执行前后触发 before/after 钩子
+     *
+     * @private
+     * @param {string} method - 方法名
+     * @param {Array} args - 方法参数
+     * @returns {Promise<*>} 方法执行结果
+     */
+    async _interceptWithHooks(method, args) {
+        const hooks = typeof this.definition.hooks === 'function'
+            ? this.definition.hooks(this)
+            : {};
+
+        // 提取操作类型（find/insert/update/delete）
+        const opType = this._getOperationType(method);
+        const opHooks = hooks[opType] || {};
+
+        // 上下文对象（用于在 before/after 之间传递数据，如事务 session）
+        const ctx = {};
+
+        // ========== Before Hook ==========
+        if (typeof opHooks.before === 'function') {
+            // 🔧 修复：before hook 错误必须中断操作
+            const modifiedArgs = await opHooks.before(ctx, ...args);
+
+            // 🔧 修复：正确应用 before hook 返回值
+            // 对于 insert 操作，第一个参数是待插入的文档
+            if (modifiedArgs !== undefined) {
+                if (opType === 'insert') {
+                    // insertOne/insertMany: args[0] 是文档/文档数组
+                    args[0] = modifiedArgs;
+                } else if (Array.isArray(modifiedArgs)) {
+                    // 其他操作：如果返回数组，替换整个 args
+                    args = modifiedArgs;
+                } else {
+                    // 单个返回值，替换第一个参数
+                    args[0] = modifiedArgs;
+                }
+            }
+        }
+
+        // ========== 自动注入时间戳（在用户 hook 之后执行）==========
+        if (this.definition._internalHooks?.timestamps) {
+            args = this._applyTimestamps(opType, method, args);
+        }
+
+        // ========== 执行原始方法 ==========
+        const result = await this.collection[method](...args);
+
+        // ========== After Hook ==========
+        if (typeof opHooks.after === 'function') {
+            try {
+                const modifiedResult = await opHooks.after(ctx, result);
+                // 如果 after 返回值，使用修改后的结果
+                if (modifiedResult !== undefined) {
+                    return modifiedResult;
+                }
+            } catch (err) {
+                // 🔧 修复：after hook 失败记录警告，但不影响操作结果
+                if (this.msq && this.msq.logger) {
+                    this.msq.logger.warn(`[Model] After hook failed for ${method}:`, err.message);
+                }
+                // 不抛出错误，返回原始结果
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * 应用时间戳到 incrementOne
+     *
+     * incrementOne 的参数: (filter, field, increment, options)
+     * 我们需要在底层的 findOneAndUpdate 调用中注入 $set.updatedAt
+     *
+     * @private
+     * @param {Array} args - incrementOne 参数数组
+     * @returns {Array} 修改后的参数
+     */
+    _applyTimestampsToIncrementOne(args) {
+        const config = this.definition._internalHooks.timestamps;
+        const now = new Date();
+
+        // 找到 options 参数（可能在 args[2] 或 args[3]）
+        let optionsIndex = -1;
+        if (args[3] && typeof args[3] === 'object') {
+            optionsIndex = 3;
+        } else if (args[2] && typeof args[2] === 'object' && typeof args[2] !== 'number') {
+            // args[2] 是对象且不是数字（increment）
+            optionsIndex = 2;
+        }
+
+        // 创建或修改 options，添加 $set.updatedAt
+        if (optionsIndex === -1) {
+            // 没有 options，创建一个
+            args[3] = { $set: { [config.updatedAt]: now } };
+        } else {
+            // 有 options，合并 $set
+            const options = args[optionsIndex];
+            if (!options.$set) {
+                options.$set = {};
+            }
+            options.$set[config.updatedAt] = now;
+        }
+
+        return args;
+    }
+
+    /**
+     * 应用时间戳
+     *
+     * @private
+     * @param {string} opType - 操作类型
+     * @param {string} method - 方法名
+     * @param {Array} args - 参数
+     * @returns {Array} 修改后的参数
+     */
+    _applyTimestamps(opType, method, args) {
+        const config = this.definition._internalHooks.timestamps;
+        const now = new Date();
+
+        if (opType === 'insert') {
+            // insertOne/insertMany
+            const docs = args[0];
+
+            if (Array.isArray(docs)) {
+                // insertMany
+                args[0] = docs.map(doc => {
+                    const newDoc = { ...doc };
+                    // 🔧 修复：只在用户未手动设置时添加时间戳
+                    if (config.createdAt && !doc[config.createdAt]) {
+                        newDoc[config.createdAt] = now;
+                    }
+                    if (config.updatedAt && !doc[config.updatedAt]) {
+                        newDoc[config.updatedAt] = now;
+                    }
+                    return newDoc;
+                });
+            } else {
+                // insertOne
+                const newDoc = { ...docs };
+                // 🔧 修复：只在用户未手动设置时添加时间戳
+                if (config.createdAt && !docs[config.createdAt]) {
+                    newDoc[config.createdAt] = now;
+                }
+                if (config.updatedAt && !docs[config.updatedAt]) {
+                    newDoc[config.updatedAt] = now;
+                }
+                args[0] = newDoc;
+            }
+        } else if (opType === 'update') {
+            // updateOne/updateMany/replaceOne/upsertOne/findOneAndUpdate/findOneAndReplace/incrementOne
+
+            if (method.startsWith('upsert')) {
+                // 🔧 upsert 特殊处理：插入时添加 createdAt，更新时只更新 updatedAt
+                const update = args[1] || {};
+
+                // $setOnInsert: 仅在插入新文档时执行
+                if (config.createdAt) {
+                    if (!update.$setOnInsert) {
+                        update.$setOnInsert = {};
+                    }
+                    update.$setOnInsert[config.createdAt] = now;
+                }
+
+                // $set: 每次都执行（插入和更新都会设置 updatedAt）
+                if (config.updatedAt) {
+                    if (!update.$set) {
+                        update.$set = {};
+                    }
+                    update.$set[config.updatedAt] = now;
+                }
+
+                args[1] = update;
+            } else if (method === 'replaceOne' || method === 'findOneAndReplace') {
+                // replaceOne/findOneAndReplace: 直接在文档中添加（不能使用操作符）
+                if (config.updatedAt) {
+                    const replacement = args[1] || {};
+                    // 🔧 修复：只在用户未手动设置时添加 updatedAt
+                    if (!replacement[config.updatedAt]) {
+                        replacement[config.updatedAt] = now;
+                    }
+                    args[1] = replacement;
+                }
+            } else if (method.startsWith('increment')) {
+                // 🔧 incrementOne 特殊处理
+                // incrementOne(filter, field, increment, options)
+                // Model 层无法直接修改内部的 $inc 对象，但可以通过 options 传递时间戳更新
+                // 注意：incrementOne 内部会调用 findOneAndUpdate，所以我们不在这里处理
+                // 而是让 incrementOne 自己处理（需要修改 increment-one.js）
+                // 暂时跳过
+            } else if (config.updatedAt) {
+                // 其他 update 操作（updateOne/updateMany/findOneAndUpdate）：在 $set 中添加 updatedAt
+                const update = args[1] || {};
+
+                if (!update.$set) {
+                    update.$set = {};
+                }
+
+                update.$set[config.updatedAt] = now;
+                args[1] = update;
+            }
+        }
+
+        return args;
+    }
+
+    /**
+     * 提取操作类型
+     *
+     * @private
+     * @param {string} method - 方法名
+     * @returns {string} 操作类型（find/insert/update/delete）
+     */
+    _getOperationType(method) {
+        // findOneAnd* 方法需要特殊处理（优先判断）
+        if (method === 'findOneAndUpdate' || method === 'findOneAndReplace' || method === 'findOneAndDelete') {
+            if (method === 'findOneAndDelete') {
+                return 'delete';
+            }
+            return 'update';
+        }
+
+        if (method.startsWith('find') || method === 'aggregate' || method === 'count') {
+            return 'find';
+        }
+        if (method.startsWith('insert')) {
+            return 'insert';
+        }
+        if (method.startsWith('update') || method.startsWith('replace') || method.startsWith('upsert') || method.startsWith('increment')) {
+            return 'update';
+        }
+        if (method.startsWith('delete')) {
+            return 'delete';
+        }
+        return 'unknown';
+    }
+
+    /**
+     * 数据验证方法
+     *
+     * @param {Object} data - 待验证的数据
+     * @param {Object} [options] - 验证选项
+     * @param {string} [options.locale] - 语言（zh-CN/en-US等）
+     * @returns {Object} 验证结果 { valid: boolean, errors: Array, data: Object }
+     *
+     * @example
+     * const result = model.validate({ username: 'test' });
+     * if (!result.valid) {
+     *   console.error(result.errors);
+     * }
+     */
+    validate(data, options = {}) {
+        try {
+            // 获取 schema（优先使用缓存）
+            let schema = this._schemaCache;
+
+            // 如果缓存为空，重新编译
+            if (!schema) {
+                if (typeof this.definition.schema === 'function') {
+                    schema = this.definition.schema.call(this.definition, dsl);
+                } else {
+                    schema = this.definition.schema;
+                }
+            }
+
+            // 执行验证
+            const result = validate(schema, data);
+
+            // 返回统一格式
+            return {
+                valid: result.valid,
+                errors: result.errors || [],
+                data: result.data || data
+            };
+
+        } catch (err) {
+            // 验证过程失败
+            return {
+                valid: false,
+                errors: [{
+                    field: '_schema',
+                    message: `Schema validation failed: ${err.message}`,
+                    code: 'SCHEMA_ERROR'
+                }],
+                data
+            };
+        }
+    }
+
+    /**
+     * 自动创建索引
+     *
+     * @private
+     * @returns {Promise<void>}
+     */
+    async _createIndexes() {
+        const indexes = this.definition.indexes || [];
+        if (!Array.isArray(indexes) || indexes.length === 0) {
+            return;
+        }
+
+        for (const indexSpec of indexes) {
+            try {
+                if (indexSpec.key && typeof indexSpec.key === 'object') {
+                    const options = { ...indexSpec };
+                    delete options.key;
+                    await this.collection.createIndex(indexSpec.key, options);
+                }
+            } catch (err) {
+                // 索引已存在或其他错误，记录但不中断
+                if (this.msq && this.msq.logger) {
+                    this.msq.logger.warn(`[Model] Index creation warning:`, err.message);
+                }
+            }
+        }
+    }
+
+    /**
+     * 获取关系定义
+     *
+     * @returns {Object} 关系定义对象
+     *
+     * @example
+     * const relations = model.getRelations();
+     * // { posts: { type: 'hasMany', target: 'Post', ... } }
+     */
+    getRelations() {
+        return this.definition.relations || {};
+    }
+
+    /**
+     * 获取 enums 配置
+     *
+     * @returns {Object} 枚举配置对象
+     *
+     * @example
+     * const enums = model.getEnums();
+     * // { role: 'admin|user', status: 'active|inactive' }
+     */
+    getEnums() {
+        return this.definition.enums || {};
+    }
+}
+
+// ========== 导出 ==========
+module.exports = Model;
+module.exports.ModelInstance = ModelInstance;
+