monsqlize 1.3.0 → 2.0.0

package/lib/common/index-options.js

@@ -1,223 +0,0 @@
-/**
- * 索引选项验证和归一化工具
- *
- * @module common/index-options
- * @since 2025-11-17
- */
-
-const { createError } = require('../errors');
-
-/**
- * 验证索引键定义
- *
- * @param {Object} keys - 索引键定义
- * @throws {Error} 如果索引键无效
- *
- * @example
- * validateIndexKeys({ email: 1 });  // ✓
- * validateIndexKeys({ age: -1 });   // ✓
- * validateIndexKeys({ name: "text" }); // ✓
- * validateIndexKeys({ "$**": 1 });  // ✓ 通配符索引
- * validateIndexKeys({});            // ✗ 抛出错误
- * validateIndexKeys({ email: 2 }); // ✗ 抛出错误
- */
-function validateIndexKeys(keys) {
-    if (!keys || typeof keys !== 'object') {
-        throw createError(
-            'INVALID_ARGUMENT',
-            '索引键必须是对象',
-            { keys }
-        );
-    }
-
-    const keyNames = Object.keys(keys);
-
-    if (keyNames.length === 0) {
-        throw createError(
-            'INVALID_ARGUMENT',
-            '索引键不能为空',
-            { keys }
-        );
-    }
-
-    // 验证每个键的值
-    for (const key of keyNames) {
-        const value = keys[key];
-
-        // 允许的值：1（升序）、-1（降序）、"text"（文本索引）、"2d"（地理索引）、"2dsphere"、"hashed"、"columnstore"
-        const validValues = [1, -1, '1', '-1', 'text', '2d', '2dsphere', 'geoHaystack', 'hashed', 'columnstore'];
-
-        if (!validValues.includes(value)) {
-            throw createError(
-                'INVALID_ARGUMENT',
-                `索引键 "${key}" 的值无效，允许的值: 1, -1, "text", "2d", "2dsphere", "hashed", "columnstore"`,
-                { key, value, validValues }
-            );
-        }
-    }
-
-    return true;
-}
-
-/**
- * 归一化索引选项
- * 验证并转换为 MongoDB 驱动接受的格式
- *
- * @param {Object} options - 用户提供的索引选项
- * @returns {Object} 归一化后的选项
- *
- * @example
- * normalizeIndexOptions({ unique: true, name: "email_idx" });
- * // 返回: { unique: true, name: "email_idx" }
- */
-function normalizeIndexOptions(options = {}) {
-    const normalized = {};
-
-    // 允许的选项列表
-    const allowedOptions = [
-        // 通用选项
-        'name',                      // 索引名称
-        'unique',                    // 唯一索引
-        'sparse',                    // 稀疏索引
-        'background',                // 后台创建（已废弃但保留兼容）
-
-        // TTL 索引
-        'expireAfterSeconds',        // 文档过期时间
-
-        // 部分索引
-        'partialFilterExpression',   // 部分索引表达式
-
-        // 排序规则
-        'collation',                 // 排序规则
-
-        // 高级选项
-        'hidden',                    // 隐藏索引（MongoDB 4.4+）
-        'wildcardProjection',        // 通配符投影
-
-        // 存储引擎
-        'storageEngine',             // 存储引擎配置
-
-        // 文本索引
-        'weights',                   // 文本权重
-        'default_language',          // 默认语言
-        'language_override',         // 语言覆盖字段
-        'textIndexVersion',          // 文本索引版本
-
-        // 2dsphere 索引
-        '2dsphereIndexVersion',      // 2dsphere 索引版本
-
-        // 其他
-        'bits',                      // 2d 索引精度
-        'min',                       // 2d 索引最小值
-        'max',                       // 2d 索引最大值
-        'bucketSize'                 // geoHaystack 索引桶大小
-    ];
-
-    // 复制允许的选项
-    for (const option of allowedOptions) {
-        if (options.hasOwnProperty(option)) {
-            normalized[option] = options[option];
-        }
-    }
-
-    // 特殊处理：background 已废弃，但保留兼容性
-    if (normalized.background !== undefined) {
-        // MongoDB 4.2+ 会忽略 background 选项，但不会报错
-        // 可以添加警告日志（如果有 logger）
-    }
-
-    // 验证特定选项
-    if (normalized.unique !== undefined && typeof normalized.unique !== 'boolean') {
-        throw createError(
-            'INVALID_ARGUMENT',
-            'unique 选项必须是布尔值',
-            { unique: normalized.unique }
-        );
-    }
-
-    if (normalized.sparse !== undefined && typeof normalized.sparse !== 'boolean') {
-        throw createError(
-            'INVALID_ARGUMENT',
-            'sparse 选项必须是布尔值',
-            { sparse: normalized.sparse }
-        );
-    }
-
-    if (normalized.hidden !== undefined && typeof normalized.hidden !== 'boolean') {
-        throw createError(
-            'INVALID_ARGUMENT',
-            'hidden 选项必须是布尔值',
-            { hidden: normalized.hidden }
-        );
-    }
-
-    if (normalized.expireAfterSeconds !== undefined) {
-        const ttl = normalized.expireAfterSeconds;
-        if (typeof ttl !== 'number' || ttl < 0 || !Number.isInteger(ttl)) {
-            throw createError(
-                'INVALID_ARGUMENT',
-                'expireAfterSeconds 必须是非负整数',
-                { expireAfterSeconds: ttl }
-            );
-        }
-    }
-
-    if (normalized.name !== undefined && typeof normalized.name !== 'string') {
-        throw createError(
-            'INVALID_ARGUMENT',
-            'name 选项必须是字符串',
-            { name: normalized.name }
-        );
-    }
-
-    if (normalized.partialFilterExpression !== undefined) {
-        if (typeof normalized.partialFilterExpression !== 'object' || normalized.partialFilterExpression === null) {
-            throw createError(
-                'INVALID_ARGUMENT',
-                'partialFilterExpression 必须是对象',
-                { partialFilterExpression: normalized.partialFilterExpression }
-            );
-        }
-    }
-
-    if (normalized.collation !== undefined) {
-        if (typeof normalized.collation !== 'object' || normalized.collation === null) {
-            throw createError(
-                'INVALID_ARGUMENT',
-                'collation 必须是对象',
-                { collation: normalized.collation }
-            );
-        }
-    }
-
-    return normalized;
-}
-
-/**
- * 生成索引名称（当用户未指定时）
- *
- * @param {Object} keys - 索引键定义
- * @returns {string} 生成的索引名称
- *
- * @example
- * generateIndexName({ email: 1 });  // "email_1"
- * generateIndexName({ userId: 1, status: -1 });  // "userId_1_status_-1"
- * generateIndexName({ name: "text" });  // "name_text"
- */
-function generateIndexName(keys) {
-    const parts = [];
-
-    for (const [field, direction] of Object.entries(keys)) {
-        parts.push(`${field}_${direction}`);
-    }
-
-    return parts.join('_');
-}
-
-module.exports = {
-    validateIndexKeys,
-    normalizeIndexOptions,
-    generateIndexName
-};
-
-

package/lib/common/log.js

@@ -1,61 +0,0 @@
-/**
- * 通用慢查询日志工具
- * - getSlowQueryThreshold: 读取阈值（默认 500ms）
- * - withSlowQueryLog: 统一包装执行并在超阈值时输出去敏慢日志
- */
-
-function getSlowQueryThreshold(defaults){
-    const d = defaults || {};
-    return (d.slowQueryMs && Number(d.slowQueryMs)) || 500;
-}
-
-/**
- *
- * @param {import('../..').LoggerLike} logger
- * @param {object} defaults
- * @param {string} op
- * @param {{iid?:string,type?:string,db:string,coll:string}} ns
- * @param {object} options
- * @param {() => Promise<any>} exec
- * @param {(options:any)=>object} [slowLogShaper]
- * @returns {Promise<any>}
- */
-async function withSlowQueryLog(logger, defaults, op, ns, options, exec, slowLogShaper, onEmit){
-    const t0 = Date.now();
-    const res = await exec();
-    const ms = Date.now() - t0;
-    const threshold = getSlowQueryThreshold(defaults);
-    if (ms > threshold) {
-        const scope = defaults?.namespace?.scope;
-        const iid = ns?.iid;
-        const base = {
-            event: (defaults?.log?.slowQueryTag?.event) || 'slow_query',
-            code:  (defaults?.log?.slowQueryTag?.code)  || 'SLOW_QUERY',
-            category: 'performance',
-            type: ns?.type || 'mongodb',
-            iid,
-            scope,
-            db: ns.db,
-            coll: ns.coll,
-            op,
-            ms,
-            threshold,
-            ts: new Date().toISOString(),
-            ...(typeof slowLogShaper === 'function' ? slowLogShaper(options) : {})
-        };
-        try {
-            if (typeof defaults?.log?.formatSlowQuery === 'function') {
-                const formatted = defaults.log.formatSlowQuery(base) || base;
-                logger.warn('\u23f1\ufe0f Slow query', formatted);
-                if (typeof onEmit === 'function') { try { onEmit(formatted); } catch(_) {} }
-            } else {
-                logger.warn('\u23f1\ufe0f Slow query', base);
-                if (typeof onEmit === 'function') { try { onEmit(base); } catch(_) {} }
-            }
-        } catch (_) { /* ignore logging errors */ }
-    }
-    return res;
-}
-
-module.exports = { getSlowQueryThreshold, withSlowQueryLog };
-

package/lib/common/namespace.js

@@ -1,22 +0,0 @@
-/**
- * 命名空间实例 id（iid）解析流程（通用）
- * 适配器需提供 genInstanceId(databaseName, uri, explicitId?) 实现。
- */
-
-/**
- * @param {{ genInstanceId: (db:string, uri?:string, explicitId?:string)=>string }} adapter
- * @param {object} defaults
- * @param {string} currentDb
- * @param {string} initialDb
- * @param {string} uri
- */
-function resolveInstanceId(adapter, defaults, currentDb, initialDb, uri) {
-    const explicit = defaults?.namespace?.instanceId;
-    if (explicit) return String(explicit);
-    const scope = defaults?.namespace?.scope; // 'database'|'connection'
-    const dbName = scope === 'connection' ? initialDb : (currentDb || initialDb);
-    return adapter.genInstanceId(dbName, uri);
-}
-
-module.exports = { resolveInstanceId };
-

package/lib/common/normalize.js

@@ -1,34 +0,0 @@
-/**
- * 通用规范化工具
- * - normalizeProjection: 将数组形式的投影转换为对象形式；对象原样返回；其他为 undefined。
- * - normalizeSort: 仅当为对象时返回；否则 undefined。
- */
-
-/**
- * 规范化投影参数
- * @param {string[]|Record<string, any>|undefined} p
- * @returns {Record<string, 1>|undefined}
- */
-function normalizeProjection(p) {
-    if (!p) return undefined;
-    if (Array.isArray(p)) {
-        const obj = {};
-        for (const k of p) {
-            if (typeof k === 'string') obj[k] = 1;
-        }
-        return Object.keys(obj).length ? obj : undefined;
-    }
-    return (p && typeof p === 'object') ? p : undefined;
-}
-
-/**
- * 规范化排序参数
- * @param {Record<string, 1|-1>|undefined} s
- * @returns {Record<string, 1|-1>|undefined}
- */
-function normalizeSort(s) {
-    return (s && typeof s === 'object') ? s : undefined;
-}
-
-module.exports = { normalizeProjection, normalizeSort };
-

package/lib/common/page-result.js

@@ -1,43 +0,0 @@
-/**
- * 通用分页结果计算
- * - 采用 limit+1 探测是否有更多，然后裁剪为 `items` 与 `pageInfo`。
- * - 游标生成委托给适配器提供的 `pickAnchor`（用于从行/文档提取锚点字段值）。
- */
-
-const { encodeCursor } = require('./cursor');
-
-/**
- * 生成分页结果
- * @param {any[]} rows - 后端返回的数组（长度可能为 limit 或 limit+1）
- * @param {object} ctx
- * @param {number} ctx.limit
- * @param {Record<string,1|-1>} ctx.stableSort
- * @param {'after'|'before'|null} ctx.direction
- * @param {boolean} ctx.hasCursor
- * @param {(doc:any, sort:Record<string,1|-1>)=>Record<string,any>} ctx.pickAnchor
- * @returns {{ items:any[], pageInfo:{ hasNext:boolean, hasPrev:boolean, startCursor:string|null, endCursor:string|null } }}
- */
-function makePageResult(rows, { limit, stableSort, direction, hasCursor, pickAnchor }) {
-    const hasMore = rows.length > limit;
-    const items = hasMore ? rows.slice(0, limit) : rows;
-
-    const first = items[0] || null;
-    const last = items[items.length - 1] || null;
-
-    // 修复：游标不应该包含方向信息，方向由使用游标的参数（after/before）决定
-    // 游标只是一个位置标记，不包含使用方向
-    const makeCur = (doc) => encodeCursor({ v: 1, s: stableSort, a: pickAnchor(doc, stableSort) });
-
-    return {
-        items,
-        pageInfo: {
-            hasNext: direction === 'before' ? Boolean(hasCursor) : hasMore,
-            hasPrev: direction === 'before' ? hasMore : Boolean(hasCursor),
-            startCursor: first ? makeCur(first) : null,
-            endCursor: last ? makeCur(last) : null,
-        }
-    };
-}
-
-module.exports = { makePageResult };
-

package/lib/common/runner.js

@@ -1,57 +0,0 @@
-const CacheFactory = require('../cache');
-const { withSlowQueryLog } = require('./log');
-
-/**
- * 统一执行器：包装缓存与慢日志，并可选返回 meta（耗时等）与发出 query 事件
- * @param {import('../..').CacheLike|any} cache
- * @param {{iid:string, type:string, db:string, collection:string}} nsAll
- * @param {import('../..').LoggerLike} logger
- * @param {object} defaults
- * @param {{ keyBuilder?: (op:string, options:any)=>any, slowLogShaper?: (options:any)=>object, onSlowQueryEmit?: (meta:any)=>void, onQueryEmit?: (meta:any)=>void }} hooks
- */
-function createCachedRunner(cache, nsAll, logger, defaults, hooks = {}) {
-    const cached = CacheFactory.createCachedReader(cache, nsAll);
-    return async (op, options = {}, exec) => {
-        const optsForKey = typeof hooks.keyBuilder === 'function' ? hooks.keyBuilder(op, options || {}) : (options || {});
-        const runExec = () => cached(op, optsForKey, exec);
-        const ns = { db: nsAll.db, coll: nsAll.collection, iid: nsAll.iid, type: nsAll.type };
-        const t0 = Date.now();
-        let res;
-        let err;
-        try {
-            res = await withSlowQueryLog(logger, defaults, op, ns, options, runExec, hooks.slowLogShaper, hooks.onSlowQueryEmit);
-        } catch (e) {
-            err = e;
-            throw e;
-        } finally {
-            const endTs = Date.now();
-            const durationMs = endTs - t0;
-            const wantMeta = !!options.meta;
-            const meta = {
-                op,
-                ns,
-                startTs: endTs - durationMs,
-                endTs,
-                durationMs,
-                maxTimeMS: options && options.maxTimeMS,
-            };
-            if (err) meta.error = { code: err.code, message: String(err && (err.message || err)) };
-            // emit query event if enabled
-            if (defaults && defaults.metrics && defaults.metrics.emitQueryEvent && typeof hooks.onQueryEmit === 'function') {
-                try { hooks.onQueryEmit(meta); } catch (_) {}
-            }
-            if (wantMeta) {
-                // 按方法统一返回：findPage 在对象上挂 meta，其它读 API 返回 { data, meta }
-                if (op === 'findPage' && res && typeof res === 'object') {
-                    res.meta = meta;
-                } else {
-                    res = { data: res, meta };
-                }
-            }
-        }
-        return res;
-    };
-}
-
-module.exports = { createCachedRunner };
-

package/lib/common/server-features.js

@@ -1,232 +0,0 @@
-/**
- * MongoDB Server 特性探测模块
- * 检测 MongoDB Server 版本和支持的特性
- *
- * 使用方式:
- * ```javascript
- * const ServerFeatures = require('./lib/common/server-features');
- *
- * // 方式 1: 传入 monSQLize 实例
- * const msq = new MonSQLize({ ... });
- * await msq.connect();
- * const features = new ServerFeatures(msq);
- * const report = await features.generateFeatureReport();
- *
- * // 方式 2: 传入原生 MongoDB client
- * const { MongoClient } = require('mongodb');
- * const client = await MongoClient.connect(uri);
- * const features = new ServerFeatures(client);
- * ```
- *
- * @module lib/common/server-features
- */
-
-/**
- * Server 特性探测类
- */
-class ServerFeatures {
-  constructor(clientOrInstance) {
-    // 智能识别输入类型
-    if (clientOrInstance._adapter && clientOrInstance._adapter.client) {
-      // monSQLize 实例（有 _adapter 属性）
-      this.client = clientOrInstance._adapter.client;
-    } else if (clientOrInstance.client && typeof clientOrInstance.client.db === 'function') {
-      // adapter 实例（有 client 属性）
-      this.client = clientOrInstance.client;
-    } else if (typeof clientOrInstance.db === 'function') {
-      // 原生 MongoDB client
-      this.client = clientOrInstance;
-    } else {
-      // 无法识别的类型
-      throw new Error('ServerFeatures: Invalid client type. Expected MongoClient, adapter, or monSQLize instance.');
-    }
-
-    this.serverVersion = null;
-    this.serverInfo = null;
-  }
-
-  /**
-   * 获取 MongoDB Server 版本信息
-   * @returns {Promise<Object>} 版本信息
-   */
-  async getServerInfo() {
-    if (this.serverInfo) {
-      return this.serverInfo;
-    }
-
-    try {
-      const admin = this.client.db().admin();
-      const buildInfo = await admin.buildInfo();
-
-      this.serverInfo = {
-        version: buildInfo.version,
-        versionArray: buildInfo.versionArray,
-        gitVersion: buildInfo.gitVersion,
-        bits: buildInfo.bits,
-        maxBsonObjectSize: buildInfo.maxBsonObjectSize,
-      };
-
-      this.serverVersion = this.serverInfo.versionArray;
-
-      return this.serverInfo;
-    } catch (error) {
-      console.error('获取 Server 信息失败:', error);
-      return null;
-    }
-  }
-
-  /**
-   * 获取主版本号
-   * @returns {Promise<number>} 主版本号
-   */
-  async getMajorVersion() {
-    if (!this.serverVersion) {
-      await this.getServerInfo();
-    }
-    return this.serverVersion ? this.serverVersion[0] : 0;
-  }
-
-  /**
-   * 获取次版本号
-   * @returns {Promise<number>} 次版本号
-   */
-  async getMinorVersion() {
-    if (!this.serverVersion) {
-      await this.getServerInfo();
-    }
-    return this.serverVersion ? this.serverVersion[1] : 0;
-  }
-
-  /**
-   * 检查是否支持事务
-   * @returns {Promise<boolean>}
-   */
-  async supportsTransactions() {
-    const major = await this.getMajorVersion();
-    // MongoDB 4.0+ 支持事务（副本集）
-    return major >= 4;
-  }
-
-  /**
-   * 检查是否支持多文档事务
-   * @returns {Promise<boolean>}
-   */
-  async supportsMultiDocumentTransactions() {
-    const major = await this.getMajorVersion();
-    // MongoDB 4.0+ 副本集支持，4.2+ 分片集群支持
-    return major >= 4;
-  }
-
-  /**
-   * 检查是否支持通配符索引
-   * @returns {Promise<boolean>}
-   */
-  async supportsWildcardIndexes() {
-    const major = await this.getMajorVersion();
-    const minor = await this.getMinorVersion();
-    // MongoDB 4.2+ 支持通配符索引
-    return major > 4 || (major === 4 && minor >= 2);
-  }
-
-  /**
-   * 检查是否支持 $function 操作符
-   * @returns {Promise<boolean>}
-   */
-  async supportsFunctionOperator() {
-    const major = await this.getMajorVersion();
-    const minor = await this.getMinorVersion();
-    // MongoDB 4.4+ 支持 $function
-    return major > 4 || (major === 4 && minor >= 4);
-  }
-
-  /**
-   * 检查是否支持 $setWindowFields 操作符
-   * @returns {Promise<boolean>}
-   */
-  async supportsSetWindowFields() {
-    const major = await this.getMajorVersion();
-    // MongoDB 5.0+ 支持 $setWindowFields
-    return major >= 5;
-  }
-
-  /**
-   * 检查是否支持时间序列集合
-   * @returns {Promise<boolean>}
-   */
-  async supportsTimeSeriesCollections() {
-    const major = await this.getMajorVersion();
-    // MongoDB 5.0+ 支持时间序列集合
-    return major >= 5;
-  }
-
-  /**
-   * 检查是否支持加密字段
-   * @returns {Promise<boolean>}
-   */
-  async supportsEncryptedFields() {
-    const major = await this.getMajorVersion();
-    // MongoDB 6.0+ 支持 Queryable Encryption
-    return major >= 6;
-  }
-
-  /**
-   * 检查是否支持聚合表达式
-   * @param {string} expression - 表达式名称（如 '$dateAdd'）
-   * @returns {Promise<boolean>}
-   */
-  async supportsAggregationExpression(expression) {
-    const major = await this.getMajorVersion();
-    const minor = await this.getMinorVersion();
-
-    // 常见聚合表达式的版本要求
-    const expressionVersions = {
-      '$function': { major: 4, minor: 4 },
-      '$setWindowFields': { major: 5, minor: 0 },
-      '$dateAdd': { major: 5, minor: 0 },
-      '$dateDiff': { major: 5, minor: 0 },
-      '$dateSubtract': { major: 5, minor: 0 },
-      '$dateTrunc': { major: 5, minor: 0 },
-      '$getField': { major: 5, minor: 0 },
-      '$setField': { major: 5, minor: 0 },
-    };
-
-    const required = expressionVersions[expression];
-    if (!required) {
-      // 未知表达式，假设支持
-      return true;
-    }
-
-    return major > required.major ||
-           (major === required.major && minor >= required.minor);
-  }
-
-  /**
-   * 生成特性支持报告
-   * @returns {Promise<Object>} 特性报告
-   */
-  async generateFeatureReport() {
-    const info = await this.getServerInfo();
-
-    return {
-      serverVersion: info ? info.version : 'Unknown',
-      features: {
-        transactions: await this.supportsTransactions(),
-        multiDocumentTransactions: await this.supportsMultiDocumentTransactions(),
-        wildcardIndexes: await this.supportsWildcardIndexes(),
-        functionOperator: await this.supportsFunctionOperator(),
-        setWindowFields: await this.supportsSetWindowFields(),
-        timeSeriesCollections: await this.supportsTimeSeriesCollections(),
-        encryptedFields: await this.supportsEncryptedFields(),
-      },
-      aggregationExpressions: {
-        '$function': await this.supportsAggregationExpression('$function'),
-        '$setWindowFields': await this.supportsAggregationExpression('$setWindowFields'),
-        '$dateAdd': await this.supportsAggregationExpression('$dateAdd'),
-      },
-    };
-  }
-}
-
-module.exports = ServerFeatures;
-
-