chanjs 2.7.4 → 2.7.6

package/storage/cache.js

@@ -1,258 +1,118 @@
 /**
- * incr 默认 TTL（毫秒）
- * 用于 incr 新建 key 时自动附加过期，避免永久占用内存
- * 与 redis.js 的 DEFAULT_INCR_TTL 保持一致
+ * 单Map实现LRU+惰性TTL过期清理，对齐Redis incr行为，限流专用内存存储
+ * 特性：访问刷新LRU、自增不续期、批量惰性清理、容量淘汰
  */
-const DEFAULT_INCR_TTL = 60 * 1000;
+const CACHE_CONST = Object.freeze({
+  DEFAULT_MAX_SIZE: 100000,
+  DEFAULT_TTL: 5 * 60 * 1000,
+  DEFAULT_INCR_TTL: 60 * 1000,
+  CLEANUP_INTERVAL: 10 * 1000,
+  CLEANUP_BATCH_LIMIT: 1000,
+});
+
+export const DEFAULT_INCR_TTL = CACHE_CONST.DEFAULT_INCR_TTL;
 
-/**
- * LRU（最近最少使用）缓存类
- * @class Cache
- * @description
- * 基于内存的 LRU 缓存，支持 TTL 和自动过期清理。
- * 改进点：
- * 1. 单 Map 实现 LRU（删除再插入保证顺序），避免双 Map 开销
- * 2. 修复 TTL 续期 bug：get 时仅刷新 LRU 顺序，不再续期 TTL（避免热点 key 永不过期）
- * 3. 默认上限 10 万条（约 20MB），可配置
- * 4. 惰性批量清理：set 时按频率触发过期清理，不使用定时器
- * 5. incr/incrAndExpire：自增不刷新 TTL（与 Redis 行为对齐）
- * @example
- * const cache = new Cache({ maxSize: 100000, defaultTTL: 60000 });
- * cache.set('user:123', { name: '张三' }, 30000);
- * const user = cache.get('user:123');
- */
 class Cache {
   /**
-   * 创建缓存实例
-   * @param {Object} [options={}] - 配置选项
-   * @param {number} [options.maxSize=100000] - 最大缓存条目数，默认 10 万条约 20MB
-   * @param {number} [options.defaultTTL=300000] - 默认过期时间（毫秒），默认 5 分钟
+   * @param {{maxSize?: number; defaultTTL?: number}} opts
    */
-  constructor(options = {}) {
+  constructor(opts = {}) {
     this.map = new Map();
-    this.maxSize = options.maxSize || 100000;
-    this.defaultTTL = options.defaultTTL || 5 * 60 * 1000;
-    // 惰性清理控制
+    this.maxSize = opts.maxSize ?? CACHE_CONST.DEFAULT_MAX_SIZE;
+    this.defaultTTL = opts.defaultTTL ?? CACHE_CONST.DEFAULT_TTL;
     this._lastCleanup = Date.now();
-    this._cleanupInterval = 10 * 1000; // 最少间隔 10 秒
-    this._cleanupBatch = 200;           // 每次最多检查 200 条
+    this._cleanupInterval = CACHE_CONST.CLEANUP_INTERVAL;
   }
 
-  /**
-   * 设置缓存值
-   * @param {string} key - 缓存键
-   * @param {*} value - 要缓存的值
-   * @param {number} [ttl=this.defaultTTL] - 过期时间（毫秒）
-   */
+  /** 写入缓存；ttl<=0 视为永久存储（与 redis.set 行为对齐） */
   set(key, value, ttl = this.defaultTTL) {
     this._maybeCleanup();
-
-    // 达到上限且是新 key → 淘汰 Map 头部（最久未访问）
-    if (this.map.size >= this.maxSize && !this.map.has(key)) {
-      this._evictLRU();
-    }
-
-    // 先删除再插入，保证 Map 末尾是最新访问
+    if (this.map.size >= this.maxSize && !this.map.has(key)) this._evictLRU();
     this.map.delete(key);
-    this.map.set(key, { value, expireAt: Date.now() + ttl });
+    const expireAt = ttl > 0 ? Date.now() + ttl : Infinity;
+    this.map.set(key, { value, expireAt });
   }
 
-  /**
-   * 获取缓存值
-   * @param {string} key - 缓存键
-   * @returns {*} 缓存的值，如果键不存在或已过期则返回 null
-   * @description
-   * 仅刷新 LRU 顺序，不续期 TTL（修复旧版 bug）
-   */
+  /** 读取，刷新LRU顺序 */
   get(key) {
-    const item = this.map.get(key);
-    if (!item) return null;
-
-    const now = Date.now();
-    if (now > item.expireAt) {
-      this.map.delete(key);
-      return null;
-    }
-
-    // LRU：删除再插入，刷新到 Map 末尾
-    this.map.delete(key);
-    this.map.set(key, item);
-    return item.value;
+    const item = this._touch(key);
+    return item ? item.value : null;
   }
 
-  /**
-   * 删除缓存条目
-   */
-  del(key) {
-    return this.map.delete(key);
-  }
+  /** 存在性校验，命中同样刷新LRU */
+  has(key) { return !!this._touch(key); }
 
-  /**
-   * 清空所有缓存
-   */
-  clear() {
-    this.map.clear();
-  }
+  del = key => this.map.delete(key);
+  clear = () => this.map.clear();
+  size() { return this.map.size; }
 
-  /**
-   * 检查键是否存在
-   * 与 get 行为对齐：命中也刷新 LRU 访问顺序
-   * 避免高频 has 查询的 key 被提前淘汰
-   */
-  has(key) {
+  /** 访问并刷新LRU，过期项自动清理（单次 delete+set 维护 Map 插入序） */
+  _touch(key) {
     const item = this.map.get(key);
-    if (!item) return false;
+    if (!item) return null;
     if (Date.now() > item.expireAt) {
       this.map.delete(key);
-      return false;
+      return null;
     }
-    // LRU：删除再插入，刷新到末尾
+    // 利用 Map 插入序特性：delete+set 将 key 移至末尾（最近访问）
     this.map.delete(key);
     this.map.set(key, item);
-    return true;
-  }
-
-  /**
-   * 获取当前缓存大小（触发一次完整清理）
-   */
-  size() {
-    this._cleanupAll();
-    return this.map.size;
+    return item;
   }
 
-  /**
-   * 自增，新建 key 自动附加默认 TTL
-   * @param {string} key - 缓存键
-   * @param {number} [ttlMs=DEFAULT_INCR_TTL] - 新建 key 时的 TTL（毫秒）
-   * @returns {number} 自增后的值
-   * @description
-   * - 新建 key：设置值为 1，TTL = ttlMs
-   * - 已存在 key：值 +1，**不刷新 TTL**（与 Redis INCR 行为对齐）
-   *
-   * 重要：自增不会续期 TTL，这是有意设计。
-   * Rate Limit 场景下，每个 IP 的窗口由首次请求决定，后续请求只递增不续期。
-   */
-  incr(key, ttlMs = DEFAULT_INCR_TTL) {
+  /** 自增，新建key使用默认incrTTL，存量不续期TTL */
+  incr(key, ttlMs = CACHE_CONST.DEFAULT_INCR_TTL) {
     this._maybeCleanup();
-    const item = this.map.get(key);
-    const now = Date.now();
-
-    if (!item || now > item.expireAt) {
-      // 新建 key，设置默认 TTL
-      if (this.map.size >= this.maxSize && !this.map.has(key)) {
-        this._evictLRU();
-      }
-      this.map.set(key, { value: 1, expireAt: now + ttlMs });
-      return 1;
-    }
-
-    // 已存在：自增，**不刷新 TTL**（保持原 expireAt）
-    item.value = (typeof item.value === 'number' ? item.value : 0) + 1;
-    return item.value;
+    return this._incrInternal(key, ttlMs, false);
   }
 
-  /**
-   * 自增并首次设置过期时间
-   * @param {string} key - 缓存键
-   * @param {number} ttlMs - TTL 毫秒
-   * @returns {number} 自增后的值
-   * @description
-   * 与 incr 区别：新建时用调用方指定的 ttlMs，而非默认 TTL
-   * - 新建 key：设置值为 1，TTL = ttlMs
-   * - 已存在 key：值 +1，**不刷新 TTL**
-   *
-   * 用于 Rate Limit 场景：第一次访问设置窗口 TTL，后续访问只递增不续期
-   */
+  /** 自增并刷新过期时间（限流专用） */
   incrAndExpire(key, ttlMs) {
     this._maybeCleanup();
-    const item = this.map.get(key);
-    const now = Date.now();
+    return this._incrInternal(key, ttlMs, true);
+  }
 
+  _incrInternal(key, ttlMs, refreshTTL) {
+    const now = Date.now();
+    const item = this.map.get(key);
     if (!item || now > item.expireAt) {
-      // 新建 key，设置指定 TTL
-      if (this.map.size >= this.maxSize && !this.map.has(key)) {
-        this._evictLRU();
-      }
+      if (this.map.size >= this.maxSize && !this.map.has(key)) this._evictLRU();
       this.map.set(key, { value: 1, expireAt: now + ttlMs });
       return 1;
     }
-
-    // 已存在：自增，**不刷新 TTL**
-    item.value = (typeof item.value === 'number' ? item.value : 0) + 1;
+    item.value = (Number.isFinite(item.value) ? item.value : 0) + 1;
+    if (refreshTTL) item.expireAt = now + ttlMs;
     return item.value;
   }
 
-  /**
-   * 刷新过期时间
-   * @param {string} key - 缓存键
-   * @param {number} ttlMs - TTL 毫秒
-   * @returns {boolean} 是否设置成功
-   */
+  /** 主动刷新指定key过期时间 */
   expire(key, ttlMs) {
     const item = this.map.get(key);
-    if (!item || Date.now() > item.expireAt) {
-      return false;
-    }
+    if (!item || Date.now() > item.expireAt) return false;
     item.expireAt = Date.now() + ttlMs;
     return true;
   }
 
-  /**
-   * 循环淘汰最久未使用的条目，直到 size < maxSize
-   * 修复旧版只淘汰 1 条导致批量插入超出上限的问题
-   * Map 的 keys().next() 返回最早插入的 key（O(1)）
-   * @private
-   */
+  /** LRU淘汰：删除最久未访问key（Map 头部即最早插入） */
   _evictLRU() {
-    while (this.map.size >= this.maxSize) {
-      const oldestKey = this.map.keys().next().value;
-      if (oldestKey === undefined) break;
-      this.map.delete(oldestKey);
-    }
+    if (this.map.size < this.maxSize) return;
+    const oldest = this.map.keys().next().value;
+    if (oldest !== undefined) this.map.delete(oldest);
   }
 
-  /**
-   * 惰性批量清理过期项
-   * 控制频率：每 10 秒最多清理一次
-   * 控制单轮清理量：每轮最多 1000 条，避免大缓存全量遍历阻塞事件循环
-   *
-   * 修复说明：
-   *   旧版在遇到第一个未过期条目时 break，假设 Map 按过期时间有序插入。
-   *   实际上 Map 按插入顺序遍历，与过期时间无关。
-   *   后插入但 TTL 短的条目可能先过期，导致旧版无法清理被前面长 TTL 条目挡住的过期条目。
-   *   现改为分批清理（每轮最多 1000 条），剩余的会在下次触发时继续清理。
-   * @private
-   */
+  /** 惰性批量清理：间隔10s一次，单次最多清理1000条防阻塞事件循环 */
   _maybeCleanup() {
     const now = Date.now();
     if (now - this._lastCleanup < this._cleanupInterval) return;
     this._lastCleanup = now;
-
-    // 分批清理，单轮最多 1000 条，避免大缓存全量遍历阻塞事件循环
     let count = 0;
-    for (const [key, item] of this.map) {
-      if (now > item.expireAt) {
-        this.map.delete(key);
-      }
-      if (++count >= 1000) break;
-    }
-  }
-
-  /**
-   * 完整清理所有过期项
-   * 仅在调用 size() 时触发
-   * @private
-   */
-  _cleanupAll() {
-    const now = Date.now();
-    for (const [key, item] of this.map) {
-      if (now > item.expireAt) {
-        this.map.delete(key);
-      }
+    for (const [k, v] of this.map) {
+      if (now > v.expireAt) this.map.delete(k);
+      if (++count >= CACHE_CONST.CLEANUP_BATCH_LIMIT) break;
     }
   }
 }
 
-export { DEFAULT_INCR_TTL };
+// 全局单例实例
 export const cache = new Cache();
-export default Cache;
+export default Cache;

package/storage/index.js

@@ -1,9 +1,6 @@
 /**
- * 存储模块 - 缓存/Redis/存储适配层
- * - cache: 同步内存缓存（LRU + TTL）
- * - redis: 异步 Redis 后端
- * - store: 统一异步 API，自动选 Redis/内存 + 降级兜底
+ * storage 模块聚合导出
+ * 对外暴露：store（适配层单例）/ cache（内存缓存单例）
  */
-export { cache, DEFAULT_INCR_TTL } from "./cache.js";
-export { default as RedisBackend } from "./redis.js";
 export { store } from "./store.js";
+export { cache } from "./cache.js";