monsqlize 1.0.0

package/lib/common/index-options.js

@@ -0,0 +1,222 @@
+/**
+ * 索引选项验证和归一化工具
+ *
+ * @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

@@ -0,0 +1,60 @@
+/**
+ * 通用慢查询日志工具
+ * - 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

@@ -0,0 +1,21 @@
+/**
+ * 命名空间实例 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

@@ -0,0 +1,33 @@
+/**
+ * 通用规范化工具
+ * - 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

@@ -0,0 +1,42 @@
+/**
+ * 通用分页结果计算
+ * - 采用 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

@@ -0,0 +1,56 @@
+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

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

package/lib/common/shape-builders.js

@@ -0,0 +1,26 @@
+/**
+ * 通用慢日志形状构造器（去敏）
+ * 仅保留安全元信息与标记位；真正的 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 };