baja-lite 1.8.10 → 1.8.11

package/cache.d.ts

@@ -72,10 +72,9 @@ export declare function MethodLock<T = any>(config: {
  * - 关联清除（clearKey）生效。
  * - 被清理的 key 如果启用了 StaleWhileRevalidate（CacheValue.sa=1），会保留旧值并标记 stale。
  *
- * @param key       要清理的缓存 key 或 parent key
- * @param staleTimeoutSec  stale 窗口秒数（仅对 StaleWhileRevalidate 的 key 生效）。默认 30。
+ * @param key  要清理的缓存 key 或 parent key
  */
-export declare function clearMethodCache(key: string, staleTimeoutSec?: number): Promise<void>;
+export declare function clearMethodCache(key: string): Promise<void>;
 /**
  * 执行一个方法fn，
  * 如果有缓存，则返回缓存，否则【加锁、二次检查】后执行方法并缓存，防止缓存击穿。
@@ -87,13 +86,17 @@ export declare function excuteWithCache<T>(config: {
     key: ((...args: any[]) => string) | string;
     /** 返回缓存清除key,参数=方法的参数+当前用户对象，可以用来批量清空缓存 */
     clearKey?: string[];
-    /** 自动清空缓存的时间，单位分钟 */
+    /**
+     * 自动清空缓存的时间，单位分钟。
+     * ⚠️ 不能与 `staleMode: StaleWhileRevalidate` 同时使用：
+     * stale 只是把缓存"标记为过期"，旧值仍在；而 autoClearTime 到期后会物理删除 key。
+     * 两者语义冲突——stale 期望保留旧值等后台刷新，autoClearTime 却会直接删掉它。
+     */
     autoClearTime?: number;
     /** 是否缓存 null / undefined（负缓存防穿透），默认 false。 */
     cacheNullValue?: boolean;
-    /** 负缓存 TTL（分钟），默认沿用 autoClearTime。 */
+    /** 负缓存 TTL（分钟）。默认沿用 autoClearTime；都不设时不写入。 */
     nullCacheTime?: number;
-    /** 存储后端：'redis'（跨进程共享）。 */
     /** 随着当前用户sesion的清空而一起清空 */
     clearWithSession?: boolean;
     /**
@@ -101,8 +104,6 @@ export declare function excuteWithCache<T>(config: {
      * StaleWhileRevalidate 时设 sa=1 使 clearMethodCache 走"标记 stale + 保留旧值"路径。
      */
     staleMode?: CacheStaleMode;
-    /** stale 窗口秒数（仅 StaleWhileRevalidate 生效）。默认 30。 */
-    staleTimeout?: number;
     /**
      * 缓存更新回调。异步方法，在 setMethodCache 成功写缓存后调用。
      * 调用时三个参数：this → 方法的执行上下文（config.ctx）；value → 缓存值；args → 方法输入参数。
@@ -116,7 +117,7 @@ export declare function excuteWithCache<T>(config: {
      *     key: 'calibration',
      *     ctx: service,
      *     args: ['device001'],
-     *     onCacheUpdated(this: MyService, args, value) {
+     *     onCacheUpdated(this: MyService, value, args) {
      *         this.broadcast(value);
      *     },
      * }, () => service.getCalibration('device001'));
@@ -133,7 +134,6 @@ export declare function excuteWithCache<T>(config: {
  * 缓存注解：先查缓存 → miss 才加锁 → 锁内再查一次 → 仍 miss 才执行原方法。
  * 已内置 single-flight，不需要再叠 `@MethodLock`。
  * 可选 `cacheNullValue=true` 开启负缓存，防穿透。
- * 可选 `storage: 'memory'` 用进程内 LRU 替代 redis（单进程场景，毫秒级延迟）。
  * 可选 `staleMode: CacheStaleMode.StaleWhileRevalidate` 开启异步重新验证（清理时保留旧值，零阻塞）。
  * 可选 `onCacheUpdated` 设置缓存更新回调（带 this 上下文）。
  */
@@ -142,13 +142,15 @@ export declare function MethodCache<T = any>(config: {
     key: ((this: T, ...args: any[]) => string) | string;
     /** 返回缓存清除key,参数=方法的参数[注意：必须和主方法的参数数量、完全一致，同时会追加一个当前用户对象]+当前用户对象，可以用来批量清空缓存 */
     clearKey?: ((this: T, ...args: any[]) => string[]) | string[];
-    /** 自动清空缓存的时间，单位分钟 */
+    /**
+     * 自动清空缓存的时间，单位分钟。
+     * ⚠️ 不能与 `staleMode: StaleWhileRevalidate` 同用：stale 仅标记过期，autoClearTime 会物理删除 key，语义冲突。
+     */
     autoClearTime?: number;
     /** 是否缓存 null / undefined（负缓存防穿透），默认 false。 */
     cacheNullValue?: boolean;
     /** 负缓存 TTL（分钟），默认沿用 autoClearTime。 */
     nullCacheTime?: number;
-    /** 存储后端：'redis'（跨进程共享）。 */
     /** 随着当前用户sesion的清空而一起清空 */
     clearWithSession?: boolean;
     /**
@@ -156,8 +158,6 @@ export declare function MethodCache<T = any>(config: {
      * StaleWhileRevalidate 时设 sa=1 使 clearMethodCache 走"标记 stale + 保留旧值"路径。
      */
     staleMode?: CacheStaleMode;
-    /** stale 窗口秒数（仅 StaleWhileRevalidate 生效）。默认 30。 */
-    staleTimeout?: number;
     /**
      * 缓存更新回调。异步方法，在 setMethodCache 成功写缓存后调用。
      * 调用时三个参数：this → 执行上下文；args → 方法输入参数；value → 缓存值。
@@ -168,7 +168,7 @@ export declare function MethodCache<T = any>(config: {
  * 外部直接设置缓存值。用于绕过 @MethodCache 装饰器直接更新缓存的场景
  * （如外部事件驱动的数据变更、手动刷新等）。
  *
- * 内部使用统一格式 { v, d, s } 序列化，确保与 @MethodCache 的读取逻辑兼容。
+ * 内部使用统一格式 { t, d, s, sa } 序列化，确保与 @MethodCache 的读取逻辑兼容。
  *
  * @param cacheKey   缓存 key（不含 [cache] 前缀，与 @MethodCache 的 key 一致）
  * @param value      要缓存的值

package/cache.js

@@ -232,7 +232,7 @@ async function setMethodCache(config, devid) {
         const event = CacheKey.value(config.key);
         if (globalThis[_EventBus].listenerCount(event) === 0) {
             globalThis[_EventBus].on(event, async (key) => {
-                await clearCacheKey(key, 30);
+                await clearCacheKey(key);
                 cacheLog(`cache ${key} clear by key!`);
             });
         }
@@ -241,8 +241,8 @@ async function setMethodCache(config, devid) {
         // 订阅：清空 clear list —— 同样去重，避免每次 miss 都重复注册。
         const event = `user-${devid}`;
         if (globalThis[_EventBus].listenerCount(event) === 0) {
-            globalThis[_EventBus].on(event, async function (key) {
-                await clearCacheKey(key, 30);
+            globalThis[_EventBus].on(event, async (key) => {
+                await clearCacheKey(key);
                 cacheLog(`cache ${key} clear by devid!`);
             });
         }
@@ -257,7 +257,7 @@ async function setMethodCache(config, devid) {
  *
  * @returns 受影响的 children 列表（parent 路径会返回所有被级联清理的 child key）
  */
-async function clearCacheKey(key, staleTimeoutSec) {
+async function clearCacheKey(key) {
     const db = getRedisDB();
     const affectedChildren = [];
     // 1. 先处理 parent 级联：把关联的 children 全部清掉
@@ -266,7 +266,7 @@ async function clearCacheKey(key, staleTimeoutSec) {
         const childKeys = await db.smembers(CacheKey.parent(key));
         for (const child of childKeys) {
             cacheLog(`cache ${child} cleared via parent ${key}!`);
-            await clearCacheKey(child, staleTimeoutSec);
+            await clearCacheKey(child);
             affectedChildren.push(child);
         }
         await db.del(CacheKey.parent(key));
@@ -313,14 +313,13 @@ async function clearCacheKey(key, staleTimeoutSec) {
  * - 关联清除（clearKey）生效。
  * - 被清理的 key 如果启用了 StaleWhileRevalidate（CacheValue.sa=1），会保留旧值并标记 stale。
  *
- * @param key       要清理的缓存 key 或 parent key
- * @param staleTimeoutSec  stale 窗口秒数（仅对 StaleWhileRevalidate 的 key 生效）。默认 30。
+ * @param key  要清理的缓存 key 或 parent key
  */
-export async function clearMethodCache(key, staleTimeoutSec = 30) {
+export async function clearMethodCache(key) {
     const redisDao = globalThis[_dao]?.[DBType.Redis]?.[_primaryDB];
     if (!redisDao)
         return;
-    await clearCacheKey(key, staleTimeoutSec);
+    await clearCacheKey(key);
 }
 /**
  * Redis 缓存执行：先查缓存 → miss 后单飞抢锁执行 → 其它等待者只盯缓存、不抢锁。
@@ -333,7 +332,7 @@ export async function clearMethodCache(key, staleTimeoutSec = 30) {
  * 命中判断用 `cached !== null`（ioredis 在 key 不存在时返回 `null`），
  * 这样 `cacheNullValue=true` 时存进去的字面量 `'null'` 也会算作命中，达到防穿透效果。
  *
- * 命中时若发现 stale 标记（[cache-stale]key 存在），说明该值是"已被声明过期但保留的旧值"，
+ * 命中时若发现 stale 标志（CacheValue.s=1），说明该值是"已被声明过期但保留的旧值"，
  * 此时仍返回旧值（零阻塞），同时触发后台 single-flight 异步刷新。
  * 这样 clearMethodCache 后的首次读取不会被阻塞，后续读取将命中刷新后的新值。
  *
@@ -518,7 +517,6 @@ export async function excuteWithCache(config, fn) {
  * 缓存注解：先查缓存 → miss 才加锁 → 锁内再查一次 → 仍 miss 才执行原方法。
  * 已内置 single-flight，不需要再叠 `@MethodLock`。
  * 可选 `cacheNullValue=true` 开启负缓存，防穿透。
- * 可选 `storage: 'memory'` 用进程内 LRU 替代 redis（单进程场景，毫秒级延迟）。
  * 可选 `staleMode: CacheStaleMode.StaleWhileRevalidate` 开启异步重新验证（清理时保留旧值，零阻塞）。
  * 可选 `onCacheUpdated` 设置缓存更新回调（带 this 上下文）。
  */
@@ -551,7 +549,7 @@ export function MethodCache(config) {
  * 外部直接设置缓存值。用于绕过 @MethodCache 装饰器直接更新缓存的场景
  * （如外部事件驱动的数据变更、手动刷新等）。
  *
- * 内部使用统一格式 { v, d, s } 序列化，确保与 @MethodCache 的读取逻辑兼容。
+ * 内部使用统一格式 { t, d, s, sa } 序列化，确保与 @MethodCache 的读取逻辑兼容。
  *
  * @param cacheKey   缓存 key（不含 [cache] 前缀，与 @MethodCache 的 key 一致）
  * @param value      要缓存的值
@@ -579,8 +577,10 @@ export async function setCache(cacheKey, value, options = {}) {
     }
     const dataStr = isNullish ? 'null' : JSON.stringify(value);
     const timestamp = Date.now();
-    const payload = serializeCacheValue(dataStr, timestamp);
     const db = getRedisDB();
+    // 保留旧 sa：沿用已有标志（防止外部直写清掉 sa=1，导致 clearMethodCache 变 purge）
+    const existingSa = await db.get(CacheKey.value(cacheKey)).then(r => r ? deserializeCacheValue(r).sa : undefined);
+    const payload = serializeCacheValue(dataStr, timestamp, false, !!existingSa);
     if (autoClearTime) {
         await db.set(CacheKey.value(cacheKey), payload, 'EX', autoClearTime * 60);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baja-lite",
-  "version": "1.8.10",
+  "version": "1.8.11",
   "description": "some util for self",
   "homepage": "https://github.com/void-soul/baja-lite",
   "repository": {