baja-lite 1.8.9 → 1.8.10

package/cache.d.ts

@@ -1,4 +1,30 @@
-import { StorageType } from './const/index.js';
+/**
+ * @internal 统一的 stale-allowed 注册表 key。
+ * 用带 TTL 的 string（而非全局 set），每个 stale-allowed 缓存独立管理自己的标记。
+ * key = [cache-meta]realKey，value = '1'，TTL = 缓存 TTL。
+ * 好处：自动过期，不再需要全局 set，内存占用与缓存数量而非请求数量成正比。
+ */
+/**
+ * 缓存被清理时的行为策略。
+ * 由 @MethodCache 的 `staleMode` 配置决定，clearMethodCache 依此自动选择清理方式。
+ */
+export declare enum CacheStaleMode {
+    /**
+     * 默认。清理时直接删除缓存值，下次请求触发 single-flight 重建。
+     * 优点：数据强一致，不会读到旧值。
+     * 缺点：重建期间所有请求被阻塞，直到 fn() 执行完毕。
+     */
+    Purge = 0,
+    /**
+     * 清理时保留旧值并标记为过期（stale），同时设一个 stale 窗口（默认 30s）。
+     * 窗口内：请求仍读到旧值（零阻塞），同时后台 single-flight 异步刷新。
+     * 窗口过后：stale 标记自动消失，退化回 Purge 行为。
+     *
+     * 适用场景：读多写少、能容忍秒级旧数据、fn() 执行代价高。
+     * 注意：开启后业务层可能收到乱序数据，需自行处理（如按时间戳丢弃过期包）。
+     */
+    StaleWhileRevalidate = 1
+}
 export declare function getRedisDB<T = any>(db?: string): T;
 export declare function GetRedisLock(key: string, lockMaxActive?: number): Promise<boolean>;
 /** 对FN加锁、缓存执行 */
@@ -41,15 +67,20 @@ export declare function MethodLock<T = any>(config: {
     lockMaxTime?: number;
 }): (target: T, _propertyKey: string, descriptor: PropertyDescriptor) => void;
 /**
- * 清空方法缓存。同时清 redis 和 memory 两边，业务侧无需关心存储是哪种。
+ * 清空方法缓存。
  * - redis 侧只在配置了 redis 时才操作；没配 redis 时安静跳过，不抛错。
- * - 关联清除（clearKey）在两边都生效。
+ * - 关联清除（clearKey）生效。
+ * - 被清理的 key 如果启用了 StaleWhileRevalidate（CacheValue.sa=1），会保留旧值并标记 stale。
+ *
+ * @param key       要清理的缓存 key 或 parent key
+ * @param staleTimeoutSec  stale 窗口秒数（仅对 StaleWhileRevalidate 的 key 生效）。默认 30。
  */
-export declare function clearMethodCache(key: string): Promise<void>;
+export declare function clearMethodCache(key: string, staleTimeoutSec?: number): Promise<void>;
 /**
  * 执行一个方法fn，
  * 如果有缓存，则返回缓存，否则【加锁、二次检查】后执行方法并缓存，防止缓存击穿。
  * 可选 `cacheNullValue=true` 开启负缓存，防穿透；负缓存默认沿用 autoClearTime，可单独用 nullCacheTime 设短。
+ * 可选 `staleMode: CacheStaleMode.StaleWhileRevalidate` 开启异步重新验证（清理时保留旧值，零阻塞）。
  */
 export declare function excuteWithCache<T>(config: {
     /** 返回缓存key,参数=方法的参数+当前用户对象，可以用来清空缓存。 */
@@ -62,16 +93,49 @@ export declare function excuteWithCache<T>(config: {
     cacheNullValue?: boolean;
     /** 负缓存 TTL（分钟），默认沿用 autoClearTime。 */
     nullCacheTime?: number;
-    /** 存储后端：'redis'（默认，跨进程共享）或 'memory'（进程内 LRU，更快但不跨进程）。 */
-    storage?: StorageType;
+    /** 存储后端：'redis'（跨进程共享）。 */
     /** 随着当前用户sesion的清空而一起清空 */
     clearWithSession?: boolean;
+    /**
+     * 缓存被清理时的行为策略。默认 Purge。
+     * StaleWhileRevalidate 时设 sa=1 使 clearMethodCache 走"标记 stale + 保留旧值"路径。
+     */
+    staleMode?: CacheStaleMode;
+    /** stale 窗口秒数（仅 StaleWhileRevalidate 生效）。默认 30。 */
+    staleTimeout?: number;
+    /**
+     * 缓存更新回调。异步方法，在 setMethodCache 成功写缓存后调用。
+     * 调用时三个参数：this → 方法的执行上下文（config.ctx）；value → 缓存值；args → 方法输入参数。
+     */
+    onCacheUpdated?: (this: any, value: T, ...args: any[]) => void | Promise<void>;
+    /**
+     * 方法的执行上下文。在 onCacheUpdated 回调中作为 this 传入。
+     * @example
+     * ```ts
+     * excuteWithCache({
+     *     key: 'calibration',
+     *     ctx: service,
+     *     args: ['device001'],
+     *     onCacheUpdated(this: MyService, args, value) {
+     *         this.broadcast(value);
+     *     },
+     * }, () => service.getCalibration('device001'));
+     * ```
+     */
+    ctx?: any;
+    /**
+     * 方法的输入参数。在 onCacheUpdated 回调中作为 args 传入。
+     * 用于告知回调是哪些参数触发了本次缓存更新。
+     */
+    args?: any[];
 }, fn: () => Promise<T>): Promise<T>;
 /**
  * 缓存注解：先查缓存 → miss 才加锁 → 锁内再查一次 → 仍 miss 才执行原方法。
  * 已内置 single-flight，不需要再叠 `@MethodLock`。
  * 可选 `cacheNullValue=true` 开启负缓存，防穿透。
  * 可选 `storage: 'memory'` 用进程内 LRU 替代 redis（单进程场景，毫秒级延迟）。
+ * 可选 `staleMode: CacheStaleMode.StaleWhileRevalidate` 开启异步重新验证（清理时保留旧值，零阻塞）。
+ * 可选 `onCacheUpdated` 设置缓存更新回调（带 this 上下文）。
  */
 export declare function MethodCache<T = any>(config: {
     /** 返回缓存key,参数=方法的参数[注意：必须和主方法的参数数量、完全一致，同时会追加一个当前用户对象]+当前用户对象，可以用来清空缓存。 */
@@ -84,8 +148,55 @@ export declare function MethodCache<T = any>(config: {
     cacheNullValue?: boolean;
     /** 负缓存 TTL（分钟），默认沿用 autoClearTime。 */
     nullCacheTime?: number;
-    /** 存储后端：'redis'（默认，跨进程共享）或 'memory'（进程内 LRU，更快但不跨进程）。 */
-    storage?: StorageType;
+    /** 存储后端：'redis'（跨进程共享）。 */
     /** 随着当前用户sesion的清空而一起清空 */
     clearWithSession?: boolean;
+    /**
+     * 缓存被清理时的行为策略。默认 Purge。
+     * StaleWhileRevalidate 时设 sa=1 使 clearMethodCache 走"标记 stale + 保留旧值"路径。
+     */
+    staleMode?: CacheStaleMode;
+    /** stale 窗口秒数（仅 StaleWhileRevalidate 生效）。默认 30。 */
+    staleTimeout?: number;
+    /**
+     * 缓存更新回调。异步方法，在 setMethodCache 成功写缓存后调用。
+     * 调用时三个参数：this → 执行上下文；args → 方法输入参数；value → 缓存值。
+     */
+    onCacheUpdated?: (this: any, value: T, ...args: any[]) => void | Promise<void>;
 }): (_target: T, _propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * 外部直接设置缓存值。用于绕过 @MethodCache 装饰器直接更新缓存的场景
+ * （如外部事件驱动的数据变更、手动刷新等）。
+ *
+ * 内部使用统一格式 { v, d, s } 序列化，确保与 @MethodCache 的读取逻辑兼容。
+ *
+ * @param cacheKey   缓存 key（不含 [cache] 前缀，与 @MethodCache 的 key 一致）
+ * @param value      要缓存的值
+ * @param options    选项
+ *
+ * @example
+ * ```ts
+ * // 外部事件驱动更新缓存
+ * await setCache('match-timer-123', timer, { autoClearTime: 120 });
+ *
+ * // 同时触发 onCacheUpdated 回调（如果有）
+ * await setCache('match-timer-123', timer, {
+ *     autoClearTime: 120,
+ *     onCacheUpdated(this: MyService, value) {
+ *         this.broadcast(value);
+ *     }
+ * });
+ * ```
+ */
+export declare function setCache<T = any>(cacheKey: string, value: T, options?: {
+    /** 自动清空缓存的时间，单位分钟。不设则永不过期。 */
+    autoClearTime?: number;
+    /** 是否缓存 null / undefined。默认 false。 */
+    cacheNullValue?: boolean;
+    /** 缓存更新回调 */
+    onCacheUpdated?: (this: any, value: T, ...args: any[]) => void | Promise<void>;
+    /** 回调的 this 上下文 */
+    ctx?: any;
+    /** 回调的 args 参数 */
+    args?: any[];
+}): Promise<void>;