monsqlize 1.3.0 → 2.0.0

package/lib/mongodb/writes/upsert-one.js

@@ -1,203 +0,0 @@
-/**
- * upsertOne 写操作模块
- * @description 便利方法：存在则更新，不存在则插入
- */
-
-const { createError, ErrorCodes } = require('../../errors');
-const { isInTransaction, getTransactionFromSession } = require('../common/transaction-aware');
-const { convertObjectIdStrings } = require('../../utils/objectid-converter');
-
-/**
- * 创建 upsertOne 操作
- * @param {Object} context - 上下文对象
- * @returns {Function} upsertOne 方法
- */
-function createUpsertOneOps(context) {
-    const {
-        collection,
-        defaults,
-        instanceId,
-        effectiveDbName,
-        logger,
-        emit,
-        mongoSlowLogShaper,
-        cache,
-        type
-    } = context;
-
-    /**
-     * upsert 单个文档（存在则更新，不存在则插入）
-     * @param {Object} filter - 查询条件
-     * @param {Object} update - 更新内容（直接设置字段，自动包装为 $set）
-     * @param {Object} [options={}] - 操作选项
-     * @param {number} [options.maxTimeMS] - 操作超时（毫秒）
-     * @param {string} [options.comment] - 查询注释
-     * @returns {Promise<Object>} 操作结果
-     *
-     * @example
-     * // 基础用法
-     * const result = await collection('users').upsertOne(
-     *   { userId: 'user123' },
-     *   { name: 'Alice', email: 'alice@example.com' }
-     * );
-     *
-     * @example
-     * // 带选项
-     * const result = await collection('config').upsertOne(
-     *   { key: 'theme' },
-     *   { value: 'dark', updatedAt: new Date() },
-     *   { maxTimeMS: 5000, comment: 'sync-config' }
-     * );
-     */
-    const upsertOne = async function upsertOne(filter, update, options = {}) {
-        const startTime = Date.now();
-
-        // 1. 参数验证
-        if (!filter || typeof filter !== 'object' || Array.isArray(filter)) {
-            throw createError(
-                ErrorCodes.INVALID_ARGUMENT,
-                'filter 必须是非空对象',
-                [{ field: 'filter', type: 'type', message: 'filter 必须是对象', received: typeof filter }]
-            );
-        }
-
-        if (!update || typeof update !== 'object' || Array.isArray(update)) {
-            throw createError(
-                ErrorCodes.INVALID_ARGUMENT,
-                'update 必须是非空对象',
-                [{ field: 'update', type: 'type', message: 'update 必须是对象', received: typeof update }]
-            );
-        }
-
-        // ✅ v1.3.0: 自动转换 ObjectId 字符串
-        const convertedFilter = convertObjectIdStrings(filter, 'filter', 0, new WeakSet(), {
-            logger: context.logger,
-            excludeFields: context.autoConvertConfig?.excludeFields,
-            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
-            maxDepth: context.autoConvertConfig?.maxDepth
-        });
-
-        const convertedUpdate = convertObjectIdStrings(update, 'document', 0, new WeakSet(), {
-            logger: context.logger,
-            excludeFields: context.autoConvertConfig?.excludeFields,
-            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
-            maxDepth: context.autoConvertConfig?.maxDepth
-        });
-
-        // 2. 检查 update 是否包含更新操作符
-        const hasOperator = Object.keys(convertedUpdate).some(key => key.startsWith('$'));
-
-        // 如果没有操作符，自动包装为 $set
-        const updateDoc = hasOperator ? convertedUpdate : { $set: convertedUpdate };
-
-        // 3. 构建选项
-        const maxTimeMS = options.maxTimeMS !== undefined ? options.maxTimeMS : defaults.maxTimeMS;
-        const comment = options.comment;
-
-        const driverOpts = { upsert: true, maxTimeMS };
-        if (comment) driverOpts.comment = comment;
-
-        // 4. 执行 updateOne 操作
-        let result;
-        try {
-            result = await collection.updateOne(convertedFilter, updateDoc, driverOpts);
-        } catch (error) {
-            // 统一错误处理
-            if (error.code === 11000) {
-                throw createError(
-                    ErrorCodes.DUPLICATE_KEY,
-                    '批量插入失败：违反唯一性约束',
-                    [{ field: '_id', type: 'unique', message: error.message }],
-                    error
-                );
-            }
-            throw error;
-        }
-
-        // 5. 自动失效缓存
-        const upsertedCount = result.matchedCount === 0 ? 1 : 0;
-
-        if (cache && (result.modifiedCount > 0 || upsertedCount > 0)) {
-            try {
-                // 🆕 v1.1.6: 解析精准失效配置
-                const instanceAuto = context.cacheAutoInvalidate || false;
-                const queryAuto = options.autoInvalidate;
-                const shouldAuto = queryAuto !== undefined ? queryAuto : instanceAuto;
-
-                if (shouldAuto) {
-                    // 精准失效：upsertOne 使用 filter 来匹配缓存
-                    const CacheInvalidationEngine = require('../../cache-invalidation');
-
-                    const deleted = await CacheInvalidationEngine.invalidatePrecise(cache, {
-                        instanceId,
-                        type,
-                        db: effectiveDbName,
-                        collection: collection.collectionName,
-                        document: convertedFilter,  // 使用 filter 来匹配
-                        operation: 'upsertOne'
-                    });
-
-                    if (deleted > 0) {
-                        logger?.debug?.(`[upsertOne] 精准失效缓存: ${collection.collectionName}, 删除 ${deleted} 个缓存键`);
-                    }
-                } else {
-                    logger?.debug?.(`[upsertOne] 跳过自动失效（autoInvalidate=false）`);
-                }
-            } catch (cacheError) {
-                logger?.warn?.('[upsertOne] 缓存失效失败', { error: cacheError.message });
-            }
-        }
-
-        // 6. 慢查询日志
-        const duration = Date.now() - startTime;
-        const slowQueryMs = defaults?.slowQueryMs || 1000;
-
-        if (duration >= slowQueryMs) {
-            try {
-                const meta = {
-                    operation: 'upsertOne',
-                    durationMs: duration,
-                    iid: instanceId,
-                    type,
-                    db: effectiveDbName,
-                    collection: collection.collectionName,
-                    matchedCount: result.matchedCount,
-                    modifiedCount: result.modifiedCount,
-                    upsertedId: result.upsertedId,
-                    filter: mongoSlowLogShaper?.sanitize ? mongoSlowLogShaper.sanitize(filter) : filter,
-                    update: mongoSlowLogShaper?.sanitize ? mongoSlowLogShaper.sanitize(updateDoc) : updateDoc,
-                    comment
-                };
-                logger?.warn?.('🐌 Slow query: upsertOne', meta);
-                emit?.('slow-query', meta);
-            } catch (_) {
-                // 忽略日志错误
-            }
-        }
-
-        // 7. 日志记录
-        logger?.debug?.('[upsertOne] 操作完成', {
-            ns: `${effectiveDbName}.${collection.collectionName}`,
-            duration,
-            matchedCount: result.matchedCount,
-            modifiedCount: result.modifiedCount,
-            upsertedId: result.upsertedId === null ? undefined : result.upsertedId,
-            upsertedCount
-        });
-
-        // 8. 返回结果
-        return {
-            acknowledged: result.acknowledged,
-            matchedCount: result.matchedCount,
-            modifiedCount: result.modifiedCount,
-            upsertedId: result.upsertedId === null ? undefined : result.upsertedId,
-            upsertedCount
-        };
-    };
-
-    return { upsertOne };
-}
-
-module.exports = { createUpsertOneOps };
-
-

package/lib/multi-level-cache.js

@@ -1,244 +0,0 @@
-/**
- * MultiLevelCache: 组合本地与远端缓存，实现 CacheLike 接口
- * 设计要点：
- * - 读：本地优先；本地未命中查远端，命中则异步回填本地；远端失败需优雅降级
- * - 写：默认本地+远端双写；可配置本地优先、远端异步
- * - 删：本地删除；远端删除尽力而为；delPattern 默认仅本地执行并返回删除数（重型场景交由远端广播/索引）
- * - keys/clear：仅作用于本地层（避免误伤远端）
- * - TTL 单位毫秒，与上层保持一致
- */
-
-class MultiLevelCache {
-  /**
-   * @param {Object} options
-   * @param {Object} options.local - 本地 CacheLike
-   * @param {Object} options.remote - 远端 CacheLike（可选）
-   * @param {Object} [options.policy]
-   * @param {'both'|'local-first-async-remote'} [options.policy.writePolicy='both']
-   * @param {boolean} [options.policy.backfillLocalOnRemoteHit=true]
-   * @param {number} [options.policy.backfillLocalTTL=0] - 回填 L1 时使用的兜底 TTL（毫秒）；
-   *   当 remote 支持 getWithTTL 时优先使用 L2 剩余 TTL，否则降级到此值；
-   *   0 = 不设 TTL（永不过期，向后兼容）。建议生产环境配置合理值（如 60000）
-   * @param {number} [options.remoteTimeoutMs=50] - 远端单次操作超时
-   * @param {(msg:object)=>void} [options.publish] - 可选：失效广播发布器
-   * @since 1.1.9 backfillLocalTTL 支持
-   */
-  constructor(options = {}) {
-    const { local, remote, policy = {}, remoteTimeoutMs = 50, publish } = options;
-    if (!local || typeof local.get !== 'function') {
-      throw new Error('MultiLevelCache requires a valid local cache');
-    }
-    this.local = local;
-    this.remote = remote;
-    this.policy = {
-      writePolicy: policy.writePolicy || 'both',
-      backfillLocalOnRemoteHit: policy.backfillLocalOnRemoteHit !== false,
-      // 🔧 v1.1.9 修复：新增回填 TTL 兜底配置，0 = 不设 TTL（向后兼容）
-      backfillLocalTTL: typeof policy.backfillLocalTTL === 'number' ? policy.backfillLocalTTL : 0,
-    };
-    this.remoteTimeoutMs = Number(remoteTimeoutMs) || 50;
-    this.publish = typeof publish === 'function' ? publish : null;
-  }
-
-  /**
-   * 动态设置 publish 回调（用于分布式缓存失效）
-   * @param {Function} publishFn - 发布函数，接收 { type, pattern, ts } 对象
-   */
-  setPublish(publishFn) {
-    if (typeof publishFn === 'function') {
-      this.publish = publishFn;
-    }
-  }
-
-  /**
-   * 设置锁管理器（透传到本地缓存）
-   * @param {Object} lockManager
-   */
-  setLockManager(lockManager) {
-    if (this.local && typeof this.local.setLockManager === 'function') {
-      this.local.setLockManager(lockManager);
-    }
-  }
-
-  // 工具：为远端操作加超时与降级
-  async _withTimeout(promise) {
-    if (!this.remote) return Promise.reject(new Error('NO_REMOTE'));
-    let timer;
-    const t = new Promise((_, reject) => {
-      timer = setTimeout(() => reject(new Error('REMOTE_TIMEOUT')), this.remoteTimeoutMs);
-      if (timer && typeof timer.unref === 'function') try { timer.unref(); } catch(_) {}
-    });
-    try {
-      const val = await Promise.race([promise, t]);
-      return val;
-    } finally {
-      clearTimeout(timer);
-    }
-  }
-
-  async get(key) {
-    const v = await this.local.get(key);
-    if (v !== undefined) return v;
-    try {
-      let r;
-      // 🔧 v1.1.9 修复：backfillTTL 优先取 L2 剩余 TTL（方案A），降级到 backfillLocalTTL（方案B）
-      let backfillTTL = this.policy.backfillLocalTTL;
-
-      if (this.remote && typeof this.remote.getWithTTL === 'function') {
-        // 方案A：remote 支持 getWithTTL，单次 RTT 同时获取值与剩余 TTL
-        const meta = await this._withTimeout(this.remote.getWithTTL(key));
-        if (meta !== undefined) {
-          r = meta.value;
-          if (meta.remainingTTL > 0) backfillTTL = meta.remainingTTL;
-        }
-      } else {
-        // 方案B：remote 不支持 getWithTTL，使用普通 get + backfillLocalTTL 兜底
-        r = await this._withTimeout(this.remote.get(key));
-      }
-
-      if (r !== undefined && this.policy.backfillLocalOnRemoteHit) {
-        // 🔧 v1.1.9 补充：backfillTTL=0 时跳过 null 回填，防止无配置用户触发永久驻留 Bug
-        // - backfillTTL>0：回填所有值（含 null），TTL 保护下能正常过期
-        // - backfillTTL=0 + null：跳过——无 TTL 保护的 null 永久驻留 = Bug 本身
-        // - backfillTTL=0 + 非 null：回填（保留原有永久缓存行为，向后兼容）
-        if (backfillTTL > 0 || r !== null) {
-          try { await this.local.set(key, r, backfillTTL); } catch(_) {}
-        }
-      }
-      return r;
-    } catch(_) {
-      return undefined; // 远端异常降级
-    }
-  }
-
-  async set(key, val, ttl = 0) {
-    await this.local.set(key, val, ttl);
-    if (!this.remote) return;
-    if (this.policy.writePolicy === 'both') {
-      try { await this._withTimeout(this.remote.set(key, val, ttl)); } catch(_) {}
-    } else {
-      // local-first-async-remote
-      this._withTimeout(this.remote.set(key, val, ttl)).catch(() => {});
-    }
-  }
-
-  async del(key) {
-    let a = false, b = false;
-    try { a = await this.local.del(key); } catch(_) {}
-    if (this.remote) {
-      try { b = await this._withTimeout(this.remote.del(key)).then(Boolean).catch(() => false); } catch(_) {}
-    }
-    return !!(a || b);
-  }
-
-  async exists(key) {
-    const a = await this.local.exists(key);
-    if (a) return true;
-    if (!this.remote) return false;
-    try { return !!(await this._withTimeout(this.remote.exists(key))); } catch(_) { return false; }
-  }
-
-  async getMany(keys) {
-    const out = {};
-    // 先批量从本地取
-    const localRes = await this.local.getMany(keys);
-    const misses = [];
-    for (const k of keys) {
-      const v = localRes[k];
-      if (v !== undefined) out[k] = v; else misses.push(k);
-    }
-    if (!misses.length || !this.remote) return out;
-    try {
-      const remoteRes = await this._withTimeout(this.remote.getMany(misses));
-      if (remoteRes && typeof remoteRes === 'object') {
-        // 🔧 v1.1.9 修复：传入 backfillLocalTTL，防止无 TTL 永久回填（含 null 值）
-        // 🔧 v1.1.9 补充：backfillLocalTTL=0 时过滤 null，防止无配置用户触发永久驻留 Bug
-        if (this.policy.backfillLocalOnRemoteHit) {
-          const backfillData = this.policy.backfillLocalTTL > 0
-            ? remoteRes
-            : Object.fromEntries(Object.entries(remoteRes).filter(([, v]) => v !== null));
-          if (Object.keys(backfillData).length > 0) {
-            this.local.setMany(backfillData, this.policy.backfillLocalTTL).catch(() => {});
-          }
-        }
-        for (const k of misses) { if (remoteRes[k] !== undefined) out[k] = remoteRes[k]; }
-      }
-    } catch(_) { /* 降级 */ }
-    return out;
-  }
-
-  async setMany(obj, ttl = 0) {
-    await this.local.setMany(obj, ttl);
-    if (!this.remote) return true;
-    if (this.policy.writePolicy === 'both') {
-      try { await this._withTimeout(this.remote.setMany(obj, ttl)); } catch(_) {}
-    } else {
-      this._withTimeout(this.remote.setMany(obj, ttl)).catch(() => {});
-    }
-    return true;
-  }
-
-  async delMany(keys) {
-    let n = 0;
-    try { n += await this.local.delMany(keys); } catch(_) {}
-    if (this.remote) {
-      try { await this._withTimeout(this.remote.delMany(keys)); } catch(_) {}
-    }
-    return n;
-  }
-
-  async delPattern(pattern) {
-    let deleted = 0;
-
-    // 删除本地缓存
-    try {
-      deleted = await this.local.delPattern(pattern);
-    } catch(err) {
-      // 忽略本地删除错误
-    }
-
-    // 删除远端缓存（如果存在）
-    if (this.remote && typeof this.remote.delPattern === 'function') {
-      try {
-        await this._withTimeout(this.remote.delPattern(pattern));
-      } catch(err) {
-        // 远端删除失败，降级处理
-      }
-    }
-
-    // 向集群广播（可选）
-    try {
-      if (this.publish) {
-        this.publish({ type: 'invalidate', pattern, ts: Date.now() });
-      }
-    } catch(err) {
-      // 忽略广播错误
-    }
-
-    return deleted;
-  }
-
-  clear() {
-    // 仅清理本地
-    try { this.local.clear(); } catch(_) {}
-  }
-
-  keys(pattern = '*') {
-    try { return this.local.keys(pattern); } catch(_) { return []; }
-  }
-
-  getStats() {
-    const local = this.local.getStats ? this.local.getStats() : null;
-    const remote = this.remote && this.remote.getStats ? this.remote.getStats() : null;
-    const hits = (local?.hits || 0) + (remote?.hits || 0);
-    const misses = (local?.misses || 0) + (remote?.misses || 0);
-    return {
-      local,
-      remote,
-      hitRateApprox: hits / (hits + misses) || 0,
-    };
-  }
-}
-
-module.exports = MultiLevelCache;
-