monsqlize 1.3.0 → 2.0.0

package/lib/transaction/Transaction.js

@@ -1,315 +0,0 @@
-/**
- * Transaction 类
- * 表示一个 MongoDB 事务
- */
-
-class Transaction {
-    constructor(session, options = {}) {
-        this.session = session;
-        this.id = `tx_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
-        this.state = 'pending';
-        this.cache = options.cache;
-        this.logger = options.logger;
-        this.timeout = options.timeout || 30000;
-        this.startTime = null;
-        this.timeoutTimer = null;
-
-        // 记录待失效的缓存（事务提交后才失效）
-        this.pendingInvalidations = new Set();
-
-        // 缓存锁管理器
-        this.lockManager = options.lockManager;
-        this.lockedKeys = new Set();
-
-        // ✨ 只读优化：追踪事务是否有写操作
-        this.hasWriteOperation = false;
-        this.operationCount = { read: 0, write: 0 };
-
-        // 关键：将 Transaction 实例存储到 session 的自定义属性
-        // 这样写操作可以通过 session.__monSQLizeTransaction 访问到 Transaction 实例
-        if (session) {
-            session.__monSQLizeTransaction = this;
-        }
-    }
-
-    /**
-     * 开始事务
-     */
-    async start() {
-        if (this.state !== 'pending') {
-            throw new Error(`Cannot start transaction in state: ${this.state}`);
-        }
-
-        this.session.startTransaction();
-        this.state = 'active';
-        this.startTime = Date.now();
-
-        // 设置超时自动中止
-        if (this.timeout > 0) {
-            this.timeoutTimer = setTimeout(() => {
-                if (this.state === 'active') {
-                    this.logger?.warn(`[Transaction] Timeout after ${this.timeout}ms, auto-aborting transaction ${this.id}`);
-                    this.abort().catch(() => {});
-                }
-            }, this.timeout);
-        }
-
-        this.logger?.debug(`[Transaction] Started transaction ${this.id}`);
-    }
-
-    /**
-     * 提交事务
-     * 注意：缓存已在 recordInvalidation() 中失效，这里只释放锁
-     */
-    async commit() {
-        if (this.state !== 'active') {
-            throw new Error(`Cannot commit transaction in ${this.state} state`);
-        }
-
-        try {
-            // 1. 提交事务
-            await this.session.commitTransaction();
-            this.state = 'committed';
-
-            // 2. 释放缓存锁（允许重新缓存）
-            // 注意：缓存已在写操作时失效，这里不再失效
-            this._releaseLocks();
-
-            this.logger?.debug(`[Transaction] Committed transaction ${this.id}`);
-        } finally {
-            this._clearTimeout();
-            this.pendingInvalidations.clear();
-        }
-    }
-
-    /**
-     * 回滚事务
-     * 注意：
-     * - 缓存已在写操作时失效
-     * - 但数据实际未改变（事务回滚）
-     * - 释放锁后，下次查询会从数据库读取并重新缓存（正确的旧值）
-     */
-    async abort() {
-        if (this.state !== 'active' && this.state !== 'pending') {
-            return; // 已经结束或中止
-        }
-
-        try {
-            await this.session.abortTransaction();
-            this.state = 'aborted';
-            this.logger?.debug(`[Transaction] Aborted transaction ${this.id}`);
-        } finally {
-            this._clearTimeout();
-            // 释放缓存锁（允许重新缓存）
-            // 注意：缓存已在写时失效，不在这里失效
-            this._releaseLocks();
-            this.pendingInvalidations.clear();
-        }
-    }
-
-    /**
-     * 结束会话
-     */
-    async end() {
-        await this.session.endSession();
-        this._clearTimeout();
-        this._releaseLocks();
-        this.logger?.debug(`[Transaction] Ended session for transaction ${this.id}`);
-    }
-
-    /**
-     * 记录待失效的缓存
-     * 写操作应该调用此方法，立即失效缓存并添加锁
-     * @param {string} cachePattern - 缓存键模式（支持通配符）
-     * @param {Object} metadata - 操作元数据
-     * @param {string} metadata.operation - 操作类型：'read' | 'write'
-     * @param {Object} metadata.query - 查询条件（用于文档级别锁）
-     * @param {string} metadata.collection - 集合名称
-     * @param {boolean} metadata.useDocumentLock - 是否启用文档级别锁（默认：true）
-     */
-    async recordInvalidation(cachePattern, metadata = {}) {
-        if (this.state === 'active') {
-            const {
-                operation = 'write',
-                query = {},
-                collection = '',
-                useDocumentLock = true
-            } = metadata;
-
-            // ✨ 追踪操作类型
-            if (operation === 'read') {
-                this.operationCount.read++;
-            } else {
-                this.operationCount.write++;
-                this.hasWriteOperation = true;
-            }
-
-            // ✨ 只读优化：只读操作不失效缓存
-            if (operation === 'read') {
-                // 只添加缓存锁，不失效缓存
-                if (this.lockManager) {
-                    this.lockManager.addLock(cachePattern, this.session);
-                    this.lockedKeys.add(cachePattern);
-                    this.logger?.debug(`[Transaction] Added cache lock (read-only): ${cachePattern}`);
-                }
-                this.pendingInvalidations.add(cachePattern);
-                return;
-            }
-
-            // 🚀 文档级别锁：尝试提取文档键
-            let lockPatterns = [cachePattern];
-            let usedDocumentLock = false;
-
-            if (useDocumentLock && collection && query) {
-                const docKeys = this._extractDocumentKeys(query);
-
-                // 如果成功提取文档键，且数量合理（<100个）
-                if (docKeys.length > 0 && docKeys.length < 100) {
-                    lockPatterns = docKeys.map(key =>
-                        this._buildDocumentLockPattern(collection, key)
-                    );
-                    usedDocumentLock = true;
-                    this.logger?.debug(`[Transaction] Using document-level locks for ${docKeys.length} documents`);
-                } else if (docKeys.length >= 100) {
-                    // 文档太多，回退到集合级别
-                    lockPatterns = [this._buildCollectionLockPattern(collection)];
-                    this.logger?.debug(`[Transaction] Too many documents (${docKeys.length}), falling back to collection-level lock`);
-                } else {
-                    // 无法提取文档键，使用传入的模式（通常是集合级别）
-                    this.logger?.debug(`[Transaction] Cannot extract document keys, using pattern: ${cachePattern}`);
-                }
-            }
-
-            // 步骤 1: 立即失效缓存（写时无效化）
-            if (this.cache) {
-                try {
-                    let totalDeleted = 0;
-                    for (const pattern of lockPatterns) {
-                        const deleted = await this.cache.delPattern(pattern);
-                        totalDeleted += deleted;
-                    }
-                    this.logger?.debug(`[Transaction] Immediately invalidated ${totalDeleted} cache keys (${usedDocumentLock ? 'document-level' : 'collection-level'})`);
-                } catch (err) {
-                    this.logger?.warn(`[Transaction] Failed to invalidate cache: ${err.message}`);
-                }
-            }
-
-            // 步骤 2: 添加缓存锁
-            if (this.lockManager) {
-                for (const pattern of lockPatterns) {
-                    this.lockManager.addLock(pattern, this.session);
-                    this.lockedKeys.add(pattern);
-                }
-                this.logger?.debug(`[Transaction] Added ${lockPatterns.length} cache lock(s)`);
-            }
-
-            // 步骤 3: 记录到待处理列表
-            lockPatterns.forEach(p => this.pendingInvalidations.add(p));
-        }
-    }
-
-    /**
-     * 释放所有缓存锁
-     * @private
-     */
-    _releaseLocks() {
-        if (this.lockManager && this.session) {
-            this.lockManager.releaseLocks(this.session);
-            this.lockedKeys.clear();
-            this.logger?.debug('[Transaction] Released all cache locks');
-        }
-    }
-
-    /**
-     * 清除超时定时器
-     * @private
-     */
-    _clearTimeout() {
-        if (this.timeoutTimer) {
-            clearTimeout(this.timeoutTimer);
-            this.timeoutTimer = null;
-        }
-    }
-
-    /**
-     * 获取事务持续时间
-     */
-    getDuration() {
-        if (!this.startTime) return 0;
-        return Date.now() - this.startTime;
-    }
-
-    /**
-     * 🚀 文档级别锁：提取查询中的文档键
-     * @param {Object} query - MongoDB 查询条件
-     * @returns {Array} 文档键数组
-     * @private
-     */
-    _extractDocumentKeys(query) {
-        if (!query || typeof query !== 'object') {
-            return [];
-        }
-
-        const keys = [];
-
-        // 1. 简单的 _id 查询
-        if (query._id !== undefined && query._id !== null) {
-            if (Array.isArray(query._id)) {
-                // { _id: [1, 2, 3] }
-                keys.push(...query._id.map(id => String(id)));
-            } else if (query._id.$in && Array.isArray(query._id.$in)) {
-                // { _id: { $in: [1, 2, 3] } }
-                keys.push(...query._id.$in.map(id => String(id)));
-            } else if (typeof query._id === 'object' && query._id.constructor.name === 'ObjectId') {
-                // { _id: ObjectId("...") }
-                keys.push(String(query._id));
-            } else if (typeof query._id !== 'object' || query._id === null) {
-                // { _id: 1 } 或 { _id: "xxx" }
-                keys.push(String(query._id));
-            }
-        }
-
-        return keys;
-    }
-
-    /**
-     * 🚀 文档级别锁：构建文档级别的缓存模式
-     * @param {string} collection - 集合名称
-     * @param {string} docKey - 文档键
-     * @returns {string} 文档级别缓存模式
-     * @private
-     */
-    _buildDocumentLockPattern(collection, docKey) {
-        // 格式: *"collection":"collectionName"*"base":{"_id":"docKey"}*
-        return `*"collection":"${collection}"*"base":{"_id":"${docKey}"}*`;
-    }
-
-    /**
-     * 🚀 文档级别锁：构建集合级别的缓存模式（回退）
-     * @param {string} collection - 集合名称
-     * @returns {string} 集合级别缓存模式
-     * @private
-     */
-    _buildCollectionLockPattern(collection) {
-        // 格式: *"collection":"collectionName"*
-        return `*"collection":"${collection}"*`;
-    }
-
-    /**
-     * 🚀 获取事务统计信息
-     * @returns {Object} 统计信息
-     */
-    getStats() {
-        return {
-            id: this.id,
-            state: this.state,
-            duration: this.getDuration(),
-            hasWriteOperation: this.hasWriteOperation,
-            operationCount: { ...this.operationCount },
-            lockedKeysCount: this.lockedKeys.size
-        };
-    }
-}
-
-module.exports = Transaction;
-

package/lib/transaction/TransactionManager.js

@@ -1,267 +0,0 @@
-/**
- * 事务管理器
- * 负责管理 MongoDB 事务的生命周期
- */
-
-const Transaction = require('./Transaction');
-const CacheLockManager = require('./CacheLockManager');
-
-class TransactionManager {
-    constructor(adapter, cache, logger, options = {}) {
-        this.adapter = adapter;
-        this.cache = cache;
-        this.logger = logger;
-        this.options = {
-            maxRetries: options.maxRetries || 3,
-            retryDelay: options.retryDelay || 100,
-            retryBackoff: options.retryBackoff || 2,
-            defaultTimeout: options.defaultTimeout || 30000,
-            enableRetry: options.enableRetry !== false,
-            ...options
-        };
-        this.activeTransactions = new Map();
-
-        // ✨ 统计信息
-        this.stats = {
-            totalTransactions: 0,
-            successfulTransactions: 0,
-            failedTransactions: 0,
-            readOnlyTransactions: 0,
-            writeTransactions: 0,
-            durations: []
-        };
-        this.maxStatsSamples = options.maxStatsSamples || 1000;
-
-        // 使用传入的 lockManager 或创建新的
-        if (options.lockManager) {
-            this.lockManager = options.lockManager;
-        } else {
-            // 初始化缓存锁管理器
-            this.lockManager = new CacheLockManager({
-                logger: this.logger,
-                maxDuration: options.lockMaxDuration || 300000,
-                cleanupInterval: options.lockCleanupInterval || 10000
-            });
-
-            // 将锁管理器设置到缓存实例
-            if (cache && typeof cache.setLockManager === 'function') {
-                cache.setLockManager(this.lockManager);
-            }
-        }
-    }
-
-    /**
-     * 创建一个新的事务会话
-     * @param {Object} options - 会话选项
-     * @returns {Promise<Transaction>}
-     */
-    async startSession(options = {}) {
-        const session = this.adapter.client.startSession({
-            causalConsistency: options.causalConsistency !== false,
-            defaultTransactionOptions: {
-                readConcern: options.readConcern,
-                writeConcern: options.writeConcern,
-                readPreference: options.readPreference
-            }
-        });
-
-        const transaction = new Transaction(session, {
-            cache: this.cache,
-            logger: this.logger,
-            lockManager: this.lockManager,
-            timeout: options.timeout || this.options.defaultTimeout,
-            ...options
-        });
-
-        this.activeTransactions.set(transaction.id, transaction);
-
-        return transaction;
-    }
-
-    /**
-     * 自动管理事务（推荐用法）
-     * @param {Function} callback - 事务回调函数
-     * @param {Object} options - 事务选项
-     * @returns {Promise<any>}
-     */
-    async withTransaction(callback, options = {}) {
-        const maxRetries = options.maxRetries !== undefined
-            ? options.maxRetries
-            : this.options.maxRetries;
-
-        const enableRetry = options.enableRetry !== undefined
-            ? options.enableRetry
-            : this.options.enableRetry;
-
-        const retryDelay = options.retryDelay || this.options.retryDelay;
-        const retryBackoff = options.retryBackoff || this.options.retryBackoff;
-
-        let attempt = 0;
-        let lastError = null;
-
-        while (attempt <= maxRetries) {
-            const transaction = await this.startSession(options);
-            const startTime = Date.now();
-
-            try {
-                await transaction.start();
-                const result = await callback(transaction);
-                await transaction.commit();
-
-                // ✨ 记录统计信息（成功）
-                const duration = Date.now() - startTime;
-                this._recordStats(transaction, duration, true);
-
-                return result;
-            } catch (error) {
-                lastError = error;
-
-                // 回滚事务
-                try {
-                    await transaction.abort();
-                } catch (abortError) {
-                    // 忽略回滚错误
-                }
-
-                // ✨ 记录统计信息（失败）
-                const duration = Date.now() - startTime;
-                this._recordStats(transaction, duration, false);
-
-                // 检查是否需要重试
-                if (enableRetry &&
-                    attempt < maxRetries &&
-                    this._isTransientError(error)) {
-                    attempt++;
-
-                    // 计算延迟时间（指数退避）
-                    const delay = retryDelay * Math.pow(retryBackoff, attempt - 1);
-
-                    this.logger?.info(`[TransactionManager] Retrying transaction (attempt ${attempt}/${maxRetries}) after ${delay}ms due to transient error: ${error.message}`);
-
-                    // 等待后重试
-                    await new Promise(resolve => setTimeout(resolve, delay));
-
-                    continue;
-                }
-
-                // 不重试，抛出错误
-                throw error;
-            } finally {
-                await transaction.end();
-                this.activeTransactions.delete(transaction.id);
-            }
-        }
-
-        // 达到最大重试次数
-        throw new Error(
-            `Transaction failed after ${maxRetries} retries: ${lastError.message}`
-        );
-    }
-
-    /**
-     * 判断是否为瞬态错误（可重试）
-     * @private
-     */
-    _isTransientError(error) {
-        if (!error) return false;
-
-        // MongoDB TransientTransactionError
-        if (error.hasErrorLabel && error.hasErrorLabel('TransientTransactionError')) {
-            return true;
-        }
-
-        // 写冲突错误码
-        const transientErrorCodes = [
-            112,  // WriteConflict
-            117,  // ConflictingOperationInProgress
-        ];
-
-        return transientErrorCodes.includes(error.code);
-    }
-
-    /**
-     * 获取所有活跃的事务
-     */
-    getActiveTransactions() {
-        return Array.from(this.activeTransactions.values());
-    }
-
-    /**
-     * 中止所有活跃的事务
-     */
-    async abortAll() {
-        const transactions = this.getActiveTransactions();
-        await Promise.all(transactions.map(tx => tx.abort().catch(() => {})));
-    }
-
-    /**
-     * ✨ 记录统计信息
-     * @param {Transaction} transaction - 事务实例
-     * @param {number} duration - 持续时间（毫秒）
-     * @param {boolean} success - 是否成功
-     * @private
-     */
-    _recordStats(transaction, duration, success) {
-        this.stats.totalTransactions++;
-
-        if (success) {
-            this.stats.successfulTransactions++;
-        } else {
-            this.stats.failedTransactions++;
-        }
-
-        // 记录只读/写入事务
-        if (transaction.hasWriteOperation) {
-            this.stats.writeTransactions++;
-        } else {
-            this.stats.readOnlyTransactions++;
-        }
-
-        // 记录持续时间（环形缓冲）
-        this.stats.durations.push(duration);
-        if (this.stats.durations.length > this.maxStatsSamples) {
-            this.stats.durations.shift();
-        }
-    }
-
-    /**
-     * ✨ 获取统计信息
-     * @returns {Object} 统计信息
-     */
-    getStats() {
-        const { durations } = this.stats;
-
-        // 计算统计值
-        let avgDuration = 0;
-        let p95Duration = 0;
-        let p99Duration = 0;
-
-        if (durations.length > 0) {
-            avgDuration = durations.reduce((a, b) => a + b, 0) / durations.length;
-
-            const sorted = [...durations].sort((a, b) => a - b);
-            const p95Index = Math.floor(sorted.length * 0.95);
-            const p99Index = Math.floor(sorted.length * 0.99);
-            p95Duration = sorted[p95Index] || 0;
-            p99Duration = sorted[p99Index] || 0;
-        }
-
-        return {
-            ...this.stats,
-            averageDuration: avgDuration,
-            p95Duration,
-            p99Duration,
-            successRate: this.stats.totalTransactions > 0
-                ? (this.stats.successfulTransactions / this.stats.totalTransactions * 100).toFixed(2) + '%'
-                : '0%',
-            readOnlyRatio: this.stats.totalTransactions > 0
-                ? (this.stats.readOnlyTransactions / this.stats.totalTransactions * 100).toFixed(2) + '%'
-                : '0%',
-            sampleCount: durations.length
-        };
-    }
-}
-
-module.exports = TransactionManager;
-
-

package/lib/transaction/index.js

@@ -1,11 +0,0 @@
-const TransactionManager = require('./TransactionManager');
-const Transaction = require('./Transaction');
-const CacheLockManager = require('./CacheLockManager');
-
-module.exports = {
-    TransactionManager,
-    Transaction,
-    CacheLockManager
-};
-
-