@dangao/bun-server 1.9.0 → 1.12.0

package/src/di/async-module.ts

@@ -0,0 +1,141 @@
+import type { ModuleClass, ModuleProvider, ProviderToken } from './module';
+import { MODULE_METADATA_KEY } from './module';
+import type { Container } from './container';
+import { ModuleRegistry } from './module-registry';
+
+/**
+ * 异步模块配置选项
+ */
+export interface AsyncModuleOptions<T> {
+  /**
+   * 需要导入的模块（提供 inject 依赖的来源）
+   */
+  imports?: ModuleClass[];
+  /**
+   * 要注入到 useFactory 中的 provider tokens
+   */
+  inject?: ProviderToken[];
+  /**
+   * 异步工厂函数，返回模块配置
+   */
+  useFactory: (...deps: unknown[]) => T | Promise<T>;
+}
+
+/**
+ * 异步 provider 注册表
+ * 在 Application.listen() 期间，所有待初始化的异步 provider 将被顺序执行
+ */
+export class AsyncProviderRegistry {
+  private static instance: AsyncProviderRegistry;
+  private readonly pendingFactories: Array<{
+    token: ProviderToken;
+    factory: (container: Container) => Promise<unknown>;
+  }> = [];
+
+  public static getInstance(): AsyncProviderRegistry {
+    if (!AsyncProviderRegistry.instance) {
+      AsyncProviderRegistry.instance = new AsyncProviderRegistry();
+    }
+    return AsyncProviderRegistry.instance;
+  }
+
+  /**
+   * 注册一个异步 provider
+   */
+  public register(
+    token: ProviderToken,
+    factory: (container: Container) => Promise<unknown>,
+  ): void {
+    this.pendingFactories.push({ token, factory });
+  }
+
+  /**
+   * 初始化所有异步 providers
+   * 同时注册到根容器和所有模块子容器（覆盖占位 factory）
+   * @param container - 根 DI 容器
+   */
+  public async initializeAll(container: Container): Promise<void> {
+    const moduleContainers = ModuleRegistry.getInstance().getAllModuleContainers();
+
+    for (const { token, factory } of this.pendingFactories) {
+      const value = await factory(container);
+      container.registerInstance(token, value);
+
+      for (const moduleContainer of moduleContainers) {
+        if (moduleContainer.isRegistered(token)) {
+          moduleContainer.registerInstance(token, value);
+        }
+      }
+    }
+    this.pendingFactories.length = 0;
+  }
+
+  /**
+   * 检查是否有待初始化的异步 providers
+   */
+  public hasPending(): boolean {
+    return this.pendingFactories.length > 0;
+  }
+
+  public clear(): void {
+    this.pendingFactories.length = 0;
+  }
+}
+
+/**
+ * 辅助函数：为模块添加 forRootAsync 的标准实现
+ * 各模块可直接在 forRootAsync 中调用此函数
+ */
+export function registerAsyncProviders<T>(
+  moduleClass: ModuleClass,
+  asyncOptions: AsyncModuleOptions<T>,
+  tokenMap: Map<ProviderToken, (config: T) => unknown>,
+  extraProviders?: ModuleProvider[],
+): typeof moduleClass {
+  const providers: ModuleProvider[] = [];
+  const exports: ProviderToken[] = [];
+
+  for (const [token] of tokenMap) {
+    // Placeholder factory that will be resolved async during init
+    providers.push({
+      provide: token,
+      useFactory: () => {
+        throw new Error(
+          `Async provider ${String(token)} not yet initialized. ` +
+          'Ensure Application.listen() is called before resolving async providers.',
+        );
+      },
+    });
+    exports.push(token);
+  }
+
+  if (extraProviders) {
+    providers.push(...extraProviders);
+  }
+
+  // Register the async factory
+  const registry = AsyncProviderRegistry.getInstance();
+  for (const [token, mapper] of tokenMap) {
+    registry.register(token, async (container) => {
+      const deps: unknown[] = [];
+      if (asyncOptions.inject) {
+        for (const injectToken of asyncOptions.inject) {
+          deps.push(container.resolve(injectToken as any));
+        }
+      }
+      const config = await asyncOptions.useFactory(...deps);
+      return mapper(config);
+    });
+  }
+
+  const existingMetadata = Reflect.getMetadata(MODULE_METADATA_KEY, moduleClass) || {};
+  const metadata = {
+    ...existingMetadata,
+    imports: [...(existingMetadata.imports || []), ...(asyncOptions.imports || [])],
+    providers: [...(existingMetadata.providers || []), ...providers],
+    exports: [...(existingMetadata.exports || []), ...exports],
+  };
+  Reflect.defineMetadata(MODULE_METADATA_KEY, metadata, moduleClass);
+
+  return moduleClass;
+}

package/src/di/lifecycle.ts

@@ -0,0 +1,117 @@
+/**
+ * 模块初始化钩子
+ * 在模块所有 providers 注册完成后调用
+ */
+export interface OnModuleInit {
+  onModuleInit(): Promise<void> | void;
+}
+
+/**
+ * 模块销毁钩子
+ * 在应用关闭时调用（反向顺序）
+ */
+export interface OnModuleDestroy {
+  onModuleDestroy(): Promise<void> | void;
+}
+
+/**
+ * 应用启动钩子
+ * 在所有模块初始化完成后、服务器开始监听前调用
+ */
+export interface OnApplicationBootstrap {
+  onApplicationBootstrap(): Promise<void> | void;
+}
+
+/**
+ * 应用关闭钩子
+ * 在优雅停机开始时调用
+ */
+export interface OnApplicationShutdown {
+  onApplicationShutdown(signal?: string): Promise<void> | void;
+}
+
+export function hasOnModuleInit(instance: unknown): instance is OnModuleInit {
+  return (
+    instance !== null &&
+    instance !== undefined &&
+    typeof instance === 'object' &&
+    'onModuleInit' in instance &&
+    typeof (instance as OnModuleInit).onModuleInit === 'function'
+  );
+}
+
+export function hasOnModuleDestroy(instance: unknown): instance is OnModuleDestroy {
+  return (
+    instance !== null &&
+    instance !== undefined &&
+    typeof instance === 'object' &&
+    'onModuleDestroy' in instance &&
+    typeof (instance as OnModuleDestroy).onModuleDestroy === 'function'
+  );
+}
+
+export function hasOnApplicationBootstrap(instance: unknown): instance is OnApplicationBootstrap {
+  return (
+    instance !== null &&
+    instance !== undefined &&
+    typeof instance === 'object' &&
+    'onApplicationBootstrap' in instance &&
+    typeof (instance as OnApplicationBootstrap).onApplicationBootstrap === 'function'
+  );
+}
+
+export function hasOnApplicationShutdown(instance: unknown): instance is OnApplicationShutdown {
+  return (
+    instance !== null &&
+    instance !== undefined &&
+    typeof instance === 'object' &&
+    'onApplicationShutdown' in instance &&
+    typeof (instance as OnApplicationShutdown).onApplicationShutdown === 'function'
+  );
+}
+
+/**
+ * 按顺序调用 onModuleInit
+ */
+export async function callOnModuleInit(instances: unknown[]): Promise<void> {
+  for (const instance of instances) {
+    if (hasOnModuleInit(instance)) {
+      await instance.onModuleInit();
+    }
+  }
+}
+
+/**
+ * 按顺序调用 onApplicationBootstrap
+ */
+export async function callOnApplicationBootstrap(instances: unknown[]): Promise<void> {
+  for (const instance of instances) {
+    if (hasOnApplicationBootstrap(instance)) {
+      await instance.onApplicationBootstrap();
+    }
+  }
+}
+
+/**
+ * 按反向顺序调用 onModuleDestroy
+ */
+export async function callOnModuleDestroy(instances: unknown[]): Promise<void> {
+  for (let i = instances.length - 1; i >= 0; i--) {
+    const instance = instances[i];
+    if (hasOnModuleDestroy(instance)) {
+      await instance.onModuleDestroy();
+    }
+  }
+}
+
+/**
+ * 按反向顺序调用 onApplicationShutdown
+ */
+export async function callOnApplicationShutdown(instances: unknown[], signal?: string): Promise<void> {
+  for (let i = instances.length - 1; i >= 0; i--) {
+    const instance = instances[i];
+    if (hasOnApplicationShutdown(instance)) {
+      await instance.onApplicationShutdown(signal);
+    }
+  }
+}

package/src/di/module-registry.ts

@@ -6,6 +6,12 @@ import { isGlobalModule } from './decorators';
 import type { Constructor } from '@/core/types';
 import type { ApplicationExtension } from '../extensions/types';
 import type { Middleware } from '../middleware';
+import {
+  callOnModuleInit,
+  callOnModuleDestroy,
+  callOnApplicationBootstrap,
+  callOnApplicationShutdown,
+} from './lifecycle';
 
 interface ModuleRef {
   moduleClass: ModuleClass;
@@ -49,6 +55,17 @@ export class ModuleRegistry {
     return this.moduleRefs.get(moduleClass);
   }
 
+  /**
+   * 获取所有模块的子容器（用于异步 provider 初始化）
+   */
+  public getAllModuleContainers(): Container[] {
+    const containers: Container[] = [];
+    for (const [, ref] of this.moduleRefs) {
+      containers.push(ref.container);
+    }
+    return containers;
+  }
+
   public clear(): void {
     this.moduleRefs.clear();
     this.processing.clear();
@@ -207,6 +224,64 @@ export class ModuleRegistry {
     return moduleRef.middlewares;
   }
 
+  /**
+   * 解析所有模块中的 provider 实例，用于生命周期钩子调用
+   */
+  public resolveAllProviderInstances(): unknown[] {
+    const instances: unknown[] = [];
+    for (const [, ref] of this.moduleRefs) {
+      for (const provider of ref.metadata.providers) {
+        try {
+          if (typeof provider === 'function') {
+            instances.push(ref.container.resolve(provider));
+          } else if ('useClass' in provider) {
+            const token = provider.provide ?? provider.useClass;
+            instances.push(ref.container.resolve(token as Constructor<unknown>));
+          } else if ('useValue' in provider) {
+            instances.push(provider.useValue);
+          } else if ('useFactory' in provider) {
+            instances.push(ref.container.resolve(provider.provide as Constructor<unknown>));
+          }
+        } catch {
+          // skip providers that can't be resolved (e.g. pending async providers)
+        }
+      }
+    }
+    return instances;
+  }
+
+  /**
+   * 调用所有 provider 的 onModuleInit 钩子
+   */
+  public async callModuleInitHooks(): Promise<void> {
+    const instances = this.resolveAllProviderInstances();
+    await callOnModuleInit(instances);
+  }
+
+  /**
+   * 调用所有 provider 的 onApplicationBootstrap 钩子
+   */
+  public async callBootstrapHooks(): Promise<void> {
+    const instances = this.resolveAllProviderInstances();
+    await callOnApplicationBootstrap(instances);
+  }
+
+  /**
+   * 调用所有 provider 的 onModuleDestroy 钩子
+   */
+  public async callModuleDestroyHooks(): Promise<void> {
+    const instances = this.resolveAllProviderInstances();
+    await callOnModuleDestroy(instances);
+  }
+
+  /**
+   * 调用所有 provider 的 onApplicationShutdown 钩子
+   */
+  public async callShutdownHooks(signal?: string): Promise<void> {
+    const instances = this.resolveAllProviderInstances();
+    await callOnApplicationShutdown(instances, signal);
+  }
+
   private registerExport(parentContainer: Container, moduleRef: ModuleRef, token: ProviderToken): void {
     if (!moduleRef.container.isRegistered(token)) {
       throw new Error(

package/src/index.ts

@@ -1,5 +1,7 @@
 export { Application, type ApplicationOptions } from './core/application';
+export { applyDecorators } from './core/apply-decorators';
 export { BunServer, type ServerOptions } from './core/server';
+export { ClusterManager, type ClusterOptions } from './core/cluster';
 export { Context } from './core/context';
 export { ContextService, CONTEXT_SERVICE_TOKEN, contextStore } from './core/context-service';
 export { Route, Router, RouteRegistry } from './router';
@@ -34,6 +36,13 @@ export {
   type ModuleClass,
 } from './di/module';
 export { ModuleRegistry } from './di/module-registry';
+export { AsyncProviderRegistry, type AsyncModuleOptions } from './di/async-module';
+export type {
+  OnModuleInit,
+  OnModuleDestroy,
+  OnApplicationBootstrap,
+  OnApplicationShutdown,
+} from './di/lifecycle';
 export {
   InterceptorRegistry,
   InterceptorChain,
@@ -271,6 +280,12 @@ export {
   HEALTH_INDICATORS_TOKEN,
   HEALTH_OPTIONS_TOKEN,
 } from './health';
+export {
+  DashboardModule,
+  DashboardService,
+  DASHBOARD_OPTIONS_TOKEN,
+  type DashboardModuleOptions,
+} from './dashboard';
 export {
   MetricsModule,
   MetricsCollector,
@@ -351,12 +366,32 @@ export {
   type AuthContext,
   type AuthConfig,
 } from './auth';
+export {
+  DebugModule,
+  RequestRecorder,
+  createDebugMiddleware,
+  DEBUG_OPTIONS_TOKEN,
+  DEBUG_RECORDER_TOKEN,
+  type DebugModuleOptions,
+  type RequestRecord,
+} from './debug';
 export {
   PerformanceHarness,
   StressTester,
   type BenchmarkResult,
   type StressResult,
 } from './testing/harness';
+export { Test, TestingModule, TestingModuleBuilder } from './testing/testing-module';
+export { TestHttpClient } from './testing/test-client';
+// Client Generation
+export {
+  ClientGenerator,
+  createClient,
+  type RouteManifest,
+  type RouteManifestEntry,
+  type ClientConfig,
+  type ClientRequestOptions,
+} from './client';
 // Cache 模块
 export {
   CacheModule,

package/src/router/route.ts

@@ -35,14 +35,14 @@ export class Route {
   public readonly methodName?: string;
 
   /**
-   * 路径模式（用于匹配）
+   * 动态路由匹配用正则（比 URLPattern.exec() 快约 10 倍）
    */
-  private readonly pattern: RegExp;
+  private readonly pattern?: RegExp;
 
   /**
-   * 路径参数名列表
+   * 动态路由参数名列表
    */
-  private readonly paramNames: string[];
+  private readonly paramNames?: string[];
 
   private readonly middlewarePipeline: MiddlewarePipeline | null;
   private readonly staticKey?: string;
@@ -62,23 +62,21 @@ export class Route {
     this.controllerClass = controllerClass;
     this.methodName = methodName;
 
-    // 解析路径参数
-    const { pattern, paramNames } = this.parsePath(path);
-    this.pattern = pattern;
-    this.paramNames = paramNames;
-    this.middlewarePipeline = middlewares.length > 0 ? new MiddlewarePipeline(middlewares) : null;
     this.isStatic = !path.includes(':') && !path.includes('*');
     if (this.isStatic) {
       this.staticKey = `${method}:${path}`;
+    } else {
+      const { pattern, paramNames } = Route.parsePath(path);
+      this.pattern = pattern;
+      this.paramNames = paramNames;
     }
+    this.middlewarePipeline = middlewares.length > 0 ? new MiddlewarePipeline(middlewares) : null;
   }
 
   /**
    * 解析路径，生成匹配模式和参数名列表
-   * @param path - 路由路径
-   * @returns 匹配模式和参数名列表
    */
-  private parsePath(path: string): { pattern: RegExp; paramNames: string[] } {
+  private static parsePath(path: string): { pattern: RegExp; paramNames: string[] } {
     const paramNames: string[] = [];
     const patternString = path
       .replace(/:([^/]+)/g, (_, paramName) => {
@@ -87,8 +85,7 @@ export class Route {
       })
       .replace(/\*/g, '.*');
 
-    const pattern = new RegExp(`^${patternString}$`);
-    return { pattern, paramNames };
+    return { pattern: new RegExp(`^${patternString}$`), paramNames };
   }
 
   /**
@@ -98,21 +95,24 @@ export class Route {
    * @returns 匹配结果
    */
   public match(method: HttpMethod, path: string): RouteMatch {
-    // 方法不匹配
     if (this.method !== method) {
       return { matched: false, params: {} };
     }
 
-    // 路径不匹配
-    const match = path.match(this.pattern);
+    if (this.isStatic) {
+      return path === this.path
+        ? { matched: true, params: {} }
+        : { matched: false, params: {} };
+    }
+
+    const match = path.match(this.pattern!);
     if (!match) {
       return { matched: false, params: {} };
     }
 
-    // 提取路径参数
     const params: Record<string, string> = {};
-    for (let i = 0; i < this.paramNames.length; i++) {
-      params[this.paramNames[i]] = match[i + 1] ?? '';
+    for (let i = 0; i < this.paramNames!.length; i++) {
+      params[this.paramNames![i]] = match[i + 1] ?? '';
     }
 
     return { matched: true, params };

package/src/swagger/generator.ts

@@ -214,6 +214,106 @@ export class SwaggerGenerator {
     return document;
   }
 
+  /**
+   * 生成 Markdown 格式的 API 文档
+   * 利用 Bun 1.3.8+ 原生 Bun.markdown 内置解析器
+   */
+  public generateMarkdown(): string {
+    const doc = this.generate();
+    const lines: string[] = [];
+
+    lines.push(`# ${doc.info.title}`);
+    lines.push('');
+    if (doc.info.description) {
+      lines.push(doc.info.description);
+      lines.push('');
+    }
+    lines.push(`**Version:** ${doc.info.version}`);
+    lines.push('');
+
+    if (doc.servers?.length) {
+      lines.push('## Servers');
+      lines.push('');
+      for (const server of doc.servers) {
+        lines.push(`- \`${server.url}\`${server.description ? ' — ' + server.description : ''}`);
+      }
+      lines.push('');
+    }
+
+    if (doc.tags?.length) {
+      lines.push('## Tags');
+      lines.push('');
+      for (const tag of doc.tags) {
+        lines.push(`- **${tag.name}**${tag.description ? ': ' + tag.description : ''}`);
+      }
+      lines.push('');
+    }
+
+    lines.push('## Endpoints');
+    lines.push('');
+
+    const methods = ['get', 'post', 'put', 'delete', 'patch'] as const;
+    for (const [path, pathObj] of Object.entries(doc.paths)) {
+      for (const method of methods) {
+        const operation = pathObj[method];
+        if (!operation) continue;
+
+        lines.push(`### \`${method.toUpperCase()}\` ${path}`);
+        lines.push('');
+        if (operation.summary) {
+          lines.push(`**${operation.summary}**`);
+          lines.push('');
+        }
+        if (operation.description) {
+          lines.push(operation.description);
+          lines.push('');
+        }
+        if (operation.tags?.length) {
+          lines.push(`Tags: ${operation.tags.map((t) => `\`${t}\``).join(', ')}`);
+          lines.push('');
+        }
+        if (operation.deprecated) {
+          lines.push('> **Deprecated**');
+          lines.push('');
+        }
+
+        if (operation.parameters?.length) {
+          lines.push('| Parameter | In | Type | Required | Description |');
+          lines.push('|---|---|---|---|---|');
+          for (const param of operation.parameters) {
+            const type = param.schema?.type ?? 'string';
+            const required = param.required ? 'Yes' : 'No';
+            lines.push(`| \`${param.name}\` | ${param.in} | ${type} | ${required} | ${param.description ?? ''} |`);
+          }
+          lines.push('');
+        }
+
+        if (operation.responses) {
+          lines.push('**Responses:**');
+          lines.push('');
+          for (const [status, resp] of Object.entries(operation.responses)) {
+            lines.push(`- **${status}**: ${resp.description ?? ''}`);
+          }
+          lines.push('');
+        }
+
+        lines.push('---');
+        lines.push('');
+      }
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * 生成 Markdown 并渲染为 HTML
+   * 利用 Bun.markdown.html() 进行高性能渲染
+   */
+  public generateMarkdownHtml(): string {
+    const md = this.generateMarkdown();
+    return Bun.markdown.html(md, { headings: true });
+  }
+
   /**
    * 规范化路径
    */