monsqlize 1.0.0

package/lib/common/validation.js

@@ -0,0 +1,49 @@
+/**
+ * 通用校验工具
+ * - validateLimitAfterBefore: 校验 limit 合法与 after/before 互斥
+ * - assertCursorSortCompatible: 校验游标中的排序与当前排序一致（字段与方向完全一致）
+ */
+
+const { createValidationError, createCursorError } = require('../errors');
+
+/**
+ * @param {{limit?:number, after?:string, before?:string}} opts
+ * @param {{maxLimit?:number}} cfg
+ */
+function validateLimitAfterBefore(opts, { maxLimit = 500 } = {}) {
+    const { limit, after, before } = opts || {};
+    if (!Number.isInteger(limit) || limit <= 0 || limit > maxLimit) {
+        throw createValidationError([{ path:['limit'], type:'number.range', message:`1..${maxLimit}` }]);
+    }
+    if (after && before) {
+        throw createValidationError([{ path:['after'], type:'any.conflict', message:'after/before 互斥' }]);
+    }
+}
+
+/**
+ * 校验游标排序与当前排序一致
+ * @param {Record<string,1|-1>} currentSort
+ * @param {Record<string,1|-1>|undefined} cursorSort
+ */
+function assertCursorSortCompatible(currentSort, cursorSort) {
+    const k1 = Object.keys(currentSort || {});
+    const k2 = Object.keys(cursorSort || {});
+    const same = k1.length === k2.length && k1.every(k => cursorSort && cursorSort[k] === currentSort[k]);
+    if (!same) {
+        // 使用专门的 CURSOR_SORT_MISMATCH 错误码
+        const { ErrorCodes, createError } = require('../errors');
+        throw createError(
+            ErrorCodes.CURSOR_SORT_MISMATCH,
+            '游标排序不匹配：游标中的排序与当前查询的排序不一致',
+            [{
+                path: ['cursor'],
+                type: 'cursor.sort.mismatch',
+                message: 'cursor sort mismatches current sort',
+                cursorSort,
+                currentSort
+            }]
+        );
+    }
+}
+
+module.exports = { validateLimitAfterBefore, assertCursorSortCompatible };

package/lib/connect.js

@@ -0,0 +1,76 @@
+/**
+ * 数据库连接管理器
+ * 统一管理各种数据库的连接创建和实例化逻辑
+ */
+const Mongo = require('./mongodb');
+
+module.exports = class ConnectionManager {
+
+    /**
+     * 支持的数据库类型映射
+     */
+    static get SUPPORTED_DATABASES() {
+        return {
+            'mongodb': Mongo,
+        };
+    }
+
+    /**
+     * 创建数据库实例
+     * @param {string} type - 数据库类型
+     * @param {string} databaseName - 数据库名称
+     * @param {Object} cache - 缓存实例（内存缓存）
+     * @param {Object} logger - 日志记录器
+     * @param {Object} [defaults] - 统一默认配置（如 maxTimeMS、namespace）
+     * @returns {Object} 数据库实例
+     * @throws {Error} 当数据库类型不支持或未实现时抛出错误
+     */
+    static createInstance(type, databaseName, cache, logger, defaults) {
+        const SUPPORTED_DATABASES = this.SUPPORTED_DATABASES;
+        // 验证数据库类型是否支持
+        if (!(type in SUPPORTED_DATABASES)) {
+            const supportedTypes = Object.keys(SUPPORTED_DATABASES).join(', ');
+            throw new Error(`Invalid database type: ${type}. Supported types are: ${supportedTypes}`);
+        }
+
+        // 检查是否已实现
+        if (SUPPORTED_DATABASES[type] === null) {
+            throw new Error(`${type} support not implemented yet`);
+        }
+
+        // 获取对应的数据库类
+        const DatabaseClass = SUPPORTED_DATABASES[type];
+
+        // 创建并返回实例
+        return new DatabaseClass(type, databaseName, cache, logger, defaults);
+    }
+
+    /**
+     * 连接数据库
+     * @param {string} type - 数据库类型
+     * @param {string} databaseName - 数据库名称
+     * @param {Object} config - 数据库连接配置
+     * @param {Object} cache - 缓存实例
+     * @param {Object} logger - 日志记录器
+     * @param {Object} [defaults] - 统一默认配置（如 maxTimeMS、namespace）
+     * @returns {{accessor: Function, instance: Object}} 访问器与底层适配器实例
+     * @throws {Error} 连接失败时抛出错误
+     */
+    static async connect(type, databaseName, config, cache, logger, defaults) {
+        // 创建数据库实例
+        const instance = this.createInstance(type, databaseName, cache, logger, defaults);
+
+        // 建立连接
+        await instance.connect(config);
+
+        // ---------- 构建访问器 ----------
+        const collection = (collectionName) => instance.collection(databaseName, collectionName);
+        const db = (databaseName)=>{
+            return {
+                collection:(collectionName)=>instance.collection(databaseName, collectionName)
+            }
+        }
+
+        return { collection, db, instance };
+    }
+}

package/lib/constants.js

@@ -0,0 +1,54 @@
+/**
+ * 统一常量定义
+ * 集中管理所有魔法数字和配置常量
+ */
+
+module.exports = {
+    // 缓存相关
+    CACHE: {
+        DEFAULT_MAX_SIZE: 100000,           // 默认最大缓存条目数
+        DEFAULT_MAX_MEMORY: 0,              // 默认最大内存（字节），0 表示不限制
+        TOTALS_INFLIGHT_WINDOW_MS: 5000,   // totals 去重窗口（毫秒）
+        REMOTE_TIMEOUT_MS: 50,              // 远端缓存操作超时（毫秒）
+    },
+
+    // 查询相关
+    QUERY: {
+        DEFAULT_SLOW_QUERY_MS: 500,         // 慢查询阈值（毫秒）
+        DEFAULT_FIND_LIMIT: 10,             // find 默认 limit
+        DEFAULT_FINDPAGE_MAX_LIMIT: 500,    // findPage 最大 limit
+        DEFAULT_MAX_TIME_MS: 30000,         // 默认查询超时（毫秒）
+    },
+
+    // 分页相关
+    PAGINATION: {
+        DEFAULT_STEP: 10,                   // 书签密度：每隔多少页存一个书签
+        DEFAULT_MAX_HOPS: 20,               // 单次跳页最大 hops
+        DEFAULT_MAX_SKIP: 50000,            // offset 跳页最大 skip
+    },
+
+    // 流式查询相关
+    STREAM: {
+        DEFAULT_BATCH_SIZE: 1000,           // 流式查询默认批次大小
+    },
+
+    // 连接相关
+    CONNECTION: {
+        DEFAULT_POOL_SIZE: 10,              // 默认连接池大小
+        CONNECTION_TIMEOUT_MS: 30000,       // 连接超时（毫秒）
+    },
+
+    // 命名空间相关
+    NAMESPACE: {
+        DEFAULT_SCOPE: 'database',          // 默认命名空间范围
+        BOOKMARK_PREFIX: 'bm:',             // 书签键前缀
+        TOTALS_PREFIX: 'tot:',              // 总数键前缀
+    },
+
+    // 日志相关
+    LOG: {
+        MAX_QUERY_SHAPE_LENGTH: 1000,      // 查询形状最大长度（日志）
+        MAX_ERROR_MESSAGE_LENGTH: 500,     // 错误消息最大长度
+    },
+};
+

package/lib/count-queue.js

@@ -0,0 +1,187 @@
+/**
+ * Count 队列控制器
+ * 限制同时执行的 count 数量，避免高并发下压垮数据库
+ *
+ * 使用场景:
+ * - findPage 的 totals 统计
+ * - 任何需要执行 countDocuments 的场景
+ *
+ * 核心功能:
+ * 1. 并发控制 - 限制同时执行的 count 数量
+ * 2. 队列管理 - 超出并发限制的请求排队等待
+ * 3. 超时保护 - 防止请求长时间等待
+ * 4. 统计监控 - 提供队列状态和统计信息
+ */
+class CountQueue {
+    constructor(options = {}) {
+        // 默认并发数：CPU 核心数（最少 4，最多 16）
+        const cpuCount = require('os').cpus().length;
+        const defaultConcurrency = Math.max(4, Math.min(cpuCount, 16));
+
+        this.concurrency = options.concurrency || defaultConcurrency;
+        this.maxQueueSize = options.maxQueueSize || 10000;  // 队列最大长度（增加到 10000）
+        this.timeout = options.timeout || 60000;  // 超时 60 秒（增加到 1 分钟）
+
+        this.queue = [];  // 等待队列
+        this.running = 0;  // 当前执行数
+
+        // 统计信息
+        this.stats = {
+            executed: 0,      // 已执行总数
+            queued: 0,        // 曾排队总数
+            timeout: 0,       // 超时次数
+            rejected: 0,      // 拒绝次数（队列满）
+            avgWaitTime: 0,   // 平均等待时间
+            maxWaitTime: 0    // 最大等待时间
+        };
+    }
+
+    /**
+     * 执行 count 操作（带队列控制）
+     * @param {Function} fn - count 操作函数
+     * @returns {Promise<number>} count 结果
+     * @throws {Error} 队列满或超时
+     */
+    async execute(fn) {
+        const startTime = Date.now();
+
+        // 检查是否需要排队
+        if (this.running >= this.concurrency) {
+            // 检查队列是否满了
+            if (this.queue.length >= this.maxQueueSize) {
+                this.stats.rejected++;
+                throw new Error(`Count queue is full (${this.maxQueueSize})`);
+            }
+
+            this.stats.queued++;
+            // 等待轮到自己
+            await this._waitInQueue(startTime);
+        }
+
+        // 获得执行机会，增加 running
+        this.running++;
+        this.stats.executed++;
+
+        try {
+            // 带超时控制
+            return await this._executeWithTimeout(fn);
+        } finally {
+            this.running--;
+            // 唤醒队列中的下一个
+            this._wakeNext();
+        }
+    }
+
+    /**
+     * 等待队列
+     * @private
+     */
+    async _waitInQueue(startTime) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                // 超时，从队列中移除
+                const index = this.queue.findIndex(item => item.resolve === resolve);
+                if (index !== -1) {
+                    this.queue.splice(index, 1);
+                    this.stats.timeout++;
+                    reject(new Error(`Count queue wait timeout (${this.timeout}ms)`));
+                }
+            }, this.timeout);
+
+            this.queue.push({
+                resolve: () => {
+                    const waitTime = Date.now() - startTime;
+                    this._updateWaitTimeStats(waitTime);
+                    resolve();
+                },
+                timer,
+                startTime
+            });
+        });
+    }
+
+    /**
+     * 唤醒队列中的下一个
+     * @private
+     */
+    _wakeNext() {
+        if (this.queue.length > 0) {
+            const { resolve, timer } = this.queue.shift();
+            clearTimeout(timer);
+            resolve();
+        }
+    }
+
+    /**
+     * 带超时的执行
+     * @private
+     */
+    async _executeWithTimeout(fn) {
+        return Promise.race([
+            fn(),
+            new Promise((_, reject) =>
+                setTimeout(() => reject(new Error(`Count execution timeout (${this.timeout}ms)`)), this.timeout)
+            )
+        ]);
+    }
+
+    /**
+     * 更新等待时间统计
+     * @private
+     */
+    _updateWaitTimeStats(waitTime) {
+        // 计算平均等待时间
+        const totalQueued = this.stats.queued;
+        this.stats.avgWaitTime = (this.stats.avgWaitTime * (totalQueued - 1) + waitTime) / totalQueued;
+
+        // 更新最大等待时间
+        if (waitTime > this.stats.maxWaitTime) {
+            this.stats.maxWaitTime = waitTime;
+        }
+    }
+
+    /**
+     * 获取统计信息
+     * @returns {Object} 统计信息
+     */
+    getStats() {
+        return {
+            ...this.stats,
+            running: this.running,          // 当前执行中
+            queuedNow: this.queue.length,   // 当前排队中
+            concurrency: this.concurrency,  // 并发限制
+            maxQueueSize: this.maxQueueSize // 队列容量
+        };
+    }
+
+    /**
+     * 重置统计信息
+     */
+    resetStats() {
+        this.stats = {
+            executed: 0,
+            queued: 0,
+            timeout: 0,
+            rejected: 0,
+            avgWaitTime: 0,
+            maxWaitTime: 0
+        };
+    }
+
+    /**
+     * 清空队列（慎用）
+     */
+    clear() {
+        // 拒绝所有等待中的请求
+        while (this.queue.length > 0) {
+            const item = this.queue.shift();
+            clearTimeout(item.timer);
+            // 注意：这里不能直接 resolve 错误
+            // 因为队列项只存储了 resolve，没有 reject
+            // 所以清空操作只是清理队列，不触发错误
+        }
+    }
+}
+
+module.exports = CountQueue;
+

package/lib/distributed-cache-invalidator.js

@@ -0,0 +1,259 @@
+/**
+ * 分布式缓存失效器
+ * 基于 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;