@dangao/bun-server 3.1.0 → 3.3.0

package/src/middleware/builtin/rate-limit.ts

@@ -88,7 +88,12 @@ export interface RateLimitOptions {
   /**
    * 时间窗口内的最大请求数
    */
-  max: number;
+  max?: number;
+
+  /**
+   * 时间窗口内的最大请求数别名，兼容装饰器早期写法。
+   */
+  limit?: number;
 
   /**
    * 时间窗口（毫秒）
@@ -108,6 +113,11 @@ export interface RateLimitOptions {
    */
   keyGenerator?: (context: Context) => string | Promise<string>;
 
+  /**
+   * 返回 true 时跳过限流。
+   */
+  skip?: (context: Context) => boolean | Promise<boolean>;
+
   /**
    * 是否跳过成功响应（只对错误响应计数）
    * @default false
@@ -157,9 +167,11 @@ function defaultKeyGenerator(context: Context): string {
 export function createRateLimitMiddleware(options: RateLimitOptions): Middleware {
   const {
     max,
+    limit,
     windowMs = 60000, // 默认 1 分钟
     store = new MemoryRateLimitStore(),
     keyGenerator = defaultKeyGenerator,
+    skip,
     skipSuccessfulRequests = false,
     skipFailedRequests = false,
     message = 'Too Many Requests',
@@ -167,31 +179,36 @@ export function createRateLimitMiddleware(options: RateLimitOptions): Middleware
     standardHeaders = true,
     legacyHeaders = true,
   } = options;
+  const requestLimit = limit ?? max ?? 100;
 
   return async (context: Context, next) => {
+    if (skip && await skip(context)) {
+      return await next();
+    }
+
     // 生成限流键
     const key = await keyGenerator(context);
     const currentCount = await store.increment(key, windowMs);
 
     // 计算剩余请求数和重置时间
-    const remaining = Math.max(0, max - currentCount);
+    const remaining = Math.max(0, requestLimit - currentCount);
     const resetTime = Date.now() + windowMs;
 
     // 设置响应头
     if (standardHeaders) {
-      context.setHeader('RateLimit-Limit', max.toString());
+      context.setHeader('RateLimit-Limit', requestLimit.toString());
       context.setHeader('RateLimit-Remaining', remaining.toString());
       context.setHeader('RateLimit-Reset', Math.ceil(resetTime / 1000).toString());
     }
 
     if (legacyHeaders) {
-      context.setHeader('X-RateLimit-Limit', max.toString());
+      context.setHeader('X-RateLimit-Limit', requestLimit.toString());
       context.setHeader('X-RateLimit-Remaining', remaining.toString());
       context.setHeader('X-RateLimit-Reset', Math.ceil(resetTime / 1000).toString());
     }
 
     // 检查是否超过限制
-    if (currentCount > max) {
+    if (currentCount > requestLimit) {
       context.setStatus(statusCode);
       return context.createErrorResponse({
         error: message,

package/src/queue/service.ts

@@ -17,7 +17,7 @@ import { getRuntime } from '../platform/runtime';
  */
 @Injectable()
 export class QueueService {
-  private store: QueueStore;
+  public readonly store: QueueStore;
   private defaultQueue: string;
   private enableWorker: boolean;
   private concurrency: number;

package/src/queue/types.ts

@@ -24,6 +24,11 @@ export interface JobOptions {
    */
   attempts?: number;
 
+  /**
+   * 任务重试次数别名，兼容早期 API。
+   */
+  retries?: number;
+
   /**
    * 任务重试延迟（毫秒）
    */
@@ -90,7 +95,22 @@ export interface Job<T = JobData> {
   /**
    * 更新时间
    */
-  updatedAt: number;
+  updatedAt?: number;
+
+  /**
+   * 完成结果
+   */
+  result?: unknown;
+
+  /**
+   * 完成时间
+   */
+  completedAt?: number;
+
+  /**
+   * 失败错误信息
+   */
+  error?: string;
 }
 
 /**
@@ -141,6 +161,25 @@ export interface QueueStore {
     status: Job['status'],
   ): Promise<boolean>;
 
+  complete?(
+    queueName: string,
+    jobId: string,
+    result?: unknown,
+  ): Promise<boolean>;
+
+  fail?(
+    queueName: string,
+    jobId: string,
+    error: Error,
+  ): Promise<boolean>;
+
+  getStats?(queueName: string): Promise<{
+    waiting: number;
+    active: number;
+    completed: number;
+    failed: number;
+  }>;
+
   /**
    * 删除任务
    * @param queueName - 队列名称

package/src/router/decorators.ts

@@ -1,5 +1,4 @@
 import 'reflect-metadata';
-import type { RouteHandler } from './types';
 import { RouteRegistry } from './registry';
 import type { HttpMethod } from './types';
 import { CONTROLLER_METADATA_KEY } from '../controller/controller';
@@ -15,7 +14,7 @@ export const ROUTE_METADATA_KEY = Symbol('route');
 export interface RouteMetadata {
   method: HttpMethod;
   path: string;
-  handler: RouteHandler;
+  handler: (...args: any[]) => unknown;
   /**
    * 属性键（用于控制器方法）
    */
@@ -75,7 +74,7 @@ function createRouteDecorator(method: HttpMethod, path: string = '') {
     existingRoutes.push({
       method,
       path: path ?? '',
-      handler: descriptor.value as RouteHandler,
+      handler: descriptor.value as (...args: any[]) => unknown,
       propertyKey: propertyKeyStr || undefined,
     });
     Reflect.defineMetadata(ROUTE_METADATA_KEY, existingRoutes, target);

package/src/security/guards/types.ts

@@ -16,6 +16,8 @@ export interface CanActivate {
   canActivate(context: ExecutionContext): boolean | Promise<boolean>;
 }
 
+export type Guard = CanActivate;
+
 /**
  * HTTP 参数主机接口
  * 提供 HTTP 请求相关的上下文信息
@@ -141,4 +143,3 @@ export const GUARD_REGISTRY_TOKEN = Symbol('@dangao/bun-server:guard-registry');
  * Roles 元数据键
  */
 export const ROLES_METADATA_KEY = Symbol('@dangao/bun-server:roles');
-

package/src/security/types.ts

@@ -35,7 +35,7 @@ export interface Credentials {
   /**
    * 凭据数据
    */
-  data: unknown;
+  data: any;
 }
 
 /**
@@ -162,4 +162,3 @@ export interface SecurityContext {
    */
   getAuthorities(): string[];
 }
-

package/src/session/service.ts

@@ -25,7 +25,7 @@ export class SessionService {
   ) {
     this.store = options.store!;
     this.name = options.name ?? 'sessionId';
-    this.maxAge = options.maxAge ?? 86400000; // 24 小时
+    this.maxAge = options.maxAge ?? options.ttl ?? 86400000; // 24 小时
     this.rolling = options.rolling ?? true;
     this.cookieOptions = {
       secure: options.cookie?.secure ?? false,

package/src/session/types.ts

@@ -317,6 +317,11 @@ export interface SessionModuleOptions {
    */
   maxAge?: number;
 
+  /**
+   * Session 最大存活时间别名。
+   */
+  ttl?: number;
+
   /**
    * 是否在每次访问时更新过期时间
    * @default true
@@ -327,6 +332,11 @@ export interface SessionModuleOptions {
    * Cookie 选项
    */
   cookie?: {
+    /**
+     * Cookie 名称别名，优先使用顶层 name。
+     */
+    name?: string;
+
     /**
      * 是否只在 HTTPS 下发送
      * @default false

package/src/swagger/decorators.ts

@@ -50,13 +50,25 @@ export function ApiOperation(metadata: ApiOperationMetadata): MethodDecorator {
  * 用于描述 API 参数
  * @param metadata - 参数元数据
  */
-export function ApiParam(metadata: ApiParamMetadata): ParameterDecorator {
-  return function (target: unknown, propertyKey: string | symbol | undefined, parameterIndex: number) {
+export function ApiParam(metadata: ApiParamMetadata): ParameterDecorator & MethodDecorator {
+  const decorator = (
+    target: Object,
+    propertyKey: string | symbol | undefined,
+    descriptorOrParameterIndex: TypedPropertyDescriptor<any> | number,
+  ): void => {
+    const paramMetadata: ApiParamMetadata = {
+      in: 'path',
+      ...metadata,
+    };
     const existingParams: Array<{ index: number; metadata: ApiParamMetadata }> =
       Reflect.getMetadata(API_PARAM_METADATA_KEY, target as Object, propertyKey!) || [];
-    existingParams.push({ index: parameterIndex, metadata });
+    const index = typeof descriptorOrParameterIndex === 'number'
+      ? descriptorOrParameterIndex
+      : -1;
+    existingParams.push({ index, metadata: paramMetadata });
     Reflect.defineMetadata(API_PARAM_METADATA_KEY, existingParams, target as Object, propertyKey!);
   };
+  return decorator as ParameterDecorator & MethodDecorator;
 }
 
 /**
@@ -130,4 +142,3 @@ export function getApiResponses(
 ): ApiResponseMetadata[] {
   return Reflect.getMetadata(API_RESPONSE_METADATA_KEY, target as Object, propertyKey) || [];
 }
-

package/src/swagger/generator.ts

@@ -139,7 +139,7 @@ export class SwaggerGenerator {
         for (const match of pathParamMatches) {
           const paramName = match[1];
           // 检查是否已经有手动定义的参数
-          const existingParam = params.find((p) => p.metadata.name === paramName && p.metadata.in === 'path');
+          const existingParam = params.find((p) => p.metadata.name === paramName && (p.metadata.in ?? 'path') === 'path');
           if (!existingParam) {
             // 自动添加路径参数
             pathParams.push({
@@ -155,7 +155,7 @@ export class SwaggerGenerator {
         for (const param of params) {
           pathParams.push({
             name: param.metadata.name,
-            in: param.metadata.in,
+            in: param.metadata.in ?? 'path',
             description: param.metadata.description,
             required: param.metadata.required,
             schema: param.metadata.schema,
@@ -332,4 +332,3 @@ export class SwaggerGenerator {
     return path;
   }
 }
-

package/src/swagger/types.ts

@@ -60,7 +60,7 @@ export interface ApiParamMetadata {
     enum?: unknown[];
     default?: unknown;
   };
-  in: 'query' | 'path' | 'header' | 'cookie';
+  in?: 'query' | 'path' | 'header' | 'cookie';
 }
 
 /**
@@ -185,4 +185,3 @@ export interface SwaggerDocument {
     patch?: SwaggerPathItem;
   }>;
 }
-

package/src/testing/harness.ts

@@ -22,7 +22,7 @@ export class PerformanceHarness {
   public static async benchmark(
     name: string,
     iterations: number,
-    runner: (iteration: number) => void | Promise<void>,
+    runner: (iteration: number) => unknown | Promise<unknown>,
   ): Promise<BenchmarkResult> {
     if (iterations <= 0) {
       throw new Error('iterations must be greater than 0');
@@ -93,4 +93,3 @@ export class StressTester {
     };
   }
 }
-

package/src/testing/test-client.ts

@@ -9,7 +9,7 @@ interface RequestOptions {
 interface TestResponse {
   status: number;
   headers: Headers;
-  body: unknown;
+  body: any;
   text: string;
   ok: boolean;
 }
@@ -94,7 +94,7 @@ export class TestHttpClient {
     const response = await fetch(url, fetchOptions);
     const text = await response.text();
 
-    let body: unknown;
+    let body: any;
     try {
       body = JSON.parse(text);
     } catch (_error) {

package/src/testing/testing-module.ts

@@ -5,7 +5,7 @@ import { Container } from '../di/container';
 import { ModuleRegistry } from '../di/module-registry';
 import { ControllerRegistry } from '../controller/controller';
 import { RouteRegistry } from '../router/registry';
-import { MODULE_METADATA_KEY, type ModuleMetadata, type ModuleClass, type ModuleProvider, type ProviderToken } from '../di/module';
+import { MODULE_METADATA_KEY, invokeFactoryProvider, type ModuleMetadata, type ModuleClass, type ModuleProvider, type ProviderToken } from '../di/module';
 import type { Constructor } from '../core/types';
 import { TestHttpClient } from './test-client';
 
@@ -13,7 +13,7 @@ interface ProviderOverride {
   token: ProviderToken;
   useValue?: unknown;
   useClass?: Constructor<unknown>;
-  useFactory?: () => unknown;
+  useFactory?: (...args: any[]) => unknown;
 }
 
 /**
@@ -75,7 +75,7 @@ export class TestingModuleBuilder {
         } else if (override.useClass) {
           result.push({ provide: override.token, useClass: override.useClass });
         } else if (override.useFactory) {
-          result.push({ provide: override.token, useFactory: override.useFactory as (container: Container) => unknown });
+          result.push({ provide: override.token, useFactory: override.useFactory });
         }
         overrideMap.delete(key as string | symbol);
       } else {
@@ -121,7 +121,7 @@ class ProviderOverrideBuilder {
   /**
    * 使用工厂函数覆盖
    */
-  public useFactory(factory: () => unknown): TestingModuleBuilder {
+  public useFactory(factory: (...args: any[]) => unknown): TestingModuleBuilder {
     this.builder.addOverride({ token: this.token, useFactory: factory });
     return this.builder;
   }
@@ -177,7 +177,7 @@ export class TestingModule {
         container.registerInstance(provider.provide, provider.useValue);
       } else if ('useFactory' in provider && provider.provide) {
         container.register(provider.provide as Constructor<unknown>, {
-          factory: () => (provider as { useFactory: (container: Container) => unknown }).useFactory(container),
+          factory: () => invokeFactoryProvider(provider, container),
         });
       } else if ('useClass' in provider) {
         const token = (provider as { provide?: ProviderToken }).provide ?? (provider as { useClass: Constructor<unknown> }).useClass;

package/src/validation/errors.ts

@@ -9,10 +9,15 @@ export interface ValidationIssue {
    */
   property?: string;
 
+  /**
+   * 属性路径别名，兼容早期错误对象形状。
+   */
+  path?: string;
+
   /**
    * 失败的规则名称
    */
-  rule: string;
+  rule?: string;
 
   /**
    * 错误信息
@@ -73,4 +78,3 @@ export class ValidationError extends Error {
   }
 }
 
-

package/tests/bun-test-shim.d.ts

@@ -0,0 +1,11 @@
+declare module 'bun:test' {
+  export const describe: any;
+  export const test: any;
+  export const it: any;
+  export const expect: any;
+  export const beforeEach: any;
+  export const afterEach: any;
+  export const beforeAll: any;
+  export const afterAll: any;
+  export const mock: any;
+}

package/tests/controller/context-decorator.test.ts

@@ -155,7 +155,7 @@ describe('@Context() Decorator', () => {
     // 这个测试验证 ContextService 可以在服务层使用
     const { ContextService, CONTEXT_SERVICE_TOKEN } = await import('../../src/core/context-service');
     const container = app.getContainer();
-    const contextService = container.resolve<ContextService>(CONTEXT_SERVICE_TOKEN);
+    const contextService = container.resolve<InstanceType<typeof ContextService>>(CONTEXT_SERVICE_TOKEN);
 
     @Controller('/api/test')
     class TestController {
@@ -180,4 +180,3 @@ describe('@Context() Decorator', () => {
     expect(data.method).toBe('GET');
   });
 });
-

package/tests/database/database-module.test.ts

@@ -9,9 +9,13 @@ import {
   SQLITE_MANAGER_TOKEN,
 } from '../../src/database';
 import { MODULE_METADATA_KEY } from '../../src/di/module';
+import { initRuntime } from '../../src/platform/runtime';
 
 describe('DatabaseModule V2', () => {
   beforeEach(() => {
+    // forRoot() 会在创建 sqlite/sql 管理器时读取 getRuntime()，确保运行时已初始化
+    // （避免依赖其他测试文件的执行顺序）
+    initRuntime('bun');
     Reflect.deleteMetadata(MODULE_METADATA_KEY, DatabaseModule);
   });
 

package/tests/database/driver-mysql2.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test, mock, beforeAll } from 'bun:test';
+
+import { initRuntime, getRuntime } from '../../src/platform/runtime';
+
+/**
+ * 验证：在 Bun 运行时下显式选用 driver: 'mysql2' 时，
+ * 连接创建 / 参数化查询 / health check / close 全部走 mysql2（而非 Bun.SQL）。
+ *
+ * 通过 mock 'mysql2/promise' 模块注入假连接，无需真实 MySQL。
+ */
+
+const createdConnections: Array<Record<string, unknown>> = [];
+const queryCalls: Array<{ sql: string; params: unknown[] }> = [];
+let endCount = 0;
+
+function makeFakeConnection() {
+  const conn = {
+    query: async (sql: string, params: unknown[]) => {
+      queryCalls.push({ sql, params });
+      // mysql2 返回 [rows, fields]
+      if (/select\s+1/i.test(sql)) {
+        return [[{ '1': 1 }], []];
+      }
+      return [[{ id: 1, name: 'alice' }], [{ name: 'id' }, { name: 'name' }]];
+    },
+    end: async () => {
+      endCount += 1;
+    },
+    close: async () => {
+      throw new Error('mysql2 connection should be closed via end(), not close()');
+    },
+  };
+  createdConnections.push(conn);
+  return conn;
+}
+
+mock.module('mysql2/promise', () => {
+  const createConnection = async (_opts: unknown) => makeFakeConnection();
+  const createPool = (_opts: unknown) => makeFakeConnection();
+  return {
+    default: { createConnection, createPool },
+    createConnection,
+    createPool,
+  };
+});
+
+describe('DatabaseService with driver: mysql2 on Bun runtime', () => {
+  beforeAll(() => {
+    initRuntime('bun');
+  });
+
+  test('runs the full lifecycle (create/query/health/close) through mysql2', async () => {
+    // 前置确认：当前进程运行在 Bun，但我们强制 mysql2
+    expect(getRuntime().engine).toBe('bun');
+
+    const { DatabaseService } = await import('../../src/database/service');
+
+    const svc = new DatabaseService({
+      database: {
+        type: 'mysql',
+        driver: 'mysql2',
+        config: {
+          host: 'localhost',
+          port: 3306,
+          database: 'testdb',
+          user: 'root',
+          password: 'secret',
+        },
+      },
+      enableHealthCheck: true,
+    });
+
+    await svc.initialize();
+
+    // 连接由 mysql2.createConnection 创建
+    expect(createdConnections.length).toBeGreaterThan(0);
+
+    // 参数化查询走 mysql2.query(sql, params)，并返回 rows（而非 [rows, fields]）
+    const rows = await svc.query<{ id: number; name: string }>(
+      'SELECT * FROM users WHERE id = ?',
+      [1],
+    );
+    expect(rows).toEqual([{ id: 1, name: 'alice' }]);
+    expect(queryCalls.some((c) => c.sql === 'SELECT * FROM users WHERE id = ?' && c.params[0] === 1)).toBe(true);
+
+    // health check 走 mysql2.query('SELECT 1')
+    const healthy = await svc.healthCheck();
+    expect(healthy).toBe(true);
+    expect(queryCalls.some((c) => /select\s+1/i.test(c.sql))).toBe(true);
+
+    // close 走 mysql2 的 end()
+    await svc.closePool();
+    expect(endCount).toBeGreaterThan(0);
+  });
+});