@qimen-lab/core 0.1.1

package/dist/events/EventBus.esm.js

@@ -0,0 +1,177 @@
+import { EventScope } from './EventScope';
+import { string } from '@qimenjs/utils';
+/**
+ * 事件总线 - 用于管理事件订阅、发布和取消订阅的核心类
+ *
+ * EventBus 提供了一个基于事件驱动的通信机制，允许不同组件之间解耦合地进行通信。
+ * 它支持多种事件处理模式，包括一次性订阅、取消订阅等功能。
+ *
+ * @template Events 事件映射类型，定义了事件名称和载荷类型的对应关系
+ *
+ * @example
+ * ```ts
+ * // 定义事件类型
+ * type MyEvents = {
+ *   'user:login': { userId: string };
+ *   'user:logout': void;
+ * };
+ *
+ * // 创建事件总线实例
+ * const bus = new EventBus<MyEvents>();
+ *
+ * // 订阅事件
+ * const unsubscribe = bus.on('user:login', (payload) => {
+ *   console.log('用户登录:', payload.userId);
+ * });
+ *
+ * // 发布事件
+ * bus.emit('user:login', { userId: '123' });
+ *
+ * // 取消订阅
+ * unsubscribe();
+ * ```
+ */
+export class EventBus {
+    /**
+     * 构造函数
+     *
+     * @param logger - 可选的日志记录器，用于记录事件总线的操作日志
+     */
+    constructor(logger) {
+        this.logger = logger;
+        this.busId = string.getId();
+        this.listeners = new Map();
+    }
+    // --- 内置日志方法 ---
+    /**
+     * 记录事件总线相关的日志
+     *
+     * @param level - 日志级别
+     * @param action - 操作动作
+     * @param data - 附加数据
+     */
+    logBus(level, action, data) {
+        if (!this.logger)
+            return;
+        this.logger[level](`[event.bus] ${action}`, { busId: this.busId, ...data });
+    }
+    /**
+     * 记录事件相关的日志
+     *
+     * @param level - 日志级别
+     * @param action - 事件操作动作
+     * @param event - 事件名称
+     * @param data - 附加数据
+     */
+    logEvent(level, action, event, data) {
+        if (!this.logger)
+            return;
+        this.logger[level](`[event] ${action}`, { busId: this.busId, event, ...data });
+    }
+    // --- 事件订阅/触发 ---
+    /**
+     * 订阅事件
+     *
+     * 添加一个事件处理器，该处理器会在每次事件被触发时被调用。
+     *
+     * @param event - 事件名称
+     * @param handler - 事件处理器函数
+     * @returns 返回一个取消订阅的函数
+     */
+    on(event, handler) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(handler);
+        return () => {
+            set === null || set === void 0 ? void 0 : set.delete(handler);
+            if ((set === null || set === void 0 ? void 0 : set.size) === 0)
+                this.listeners.delete(event);
+        };
+    }
+    /**
+     * 一次性订阅事件
+     *
+     * 添加一个事件处理器，该处理器只会在事件第一次被触发时调用，之后自动取消订阅。
+     *
+     * @param event - 事件名称
+     * @param handler - 事件处理器函数
+     */
+    once(event, handler) {
+        const off = this.on(event, payload => {
+            off();
+            handler(payload);
+        });
+    }
+    /**
+     * 触发事件
+     *
+     * 将事件数据传递给所有订阅了该事件的处理器。
+     *
+     * @param event - 事件名称
+     * @param data - 事件数据载荷
+     * @param source - 事件源（可选）
+     * @param scopeId - 作用域ID（可选，默认为'NO_SCOPE'）
+     */
+    emit(event, data, source, scopeId = 'NO_SCOPE') {
+        var _a;
+        const context = {
+            event,
+            data,
+            source: source || 'UNKNOWN',
+            busId: this.busId,
+            scopeId,
+            timestamp: Date.now(),
+        };
+        const handlers = this.listeners.get(event);
+        if (!handlers || handlers.size === 0) {
+            this.logBus('debug', 'emit_no_listeners', { event: String(event) });
+            return;
+        }
+        this.logEvent('debug', 'emit', String(event), {
+            handlerCount: handlers.size,
+            source: (_a = context.source) === null || _a === void 0 ? void 0 : _a.constructor.name,
+        });
+        handlers.forEach(handler => {
+            try {
+                handler(context);
+            }
+            catch (err) {
+                this.logEvent('error', 'handler_error', String(event), { error: err });
+            }
+        });
+    }
+    /**
+     * 清理事件订阅
+     *
+     * @param event 可选参数，如果指定则只清理该事件的订阅，否则清理所有事件订阅
+     */
+    clear(event) {
+        if (event)
+            this.listeners.delete(event);
+        else
+            this.listeners.clear();
+        this.logBus('warn', 'clear', { event: event ? String(event) : 'all' });
+    }
+    /**
+     * 创建事件作用域
+     *
+     * 用于管理一组相关事件的生命周期
+     *
+     * @returns 返回一个EventScope实例
+     */
+    createScope() {
+        return new EventScope(this, this.logger);
+    }
+    /**
+     * 获取事件总线的唯一标识符
+     *
+     * @returns 返回事件总线的ID
+     */
+    getBusId() {
+        return this.busId;
+    }
+}
+//# sourceMappingURL=EventBus.js.map

package/dist/events/EventBus.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventBus.js","sourceRoot":"","sources":["../../../src/events/EventBus.ts"],"names":[],"mappings":"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"}

package/dist/events/EventBus.js

@@ -0,0 +1,181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventBus = void 0;
+const EventScope_1 = require("./EventScope");
+const utils_1 = require("@qimenjs/utils");
+/**
+ * 事件总线 - 用于管理事件订阅、发布和取消订阅的核心类
+ *
+ * EventBus 提供了一个基于事件驱动的通信机制，允许不同组件之间解耦合地进行通信。
+ * 它支持多种事件处理模式，包括一次性订阅、取消订阅等功能。
+ *
+ * @template Events 事件映射类型，定义了事件名称和载荷类型的对应关系
+ *
+ * @example
+ * ```ts
+ * // 定义事件类型
+ * type MyEvents = {
+ *   'user:login': { userId: string };
+ *   'user:logout': void;
+ * };
+ *
+ * // 创建事件总线实例
+ * const bus = new EventBus<MyEvents>();
+ *
+ * // 订阅事件
+ * const unsubscribe = bus.on('user:login', (payload) => {
+ *   console.log('用户登录:', payload.userId);
+ * });
+ *
+ * // 发布事件
+ * bus.emit('user:login', { userId: '123' });
+ *
+ * // 取消订阅
+ * unsubscribe();
+ * ```
+ */
+class EventBus {
+    /**
+     * 构造函数
+     *
+     * @param logger - 可选的日志记录器，用于记录事件总线的操作日志
+     */
+    constructor(logger) {
+        this.logger = logger;
+        this.busId = utils_1.string.getId();
+        this.listeners = new Map();
+    }
+    // --- 内置日志方法 ---
+    /**
+     * 记录事件总线相关的日志
+     *
+     * @param level - 日志级别
+     * @param action - 操作动作
+     * @param data - 附加数据
+     */
+    logBus(level, action, data) {
+        if (!this.logger)
+            return;
+        this.logger[level](`[event.bus] ${action}`, { busId: this.busId, ...data });
+    }
+    /**
+     * 记录事件相关的日志
+     *
+     * @param level - 日志级别
+     * @param action - 事件操作动作
+     * @param event - 事件名称
+     * @param data - 附加数据
+     */
+    logEvent(level, action, event, data) {
+        if (!this.logger)
+            return;
+        this.logger[level](`[event] ${action}`, { busId: this.busId, event, ...data });
+    }
+    // --- 事件订阅/触发 ---
+    /**
+     * 订阅事件
+     *
+     * 添加一个事件处理器，该处理器会在每次事件被触发时被调用。
+     *
+     * @param event - 事件名称
+     * @param handler - 事件处理器函数
+     * @returns 返回一个取消订阅的函数
+     */
+    on(event, handler) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(handler);
+        return () => {
+            set === null || set === void 0 ? void 0 : set.delete(handler);
+            if ((set === null || set === void 0 ? void 0 : set.size) === 0)
+                this.listeners.delete(event);
+        };
+    }
+    /**
+     * 一次性订阅事件
+     *
+     * 添加一个事件处理器，该处理器只会在事件第一次被触发时调用，之后自动取消订阅。
+     *
+     * @param event - 事件名称
+     * @param handler - 事件处理器函数
+     */
+    once(event, handler) {
+        const off = this.on(event, payload => {
+            off();
+            handler(payload);
+        });
+    }
+    /**
+     * 触发事件
+     *
+     * 将事件数据传递给所有订阅了该事件的处理器。
+     *
+     * @param event - 事件名称
+     * @param data - 事件数据载荷
+     * @param source - 事件源（可选）
+     * @param scopeId - 作用域ID（可选，默认为'NO_SCOPE'）
+     */
+    emit(event, data, source, scopeId = 'NO_SCOPE') {
+        var _a;
+        const context = {
+            event,
+            data,
+            source: source || 'UNKNOWN',
+            busId: this.busId,
+            scopeId,
+            timestamp: Date.now(),
+        };
+        const handlers = this.listeners.get(event);
+        if (!handlers || handlers.size === 0) {
+            this.logBus('debug', 'emit_no_listeners', { event: String(event) });
+            return;
+        }
+        this.logEvent('debug', 'emit', String(event), {
+            handlerCount: handlers.size,
+            source: (_a = context.source) === null || _a === void 0 ? void 0 : _a.constructor.name,
+        });
+        handlers.forEach(handler => {
+            try {
+                handler(context);
+            }
+            catch (err) {
+                this.logEvent('error', 'handler_error', String(event), { error: err });
+            }
+        });
+    }
+    /**
+     * 清理事件订阅
+     *
+     * @param event 可选参数，如果指定则只清理该事件的订阅，否则清理所有事件订阅
+     */
+    clear(event) {
+        if (event)
+            this.listeners.delete(event);
+        else
+            this.listeners.clear();
+        this.logBus('warn', 'clear', { event: event ? String(event) : 'all' });
+    }
+    /**
+     * 创建事件作用域
+     *
+     * 用于管理一组相关事件的生命周期
+     *
+     * @returns 返回一个EventScope实例
+     */
+    createScope() {
+        return new EventScope_1.EventScope(this, this.logger);
+    }
+    /**
+     * 获取事件总线的唯一标识符
+     *
+     * @returns 返回事件总线的ID
+     */
+    getBusId() {
+        return this.busId;
+    }
+}
+exports.EventBus = EventBus;
+//# sourceMappingURL=EventBus.js.map

package/dist/events/EventBus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventBus.js","sourceRoot":"","sources":["../../../src/events/EventBus.ts"],"names":[],"mappings":"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"}

package/dist/events/EventScope.d.ts

@@ -0,0 +1,104 @@
+import { EventBus } from './EventBus';
+import { EventHandler, IEventScope, ScopeLogAction } from './types';
+import { ILogger, LogLevel } from '@qimenjs/logger';
+/**
+ * 事件作用域 - 用于管理一组相关事件的生命周期
+ *
+ * EventScope 可以将多个事件订阅绑定到一个作用域中，当作用域被销毁时，
+ * 所有绑定到该作用域的事件订阅都会被自动取消，避免内存泄漏。
+ *
+ * @template Events 事件映射类型，定义了事件名称和载荷类型的对应关系
+ *
+ * @example
+ * ```ts
+ * const bus = new EventBus<MyEvents>();
+ * const scope = bus.createScope();
+ *
+ * // 使用作用域订阅事件
+ * scope.on('user:login', (payload) => {
+ *   console.log('用户登录:', payload.userId);
+ * });
+ *
+ * // 一次性订阅
+ * scope.once('user:logout', () => {
+ *   console.log('用户登出');
+ * });
+ *
+ * // 批量清理所有绑定到此作用域的事件订阅
+ * scope.dispose();
+ * ```
+ */
+export declare class EventScope implements IEventScope {
+    private readonly bus;
+    private readonly logger?;
+    private readonly scopeId;
+    private readonly disposers;
+    private disposed;
+    /**
+     * 构造函数
+     *
+     * @param bus - 关联的事件总线实例
+     * @param logger - 可选的日志记录器，用于记录事件作用域的操作日志
+     */
+    constructor(bus: EventBus, logger?: ILogger | undefined);
+    /**
+     * 记录作用域相关的日志
+     *
+     * @param level - 日志级别
+     * @param action - 作用域操作动作
+     * @param data - 附加数据
+     */
+    logScope(level: LogLevel, action: ScopeLogAction, data?: Record<string, any>): void;
+    /**
+     * 触发事件
+     *
+     * 在当前作用域上下文中触发一个事件，如果作用域已被销毁，则记录警告日志。
+     *
+     * @param event - 事件名称
+     * @param data - 事件数据
+     * @param source - 事件源，默认为'UNKNOWN'
+     */
+    emit(event: string, data?: any, source?: any): void;
+    /**
+     * 订阅事件
+     *
+     * 将事件处理器添加到事件总线并将其取消函数注册到当前作用域中，
+     * 当作用域被销毁时，这些事件处理器也会被自动取消订阅。
+     *
+     * @param event - 事件名称
+     * @param handler - 事件处理器函数
+     * @returns 返回一个取消订阅的函数
+     */
+    on(event: string, handler: EventHandler): () => void;
+    /**
+     * 一次性订阅事件
+     *
+     * 与 on 方法类似，但处理器只会在事件第一次被触发时调用，之后自动取消订阅。
+     *
+     * @param event - 事件名称
+     * @param handler - 事件处理器函数
+     */
+    once(event: string, handler: EventHandler): void;
+    /**
+     * 添加清理函数
+     *
+     * 将一个清理函数添加到作用域中，当作用域被销毁时，该函数会被调用。
+     *
+     * @param cleanup - 清理函数
+     */
+    addCleanup(cleanup: () => void): void;
+    /**
+     * 销毁作用域
+     *
+     * 执行所有注册的清理函数，释放资源并标记作用域为已销毁状态。
+     * 如果作用域已经被销毁，则记录调试日志。
+     */
+    dispose(): void;
+    /**
+     * 获取事件作用域的唯一标识符
+     *
+     * @returns 返回事件作用域的ID
+     */
+    getScopeId(): string;
+}
+//# sourceMappingURL=EventScope.d.ts.map

package/dist/events/EventScope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventScope.d.ts","sourceRoot":"","sources":["../../../src/events/EventScope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,YAAY,EAAiB,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEnF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAGpD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,UAAW,YAAW,WAAW;IAYtC,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAZ5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;IACvD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IACnD,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;;OAKG;gBAEkB,GAAG,EAAE,QAAQ,EACb,MAAM,CAAC,EAAE,OAAO,YAAA;IAOrC;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAS5E;;;;;;;;OAQG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,GAAG,GAAG,IAAI;IAQnD;;;;;;;;;OASG;IACH,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,MAAM,IAAI;IAWpD;;;;;;;OAOG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI;IAOhD;;;;;;OAMG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI;IAIrC;;;;;OAKG;IACH,OAAO,IAAI,IAAI;IAoBf;;;;OAIG;IACH,UAAU,IAAI,MAAM;CAGvB"}

package/dist/events/EventScope.esm.js

@@ -0,0 +1,153 @@
+import { string } from '@qimenjs/utils';
+/**
+ * 事件作用域 - 用于管理一组相关事件的生命周期
+ *
+ * EventScope 可以将多个事件订阅绑定到一个作用域中，当作用域被销毁时，
+ * 所有绑定到该作用域的事件订阅都会被自动取消，避免内存泄漏。
+ *
+ * @template Events 事件映射类型，定义了事件名称和载荷类型的对应关系
+ *
+ * @example
+ * ```ts
+ * const bus = new EventBus<MyEvents>();
+ * const scope = bus.createScope();
+ *
+ * // 使用作用域订阅事件
+ * scope.on('user:login', (payload) => {
+ *   console.log('用户登录:', payload.userId);
+ * });
+ *
+ * // 一次性订阅
+ * scope.once('user:logout', () => {
+ *   console.log('用户登出');
+ * });
+ *
+ * // 批量清理所有绑定到此作用域的事件订阅
+ * scope.dispose();
+ * ```
+ */
+export class EventScope {
+    /**
+     * 构造函数
+     *
+     * @param bus - 关联的事件总线实例
+     * @param logger - 可选的日志记录器，用于记录事件作用域的操作日志
+     */
+    constructor(bus, logger) {
+        this.bus = bus;
+        this.logger = logger;
+        this.scopeId = string.getId('event-scope');
+        this.disposers = [];
+        this.disposed = false;
+        this.logScope('debug', 'created');
+    }
+    // --- 内置日志方法 ---
+    /**
+     * 记录作用域相关的日志
+     *
+     * @param level - 日志级别
+     * @param action - 作用域操作动作
+     * @param data - 附加数据
+     */
+    logScope(level, action, data) {
+        if (!this.logger)
+            return;
+        this.logger[level](`[event.scope] ${action}`, {
+            busId: this.bus.getBusId(),
+            scopeId: this.scopeId,
+            ...data,
+        });
+    }
+    /**
+     * 触发事件
+     *
+     * 在当前作用域上下文中触发一个事件，如果作用域已被销毁，则记录警告日志。
+     *
+     * @param event - 事件名称
+     * @param data - 事件数据
+     * @param source - 事件源，默认为'UNKNOWN'
+     */
+    emit(event, data, source) {
+        if (this.disposed) {
+            this.logScope('warn', 'emit_after_dispose', { event: String(event) });
+            return;
+        }
+        this.bus.emit(event, data, source || this, this.scopeId);
+    }
+    /**
+     * 订阅事件
+     *
+     * 将事件处理器添加到事件总线并将其取消函数注册到当前作用域中，
+     * 当作用域被销毁时，这些事件处理器也会被自动取消订阅。
+     *
+     * @param event - 事件名称
+     * @param handler - 事件处理器函数
+     * @returns 返回一个取消订阅的函数
+     */
+    on(event, handler) {
+        if (this.disposed) {
+            this.logScope('warn', 'subscribe_after_dispose', { event: String(event) });
+            return () => { };
+        }
+        const off = this.bus.on(event, handler);
+        this.disposers.push(off);
+        return off;
+    }
+    /**
+     * 一次性订阅事件
+     *
+     * 与 on 方法类似，但处理器只会在事件第一次被触发时调用，之后自动取消订阅。
+     *
+     * @param event - 事件名称
+     * @param handler - 事件处理器函数
+     */
+    once(event, handler) {
+        const off = this.on(event, payload => {
+            off();
+            handler(payload);
+        });
+    }
+    /**
+     * 添加清理函数
+     *
+     * 将一个清理函数添加到作用域中，当作用域被销毁时，该函数会被调用。
+     *
+     * @param cleanup - 清理函数
+     */
+    addCleanup(cleanup) {
+        if (!this.disposed)
+            this.disposers.push(cleanup);
+    }
+    /**
+     * 销毁作用域
+     *
+     * 执行所有注册的清理函数，释放资源并标记作用域为已销毁状态。
+     * 如果作用域已经被销毁，则记录调试日志。
+     */
+    dispose() {
+        if (this.disposed) {
+            this.logScope('debug', 'dispose_twice');
+            return;
+        }
+        this.disposed = true;
+        this.disposers.forEach(fn => {
+            try {
+                fn();
+            }
+            catch (err) {
+                this.logScope('error', 'cleanup_error', { error: err });
+            }
+        });
+        this.disposers.length = 0;
+        this.logScope('info', 'disposed');
+    }
+    /**
+     * 获取事件作用域的唯一标识符
+     *
+     * @returns 返回事件作用域的ID
+     */
+    getScopeId() {
+        return this.scopeId;
+    }
+}
+//# sourceMappingURL=EventScope.js.map

package/dist/events/EventScope.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventScope.js","sourceRoot":"","sources":["../../../src/events/EventScope.ts"],"names":[],"mappings":"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"}