monsqlize 1.0.1 → 1.0.5

package/lib/model/features/soft-delete.js

@@ -0,0 +1,348 @@
+/**
+ * Soft Delete Feature for Model
+ *
+ * Provides soft delete functionality:
+ * - Mark documents as deleted instead of physical deletion
+ * - Auto-filter deleted documents in queries
+ * - Restore deleted documents
+ * - Force physical deletion
+ * - TTL index for auto-cleanup
+ *
+ * @module lib/model/features/soft-delete
+ */
+
+/**
+ * Parse soft delete configuration
+ * @param {Object|boolean} config - Soft delete config
+ * @returns {Object|null} Parsed config or null if disabled
+ */
+function parseSoftDeleteConfig(config) {
+    if (!config) return null;
+
+    // shorthand: softDelete: true
+    if (config === true) {
+        return {
+            enabled: true,
+            field: 'deletedAt',
+            type: 'timestamp',
+            ttl: null
+        };
+    }
+
+    // full config: softDelete: { ... }
+    return {
+        enabled: config.enabled !== false,
+        field: config.field || 'deletedAt',
+        type: config.type || 'timestamp',
+        ttl: config.ttl || null
+    };
+}
+
+/**
+ * Get delete value based on type
+ * @param {string} type - 'timestamp' or 'boolean'
+ * @returns {Date|boolean} Delete value
+ */
+function getDeleteValue(type) {
+    return type === 'boolean' ? true : new Date();
+}
+
+/**
+ * Apply soft delete filter to query
+ * @param {Object} filter - Original filter
+ * @param {Object} config - Soft delete config
+ * @param {Object} options - Query options
+ * @returns {Object} Modified filter
+ */
+function applySoftDeleteFilter(filter, config, options = {}) {
+    if (!config?.enabled) return filter;
+
+    const field = config.field;
+
+    // Already has explicit deletedAt filter - don't modify
+    if (filter[field] !== undefined) {
+        return filter;
+    }
+
+    // withDeleted: include all (no filter)
+    if (options.withDeleted) {
+        return filter;
+    }
+
+    // onlyDeleted: only deleted documents
+    if (options.onlyDeleted) {
+        return {
+            ...filter,
+            [field]: { $ne: null }
+        };
+    }
+
+    // default: only non-deleted documents
+    return {
+        ...filter,
+        [field]: null
+    };
+}
+
+/**
+ * Register soft delete hooks
+ * @param {Object} modelInstance - Model instance
+ * @param {Object} config - Soft delete config
+ */
+function registerSoftDeleteHooks(modelInstance, config) {
+    if (!config?.enabled) return;
+
+    const field = config.field;
+    const type = config.type;
+
+    // Store original deleteOne and deleteMany methods
+    const originalDeleteOne = modelInstance.collection.deleteOne.bind(modelInstance.collection);
+    const originalDeleteMany = modelInstance.collection.deleteMany.bind(modelInstance.collection);
+
+    // Override deleteOne - convert to updateOne
+    modelInstance.collection.deleteOne = async function(filter, options = {}) {
+        // Check if force delete (bypass soft delete)
+        if (options._forceDelete) {
+            delete options._forceDelete;
+            return await originalDeleteOne(filter, options);
+        }
+
+        // Soft delete: convert to updateOne
+        const updateResult = await modelInstance.collection.updateOne(
+            filter,
+            { $set: { [field]: getDeleteValue(type) } },
+            options
+        );
+
+        // Convert updateOne result to deleteOne result format
+        return {
+            acknowledged: updateResult.acknowledged,
+            deletedCount: updateResult.modifiedCount
+        };
+    };
+
+    // Override deleteMany - convert to updateMany
+    modelInstance.collection.deleteMany = async function(filter, options = {}) {
+        // Check if force delete (bypass soft delete)
+        if (options._forceDelete) {
+            delete options._forceDelete;
+            return await originalDeleteMany(filter, options);
+        }
+
+        // Soft delete: convert to updateMany
+        const updateResult = await modelInstance.collection.updateMany(
+            filter,
+            { $set: { [field]: getDeleteValue(type) } },
+            options
+        );
+
+        // Convert updateMany result to deleteMany result format
+        return {
+            acknowledged: updateResult.acknowledged,
+            deletedCount: updateResult.modifiedCount
+        };
+    };
+
+    // Store original find/findOne/count methods
+    const originalFind = modelInstance.collection.find.bind(modelInstance.collection);
+    const originalFindOne = modelInstance.collection.findOne.bind(modelInstance.collection);
+    const originalCount = modelInstance.collection.count.bind(modelInstance.collection);
+
+    // Override find - auto-filter deleted
+    modelInstance.collection.find = async function(filter = {}, options = {}) {
+        const modifiedFilter = applySoftDeleteFilter(filter, config, options);
+        return await originalFind(modifiedFilter, options);
+    };
+
+    // Override findOne - auto-filter deleted
+    modelInstance.collection.findOne = async function(filter = {}, options = {}) {
+        const modifiedFilter = applySoftDeleteFilter(filter, config, options);
+        return await originalFindOne(modifiedFilter, options);
+    };
+
+    // Override count - auto-filter deleted
+    modelInstance.collection.count = async function(filter = {}, options = {}) {
+        const modifiedFilter = applySoftDeleteFilter(filter, config, options);
+        return await originalCount(modifiedFilter, options);
+    };
+}
+
+/**
+ * Add soft delete methods to ModelInstance
+ * @param {Object} modelInstance - Model instance
+ * @param {Object} config - Soft delete config
+ */
+function addSoftDeleteMethods(modelInstance, config) {
+    if (!config?.enabled) return;
+
+    const field = config.field;
+
+    /**
+     * Find documents including deleted ones
+     * @param {Object} filter - Query filter
+     * @param {Object} options - Query options
+     * @returns {Promise<Array>} Documents
+     */
+    modelInstance.findWithDeleted = async function(filter = {}, options = {}) {
+        return await this.find(filter, { ...options, withDeleted: true });
+    };
+
+    /**
+     * Find only deleted documents
+     * @param {Object} filter - Query filter
+     * @param {Object} options - Query options
+     * @returns {Promise<Array>} Deleted documents
+     */
+    modelInstance.findOnlyDeleted = async function(filter = {}, options = {}) {
+        return await this.find(filter, { ...options, onlyDeleted: true });
+    };
+
+    /**
+     * Find one document including deleted ones
+     * @param {Object} filter - Query filter
+     * @param {Object} options - Query options
+     * @returns {Promise<Object|null>} Document
+     */
+    modelInstance.findOneWithDeleted = async function(filter = {}, options = {}) {
+        return await this.findOne(filter, { ...options, withDeleted: true });
+    };
+
+    /**
+     * Find one deleted document
+     * @param {Object} filter - Query filter
+     * @param {Object} options - Query options
+     * @returns {Promise<Object|null>} Deleted document
+     */
+    modelInstance.findOneOnlyDeleted = async function(filter = {}, options = {}) {
+        return await this.findOne(filter, { ...options, onlyDeleted: true });
+    };
+
+    /**
+     * Count documents including deleted ones
+     * @param {Object} filter - Query filter
+     * @param {Object} options - Query options
+     * @returns {Promise<number>} Count
+     */
+    modelInstance.countWithDeleted = async function(filter = {}, options = {}) {
+        return await this.count(filter, { ...options, withDeleted: true });
+    };
+
+    /**
+     * Count only deleted documents
+     * @param {Object} filter - Query filter
+     * @param {Object} options - Query options
+     * @returns {Promise<number>} Count
+     */
+    modelInstance.countOnlyDeleted = async function(filter = {}, options = {}) {
+        return await this.count(filter, { ...options, onlyDeleted: true });
+    };
+
+    /**
+     * Restore a deleted document
+     * @param {Object} filter - Query filter
+     * @param {Object} options - Update options
+     * @returns {Promise<Object>} Update result
+     */
+    modelInstance.restore = async function(filter, options) {
+        // Add deleted filter to ensure we only restore deleted documents
+        const restoreFilter = {
+            ...filter,
+            [field]: { $ne: null }
+        };
+
+        return await this.updateOne(
+            restoreFilter,
+            { $unset: { [field]: 1 } },
+            options
+        );
+    };
+
+    /**
+     * Restore multiple deleted documents
+     * @param {Object} filter - Query filter
+     * @param {Object} options - Update options
+     * @returns {Promise<Object>} Update result
+     */
+    modelInstance.restoreMany = async function(filter, options) {
+        // Add deleted filter to ensure we only restore deleted documents
+        const restoreFilter = {
+            ...filter,
+            [field]: { $ne: null }
+        };
+
+        return await this.updateMany(
+            restoreFilter,
+            { $unset: { [field]: 1 } },
+            options
+        );
+    };
+
+    /**
+     * Force physical deletion (bypass soft delete)
+     * @param {Object} filter - Query filter
+     * @param {Object} options - Delete options
+     * @returns {Promise<Object>} Delete result
+     */
+    modelInstance.forceDelete = async function(filter, options = {}) {
+        // Set flag to bypass soft delete
+        return await this.collection.deleteOne(filter, { ...options, _forceDelete: true });
+    };
+
+    /**
+     * Force physical deletion of multiple documents
+     * @param {Object} filter - Query filter
+     * @param {Object} options - Delete options
+     * @returns {Promise<Object>} Delete result
+     */
+    modelInstance.forceDeleteMany = async function(filter, options = {}) {
+        // Set flag to bypass soft delete
+        return await this.collection.deleteMany(filter, { ...options, _forceDelete: true });
+    };
+}
+
+/**
+ * Add TTL index for soft deleted documents
+ * @param {Object} modelInstance - Model instance
+ * @param {Object} config - Soft delete config
+ */
+function addTTLIndex(modelInstance, config) {
+    if (!config?.enabled || !config.ttl) return;
+
+    // Add TTL index to automatically clean up old deleted documents
+    modelInstance.indexes.push({
+        key: { [config.field]: 1 },
+        expireAfterSeconds: config.ttl,
+        name: `${config.field}_ttl`
+    });
+}
+
+/**
+ * Setup soft delete feature for a model
+ * @param {Object} modelInstance - Model instance
+ * @param {Object|boolean} config - Soft delete config
+ */
+function setupSoftDelete(modelInstance, config) {
+    const parsedConfig = parseSoftDeleteConfig(config);
+
+    if (!parsedConfig) return;
+
+    // Store config on model instance
+    modelInstance.softDeleteConfig = parsedConfig;
+
+    // Register hooks
+    registerSoftDeleteHooks(modelInstance, parsedConfig);
+
+    // Add methods
+    addSoftDeleteMethods(modelInstance, parsedConfig);
+
+    // Add TTL index
+    addTTLIndex(modelInstance, parsedConfig);
+}
+
+module.exports = {
+    setupSoftDelete,
+    parseSoftDeleteConfig,
+    applySoftDeleteFilter,
+    getDeleteValue
+};
+

package/lib/model/features/version.js

@@ -0,0 +1,156 @@
+/**
+ * Model 乐观锁版本控制功能
+ *
+ * 功能：
+ * 1. 插入时自动初始化 version: 0
+ * 2. 更新时自动递增版本号
+ * 3. 支持并发冲突检测
+ * 4. 支持自定义字段名
+ *
+ * 使用示例：
+ * ```javascript
+ * Model.define('users', {
+ *     options: {
+ *         version: true  // 或 { enabled: true, field: '__v' }
+ *     }
+ * });
+ *
+ * // 插入时自动初始化
+ * await User.insertOne({ username: 'john' });
+ * // { _id, username: 'john', version: 0 }
+ *
+ * // 更新时自动递增
+ * await User.updateOne({ _id, version: 0 }, { $set: { status: 'active' } });
+ * // 实际执行：{ $set: { status: 'active' }, $inc: { version: 1 } }
+ *
+ * // 并发冲突检测
+ * const result = await User.updateOne({ _id, version: 0 }, { $set: { status: 'inactive' } });
+ * // result.modifiedCount === 0（版本号不匹配，更新失败）
+ * ```
+ *
+ * @module lib/model/features/version
+ */
+
+/**
+ * 解析版本控制配置
+ *
+ * @param {boolean|object} versionConfig - 版本控制配置
+ * @returns {object|null} 解析后的配置对象
+ */
+function parseVersionConfig(versionConfig) {
+    if (!versionConfig) {
+        return null;
+    }
+
+    // 简单模式：version: true
+    if (versionConfig === true) {
+        return {
+            enabled: true,
+            field: 'version'
+        };
+    }
+
+    // 完整配置模式
+    if (typeof versionConfig === 'object') {
+        return {
+            enabled: versionConfig.enabled !== false,
+            field: versionConfig.field || 'version'
+        };
+    }
+
+    return null;
+}
+
+/**
+ * 为 Model 实例设置版本控制功能
+ *
+ * @param {object} modelInstance - Model 实例
+ * @param {boolean|object} versionConfig - 版本控制配置
+ */
+function setupVersion(modelInstance, versionConfig) {
+    // 解析配置
+    const config = parseVersionConfig(versionConfig);
+
+    if (!config || !config.enabled) {
+        return;  // 未启用，直接返回
+    }
+
+    const { field } = config;
+
+    // 保存配置到 Model 实例（供测试验证）
+    modelInstance._versionConfig = config;
+
+    // ========== 功能1: 插入时初始化版本号 ==========
+
+    // 保存原始方法
+    const originalInsertOne = modelInstance.collection.insertOne.bind(modelInstance.collection);
+    const originalInsertMany = modelInstance.collection.insertMany.bind(modelInstance.collection);
+
+    // 覆盖 insertOne
+    modelInstance.collection.insertOne = async function(doc, options) {
+        // 只在用户未手动设置时添加版本号
+        if (doc && typeof doc === 'object' && doc[field] === undefined) {
+            doc[field] = 0;
+        }
+        return await originalInsertOne(doc, options);
+    };
+
+    // 覆盖 insertMany
+    modelInstance.collection.insertMany = async function(docs, options) {
+        if (Array.isArray(docs)) {
+            docs.forEach(doc => {
+                if (doc && typeof doc === 'object' && doc[field] === undefined) {
+                    doc[field] = 0;
+                }
+            });
+        }
+        return await originalInsertMany(docs, options);
+    };
+
+    // ========== 功能2: 更新时自动递增版本号 ==========
+
+    // 保存原始方法
+    const originalUpdateOne = modelInstance.collection.updateOne.bind(modelInstance.collection);
+    const originalUpdateMany = modelInstance.collection.updateMany.bind(modelInstance.collection);
+
+    // 覆盖 updateOne
+    modelInstance.collection.updateOne = async function(filter, update, options) {
+        // 检查 update 是否为空
+        if (update && typeof update === 'object') {
+            // 检查用户是否已手动设置 $inc.version
+            if (!update.$inc || update.$inc[field] === undefined) {
+                // 自动添加 $inc
+                if (!update.$inc) {
+                    update.$inc = {};
+                }
+                update.$inc[field] = 1;
+            }
+        }
+        return await originalUpdateOne(filter, update, options);
+    };
+
+    // 覆盖 updateMany
+    modelInstance.collection.updateMany = async function(filter, update, options) {
+        // 检查 update 是否为空
+        if (update && typeof update === 'object') {
+            // 检查用户是否已手动设置 $inc.version
+            if (!update.$inc || update.$inc[field] === undefined) {
+                // 自动添加 $inc
+                if (!update.$inc) {
+                    update.$inc = {};
+                }
+                update.$inc[field] = 1;
+            }
+        }
+        return await originalUpdateMany(filter, update, options);
+    };
+
+    // 注意：并发冲突检测通过 filter 中的版本号自然实现
+    // 用户提供 { _id, version: 0 } 时，如果版本号不匹配，matchedCount 为 0
+}
+
+module.exports = {
+    setupVersion,
+    parseVersionConfig  // 导出供测试使用
+};
+