monsqlize 1.3.0 → 2.0.0

package/lib/distributed-cache-invalidator.js

@@ -1,260 +0,0 @@
-/**
- * 分布式缓存失效器
- * 基于 Redis Pub/Sub 实现跨实例的缓存失效通知
- *
- * @example
- * const invalidator = new DistributedCacheInvalidator({
- *   redisUrl: 'redis://localhost:6379',
- *   channel: 'monsqlize:cache:invalidate',
- *   cache: multiLevelCacheInstance
- * });
- *
- * // 广播失效消息
- * await invalidator.invalidate('user:*');
- */
-
-class DistributedCacheInvalidator {
-    /**
-     * @param {Object} options
-     * @param {string} [options.redisUrl] - Redis 连接 URL
-     * @param {Object} [options.redis] - 已创建的 Redis 实例（与 redisUrl 二选一）
-     * @param {string} [options.channel='monsqlize:cache:invalidate'] - Pub/Sub 频道
-     * @param {string} [options.instanceId] - 实例 ID（自动生成）
-     * @param {Object} options.cache - MultiLevelCache 实例
-     * @param {Object} [options.logger] - 日志记录器
-     */
-    constructor(options = {}) {
-        if (!options.cache) {
-            throw new Error('DistributedCacheInvalidator requires a cache instance');
-        }
-
-        this.cache = options.cache;
-        this.logger = options.logger;
-        this.channel = options.channel || 'monsqlize:cache:invalidate';
-        this.instanceId = options.instanceId || `instance-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
-
-        // 初始化 Redis 连接
-        this._initRedis(options);
-
-        // 设置订阅
-        this._setupSubscription();
-
-        // 统计信息
-        this.stats = {
-            messagesSent: 0,
-            messagesReceived: 0,
-            invalidationsTriggered: 0,
-            errors: 0
-        };
-    }
-
-    /**
-     * 初始化 Redis 连接
-     * @private
-     */
-    _initRedis(options) {
-        try {
-            const Redis = require('ioredis');
-
-            if (options.redis) {
-                // 使用已有的 Redis 实例
-                this.pub = options.redis;
-                // 订阅需要单独的连接
-                const redisConfig = options.redis.options || {};
-                this.sub = new Redis({
-                    ...redisConfig,
-                    host: redisConfig.host || 'localhost',
-                    port: redisConfig.port || 6379
-                });
-                this._ownsConnections = false;
-            } else if (options.redisUrl) {
-                // 创建新的 Redis 连接
-                this.pub = new Redis(options.redisUrl);
-                this.sub = new Redis(options.redisUrl);
-                this._ownsConnections = true;
-            } else {
-                // 默认本地连接
-                this.pub = new Redis('redis://localhost:6379');
-                this.sub = new Redis('redis://localhost:6379');
-                this._ownsConnections = true;
-            }
-
-            // 错误处理
-            this.pub.on('error', (err) => {
-                this.stats.errors++;
-                if (this.logger) {
-                    this.logger.error('[DistributedCacheInvalidator] Redis pub error:', err.message);
-                }
-            });
-
-            this.sub.on('error', (err) => {
-                this.stats.errors++;
-                if (this.logger) {
-                    this.logger.error('[DistributedCacheInvalidator] Redis sub error:', err.message);
-                }
-            });
-        } catch (error) {
-            throw new Error(
-                'Failed to initialize Redis for DistributedCacheInvalidator. ' +
-                'Please ensure ioredis is installed: npm install ioredis'
-            );
-        }
-    }
-
-    /**
-     * 设置订阅处理
-     * @private
-     */
-    _setupSubscription() {
-        this.sub.subscribe(this.channel, (err) => {
-            if (err) {
-                this.stats.errors++;
-                if (this.logger) {
-                    this.logger.error('[DistributedCacheInvalidator] Subscribe error:', err.message);
-                }
-            } else {
-                if (this.logger) {
-                    this.logger.info(`[DistributedCacheInvalidator] Subscribed to channel: ${this.channel}`);
-                }
-            }
-        });
-
-        this.sub.on('message', (channel, message) => {
-            if (channel !== this.channel) return;
-
-            this.stats.messagesReceived++;
-
-            try {
-                const data = JSON.parse(message);
-
-                // 忽略自己发送的消息（避免重复失效）
-                if (data.instanceId === this.instanceId) {
-                    return;
-                }
-
-                // 处理失效消息
-                if (data.type === 'invalidate' && data.pattern) {
-                    this._handleInvalidation(data.pattern);
-                }
-            } catch (error) {
-                this.stats.errors++;
-                if (this.logger) {
-                    this.logger.error('[DistributedCacheInvalidator] Message parse error:', error.message);
-                }
-            }
-        });
-    }
-
-    /**
-     * 处理缓存失效
-     * @private
-     */
-    async _handleInvalidation(pattern) {
-        try {
-            if (this.logger) {
-                this.logger.debug(`[DistributedCacheInvalidator] Handling invalidation, pattern: ${pattern}`);
-            }
-
-            let deleted = 0;
-
-            // 1. 失效本地缓存
-            if (this.cache.local && typeof this.cache.local.delPattern === 'function') {
-                deleted = await this.cache.local.delPattern(pattern);
-                if (this.logger) {
-                    this.logger.debug(`[DistributedCacheInvalidator] Invalidated local cache: ${pattern}, deleted: ${deleted} keys`);
-                }
-            }
-
-            // 2. 失效远端缓存（Redis）
-            if (this.cache.remote && typeof this.cache.remote.delPattern === 'function') {
-                const remoteDeleted = await this.cache.remote.delPattern(pattern);
-                deleted += remoteDeleted;
-                if (this.logger) {
-                    this.logger.debug(`[DistributedCacheInvalidator] Invalidated remote cache: ${pattern}, deleted: ${remoteDeleted} keys`);
-                }
-            }
-
-            this.stats.invalidationsTriggered++;
-
-            if (this.logger) {
-                this.logger.info(`[DistributedCacheInvalidator] Total invalidated: ${pattern}, deleted: ${deleted} keys`);
-            }
-        } catch (error) {
-            this.stats.errors++;
-            if (this.logger) {
-                this.logger.error('[DistributedCacheInvalidator] Invalidation error:', error.message);
-            }
-        }
-    }
-
-    /**
-     * 广播缓存失效消息
-     * @param {string} pattern - 缓存键模式（支持通配符 *）
-     * @returns {Promise<void>}
-     */
-    async invalidate(pattern) {
-        if (!pattern) return;
-
-        const message = JSON.stringify({
-            type: 'invalidate',
-            pattern,
-            instanceId: this.instanceId,
-            timestamp: Date.now()
-        });
-
-        try {
-            await this.pub.publish(this.channel, message);
-            this.stats.messagesSent++;
-
-            if (this.logger) {
-                this.logger.debug(`[DistributedCacheInvalidator] Published invalidation: ${pattern}`);
-            }
-        } catch (error) {
-            this.stats.errors++;
-            if (this.logger) {
-                this.logger.error('[DistributedCacheInvalidator] Publish error:', error.message);
-            }
-            throw error;
-        }
-    }
-
-    /**
-     * 获取统计信息
-     * @returns {Object}
-     */
-    getStats() {
-        return {
-            ...this.stats,
-            instanceId: this.instanceId,
-            channel: this.channel
-        };
-    }
-
-    /**
-     * 关闭连接
-     * @returns {Promise<void>}
-     */
-    async close() {
-        try {
-            // 取消订阅
-            await this.sub.unsubscribe(this.channel);
-
-            // 如果是自己创建的连接，才关闭
-            if (this._ownsConnections) {
-                await this.pub.quit();
-                await this.sub.quit();
-            }
-
-            if (this.logger) {
-                this.logger.info('[DistributedCacheInvalidator] Closed');
-            }
-        } catch (error) {
-            if (this.logger) {
-                this.logger.error('[DistributedCacheInvalidator] Close error:', error.message);
-            }
-        }
-    }
-}
-
-module.exports = DistributedCacheInvalidator;
-

package/lib/errors.js

@@ -1,168 +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/expression/cache/ExpressionCache.js

@@ -1,114 +0,0 @@
-/**
- * 表达式编译缓存
- * 使用 LRU 缓存策略
- */
-
-class ExpressionCache {
-  /**
-   * @param {Object} options - 缓存配置
-   * @param {number} options.maxSize - 最大缓存数量，默认 1000
-   * @param {boolean} options.enabled - 是否启用缓存，默认 true
-   */
-  constructor(options = {}) {
-    this.maxSize = options.maxSize || 1000;
-    this.enabled = options.enabled !== false;
-    this.cache = new Map();
-    this.stats = {
-      hits: 0,
-      misses: 0,
-      evictions: 0
-    };
-  }
-
-  /**
-   * 生成缓存键
-   * @param {string} expression - 表达式字符串
-   * @param {string} targetDB - 目标数据库
-   * @returns {string} 缓存键
-   */
-  _generateKey(expression, targetDB = 'mongodb') {
-    return `${targetDB}:${expression}`;
-  }
-
-  /**
-   * 获取缓存
-   * @param {string} expression - 表达式字符串
-   * @param {string} targetDB - 目标数据库
-   * @returns {*} 缓存的编译结果，不存在则返回 null
-   */
-  get(expression, targetDB = 'mongodb') {
-    if (!this.enabled) {
-      return null;
-    }
-
-    const key = this._generateKey(expression, targetDB);
-
-    if (this.cache.has(key)) {
-      this.stats.hits++;
-      // LRU: 将访问的项移到最后
-      const value = this.cache.get(key);
-      this.cache.delete(key);
-      this.cache.set(key, value);
-      return value;
-    }
-
-    this.stats.misses++;
-    return null;
-  }
-
-  /**
-   * 设置缓存
-   * @param {string} expression - 表达式字符串
-   * @param {*} compiled - 编译结果
-   * @param {string} targetDB - 目标数据库
-   */
-  set(expression, compiled, targetDB = 'mongodb') {
-    if (!this.enabled) {
-      return;
-    }
-
-    const key = this._generateKey(expression, targetDB);
-
-    // 如果缓存已满，删除最旧的项（Map 的第一个项）
-    if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
-      const firstKey = this.cache.keys().next().value;
-      this.cache.delete(firstKey);
-      this.stats.evictions++;
-    }
-
-    this.cache.set(key, compiled);
-  }
-
-  /**
-   * 清空缓存
-   */
-  clear() {
-    this.cache.clear();
-    this.stats = {
-      hits: 0,
-      misses: 0,
-      evictions: 0
-    };
-  }
-
-  /**
-   * 获取缓存统计
-   * @returns {Object} 缓存统计
-   */
-  getStats() {
-    const total = this.stats.hits + this.stats.misses;
-    const hitRate = total > 0 ? (this.stats.hits / total * 100).toFixed(2) : '0.00';
-
-    return {
-      ...this.stats,
-      size: this.cache.size,
-      maxSize: this.maxSize,
-      hitRate: `${hitRate}%`,
-      enabled: this.enabled
-    };
-  }
-}
-
-module.exports = ExpressionCache;
-
-