monsqlize 1.3.1 → 2.0.1

package/lib/errors.js

@@ -1,167 +0,0 @@
-/**
- * 统一错误码定义
- * 集中管理所有错误类型，确保错误处理的一致性
- */
-
-const ErrorCodes = {
-    // 验证相关错误
-    VALIDATION_ERROR: 'VALIDATION_ERROR',
-    INVALID_ARGUMENT: 'INVALID_ARGUMENT',
-    INVALID_COLLECTION_NAME: 'INVALID_COLLECTION_NAME',
-    INVALID_DATABASE_NAME: 'INVALID_DATABASE_NAME',
-
-    // 游标相关错误
-    INVALID_CURSOR: 'INVALID_CURSOR',
-    CURSOR_SORT_MISMATCH: 'CURSOR_SORT_MISMATCH',
-
-    // 分页相关错误
-    JUMP_TOO_FAR: 'JUMP_TOO_FAR',
-    STREAM_NO_JUMP: 'STREAM_NO_JUMP',
-    STREAM_NO_TOTALS: 'STREAM_NO_TOTALS',
-    STREAM_NO_EXPLAIN: 'STREAM_NO_EXPLAIN',
-
-    // 连接相关错误
-    CONNECTION_TIMEOUT: 'CONNECTION_TIMEOUT',
-    CONNECTION_FAILED: 'CONNECTION_FAILED',
-    CONNECTION_CLOSED: 'CONNECTION_CLOSED',
-
-    // 数据库相关错误
-    DATABASE_ERROR: 'DATABASE_ERROR',
-    QUERY_TIMEOUT: 'QUERY_TIMEOUT',
-
-    // 缓存相关错误
-    CACHE_ERROR: 'CACHE_ERROR',
-    CACHE_TIMEOUT: 'CACHE_TIMEOUT',
-
-    // 配置相关错误
-    INVALID_CONFIG: 'INVALID_CONFIG',
-    UNSUPPORTED_DATABASE: 'UNSUPPORTED_DATABASE',
-
-    // 写操作相关错误
-    WRITE_ERROR: 'WRITE_ERROR',
-    DOCUMENT_REQUIRED: 'DOCUMENT_REQUIRED',
-    DOCUMENTS_REQUIRED: 'DOCUMENTS_REQUIRED',
-    DUPLICATE_KEY: 'DUPLICATE_KEY',
-    WRITE_CONFLICT: 'WRITE_CONFLICT',
-
-    // 🆕 v1.4.0: 锁相关错误
-    LOCK_ACQUIRE_FAILED: 'LOCK_ACQUIRE_FAILED',
-    LOCK_TIMEOUT: 'LOCK_TIMEOUT',
-};
-
-/**
- * 创建标准错误对象
- * @param {string} code - 错误码
- * @param {string} message - 错误消息
- * @param {Array} [details] - 详细错误信息
- * @param {Error} [cause] - 原始错误
- * @returns {Error} 标准错误对象
- */
-function createError(code, message, details, cause) {
-    const error = new Error(message);
-    error.code = code;
-    if (details !== undefined) error.details = details;
-    if (cause !== undefined) error.cause = cause;
-    return error;
-}
-
-/**
- * 创建验证错误
- * @param {string|Array} messageOrDetails - 错误消息或验证错误详情（向后兼容）
- * @param {Array} [details] - 详细信息（当第一个参数是字符串时使用）
- * @returns {Error}
- */
-function createValidationError(messageOrDetails, details) {
-    // 向后兼容：如果第一个参数是数组，当作 details 处理
-    if (Array.isArray(messageOrDetails)) {
-        return createError(
-            ErrorCodes.VALIDATION_ERROR,
-            '参数校验失败',
-            messageOrDetails
-        );
-    }
-
-    // 新用法：第一个参数是消息字符串
-    return createError(
-        ErrorCodes.VALIDATION_ERROR,
-        messageOrDetails || '参数校验失败',
-        details
-    );
-}
-
-/**
- * 创建游标错误
- * @param {string} message - 错误消息
- * @param {Array} [details] - 详细信息
- * @returns {Error}
- */
-function createCursorError(message, details = null) {
-    return createError(
-        ErrorCodes.INVALID_CURSOR,
-        message || '游标无效',
-        details
-    );
-}
-
-/**
- * 创建连接错误
- * @param {string} message - 错误消息
- * @param {Error} [cause] - 原始错误
- * @returns {Error}
- */
-function createConnectionError(message, cause = null) {
-    return createError(
-        ErrorCodes.CONNECTION_FAILED,
-        message || '数据库连接失败',
-        null,
-        cause
-    );
-}
-
-/**
- * 创建查询超时错误
- * @param {number} timeoutMs - 超时时间（毫秒）
- * @param {Error} [cause] - 原始错误
- * @returns {Error}
- */
-function createQueryTimeoutError(timeoutMs, cause = null) {
-    return createError(
-        ErrorCodes.QUERY_TIMEOUT,
-        `查询超时 (${timeoutMs}ms)`,
-        null,
-        cause
-    );
-}
-
-/**
- * 创建写操作错误
- * @param {string} operation - 操作名称
- * @param {string} message - 错误消息
- * @param {Error} [cause] - 原始错误
- * @returns {Error}
- */
-function createWriteError(operation, message, cause = null) {
-    return createError(
-        ErrorCodes.WRITE_ERROR,
-        `${operation} 失败: ${message}`,
-        null,
-        cause
-    );
-}
-
-// 🆕 v1.4.0: 导入锁错误类
-const { LockAcquireError, LockTimeoutError } = require('./lock/errors');
-
-module.exports = {
-    ErrorCodes,
-    createError,
-    createValidationError,
-    createCursorError,
-    createConnectionError,
-    createQueryTimeoutError,
-    createWriteError,
-    // 🆕 v1.4.0: 锁错误类
-    LockAcquireError,
-    LockTimeoutError,
-};
-

package/lib/index.js

@@ -1,461 +0,0 @@
-const Logger = require('./logger');
-const ConnectionManager = require('./connect');
-const MemoryCache = require('./cache');
-const { createRedisCacheAdapter } = require('./redis-cache-adapter');
-const TransactionManager = require('./transaction/TransactionManager');
-const CacheLockManager = require('./transaction/CacheLockManager');
-const DistributedCacheInvalidator = require('./distributed-cache-invalidator');
-const { validateRange } = require('./common/validation');
-
-module.exports = class {
-
-    /**
-     * 初始化数据库连接配置
-     * @param {Object} options - 数据库连接配置选项
-     * @param {string} options.type - 数据库类型,支持 mongodb
-     * @param {Object} options.config - 数据库连接配置
-     * @param {Object} [options.cache] - 缓存配置选项
-     * @param {Object} [options.logger] - 日志记录器
-     * @param {number} [options.maxTimeMS] - 全局默认查询超时时间（毫秒）
-     * @param {{instanceId?: string}} [options.namespace] - 命名空间设置（用于缓存隔离）
-     * @throws {Error} 如果数据库类型无效则抛出错误
-     */
-    constructor(options) {
-        if (!options.type || !['mongodb'].includes(options.type)) {
-            throw new Error('Invalid database type. Supported types are: mongodb');
-        }
-        const { type = 'mongodb', databaseName, config, cache, logger } = options;
-        this.type = type;
-        this.databaseName = databaseName;
-        this.config = config;
-
-        // ✅ v1.3.0: 自动 ObjectId 转换配置
-        this.autoConvertConfig = this._initAutoConvertConfig(
-            options.autoConvertObjectId,
-            options.type
-        );
-
-        // 🔧 修复：保存 distributed 配置到单独的变量
-        this._cacheConfig = cache;
-
-        // Count 队列配置（高并发控制，避免压垮数据库）
-        // 默认值：
-        //   - enabled: true (默认启用)
-        //   - concurrency: CPU 核心数（最少 4，最多 16）
-        //   - maxQueueSize: 10000
-        //   - timeout: 60000ms (1分钟)
-        this.countQueue = options.countQueue !== undefined ? options.countQueue : {
-            enabled: true,       // 默认启用
-            concurrency: undefined,  // undefined 则使用 CPU 核心数
-            maxQueueSize: 10000,     // 队列最大 10000
-            timeout: 60000           // 超时 60 秒
-        };
-
-        // 使用缓存工厂获取有效的缓存实例
-        this.cache = MemoryCache.getOrCreateCache(cache);
-
-        // 使用 Logger 工具类创建日志记录器
-        this.logger = Logger.create(logger);
-
-        // 🔒 参数验证：防止 DoS 攻击（允许null值用于显式禁用）
-        if (options.maxTimeMS !== undefined && options.maxTimeMS !== null) {
-            validateRange(options.maxTimeMS, 1, 300000, 'maxTimeMS');
-        }
-        if (options.findLimit !== undefined && options.findLimit !== null) {
-            validateRange(options.findLimit, 1, 10000, 'findLimit');
-        }
-        if (options.findPageMaxLimit !== undefined && options.findPageMaxLimit !== null) {
-            validateRange(options.findPageMaxLimit, 1, 10000, 'findPageMaxLimit');
-        }
-        if (options.slowQueryMs !== undefined && options.slowQueryMs !== null && options.slowQueryMs !== -1) {
-            validateRange(options.slowQueryMs, 0, 60000, 'slowQueryMs');
-        }
-
-        // 集中默认配置（库内默认 + 用户覆盖）
-        const DEFAULTS = {
-            maxTimeMS: 2000,
-            findLimit: 10,
-            slowQueryMs: 500,
-            namespace: { scope: 'database' },
-            // 深分页/聚合相关
-            findPageMaxLimit: 500,
-            cursorSecret: undefined,
-            // 慢日志扩展
-            log: { slowQueryTag: { event: 'slow_query', code: 'SLOW_QUERY' } },
-        };
-        const deepMerge = (base, patch) => {
-            const out = { ...base };
-            for (const k of Object.keys(patch || {})) {
-                const v = patch[k];
-                if (v && typeof v === 'object' && !Array.isArray(v)) {
-                    out[k] = deepMerge(base[k] || {}, v);
-                } else if (v !== undefined) {
-                    out[k] = v;
-                }
-            }
-            return out;
-        };
-        this.defaults = deepMerge(DEFAULTS, {
-            maxTimeMS: options.maxTimeMS,
-            findLimit: options.findLimit,
-            namespace: options.namespace,
-            slowQueryMs: options.slowQueryMs,
-            // 新增可选项
-            findPageMaxLimit: options.findPageMaxLimit,
-            cursorSecret: options.cursorSecret,
-            log: options.log,
-            // 🔴 v1.3.1: 慢查询日志持久化存储配置
-            slowQueryLog: options.slowQueryLog,
-        });
-        // 冻结默认配置，避免运行期被意外修改
-        this.defaults = Object.freeze(this.defaults);
-    }
-
-    /**
- * 连接数据库并返回访问集合/表的对象
- * @returns {{collection: Function, db: Function}} 返回包含 collection 与 db 方法的对象
- * @throws {Error} 当连接失败时抛出错误
- */
-    async connect() {
-        // 如果已经有连接，直接返回访问对象
-        if (this.dbInstance) {
-            return this.dbInstance;
-        }
-
-        // 防止并发连接：使用连接锁
-        if (this._connecting) {
-            return this._connecting;
-        }
-
-        try {
-            this._connecting = (async () => {
-                // 使用 ConnectionManager 建立连接
-                const { collection, db, instance } = await ConnectionManager.connect(
-                    this.type,
-                    this.databaseName,
-                    this.config,
-                    this.cache,
-                    this.logger,
-                    this.defaults,
-                );
-
-                // 保存连接状态（关键：缓存对象，保证多次调用幂等返回同一形态/引用）
-                this.dbInstance = { collection, db };
-                this._adapter = instance;
-
-                // 初始化分布式缓存失效器（如果配置了）
-                // 🔧 修复：使用 _cacheConfig 读取 distributed 配置
-                if (this._cacheConfig &&
-                    typeof this._cacheConfig.distributed === 'object' &&
-                    this._cacheConfig.distributed.enabled !== false) {
-                    try {
-                        // 🆕 自动从 cache.remote 提取 Redis 实例（如果未配置）
-                        let redis = this._cacheConfig.distributed.redis;
-                        if (!redis && !this._cacheConfig.distributed.redisUrl) {
-                            // 尝试从 remote 缓存适配器中获取 Redis 实例
-                            if (this.cache.remote && typeof this.cache.remote.getRedisInstance === 'function') {
-                                redis = this.cache.remote.getRedisInstance();
-                                if (this.logger) {
-                                    this.logger.info('[DistributedCache] Auto-detected Redis from cache.remote');
-                                }
-                            }
-                        }
-
-                        this._cacheInvalidator = new DistributedCacheInvalidator({
-                            redisUrl: this._cacheConfig.distributed.redisUrl,
-                            redis,
-                            channel: this._cacheConfig.distributed.channel,
-                            instanceId: this._cacheConfig.distributed.instanceId,
-                            cache: this.cache,
-                            logger: this.logger
-                        });
-
-                        // 🆕 关键：将 invalidate 方法注入到 MultiLevelCache
-                        if (this.cache && typeof this.cache.setPublish === 'function') {
-                            this.cache.setPublish((msg) => {
-                                if (msg && msg.type === 'invalidate' && msg.pattern) {
-                                    this._cacheInvalidator.invalidate(msg.pattern).catch((err) => {
-                                        this.logger.error('❌ Broadcast invalidation failed:', err.message);
-                                    });
-                                }
-                            });
-                            this.logger.info('✅ Distributed cache invalidator initialized', {
-                                channel: this._cacheInvalidator.channel,
-                                integrated: true
-                            });
-                        } else {
-                            this.logger.warn('⚠️  Cache does not support setPublish, distributed invalidation disabled');
-                        }
-                    } catch (error) {
-                        this.logger.error('❌ Failed to initialize distributed cache invalidator:', error.message);
-                    }
-                }
-
-                // 初始化事务管理器和缓存锁管理器
-                if (this.type === 'mongodb' && instance.client) {
-                    // 检查是否配置了分布式事务锁
-                    const useDistributedLock = this._cacheConfig &&
-                        typeof this._cacheConfig.transaction === 'object' &&
-                        this._cacheConfig.transaction.distributedLock &&
-                        this._cacheConfig.transaction.distributedLock.redis;
-
-                    if (useDistributedLock) {
-                        // 使用分布式缓存锁管理器
-                        const DistributedCacheLockManager = require('./transaction/DistributedCacheLockManager');
-                        this._lockManager = new DistributedCacheLockManager({
-                            redis: this._cacheConfig.transaction.distributedLock.redis,
-                            lockKeyPrefix: this._cacheConfig.transaction.distributedLock.keyPrefix || 'monsqlize:cache:lock:',
-                            maxDuration: 300000,
-                            logger: this.logger
-                        });
-                        this.logger.info('✅ Distributed cache lock manager initialized');
-                    } else {
-                        // 使用本地缓存锁管理器
-                        this._lockManager = new CacheLockManager({
-                            logger: this.logger,
-                            maxDuration: 300000,  // 锁最长持续5分钟
-                            cleanupInterval: 10000  // 每10秒清理一次
-                        });
-                    }
-
-                    // 将锁管理器注入到缓存
-                    if (this.cache && typeof this.cache.setLockManager === 'function') {
-                        this.cache.setLockManager(this._lockManager);
-                    }
-
-                    // 创建事务管理器
-                    this._transactionManager = new TransactionManager(
-                        instance,  // 传入完整的 adapter 实例
-                        this.cache,
-                        this.logger,
-                        {
-                            lockManager: this._lockManager
-                        }
-                    );
-
-                    this.logger.info('✅ Transaction manager initialized', {
-                        hasClient: !!instance.client,
-                        hasLockManager: !!this._lockManager,
-                        isDistributed: useDistributedLock
-                    });
-
-                    // 🆕 v1.4.0: 挂载业务锁 API（仅在使用分布式锁时可用）
-                    if (this._lockManager && typeof this._lockManager.withLock === 'function') {
-                        this.dbInstance.withLock = (key, callback, opts) =>
-                            this._lockManager.withLock(key, callback, opts);
-                        this.dbInstance.acquireLock = (key, opts) =>
-                            this._lockManager.acquireLock(key, opts);
-                        this.dbInstance.tryAcquireLock = (key, opts) =>
-                            this._lockManager.tryAcquireLock(key, opts);
-                        this.dbInstance.getLockStats = () =>
-                            this._lockManager.getStats();
-
-                        this.logger.info('✅ Business lock API initialized', {
-                            isDistributed: useDistributedLock
-                        });
-                    } else {
-                        this.logger.warn('⚠️  Business lock API not available (Redis required)', {
-                            hasLockManager: !!this._lockManager,
-                            isDistributed: useDistributedLock
-                        });
-                    }
-                } else {
-                    this.logger.warn('⚠️  Transaction manager not initialized', {
-                        type: this.type,
-                        hasClient: !!instance.client
-                    });
-                }
-
-                return this.dbInstance;
-            })();
-
-            const result = await this._connecting;
-            this._connecting = null;
-            return result;
-        } catch (err) {
-            this._connecting = null;
-            throw err;
-        }
-    }
-
-    /**
-     * 获取底层缓存实例（用于查看统计或手动失效）
-     * @returns {Object} 缓存实例
-     */
-    getCache() {
-        return this.cache;
-    }
-
-    /**
-     * 获取当前实例的默认配置（只读视图）
-     * @returns {{maxTimeMS?:number, findLimit?:number, namespace?:object, slowQueryMs?:number}}
-     */
-    getDefaults() {
-        return { ...this.defaults };
-    }
-
-    /**
-     * 关闭底层数据库连接（释放资源）
-     */
-    async close() {
-        // 清理分布式缓存失效器
-        if (this._cacheInvalidator && typeof this._cacheInvalidator.close === 'function') {
-            await this._cacheInvalidator.close();
-            this._cacheInvalidator = null;
-        }
-
-        // 清理事务管理器
-        if (this._transactionManager && typeof this._transactionManager.destroy === 'function') {
-            await this._transactionManager.destroy();
-            this._transactionManager = null;
-        }
-
-        // 清理锁管理器
-        if (this._lockManager && typeof this._lockManager.destroy === 'function') {
-            this._lockManager.destroy();
-            this._lockManager = null;
-        }
-
-        // 关闭数据库连接
-        if (this._adapter && typeof this._adapter.close === 'function') {
-            await this._adapter.close();
-        }
-
-        // 清理状态
-        this.dbInstance = null;
-        this._adapter = null;
-        this._connecting = null;
-    }
-
-    /**
-     * 健康检查（适配器透传）
-     */
-    async health() {
-        if (this._adapter && typeof this._adapter.health === 'function') {
-            return this._adapter.health();
-        }
-        return { status: 'down', connected: false };
-    }
-
-    /**
-     * 查询慢查询日志（v1.3.1+）
-     * @param {Object} filter - 查询条件 { db, collection, operation }
-     * @param {Object} options - 查询选项 { sort, limit, skip }
-     * @returns {Promise<Array>} 慢查询日志列表
-     */
-    async getSlowQueryLogs(filter, options) {
-        if (this._adapter && typeof this._adapter.getSlowQueryLogs === 'function') {
-            return this._adapter.getSlowQueryLogs(filter, options);
-        }
-        throw new Error('Slow query log feature is not enabled or not supported');
-    }
-
-    /**
-     * 事件订阅（适配器透传）
-     * @param {'connected'|'closed'|'error'|'slow-query'} event
-     * @param {(payload:any)=>void} handler
-     */
-    on(event, handler) {
-        if (this._adapter && typeof this._adapter.on === 'function') {
-            this._adapter.on(event, handler);
-        }
-    }
-
-
-    /**
-     * 启动一个事务会话（手动管理）
-     * @param {Object} options - 事务选项
-     * @param {Object} [options.readConcern] - 读关注级别 { level: 'majority' | 'local' | 'snapshot' }
-     * @param {string} [options.readPreference] - 读偏好
-     * @param {boolean} [options.causalConsistency=true] - 因果一致性
-     * @param {number} [options.timeout=30000] - 事务超时时间（毫秒）
-     * @returns {Promise<Transaction>}
-     */
-    async startSession(options = {}) {
-        if (!this._transactionManager) {
-            throw new Error('Connection not established. Call connect() first.');
-        }
-        return this._transactionManager.startSession(options);
-    }
-
-    /**
-     * 使用事务执行操作（自动管理，推荐）
-     * @param {Function} callback - 事务回调函数，接收 Transaction 对象作为参数
-     * @param {Object} options - 事务选项（同 startSession）
-     * @param {number} [options.maxRetries=3] - 最大重试次数
-     * @param {number} [options.retryDelay=100] - 重试延迟（毫秒）
-     * @param {number} [options.retryBackoff=2] - 重试退避系数
-     * @returns {Promise<any>} 返回 callback 的返回值
-     */
-    async withTransaction(callback, options = {}) {
-        if (!this._transactionManager) {
-            throw new Error('Connection not established. Call connect() first.');
-        }
-        return this._transactionManager.withTransaction(callback, options);
-    }
-
-    /** 取消事件订阅（适配器透传） */
-    off(event, handler) {
-        if (this._adapter && typeof this._adapter.off === 'function') {
-            this._adapter.off(event, handler);
-        }
-    }
-
-    /**
-     * 导出工具函数：创建 Redis 缓存适配器
-     * @static
-     * @param {import('ioredis').Redis | import('ioredis').Cluster} client - Redis客户端
-     * @param {Object} [options] - 配置选项
-     * @returns {import('./cache').CacheLike} Redis缓存适配器
-     */
-    static createRedisCacheAdapter(client, options) {
-        return createRedisCacheAdapter(client, options);
-    }
-
-    /**
-     * 初始化 ObjectId 自动转换配置
-     * @private
-     * @param {boolean|Object} config - 用户配置
-     * @param {string} dbType - 数据库类型
-     * @returns {Object} 配置对象
-     */
-    _initAutoConvertConfig(config, dbType) {
-        // 只在 MongoDB 类型下启用
-        if (dbType !== 'mongodb') {
-            return { enabled: false };
-        }
-
-        // 默认配置
-        const defaults = {
-            enabled: true,
-            excludeFields: [],
-            customFieldPatterns: [],
-            maxDepth: 10,
-            logLevel: 'warn'
-        };
-
-        // 用户禁用
-        if (config === false) {
-            return { enabled: false };
-        }
-
-        // 用户自定义配置
-        if (typeof config === 'object' && config !== null) {
-            return {
-                enabled: config.enabled !== false,
-                excludeFields: Array.isArray(config.excludeFields)
-                    ? config.excludeFields
-                    : defaults.excludeFields,
-                customFieldPatterns: Array.isArray(config.customFieldPatterns)
-                    ? config.customFieldPatterns
-                    : defaults.customFieldPatterns,
-                maxDepth: typeof config.maxDepth === 'number'
-                    ? config.maxDepth
-                    : defaults.maxDepth,
-                logLevel: config.logLevel || defaults.logLevel
-            };
-        }
-
-        return defaults;
-    }
-};