baja-lite 1.8.13 → 1.8.15

package/boot.js

@@ -3,6 +3,7 @@ import events from 'events';
 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';
+import { initEventSubscriber } from './event.js';
 export const Boot = async function (options) {
     globalThis[_GlobalSqlOption] = Object.assign({}, _defOption);
     if (options.skipEmptyString !== undefined) {
@@ -156,6 +157,8 @@ export const Boot = async function (options) {
             globalThis[_LoggerService].error('event-bus', error);
         });
         globalThis[_EventBus] = event;
+        // 初始化 Redis 事件跨进程桥接（订阅 [event]* 频道）
+        await initEventSubscriber();
     }
     if (options.Postgresql) {
         const Pool = await import('pg-pool');

package/cache.d.ts

@@ -155,13 +155,33 @@ export declare function clearMethodCache(key: string): Promise<void>;
  * ```
  */
 export declare function excuteWithCache<T>(config: {
+    /** 返回缓存key,参数=方法的参数[注意：必须和主方法的参数数量、完全一致，同时会追加一个当前用户对象]+当前用户对象，可以用来清空缓存。 */
     key: ((...args: any[]) => string) | string;
+    /** 返回缓存清除key,参数=方法的参数[注意：必须和主方法的参数数量、完全一致，同时会追加一个当前用户对象]+当前用户对象，可以用来批量清空缓存 */
     clearKey?: ((...args: any[]) => string[]) | string[];
+    /**
+     * 自动清空缓存的时间，单位分钟。
+     * ⚠️ 不能与 `staleMode: StaleWhileRevalidate` 同用：stale 仅标记过期，autoClearTime 会物理删除 key，语义冲突。
+     */
     autoClearTime?: number;
+    /** 是否缓存 null / undefined（负缓存防穿透），默认 false。 */
     cacheNullValue?: boolean;
+    /** 负缓存 TTL（分钟），默认沿用 autoClearTime。 */
     nullCacheTime?: number;
+    /**
+     * 随着当前用户sesion的清空而一起清空,需要业务系统配合,用户退出时通过
+     * event 里的 trigger（devid）触发
+     */
     clearWithSession?: boolean;
+    /**
+     * 缓存被清理时的行为策略。默认 Purge。
+     * StaleWhileRevalidate 时设 sa=1 使 clearMethodCache 走"标记 stale + 保留旧值"路径。
+     */
     staleMode?: CacheStaleMode;
+    /**
+     * 缓存更新回调。异步方法，在 setMethodCache 成功写缓存后调用。
+     * 调用时三个参数：this → 执行上下文；args → 方法输入参数；value → 缓存值。
+     */
     onCacheUpdated?: (this: any, value: T, ...args: any[]) => void | Promise<void>;
     ctx?: any;
     args?: any[];
@@ -247,7 +267,10 @@ export declare function MethodCache<T = any>(config: {
     cacheNullValue?: boolean;
     /** 负缓存 TTL（分钟），默认沿用 autoClearTime。 */
     nullCacheTime?: number;
-    /** 随着当前用户sesion的清空而一起清空 */
+    /**
+     * 随着当前用户sesion的清空而一起清空,需要业务系统配合,用户退出时通过
+     * event 里的 trigger（devid）触发
+     */
     clearWithSession?: boolean;
     /**
      * 缓存被清理时的行为策略。默认 Purge。

package/cache.js

@@ -1,7 +1,8 @@
 import { DBType } from 'baja-lite-field';
 import { sleep } from './fn.js';
 import { Throw } from './error.js';
-import { _dao, _EventBus, _LoggerService, _primaryDB, } from './const/symbols.js';
+import { _dao, _LoggerService, _primaryDB, } from './const/symbols.js';
+import { on } from './event.js';
 /** @internal 输出缓存分类日志（仅当 setLogLevels 包含 'cache' 时生效） */
 function cacheLog(message, ...params) {
     const logger = globalThis[_LoggerService];
@@ -229,27 +230,13 @@ async function setMethodCache(config, devid) {
     // staleAllowed 已存储在缓存值内部（CacheValue.sa），无需单独的 meta key
     // 删除旧格式残留（兼容升级）
     // await db.del(`[cache-meta]${config.key}`);   // 清理旧格式残留
-    // 订阅：清空 clear list —— 同一 key 在缓存生命周期内只注册一次监听器，
-    // 否则每次 miss 都会 .on 一次，clearMethodCache 触发时回调会被执行 N 遍，
-    // 长期运行造成监听器泄漏。
-    if (config.clearKey && config.clearKey.length > 0) {
-        const event = CacheKey.value(config.key);
-        if (globalThis[_EventBus].listenerCount(event) === 0) {
-            globalThis[_EventBus].on(event, async (key) => {
-                await clearCacheKey(key);
-                cacheLog(`${key} clear by key!`);
-            });
-        }
-    }
     if (devid) {
         // 订阅：清空 clear list —— 同样去重，避免每次 miss 都重复注册。
         const event = `user-${devid}`;
-        if (globalThis[_EventBus].listenerCount(event) === 0) {
-            globalThis[_EventBus].on(event, async (key) => {
-                await clearCacheKey(key);
-                cacheLog(`${key} clear by devid!`);
-            });
-        }
+        on(event, async (key) => {
+            await clearCacheKey(key);
+            cacheLog(`${key} clear by devid!`);
+        }, { unique: true });
     }
 }
 /**

package/event.d.ts

@@ -1,10 +1,130 @@
-type EventParams = readonly unknown[];
-type EventHandler<T extends EventParams> = (...args: T) => void;
-export declare class EventBus<T extends Record<string, EventParams>> {
-    private readonly all;
-    on<K extends keyof T>(type: K, handler: EventHandler<T[K]>): this;
-    once<K extends keyof T>(type: K, handler: EventHandler<T[K]>): this;
-    off<K extends keyof T>(type: K, handler?: EventHandler<T[K]>): this;
-    emit<K extends keyof T>(type: K, ...args: T[K]): this;
+/** on() 的选项 */
+interface OnOptions {
+    /**
+     * 设为 true 后，若该事件名下已有注册的监听器，则跳过本次注册。
+     * 适用于在热点路径中反复调用 on()、不希望重复注册的场景。
+     */
+    unique?: boolean;
+    /**
+     * 设为 true 后，监听器触发一次后自动移除（标准 EventEmitter.once 语义）。
+     */
+    once?: boolean;
 }
+/** trigger() 的选项 */
+interface TriggerOptions {
+    /**
+     * 是否在进程内 emit。默认 true。
+     */
+    local?: boolean;
+    /**
+     * 是否通过 Redis 广播到其他进程。默认 true。
+     * 无 Redis 连接时静默跳过。
+     */
+    remote?: boolean;
+}
+/**
+ * 注册事件监听器（进程级 + 跨进程）。
+ *
+ * 当前进程内通过 `trigger` 触发，或从同一 Redis 集群的其他进程广播而来，
+ * 均会调起此 listener。
+ *
+ * @param event       - 事件名
+ * @param listener    - 回调函数
+ * @param opts.unique - true 时若该事件已有监听器则跳过注册（防止热点路径中重复注册）
+ * @param opts.once   - true 时触发一次后自动移除（标准 once 语义）
+ *
+ * @example
+ * ```ts
+ * import { on } from 'baja-lite/event';
+ *
+ * // 普通注册（每次调用都会新增一个 listener）
+ * on('user-login', (uid: string, ts: number) => {
+ *     console.log(`用户 ${uid} 在 ${ts} 登录`);
+ * });
+ *
+ * // 唯一注册（热点路径中多次调用也只注册一次）
+ * on('cache-cleared', handler, { unique: true });
+ *
+ * // 仅触发一次后自动移除
+ * on('ready', () => console.log('只执行一次'), { once: true });
+ * ```
+ */
+export declare function on(event: string, listener: (...args: any[]) => void, opts?: OnOptions): void;
+/**
+ * 移除事件监听器。
+ *
+ * - 传入 `listener` → 移除指定监听器（必须与注册时引用一致）
+ * - 不传 `listener` → 移除该事件下的全部监听器
+ *
+ * @example
+ * ```ts
+ * import { on, off } from 'baja-lite/event';
+ *
+ * const handler = (uid: string) => console.log(uid);
+ * on('user-login', handler);
+ *
+ * // 移除指定监听器
+ * off('user-login', handler);
+ *
+ * // 移除该事件下所有监听器
+ * off('user-login');
+ * ```
+ */
+export declare function off(event: string, listener?: (...args: any[]) => void): void;
+/**
+ * 触发事件。
+ *
+ * 通过 `opts` 控制广播范围：
+ * - `undefined`（默认）— 进程内 + 跨进程
+ * - `{ local: true }` — 仅本进程
+ * - `{ remote: true, local: false }` — 仅 Redis 广播到其他进程
+ *
+ * Redis 发布是 fire-and-forget，返回值仅反映**本进程**是否有监听器。
+ * 跨进程广播时参数需可 JSON 序列化（Function / Symbol 会被替换为 null）。
+ *
+ * @param event - 事件名
+ * @param args  - 传给监听器的参数数组
+ * @param opts  - 控制广播范围
+ * @returns 进程内是否有 listener
+ *
+ * @example
+ * ```ts
+ * import { on, trigger } from 'baja-lite/event';
+ *
+ * // PM2 4 进程全都收到
+ * trigger('order-paid', [orderId, amount]);
+ *
+ * // 仅本进程
+ * trigger('timer-tick', [Date.now()], { remote: false });
+ *
+ * // 仅通知其他进程
+ * trigger('cache-invalidated', ['user-list'], { local: false });
+ *
+ * // 无参数（默认全广播）
+ * trigger('reload-config');
+ * ```
+ */
+export declare function trigger(event: string, args?: any[], opts?: TriggerOptions): boolean;
+/**
+ * 初始化 Redis 事件订阅桥接器。
+ *
+ * 应在 `boot()` 完成后调用一次（多次调用安全，仅首次生效）。
+ * 若未连接 Redis，调用无副作用。
+ *
+ * **工作原理：**
+ * - 通过 `redis.duplicate()` 创建独立订阅连接（不影响主连接的命令操作）
+ * - 使用 `psubscribe` 订阅所有 `[event]*` 频道
+ * - 收到消息后校验 `__pid`：跳过自身发布的消息（本进程已通过本地 emit 处理）
+ * - 其余消息 deserialize 后 emit 到本地 EventBus
+ *
+ * @example
+ * ```ts
+ * import { boot } from 'baja-lite';
+ * import { initEventSubscriber } from 'baja-lite/event';
+ *
+ * await boot({ ... });
+ * await initEventSubscriber();
+ * ```
+ */
+export declare function initEventSubscriber(): Promise<void>;
 export {};

package/event.js

@@ -1,38 +1,229 @@
-export class EventBus {
-    constructor() {
-        this.all = new Map();
-    }
-    on(type, handler) {
-        let list = this.all.get(type);
-        if (!list)
-            this.all.set(type, (list = []));
-        list.push(handler);
-        return this;
-    }
-    once(type, handler) {
+import { _dao, _EventBus, _LoggerService, _primaryDB } from './const/symbols.js';
+import { DBType } from 'baja-lite-field';
+// ===== 常量 =====
+/** Redis 事件频道前缀，完整频道名 = `[event]` + 事件名 */
+const CHANNEL_PREFIX = '[event]';
+/** PSubscribe 匹配模式 */
+const SUBSCRIBE_PATTERN = `${CHANNEL_PREFIX}*`;
+/** 当前进程 pid，用于过滤自身发出的 Redis 消息 */
+const __pid = process.pid;
+/** 是否已执行过 initEventSubscriber */
+let _subscriberReady = false;
+// ===== 内部工具 =====
+function getEventBus() {
+    const bus = globalThis[_EventBus];
+    if (!bus) {
+        const logger = globalThis[_LoggerService];
+        logger?.warn?.('event-bus not initialized, did you forget to call boot()?');
+        throw new Error('EventBus not initialized. Please ensure boot() has been called before using event methods.');
+    }
+    return bus;
+}
+function getLogger() {
+    return globalThis[_LoggerService];
+}
+function getRedis() {
+    try {
+        return globalThis[_dao]?.[DBType.Redis]?.[_primaryDB];
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 将参数序列化为 Redis 消息（Function/Symbol 替换为 null，JSON 无法序列化的值跳过） */
+function safeArgs(args) {
+    return args.map(v => {
+        if (typeof v === 'function' || typeof v === 'symbol')
+            return null;
+        try {
+            JSON.stringify(v);
+            return v;
+        }
+        catch {
+            return null;
+        }
+    });
+}
+/** 构造 Redis 消息 */
+function packPayload(args) {
+    return JSON.stringify({ a: safeArgs(args), p: __pid });
+}
+// ===== 公共 API =====
+/**
+ * 注册事件监听器（进程级 + 跨进程）。
+ *
+ * 当前进程内通过 `trigger` 触发，或从同一 Redis 集群的其他进程广播而来，
+ * 均会调起此 listener。
+ *
+ * @param event       - 事件名
+ * @param listener    - 回调函数
+ * @param opts.unique - true 时若该事件已有监听器则跳过注册（防止热点路径中重复注册）
+ * @param opts.once   - true 时触发一次后自动移除（标准 once 语义）
+ *
+ * @example
+ * ```ts
+ * import { on } from 'baja-lite/event';
+ *
+ * // 普通注册（每次调用都会新增一个 listener）
+ * on('user-login', (uid: string, ts: number) => {
+ *     console.log(`用户 ${uid} 在 ${ts} 登录`);
+ * });
+ *
+ * // 唯一注册（热点路径中多次调用也只注册一次）
+ * on('cache-cleared', handler, { unique: true });
+ *
+ * // 仅触发一次后自动移除
+ * on('ready', () => console.log('只执行一次'), { once: true });
+ * ```
+ */
+export function on(event, listener, opts) {
+    const bus = getEventBus();
+    if (opts?.unique && bus.listenerCount(event) > 0)
+        return;
+    if (opts?.once) {
         const wrapper = (...args) => {
-            handler(...args);
-            this.off(type, wrapper);
+            bus.off(event, wrapper);
+            listener(...args);
         };
-        return this.on(type, wrapper);
-    }
-    off(type, handler) {
-        const list = this.all.get(type);
-        if (!list)
-            return this;
-        if (handler) {
-            const idx = list.indexOf(handler);
-            if (idx !== -1)
-                list.splice(idx, 1);
-        }
-        else {
-            this.all.delete(type);
+        bus.on(event, wrapper);
+    }
+    else {
+        bus.on(event, listener);
+    }
+}
+/**
+ * 移除事件监听器。
+ *
+ * - 传入 `listener` → 移除指定监听器（必须与注册时引用一致）
+ * - 不传 `listener` → 移除该事件下的全部监听器
+ *
+ * @example
+ * ```ts
+ * import { on, off } from 'baja-lite/event';
+ *
+ * const handler = (uid: string) => console.log(uid);
+ * on('user-login', handler);
+ *
+ * // 移除指定监听器
+ * off('user-login', handler);
+ *
+ * // 移除该事件下所有监听器
+ * off('user-login');
+ * ```
+ */
+export function off(event, listener) {
+    const bus = getEventBus();
+    if (listener) {
+        bus.off(event, listener);
+    }
+    else {
+        bus.removeAllListeners(event);
+    }
+}
+/**
+ * 触发事件。
+ *
+ * 通过 `opts` 控制广播范围：
+ * - `undefined`（默认）— 进程内 + 跨进程
+ * - `{ local: true }` — 仅本进程
+ * - `{ remote: true, local: false }` — 仅 Redis 广播到其他进程
+ *
+ * Redis 发布是 fire-and-forget，返回值仅反映**本进程**是否有监听器。
+ * 跨进程广播时参数需可 JSON 序列化（Function / Symbol 会被替换为 null）。
+ *
+ * @param event - 事件名
+ * @param args  - 传给监听器的参数数组
+ * @param opts  - 控制广播范围
+ * @returns 进程内是否有 listener
+ *
+ * @example
+ * ```ts
+ * import { on, trigger } from 'baja-lite/event';
+ *
+ * // PM2 4 进程全都收到
+ * trigger('order-paid', [orderId, amount]);
+ *
+ * // 仅本进程
+ * trigger('timer-tick', [Date.now()], { remote: false });
+ *
+ * // 仅通知其他进程
+ * trigger('cache-invalidated', ['user-list'], { local: false });
+ *
+ * // 无参数（默认全广播）
+ * trigger('reload-config');
+ * ```
+ */
+export function trigger(event, args, opts) {
+    const a = args ?? [];
+    const local = opts?.local ?? true;
+    const remote = opts?.remote ?? true;
+    if (remote) {
+        const redis = getRedis();
+        if (redis) {
+            redis.publish(`${CHANNEL_PREFIX}${event}`, packPayload(a)).catch((err) => {
+                getLogger()?.warn?.(`event publish "${event}" failed: ${err?.message ?? err}`);
+            });
         }
-        return this;
     }
-    emit(type, ...args) {
-        const list = this.all.get(type);
-        list?.slice().forEach(fn => fn(...args));
-        return this;
+    if (local) {
+        return getEventBus().emit(event, ...a);
+    }
+    return false;
+}
+/**
+ * 初始化 Redis 事件订阅桥接器。
+ *
+ * 应在 `boot()` 完成后调用一次（多次调用安全，仅首次生效）。
+ * 若未连接 Redis，调用无副作用。
+ *
+ * **工作原理：**
+ * - 通过 `redis.duplicate()` 创建独立订阅连接（不影响主连接的命令操作）
+ * - 使用 `psubscribe` 订阅所有 `[event]*` 频道
+ * - 收到消息后校验 `__pid`：跳过自身发布的消息（本进程已通过本地 emit 处理）
+ * - 其余消息 deserialize 后 emit 到本地 EventBus
+ *
+ * @example
+ * ```ts
+ * import { boot } from 'baja-lite';
+ * import { initEventSubscriber } from 'baja-lite/event';
+ *
+ * await boot({ ... });
+ * await initEventSubscriber();
+ * ```
+ */
+export async function initEventSubscriber() {
+    if (_subscriberReady)
+        return;
+    _subscriberReady = true;
+    const redis = getRedis();
+    if (!redis) {
+        getLogger()?.debug?.('event subscriber: Redis not configured, skip');
+        return;
+    }
+    try {
+        // duplicate() 基于同一套连接参数创建新实例，用于 subscribe 模式
+        const sub = typeof redis.duplicate === 'function'
+            ? redis.duplicate()
+            : redis;
+        sub.on('pmessage', (_pattern, channel, message) => {
+            try {
+                const payload = JSON.parse(message);
+                // 跳过自己发出去的消息（本进程已通过本地 emit 处理）
+                if (payload.p === __pid)
+                    return;
+                // 从频道名提取原始事件名：`[event]user-login` → `user-login`
+                const event = channel.slice(CHANNEL_PREFIX.length);
+                getEventBus().emit(event, ...(payload.a ?? []));
+            }
+            catch {
+                // 反序列化失败，静默丢弃
+            }
+        });
+        await sub.psubscribe(SUBSCRIBE_PATTERN);
+        getLogger()?.debug?.('event subscriber: Redis bridge ready');
+    }
+    catch (err) {
+        getLogger()?.warn?.(`event subscriber init failed: ${err?.message ?? err}`);
+        _subscriberReady = false; // 允许重试
     }
 }

package/package.json

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