monsqlize 1.3.0 → 2.0.0

package/lib/common/shape-builders.js

@@ -1,27 +0,0 @@
-/**
- * 通用慢日志形状构造器（去敏）
- * 仅保留安全元信息与标记位；真正的 query/projection/sort 形状由适配器层注入。
- */
-
-function buildCommonLogExtra(options) {
-    const pick = (obj, fields) => Object.fromEntries((fields || []).filter(k => obj && k in obj).map(k => [k, obj[k]]));
-    const meta = pick(options || {}, ['limit', 'skip', 'maxTimeMS', 'cache']);
-
-    // 聚合阶段名（仅名称，避免输出参数）
-    if (options?.pipeline && Array.isArray(options.pipeline)) {
-        try {
-            meta.pipelineStages = options.pipeline.map(p => Object.keys(p)[0]).slice(0, 30);
-        } catch (_) { /* ignore */ }
-    }
-
-    // 游标标记
-    if (options?.after || options?.before) {
-        meta.hasCursor = true;
-        meta.cursorDirection = options.after ? 'after' : 'before';
-    }
-
-    return meta;
-}
-
-module.exports = { buildCommonLogExtra };
-

package/lib/common/validation.js

@@ -1,113 +0,0 @@
-/**
- * 通用校验工具
- * - 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
-            }]
-        );
-    }
-}
-
-/**
- * 验证数值范围
- * @param {number} value - 要验证的数值
- * @param {number} min - 最小值（包含）
- * @param {number} max - 最大值（包含）
- * @param {string} name - 参数名称（用于错误消息）
- * @returns {number} 验证通过后的值
- * @throws {Error} 当值不在有效范围内时抛出 INVALID_ARGUMENT 错误
- */
-function validateRange(value, min, max, name) {
-    const { ErrorCodes, createError } = require('../errors');
-
-    // 检查是否为有效数字
-    if (typeof value !== 'number' || isNaN(value)) {
-        throw createError(
-            ErrorCodes.INVALID_ARGUMENT,
-            `${name} 必须是一个有效的数字`
-        );
-    }
-
-    // 检查是否为有限数（排除 Infinity）
-    if (!isFinite(value)) {
-        throw createError(
-            ErrorCodes.INVALID_ARGUMENT,
-            `${name} 必须是有限数字`
-        );
-    }
-
-    // 检查范围
-    if (value < min || value > max) {
-        throw createError(
-            ErrorCodes.INVALID_ARGUMENT,
-            `${name} 必须在 ${min} 到 ${max} 之间，当前值: ${value}`
-        );
-    }
-
-    return value;
-}
-
-/**
- * 验证正整数
- * @param {number} value - 要验证的数值
- * @param {string} name - 参数名称（用于错误消息）
- * @returns {number} 验证通过后的值
- * @throws {Error} 当值不是正整数时抛出错误
- */
-function validatePositiveInteger(value, name) {
-    const { ErrorCodes, createError } = require('../errors');
-
-    if (!Number.isInteger(value) || value <= 0) {
-        throw createError(
-            ErrorCodes.INVALID_ARGUMENT,
-            `${name} 必须是正整数，当前值: ${value}`
-        );
-    }
-    return value;
-}
-
-module.exports = {
-    validateLimitAfterBefore,
-    assertCursorSortCompatible,
-    validateRange,
-    validatePositiveInteger
-};
-

package/lib/connect.js

@@ -1,99 +0,0 @@
-/**
- * 数据库连接管理器
- * 统一管理各种数据库的连接创建和实例化逻辑
- */
-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）
-   * @param {Object} [poolManager] - 多连接池管理器（v1.0.8+）
-   * @returns {{accessor: Function, instance: Object}} 访问器与底层适配器实例
-   * @throws {Error} 连接失败时抛出错误
-   */
-  static async connect(
-    type,
-    databaseName,
-    config,
-    cache,
-    logger,
-    defaults,
-    poolManager,
-  ) {
-    // 创建数据库实例
-    const instance = this.createInstance(
-      type,
-      databaseName,
-      cache,
-      logger,
-      defaults,
-    );
-
-    // 🆕 v1.0.8: 传递 poolManager 给实例
-    if (poolManager) {
-      instance.poolManager = poolManager;
-    }
-
-    // 建立连接
-    await instance.connect(config);
-
-    // ---------- 构建访问器 ----------
-    const collection = (collectionName) =>
-      instance.collection(databaseName, collectionName);
-    const db = (databaseName) => {
-      return {
-        collection: (collectionName) =>
-          instance.collection(databaseName, collectionName),
-      };
-    };
-
-    return { collection, db, use: db, instance };
-  }
-};

package/lib/constants.js

@@ -1,55 +0,0 @@
-/**
- * 统一常量定义
- * 集中管理所有魔法数字和配置常量
- */
-
-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

@@ -1,188 +0,0 @@
-/**
- * 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;
-
-