@dangao/bun-server 1.7.1 → 1.8.0

package/src/events/event-module.ts

@@ -0,0 +1,272 @@
+import 'reflect-metadata';
+import { Module, MODULE_METADATA_KEY, type ModuleProvider } from '../di/module';
+import type { Container } from '../di/container';
+import { ModuleRegistry } from '../di/module-registry';
+
+import { EventEmitterService } from './service';
+import { getOnEventMetadata, isEventListenerClass } from './decorators';
+import {
+  EVENT_EMITTER_TOKEN,
+  EVENT_OPTIONS_TOKEN,
+  type EventModuleOptions,
+  type EventEmitter,
+} from './types';
+
+/**
+ * 事件监听器扫描器
+ * 负责扫描和注册带有 @OnEvent() 装饰器的方法
+ */
+export class EventListenerScanner {
+  /**
+   * 构造函数
+   * @param eventEmitter - 事件发射器服务
+   * @param container - DI 容器
+   */
+  public constructor(
+    private readonly eventEmitter: EventEmitter,
+    private readonly container: Container,
+  ) {}
+
+  /**
+   * 扫描并注册监听器类
+   * @param listenerClasses - 监听器类数组
+   */
+  public scanAndRegister(listenerClasses: Function[]): void {
+    for (const listenerClass of listenerClasses) {
+      this.registerListenerClass(listenerClass);
+    }
+  }
+
+  /**
+   * 注册单个监听器类
+   * @param listenerClass - 监听器类
+   */
+  public registerListenerClass(listenerClass: Function): void {
+    if (!isEventListenerClass(listenerClass)) {
+      return;
+    }
+
+    const metadata = getOnEventMetadata(listenerClass);
+    if (!metadata || metadata.length === 0) {
+      return;
+    }
+
+    // 从容器获取监听器实例
+    const instance = this.container.resolve<Record<string, Function>>(
+      listenerClass as any,
+    );
+
+    if (!instance) {
+      console.warn(
+        `[EventModule] Failed to resolve listener class: ${listenerClass.name}. ` +
+          'Make sure it is registered as a provider.',
+      );
+      return;
+    }
+
+    // 注册所有监听器方法
+    for (const listenerMetadata of metadata) {
+      const method = instance[listenerMetadata.methodName];
+      if (typeof method !== 'function') {
+        console.warn(
+          `[EventModule] Method "${listenerMetadata.methodName}" not found on ${listenerClass.name}`,
+        );
+        continue;
+      }
+
+      // 绑定方法到实例
+      const boundMethod = method.bind(instance);
+
+      // 注册到事件发射器
+      this.eventEmitter.on(listenerMetadata.event, boundMethod, {
+        async: listenerMetadata.async,
+        priority: listenerMetadata.priority,
+      });
+    }
+  }
+}
+
+/**
+ * 事件监听器扫描器 Token
+ */
+export const EVENT_LISTENER_SCANNER_TOKEN = Symbol(
+  '@dangao/bun-server:events:scanner',
+);
+
+@Module({
+  providers: [],
+})
+export class EventModule {
+  /**
+   * 已注册的监听器类（用于模块初始化后扫描）
+   */
+  private static listenerClasses: Function[] = [];
+
+  /**
+   * 创建事件模块
+   * @param options - 模块配置
+   *
+   * @example
+   * ```typescript
+   * @Module({
+   *   imports: [
+   *     EventModule.forRoot({
+   *       wildcard: true,
+   *       maxListeners: 20,
+   *     }),
+   *   ],
+   *   providers: [NotificationService, AnalyticsService],
+   * })
+   * class AppModule {}
+   * ```
+   */
+  public static forRoot(options: EventModuleOptions = {}): typeof EventModule {
+    const providers: ModuleProvider[] = [];
+
+    // 创建事件发射器服务
+    const eventEmitter = new EventEmitterService(options);
+
+    // 注册选项
+    providers.push({
+      provide: EVENT_OPTIONS_TOKEN,
+      useValue: options,
+    });
+
+    // 注册事件发射器服务
+    providers.push({
+      provide: EVENT_EMITTER_TOKEN,
+      useValue: eventEmitter,
+    });
+
+    // 更新模块元数据
+    const existingMetadata =
+      Reflect.getMetadata(MODULE_METADATA_KEY, EventModule) || {};
+    const metadata = {
+      ...existingMetadata,
+      providers: [...(existingMetadata.providers || []), ...providers],
+      exports: [
+        ...(existingMetadata.exports || []),
+        EVENT_EMITTER_TOKEN,
+        EVENT_OPTIONS_TOKEN,
+      ],
+    };
+    Reflect.defineMetadata(MODULE_METADATA_KEY, metadata, EventModule);
+
+    // 清空监听器类列表
+    EventModule.listenerClasses = [];
+
+    return EventModule;
+  }
+
+  /**
+   * 注册监听器类
+   * 用于在模块配置后手动注册监听器类
+   *
+   * @param listenerClasses - 监听器类数组
+   *
+   * @example
+   * ```typescript
+   * EventModule.registerListeners([NotificationService, AnalyticsService]);
+   * ```
+   */
+  public static registerListeners(listenerClasses: Function[]): void {
+    EventModule.listenerClasses.push(...listenerClasses);
+  }
+
+  /**
+   * 初始化事件监听器扫描
+   * 在应用启动时调用，扫描并注册所有监听器
+   *
+   * @param listenerContainer - 用于解析监听器服务的 DI 容器（通常是应用模块的容器）
+   * @param additionalListeners - 额外的监听器类
+   *
+   * @example
+   * ```typescript
+   * // 在 registerModule 之后调用
+   * app.registerModule(RootModule);
+   *
+   * // 方式1：传入监听器所在模块的容器（推荐）
+   * const moduleRef = ModuleRegistry.getInstance().getModuleRef(RootModule);
+   * EventModule.initializeListeners(moduleRef?.container, [NotificationService]);
+   *
+   * // 方式2：如果监听器在 EventModule 的 providers 中注册，可以不传容器
+   * EventModule.initializeListeners(undefined, [NotificationService]);
+   * ```
+   */
+  public static initializeListeners(
+    listenerContainer?: Container,
+    additionalListeners: Function[] = [],
+  ): void {
+    // 从 EventModule 自身的容器获取 EventEmitter
+    const registry = ModuleRegistry.getInstance();
+    const eventModuleRef = registry.getModuleRef(EventModule);
+
+    let eventEmitter: EventEmitter | undefined;
+
+    if (eventModuleRef) {
+      try {
+        eventEmitter = eventModuleRef.container.resolve<EventEmitter>(EVENT_EMITTER_TOKEN);
+      } catch {
+        // 忽略错误
+      }
+    }
+
+    if (!eventEmitter) {
+      console.warn(
+        '[EventModule] EventEmitter not found. Make sure EventModule.forRoot() is called and the module is registered.',
+      );
+      return;
+    }
+
+    // 确定用于解析监听器的容器
+    // 优先使用传入的容器，否则使用 EventModule 的容器
+    const resolveContainer = listenerContainer ?? eventModuleRef?.container;
+
+    if (!resolveContainer) {
+      console.warn(
+        '[EventModule] No container available to resolve listeners.',
+      );
+      return;
+    }
+
+    const scanner = new EventListenerScanner(eventEmitter, resolveContainer);
+
+    // 扫描所有注册的监听器类
+    const allListeners = [
+      ...EventModule.listenerClasses,
+      ...additionalListeners,
+    ];
+    scanner.scanAndRegister(allListeners);
+  }
+
+  /**
+   * 获取事件发射器服务（静态方法）
+   * 用于在模块配置后获取事件发射器
+   *
+   * @param container - DI 容器（可选，如果不提供则从 EventModule 自身的容器获取）
+   */
+  public static getEventEmitter(container?: Container): EventEmitter | undefined {
+    // 优先从 EventModule 自身的容器获取
+    const registry = ModuleRegistry.getInstance();
+    const moduleRef = registry.getModuleRef(EventModule);
+
+    if (moduleRef) {
+      try {
+        return moduleRef.container.resolve<EventEmitter>(EVENT_EMITTER_TOKEN);
+      } catch {
+        // 忽略错误，尝试从传入的容器获取
+      }
+    }
+
+    // 尝试从传入的容器获取
+    if (container) {
+      try {
+        return container.resolve<EventEmitter>(EVENT_EMITTER_TOKEN);
+      } catch {
+        // 忽略错误
+      }
+    }
+
+    return undefined;
+  }
+}

package/src/events/index.ts

@@ -0,0 +1,32 @@
+// 类型导出
+export {
+  EVENT_EMITTER_TOKEN,
+  EVENT_OPTIONS_TOKEN,
+  ON_EVENT_METADATA_KEY,
+  EVENT_LISTENER_CLASS_METADATA_KEY,
+  type EventEmitter,
+  type EventListener,
+  type EventMetadata,
+  type EventModuleOptions,
+  type ListenerOptions,
+  type OnEventMethodMetadata,
+  type RegisteredListener,
+} from './types';
+
+// 服务导出
+export { EventEmitterService } from './service';
+
+// 装饰器导出
+export {
+  OnEvent,
+  getOnEventMetadata,
+  isEventListenerClass,
+  type OnEventOptions,
+} from './decorators';
+
+// 模块导出
+export {
+  EventModule,
+  EventListenerScanner,
+  EVENT_LISTENER_SCANNER_TOKEN,
+} from './event-module';

package/src/events/service.ts

@@ -0,0 +1,352 @@
+import type {
+  EventEmitter,
+  EventListener,
+  EventModuleOptions,
+  ListenerOptions,
+  RegisteredListener,
+} from './types';
+
+/**
+ * 事件发射器服务实现
+ */
+export class EventEmitterService implements EventEmitter {
+  /**
+   * 事件监听器映射
+   */
+  private listeners: Map<string | symbol, RegisteredListener[]> = new Map();
+
+  /**
+   * 模块选项
+   */
+  private options: EventModuleOptions;
+
+  /**
+   * 构造函数
+   * @param options - 模块选项
+   */
+  public constructor(options: EventModuleOptions = {}) {
+    this.options = {
+      wildcard: false,
+      delimiter: '.',
+      maxListeners: 10,
+      ...options,
+    };
+  }
+
+  /**
+   * 发布事件（同步触发所有监听器，不等待异步监听器完成）
+   */
+  public emit<T>(event: string | symbol, payload: T): void {
+    const eventName = this.resolveEventName(event);
+    const matchedListeners = this.getMatchedListeners(eventName);
+
+    if (matchedListeners.length === 0) {
+      return;
+    }
+
+    // 按优先级排序（高优先级先执行）
+    const sortedListeners = this.sortListenersByPriority(matchedListeners);
+
+    for (const { listener, once, async: isAsync } of sortedListeners) {
+      try {
+        const result = listener(payload);
+        // 如果监听器是异步的，不等待完成
+        if (isAsync && result instanceof Promise) {
+          result.catch((error) => {
+            this.handleError(error, eventName, payload);
+          });
+        }
+      } catch (error) {
+        this.handleError(error as Error, eventName, payload);
+      }
+
+      // 如果是一次性监听器，移除它
+      if (once) {
+        this.off(eventName, listener);
+      }
+    }
+  }
+
+  /**
+   * 异步发布事件（等待所有监听器完成）
+   */
+  public async emitAsync<T>(event: string | symbol, payload: T): Promise<void> {
+    const eventName = this.resolveEventName(event);
+    const matchedListeners = this.getMatchedListeners(eventName);
+
+    if (matchedListeners.length === 0) {
+      return;
+    }
+
+    // 按优先级排序（高优先级先执行）
+    const sortedListeners = this.sortListenersByPriority(matchedListeners);
+
+    const promises: Promise<void>[] = [];
+    const toRemove: EventListener[] = [];
+
+    for (const { listener, once } of sortedListeners) {
+      try {
+        const result = listener(payload);
+        if (result instanceof Promise) {
+          promises.push(
+            result.catch((error) => {
+              this.handleError(error, eventName, payload);
+            }),
+          );
+        }
+      } catch (error) {
+        this.handleError(error as Error, eventName, payload);
+      }
+
+      if (once) {
+        toRemove.push(listener);
+      }
+    }
+
+    // 等待所有异步监听器完成
+    if (promises.length > 0) {
+      await Promise.all(promises);
+    }
+
+    // 移除一次性监听器
+    for (const listener of toRemove) {
+      this.off(eventName, listener);
+    }
+  }
+
+  /**
+   * 订阅事件
+   */
+  public on<T>(
+    event: string | symbol,
+    listener: EventListener<T>,
+    options: ListenerOptions = {},
+  ): () => void {
+    const eventName = this.resolveEventName(event);
+    return this.addListener(eventName, listener, false, options);
+  }
+
+  /**
+   * 一次性订阅
+   */
+  public once<T>(
+    event: string | symbol,
+    listener: EventListener<T>,
+    options: ListenerOptions = {},
+  ): () => void {
+    const eventName = this.resolveEventName(event);
+    return this.addListener(eventName, listener, true, options);
+  }
+
+  /**
+   * 取消订阅
+   */
+  public off<T>(event: string | symbol, listener: EventListener<T>): void {
+    const eventName = this.resolveEventName(event);
+    const eventListeners = this.listeners.get(eventName);
+
+    if (!eventListeners) {
+      return;
+    }
+
+    const index = eventListeners.findIndex((l) => l.listener === listener);
+    if (index !== -1) {
+      eventListeners.splice(index, 1);
+    }
+
+    // 如果没有监听器了，移除事件
+    if (eventListeners.length === 0) {
+      this.listeners.delete(eventName);
+    }
+  }
+
+  /**
+   * 移除所有监听器
+   */
+  public removeAllListeners(event?: string | symbol): void {
+    if (event !== undefined) {
+      const eventName = this.resolveEventName(event);
+      this.listeners.delete(eventName);
+    } else {
+      this.listeners.clear();
+    }
+  }
+
+  /**
+   * 获取指定事件的监听器数量
+   */
+  public listenerCount(event: string | symbol): number {
+    const eventName = this.resolveEventName(event);
+    const matchedListeners = this.getMatchedListeners(eventName);
+    return matchedListeners.length;
+  }
+
+  /**
+   * 获取所有已注册的事件名称
+   */
+  public eventNames(): (string | symbol)[] {
+    return Array.from(this.listeners.keys());
+  }
+
+  /**
+   * 添加监听器
+   */
+  private addListener<T>(
+    event: string | symbol,
+    listener: EventListener<T>,
+    once: boolean,
+    options: ListenerOptions,
+  ): () => void {
+    let eventListeners = this.listeners.get(event);
+
+    if (!eventListeners) {
+      eventListeners = [];
+      this.listeners.set(event, eventListeners);
+    }
+
+    // 检查监听器数量限制
+    if (
+      this.options.maxListeners &&
+      eventListeners.length >= this.options.maxListeners
+    ) {
+      console.warn(
+        `[EventEmitter] Max listeners (${this.options.maxListeners}) exceeded for event: ${String(event)}. ` +
+          'This may indicate a memory leak.',
+      );
+    }
+
+    const registeredListener: RegisteredListener<T> = {
+      listener,
+      once,
+      priority: options.priority ?? 0,
+      async: options.async ?? false,
+    };
+
+    eventListeners.push(registeredListener as RegisteredListener);
+
+    // 返回取消订阅函数
+    return () => {
+      this.off(event, listener);
+    };
+  }
+
+  /**
+   * 解析事件名称（添加全局前缀）
+   */
+  private resolveEventName(event: string | symbol): string | symbol {
+    if (typeof event === 'symbol') {
+      return event;
+    }
+
+    if (this.options.globalPrefix) {
+      return `${this.options.globalPrefix}${this.options.delimiter}${event}`;
+    }
+
+    return event;
+  }
+
+  /**
+   * 获取匹配的监听器（支持通配符）
+   */
+  private getMatchedListeners(event: string | symbol): RegisteredListener[] {
+    const result: RegisteredListener[] = [];
+
+    // 精确匹配
+    const exactListeners = this.listeners.get(event);
+    if (exactListeners) {
+      result.push(...exactListeners);
+    }
+
+    // 通配符匹配
+    if (this.options.wildcard && typeof event === 'string') {
+      const delimiter = this.options.delimiter ?? '.';
+      const eventParts = event.split(delimiter);
+
+      for (const [key, listeners] of this.listeners.entries()) {
+        if (typeof key !== 'string' || key === event) {
+          continue;
+        }
+
+        if (this.matchWildcard(eventParts, key.split(delimiter))) {
+          result.push(...listeners);
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * 匹配通配符模式
+   */
+  private matchWildcard(eventParts: string[], patternParts: string[]): boolean {
+    let eventIndex = 0;
+    let patternIndex = 0;
+
+    while (patternIndex < patternParts.length) {
+      const pattern = patternParts[patternIndex];
+
+      if (pattern === '**') {
+        // ** 匹配任意数量的部分
+        if (patternIndex === patternParts.length - 1) {
+          return true; // ** 在末尾，匹配所有剩余部分
+        }
+        // 尝试匹配后续部分
+        for (let i = eventIndex; i <= eventParts.length; i++) {
+          if (
+            this.matchWildcard(
+              eventParts.slice(i),
+              patternParts.slice(patternIndex + 1),
+            )
+          ) {
+            return true;
+          }
+        }
+        return false;
+      } else if (pattern === '*') {
+        // * 匹配单个部分
+        if (eventIndex >= eventParts.length) {
+          return false;
+        }
+        eventIndex++;
+        patternIndex++;
+      } else {
+        // 精确匹配
+        if (eventIndex >= eventParts.length || eventParts[eventIndex] !== pattern) {
+          return false;
+        }
+        eventIndex++;
+        patternIndex++;
+      }
+    }
+
+    return eventIndex === eventParts.length;
+  }
+
+  /**
+   * 按优先级排序监听器
+   */
+  private sortListenersByPriority(
+    listeners: RegisteredListener[],
+  ): RegisteredListener[] {
+    return [...listeners].sort((a, b) => b.priority - a.priority);
+  }
+
+  /**
+   * 处理错误
+   */
+  private handleError(
+    error: Error,
+    event: string | symbol,
+    payload: unknown,
+  ): void {
+    if (this.options.onError) {
+      this.options.onError(error, event, payload);
+    } else {
+      console.error(
+        `[EventEmitter] Error in listener for event "${String(event)}":`,
+        error,
+      );
+    }
+  }
+}