baja-lite 1.8.8 → 1.8.10

package/boot-remote.d.ts

@@ -1,2 +1,2 @@
-import { GlobalSqlOptionForWeb } from './sql.js';
+import { GlobalSqlOptionForWeb } from './const/index.js';
 export declare const BootRomote: (options: GlobalSqlOptionForWeb) => Promise<void>;

package/boot-remote.js

@@ -1,5 +1,7 @@
 import { DBType, _Hump, getEnums } from 'baja-lite-field';
-import { ColumnMode, PrinterLogger, SqlCache, SqliteRemote, _Context, _DataConvert, _GlobalSqlOption, _LoggerService, _dao, _defOption, _enum, _primaryDB, _sqlCache } from './sql.js';
+import { SqlCache, SqliteRemote } from './db/index.js';
+import { PrinterLogger } from './logger.js';
+import { ColumnMode, _Context, _DataConvert, _GlobalSqlOption, _LoggerService, _dao, _defOption, _enum, _primaryDB, _sqlCache } from './const/index.js';
 export const BootRomote = async function (options) {
     globalThis[_GlobalSqlOption] = Object.assign({}, _defOption);
     if (options.skipEmptyString !== undefined) {
@@ -11,6 +13,9 @@ export const BootRomote = async function (options) {
     if (options.maxDeal !== undefined) {
         globalThis[_GlobalSqlOption].maxDeal = options.maxDeal;
     }
+    if (options.memCacheMaxSize !== undefined) {
+        globalThis[_GlobalSqlOption].memCacheMaxSize = options.memCacheMaxSize;
+    }
     if (options.SqliteRemote !== undefined) {
         globalThis[_GlobalSqlOption].SqliteRemote = options.SqliteRemote;
     }

package/boot.d.ts

@@ -1,2 +1,2 @@
-import { GlobalSqlOption } from './sql.js';
+import { GlobalSqlOption } from './const/index.js';
 export declare const Boot: (options: GlobalSqlOption) => Promise<void>;

package/boot.js

@@ -1,6 +1,8 @@
 import { _Hump, DBType, getEnums } from 'baja-lite-field';
 import events from 'events';
-import { _Context, _dao, _DataConvert, _defOption, _enum, _EventBus, _fs, _GlobalSqlOption, _LoggerService, _MysqlKeepAliveTime, _path, _primaryDB, _sqlCache, ColumnMode, Mysql, Postgresql, PrinterLogger, SqlCache, Sqlite, SqliteRemote } from './sql.js';
+import { _Context, _dao, _DataConvert, _defOption, _enum, _EventBus, _fs, _GlobalSqlOption, _LoggerService, _MysqlKeepAliveTime, _path, _primaryDB, _sqlCache, ColumnMode } from './const/index.js';
+import { Mysql, Postgresql, SqlCache, Sqlite, SqliteRemote } from './db/index.js';
+import { PrinterLogger } from './logger.js';
 export const Boot = async function (options) {
     globalThis[_GlobalSqlOption] = Object.assign({}, _defOption);
     if (options.skipEmptyString !== undefined) {
@@ -12,6 +14,9 @@ export const Boot = async function (options) {
     if (options.maxDeal !== undefined) {
         globalThis[_GlobalSqlOption].maxDeal = options.maxDeal;
     }
+    if (options.memCacheMaxSize !== undefined) {
+        globalThis[_GlobalSqlOption].memCacheMaxSize = options.memCacheMaxSize;
+    }
     if (options.logger) {
         globalThis[_LoggerService] = options.logger;
     }

package/cache.d.ts

@@ -0,0 +1,202 @@
+/**
+ * @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加锁、缓存执行 */
+export declare function excuteWithLock<T>(config: {
+    /** 返回缓存key,参数=方法的参数+当前用户对象，可以用来清空缓存。 */
+    key: ((...args: any[]) => string) | string;
+    /** 被锁定线程是否sleep直到解锁为止? 默认true */
+    lockWait?: boolean;
+    /** 当设置了lockWait=true时，等待多少【毫秒】进行一次锁查询? 默认：100MS */
+    lockRetryInterval?: number;
+    /** 当设置了lockWait=true时，等待多少【毫秒】即视为超时，放弃本次访问？默认：永不放弃 */
+    lockMaxWaitTime?: number;
+    /** 错误信息 */
+    errorMessage?: string;
+    /** 允许的并发数，默认：1 */
+    lockMaxActive?: number;
+    /** 单个锁多少【毫秒】后自动释放?默认：60*1000MS  */
+    lockMaxTime?: number;
+}, fn__: () => Promise<T>): Promise<T>;
+/**
+ * 方法加锁装饰器。
+ * 与 `MethodCache` 组合时，**不要**手工叠装饰器——`MethodCache` 内部已经实现了
+ * "先查缓存 → miss 才加锁 → 锁内二次检查 → 仍 miss 才执行" 的 single-flight 语义，
+ * 直接给方法加 `@MethodCache` 即可。`@MethodLock` 单独使用时仅做并发互斥，不感知缓存。
+ */
+export declare function MethodLock<T = any>(config: {
+    /** 返回缓存key,参数=方法的参数[注意：必须和主方法的参数数量、完全一致，同时会追加一个当前用户对象]+当前用户对象，可以用来清空缓存。 */
+    key: ((this: T, ...args: any[]) => string) | string;
+    /** 被锁定线程是否sleep直到解锁为止? 默认true */
+    lockWait?: boolean;
+    /** 当设置了lockWait=true时，等待多少【毫秒】进行一次锁查询? 默认100ms */
+    lockRetryInterval?: number;
+    /** 当设置了lockWait=true时，等待多少【毫秒】即视为超时，放弃本次访问？默认永不放弃 */
+    lockMaxWaitTime?: number;
+    /** 错误信息 */
+    errorMessage?: string;
+    /** 允许的并发数，默认=1 */
+    lockMaxActive?: number;
+    /** 单个锁多少【毫秒】后自动释放?即时任务没有执行完毕或者没有主动释放锁?  */
+    lockMaxTime?: number;
+}): (target: T, _propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * 清空方法缓存。
+ * - redis 侧只在配置了 redis 时才操作；没配 redis 时安静跳过，不抛错。
+ * - 关联清除（clearKey）生效。
+ * - 被清理的 key 如果启用了 StaleWhileRevalidate（CacheValue.sa=1），会保留旧值并标记 stale。
+ *
+ * @param key       要清理的缓存 key 或 parent key
+ * @param staleTimeoutSec  stale 窗口秒数（仅对 StaleWhileRevalidate 的 key 生效）。默认 30。
+ */
+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,参数=方法的参数+当前用户对象，可以用来清空缓存。 */
+    key: ((...args: any[]) => string) | string;
+    /** 返回缓存清除key,参数=方法的参数+当前用户对象，可以用来批量清空缓存 */
+    clearKey?: string[];
+    /** 自动清空缓存的时间，单位分钟 */
+    autoClearTime?: number;
+    /** 是否缓存 null / undefined（负缓存防穿透），默认 false。 */
+    cacheNullValue?: boolean;
+    /** 负缓存 TTL（分钟），默认沿用 autoClearTime。 */
+    nullCacheTime?: number;
+    /** 存储后端：'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,参数=方法的参数[注意：必须和主方法的参数数量、完全一致，同时会追加一个当前用户对象]+当前用户对象，可以用来清空缓存。 */
+    key: ((this: T, ...args: any[]) => string) | string;
+    /** 返回缓存清除key,参数=方法的参数[注意：必须和主方法的参数数量、完全一致，同时会追加一个当前用户对象]+当前用户对象，可以用来批量清空缓存 */
+    clearKey?: ((this: T, ...args: any[]) => string[]) | string[];
+    /** 自动清空缓存的时间，单位分钟 */
+    autoClearTime?: number;
+    /** 是否缓存 null / undefined（负缓存防穿透），默认 false。 */
+    cacheNullValue?: boolean;
+    /** 负缓存 TTL（分钟），默认沿用 autoClearTime。 */
+    nullCacheTime?: number;
+    /** 存储后端：'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>;