@dangao/bun-server 1.7.0 → 1.8.0

package/src/di/container.ts

@@ -1,6 +1,8 @@
 import "reflect-metadata";
 import {
   type DependencyMetadata,
+  type InstancePostProcessor,
+  INSTANCE_POST_PROCESSOR_TOKEN,
   Lifecycle,
   type ProviderConfig,
 } from "./types";
@@ -59,6 +61,11 @@ export class Container {
     DependencyPlan
   >();
 
+  /**
+   * 实例后处理器列表
+   */
+  private readonly postProcessors: InstancePostProcessor[] = [];
+
   /**
    * 注册提供者
    * @param token - 提供者标识符（类构造函数或 token）
@@ -112,6 +119,45 @@ export class Container {
     });
   }
 
+  /**
+   * 注册实例后处理器
+   * @param processor - 后处理器实例
+   */
+  public registerPostProcessor(processor: InstancePostProcessor): void {
+    this.postProcessors.push(processor);
+    // 按优先级排序（数字越小优先级越高）
+    this.postProcessors.sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
+  }
+
+  /**
+   * 应用所有后处理器（包括父容器的后处理器）
+   * @param instance - 原始实例
+   * @param constructor - 构造函数
+   * @param originContainer - 原始调用容器（用于后处理器解析依赖）
+   * @returns 处理后的实例
+   */
+  private applyPostProcessors<T>(
+    instance: T,
+    constructor: Constructor<T>,
+    originContainer?: Container,
+  ): T {
+    // 使用原始容器或当前容器
+    const containerForProcessors = originContainer ?? this;
+    let result = instance;
+
+    // 先应用父容器的后处理器
+    if (this.parent) {
+      result = (this.parent as Container).applyPostProcessors(result, constructor, containerForProcessors);
+    }
+
+    // 再应用本容器的后处理器
+    // 传递原始调用容器，而不是当前容器
+    for (const processor of this.postProcessors) {
+      result = processor.postProcess(result, constructor, containerForProcessors);
+    }
+    return result;
+  }
+
   /**
    * 解析依赖
    * @param token - 提供者标识符
@@ -321,16 +367,19 @@ export class Container {
   private instantiate<T>(constructor: Constructor<T>): T {
     const plan = this.getDependencyPlan(constructor);
 
+    let instance: T;
     if (plan.paramLength === 0) {
-      return new constructor();
-    }
-
-    const dependencies = new Array(plan.paramLength);
-    for (let index = 0; index < plan.paramLength; index++) {
-      dependencies[index] = this.resolveFromPlan(constructor, plan, index);
+      instance = new constructor();
+    } else {
+      const dependencies = new Array(plan.paramLength);
+      for (let index = 0; index < plan.paramLength; index++) {
+        dependencies[index] = this.resolveFromPlan(constructor, plan, index);
+      }
+      instance = new constructor(...dependencies);
     }
 
-    return new constructor(...dependencies);
+    // 应用后处理器
+    return this.applyPostProcessors(instance, constructor);
   }
 
   /**
@@ -356,6 +405,7 @@ export class Container {
     this.singletons.clear();
     this.typeToToken.clear();
     this.dependencyPlans.clear();
+    this.postProcessors.length = 0;
     // scopedInstances 使用 WeakMap，当 Context 对象被 GC 时会自动清理
   }
 

package/src/di/decorators.ts

@@ -9,6 +9,11 @@ import type { Constructor } from "@/core/types";
 const DEPENDENCY_METADATA_KEY = Symbol("dependency:metadata");
 const INJECTABLE_METADATA_KEY = Symbol("injectable");
 
+/**
+ * 全局模块元数据键
+ */
+export const GLOBAL_MODULE_METADATA_KEY = Symbol("@dangao/bun-server:global-module");
+
 /**
  * 类型引用映射（用于保存构造函数类型，避免 Reflect.defineMetadata 序列化问题）
  */
@@ -226,3 +231,44 @@ export function getTypeReference(
   }
   return undefined as unknown as Constructor<unknown>;
 }
+
+/**
+ * Global 装饰器
+ * 标记模块为全局模块，其导出的提供者可在任何模块中使用，无需显式导入
+ *
+ * @example
+ * ```typescript
+ * @Global()
+ * @Module({
+ *   providers: [ConfigService],
+ *   exports: [ConfigService],
+ * })
+ * class GlobalConfigModule {}
+ *
+ * // 其他模块无需导入 GlobalConfigModule 即可使用 ConfigService
+ * @Module({
+ *   controllers: [UserController],
+ *   providers: [UserService],
+ * })
+ * class UserModule {}
+ *
+ * @Injectable()
+ * class UserService {
+ *   constructor(private readonly config: ConfigService) {}
+ * }
+ * ```
+ */
+export function Global(): ClassDecorator {
+  return (target) => {
+    Reflect.defineMetadata(GLOBAL_MODULE_METADATA_KEY, true, target);
+  };
+}
+
+/**
+ * 检查模块是否为全局模块
+ * @param target - 目标模块类
+ * @returns 是否为全局模块
+ */
+export function isGlobalModule(target: Constructor<unknown>): boolean {
+  return Reflect.getMetadata(GLOBAL_MODULE_METADATA_KEY, target) === true;
+}

package/src/di/index.ts

@@ -1,4 +1,19 @@
 export { Container } from './container';
-export { Injectable, Inject, getDependencyMetadata, isInjectable, getLifecycle } from './decorators';
-export { Lifecycle, type ProviderConfig, type DependencyMetadata } from './types';
+export {
+  Injectable,
+  Inject,
+  getDependencyMetadata,
+  isInjectable,
+  getLifecycle,
+  Global,
+  isGlobalModule,
+  GLOBAL_MODULE_METADATA_KEY,
+} from './decorators';
+export {
+  Lifecycle,
+  INSTANCE_POST_PROCESSOR_TOKEN,
+  type ProviderConfig,
+  type DependencyMetadata,
+  type InstancePostProcessor,
+} from './types';
 

package/src/di/module-registry.ts

@@ -2,6 +2,7 @@ import { ControllerRegistry } from '../controller/controller';
 import { Container } from './container';
 import { Lifecycle } from './types';
 import { getModuleMetadata, type ModuleClass, type ModuleProvider, type ProviderToken } from './module';
+import { isGlobalModule } from './decorators';
 import type { Constructor } from '@/core/types';
 import type { ApplicationExtension } from '../extensions/types';
 import type { Middleware } from '../middleware';
@@ -14,6 +15,10 @@ interface ModuleRef {
   attachedParents: Set<Container>;
   extensions: ApplicationExtension[];
   middlewares: Middleware[];
+  /**
+   * 是否为全局模块
+   */
+  isGlobal: boolean;
 }
 
 export class ModuleRegistry {
@@ -21,6 +26,10 @@ export class ModuleRegistry {
   private readonly moduleRefs = new Map<ModuleClass, ModuleRef>();
   private readonly processing = new Set<ModuleClass>();
   private rootContainer?: Container;
+  /**
+   * 存储全局模块列表，用于在其他模块注册时自动附加全局 exports
+   */
+  private readonly globalModules = new Set<ModuleClass>();
 
   public static getInstance(): ModuleRegistry {
     if (!ModuleRegistry.instance) {
@@ -43,9 +52,17 @@ export class ModuleRegistry {
   public clear(): void {
     this.moduleRefs.clear();
     this.processing.clear();
+    this.globalModules.clear();
     this.rootContainer = undefined;
   }
 
+  /**
+   * 获取所有全局模块
+   */
+  public getGlobalModules(): ModuleClass[] {
+    return Array.from(this.globalModules);
+  }
+
   private processModule(moduleClass: ModuleClass, parentContainer: Container): ModuleRef {
     if (this.processing.has(moduleClass)) {
       throw new Error(`Circular module dependency detected for ${moduleClass.name}`);
@@ -69,6 +86,7 @@ export class ModuleRegistry {
       throw new Error('ModuleRegistry is not initialized with a root container');
     }
     const metadata = getModuleMetadata(moduleClass);
+    const isGlobal = isGlobalModule(moduleClass);
     const container = new Container({ parent: this.rootContainer });
     this.registerProviders(container, metadata.providers);
     ref = {
@@ -79,12 +97,33 @@ export class ModuleRegistry {
       attachedParents: new Set<Container>(),
       extensions: metadata.extensions ?? [],
       middlewares: metadata.middlewares ?? [],
+      isGlobal,
     };
     this.registerControllers(ref);
     this.moduleRefs.set(moduleClass, ref);
+
+    // 如果是全局模块，注册到根容器并记录
+    if (isGlobal) {
+      this.globalModules.add(moduleClass);
+      this.registerGlobalExports(ref);
+    }
+
     return ref;
   }
 
+  /**
+   * 将全局模块的 exports 注册到根容器
+   * 这样所有模块都可以访问全局模块导出的提供者
+   */
+  private registerGlobalExports(moduleRef: ModuleRef): void {
+    if (!this.rootContainer) {
+      return;
+    }
+    for (const exportedToken of moduleRef.metadata.exports) {
+      this.registerExport(this.rootContainer, moduleRef, exportedToken);
+    }
+  }
+
   private registerProviders(container: Container, providers: ModuleProvider[]): void {
     for (const provider of providers) {
       if (typeof provider === 'function') {

package/src/di/types.ts

@@ -1,5 +1,34 @@
 import type { Constructor } from '@/core/types'
 
+/**
+ * 实例后处理器接口
+ * 用于在 DI 容器创建实例后进行处理（如创建代理、注入额外依赖等）
+ */
+export interface InstancePostProcessor {
+  /**
+   * 处理新创建的实例
+   * @param instance - 原始实例
+   * @param constructor - 构造函数
+   * @param container - DI 容器引用
+   * @returns 处理后的实例（可以是代理）
+   */
+  postProcess<T>(
+    instance: T,
+    constructor: Constructor<T>,
+    container: unknown,
+  ): T;
+
+  /**
+   * 优先级（数字越小优先级越高，默认 100）
+   */
+  priority?: number;
+}
+
+/**
+ * 实例后处理器注册表 Token
+ */
+export const INSTANCE_POST_PROCESSOR_TOKEN = Symbol('@dangao/bun-server:di:post-processor');
+
 /**
  * 依赖生命周期类型
  */

package/src/events/decorators.ts

@@ -0,0 +1,103 @@
+import 'reflect-metadata';
+import {
+  ON_EVENT_METADATA_KEY,
+  EVENT_LISTENER_CLASS_METADATA_KEY,
+  type OnEventMethodMetadata,
+} from './types';
+
+/**
+ * OnEvent 装饰器选项
+ */
+export interface OnEventOptions {
+  /**
+   * 是否异步处理
+   * @default false
+   */
+  async?: boolean;
+
+  /**
+   * 监听器优先级（数值越大优先级越高）
+   * @default 0
+   */
+  priority?: number;
+}
+
+/**
+ * 事件监听器装饰器
+ * 用于标记方法为事件监听器
+ *
+ * @param event - 事件名称或标识符
+ * @param options - 监听选项
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * class NotificationService {
+ *   @OnEvent('user.created')
+ *   handleUserCreated(payload: UserCreatedEvent) {
+ *     console.log('User created:', payload.userId);
+ *   }
+ *
+ *   @OnEvent(USER_DELETED, { async: true, priority: 10 })
+ *   async handleUserDeleted(payload: UserDeletedEvent) {
+ *     await this.cleanup(payload.userId);
+ *   }
+ * }
+ * ```
+ */
+export function OnEvent(
+  event: string | symbol,
+  options: OnEventOptions = {},
+): MethodDecorator {
+  return (
+    target: object,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor,
+  ): PropertyDescriptor => {
+    const methodName = String(propertyKey);
+    const constructor = target.constructor;
+
+    // 获取类上已有的事件监听器元数据
+    const existingMetadata: OnEventMethodMetadata[] =
+      Reflect.getMetadata(ON_EVENT_METADATA_KEY, constructor) || [];
+
+    // 添加新的监听器元数据
+    const metadata: OnEventMethodMetadata = {
+      methodName,
+      event,
+      async: options.async ?? false,
+      priority: options.priority ?? 0,
+    };
+
+    Reflect.defineMetadata(
+      ON_EVENT_METADATA_KEY,
+      [...existingMetadata, metadata],
+      constructor,
+    );
+
+    // 标记类为事件监听器类
+    Reflect.defineMetadata(EVENT_LISTENER_CLASS_METADATA_KEY, true, constructor);
+
+    return descriptor;
+  };
+}
+
+/**
+ * 获取类的事件监听器元数据
+ * @param target - 目标类
+ */
+export function getOnEventMetadata(
+  target: Function,
+): OnEventMethodMetadata[] | undefined {
+  return Reflect.getMetadata(ON_EVENT_METADATA_KEY, target);
+}
+
+/**
+ * 检查类是否为事件监听器类
+ * @param target - 目标类
+ */
+export function isEventListenerClass(target: Function): boolean {
+  return (
+    Reflect.getMetadata(EVENT_LISTENER_CLASS_METADATA_KEY, target) === true
+  );
+}

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';