@onebun/core 0.2.6 → 0.2.8

package/src/testing/testing-module.ts

@@ -0,0 +1,252 @@
+/**
+ * TestingModule — lightweight harness for testing OneBun controllers and services
+ * without the full application startup overhead.
+ *
+ * Usage:
+ * ```typescript
+ * const module = await TestingModule
+ *   .create({ controllers: [UserController], providers: [UserService] })
+ *   .overrideProvider(UserService).useValue(mockUserService)
+ *   .compile();
+ *
+ * const response = await module.inject('GET', '/users/1');
+ * expect(response.ok).toBe(true);
+ *
+ * await module.close();
+ * ```
+ */
+
+import type { OneBunApplication } from '../application/application';
+import type { HttpMethod, OneBunResponse } from '../types';
+import type { Context } from 'effect';
+
+import { Module } from '../decorators/decorators';
+import { getServiceTag } from '../module/service';
+
+import { makeMockLoggerLayer } from './test-utils';
+
+// Re-export for convenience
+export { makeMockLoggerLayer };
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface TestingModuleCreateOptions {
+  /** Module classes to import (already decorated with @Module) */
+  imports?: Function[];
+  /** Controller classes to include */
+  controllers?: Function[];
+  /** Service/provider classes to include */
+  providers?: Function[];
+}
+
+interface InjectOptions {
+  /** Request body (will be JSON-serialised) */
+  body?: unknown;
+  /** Extra headers */
+  headers?: Record<string, string>;
+  /** Query parameters */
+  query?: Record<string, string>;
+}
+
+type OverrideBuilder = {
+  /** Replace the service with a plain value / mock instance */
+  useValue(val: unknown): TestingModule;
+  /** Replace the service with an instance of the given class */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  useClass(cls: new (...args: any[]) => unknown): TestingModule;
+};
+
+// ============================================================================
+// CompiledTestingModule
+// ============================================================================
+
+/**
+ * Result of `TestingModule.compile()`.
+ * Provides `inject()` for HTTP calls and `get()` for service access.
+ * Call `close()` when done to release the underlying server.
+ */
+export class CompiledTestingModule {
+  constructor(
+    private readonly app: OneBunApplication,
+    private readonly port: number,
+  ) {}
+
+  /**
+   * Get a service instance by its class constructor.
+   * Useful for asserting service state after a request.
+   *
+   * @param serviceClass - The `@Service()`-decorated class
+   * @returns The service instance registered in the module
+   * @throws If the service is not found
+   */
+  get<T>(serviceClass: new (...args: unknown[]) => T): T {
+    return this.app.getService(serviceClass) as T;
+  }
+
+  /**
+   * Send a fake HTTP request to the testing application.
+   * No real network call is made — the request goes through the full
+   * middleware → guards → filters → handler pipeline.
+   *
+   * @param method - HTTP method (GET, POST, PUT, DELETE, etc.)
+   * @param path - URL path (e.g. '/users/1')
+   * @param options - Optional body, headers, query params
+   */
+  async inject(
+    method: HttpMethod | string,
+    path: string,
+    options?: InjectOptions,
+  ): Promise<OneBunResponse> {
+    let url = `http://localhost:${this.port}${path}`;
+
+    if (options?.query && Object.keys(options.query).length > 0) {
+      const qs = new URLSearchParams(options.query).toString();
+      url = `${url}?${qs}`;
+    }
+
+    const headers = new Headers(options?.headers);
+    if (!headers.has('content-type')) {
+      headers.set('content-type', 'application/json');
+    }
+
+    // Use the native undici fetch to bypass any global `fetch` mock that may be set by
+    // other concurrent test files. This ensures real network calls reach the test server.
+     
+    const nativeFetch = (require('undici') as { fetch: typeof fetch }).fetch ?? globalThis.fetch;
+
+    return await nativeFetch(url, {
+      method,
+      headers,
+      body: options?.body !== undefined ? JSON.stringify(options.body) : undefined,
+    }) as OneBunResponse;
+  }
+
+  /**
+   * Stop the test server and release resources.
+   * Call this in `afterEach` / `afterAll` to prevent port leaks.
+   */
+  async close(): Promise<void> {
+    await this.app.stop?.({ closeSharedRedis: false });
+  }
+}
+
+// ============================================================================
+// TestingModule
+// ============================================================================
+
+/**
+ * Fluent builder for creating isolated test environments for OneBun modules.
+ *
+ * @example Basic usage
+ * ```typescript
+ * describe('UserController', () => {
+ *   let module: CompiledTestingModule;
+ *
+ *   beforeEach(async () => {
+ *     module = await TestingModule
+ *       .create({ controllers: [UserController], providers: [UserService] })
+ *       .compile();
+ *   });
+ *
+ *   afterEach(() => module.close());
+ *
+ *   it('returns 200 for GET /users', async () => {
+ *     const res = await module.inject('GET', '/users');
+ *     expect(res.ok).toBe(true);
+ *   });
+ * });
+ * ```
+ *
+ * @example With provider overrides
+ * ```typescript
+ * const mockService = { getUser: () => ({ id: 1, name: 'Test' }) };
+ *
+ * module = await TestingModule
+ *   .create({ controllers: [UserController], providers: [UserService] })
+ *   .overrideProvider(UserService).useValue(mockService)
+ *   .compile();
+ * ```
+ */
+export class TestingModule {
+  private readonly options: TestingModuleCreateOptions;
+  private readonly overrides: Array<{
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    tag: Context.Tag<any, any>;
+    value: unknown;
+  }> = [];
+
+  private constructor(options: TestingModuleCreateOptions) {
+    this.options = options;
+  }
+
+  /**
+   * Create a new TestingModule builder.
+   *
+   * @param options - Module options (controllers, providers, imports)
+   */
+  static create(options: TestingModuleCreateOptions): TestingModule {
+    return new TestingModule(options);
+  }
+
+  /**
+   * Override a provider with a mock value or class.
+   * Overrides are applied before `setup()` so controllers receive mocks at construction time.
+   *
+   * @param serviceClass - The `@Service()`-decorated class to override
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  overrideProvider<T>(serviceClass: new (...args: any[]) => T): OverrideBuilder {
+    return {
+      useValue: (val: unknown): TestingModule => {
+        this.overrides.push({ tag: getServiceTag(serviceClass), value: val });
+
+        return this;
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      useClass: (cls: new (...args: any[]) => unknown): TestingModule => {
+        this.overrides.push({ tag: getServiceTag(serviceClass), value: new cls() });
+
+        return this;
+      },
+    };
+  }
+
+  /**
+   * Compile the testing module and start the test server.
+   * Returns a `CompiledTestingModule` with `inject()` and `get()` methods.
+   *
+   * @returns Compiled module ready for testing
+   */
+  async compile(): Promise<CompiledTestingModule> {
+    // Lazily import to avoid circular dependencies at module parse time
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    const { OneBunApplication } = await import('../application/application');
+
+    // Build a synthetic module class from the provided options
+    const { controllers = [], providers = [], imports = [] } = this.options;
+
+    class _TestingAppModule {}
+    Module({
+      controllers,
+      providers: providers as unknown[],
+      imports,
+    })(_TestingAppModule);
+
+    // Create the application with:
+    // - port 0 → OS picks a free port
+    // - silent logger
+    // - test provider overrides injected before setup()
+    const app = new OneBunApplication(_TestingAppModule, {
+      port: 0,
+      loggerLayer: makeMockLoggerLayer() as import('effect').Layer.Layer<import('@onebun/logger').Logger>,
+      gracefulShutdown: false,
+      _testProviders: this.overrides,
+    });
+
+    await app.start();
+
+    return new CompiledTestingModule(app, app.getPort());
+  }
+}

package/src/types.ts

@@ -1,9 +1,15 @@
 import type { BaseMiddleware } from './module/middleware';
+import type { QueueAdapterConstructor } from './queue/types';
 import type { Type } from 'arktype';
-import type { Effect, Layer } from 'effect';
+import type {
+  Context,
+  Effect,
+  Layer,
+} from 'effect';
 
 import type { Logger, LoggerOptions } from '@onebun/logger';
 
+
 /**
  * HTTP Request type used in OneBun controllers.
  * Extends standard Web API Request with:
@@ -175,6 +181,11 @@ export interface ModuleInstance {
    * using this module's DI scope (services + logger + config).
    */
   resolveMiddleware?(classes: Function[]): Function[];
+
+  /**
+   * Register a service instance by tag (e.g. before setup() for application-provided services like QueueService proxy).
+   */
+  registerService?<T>(tag: Context.Tag<unknown, T>, instance: T): void;
 }
 
 /**
@@ -422,6 +433,12 @@ export interface ApplicationOptions {
    */
   queue?: QueueApplicationOptions;
 
+  /**
+   * Static file serving: serve files from a directory for requests not matched by API routes.
+   * Optional path prefix and fallback file (e.g. index.html) for SPA-style routing.
+   */
+  static?: StaticApplicationOptions;
+
   /**
    * Documentation configuration (OpenAPI/Swagger)
    */
@@ -454,6 +471,71 @@ export interface ApplicationOptions {
    * @defaultValue true
    */
   gracefulShutdown?: boolean;
+
+  /**
+   * Global exception filters applied to all routes.
+   * Route-level and controller-level filters take priority over global ones.
+   * If no filters match, the built-in default filter is used.
+   *
+   * @example
+   * ```typescript
+   * const app = new OneBunApplication(AppModule, {
+   *   filters: [new GlobalExceptionFilter()],
+   * });
+   * ```
+   */
+  filters?: import('./exception-filters/exception-filters').ExceptionFilter[];
+
+  /**
+   * CORS configuration. When provided, `CorsMiddleware` is automatically prepended
+   * to the global middleware chain.
+   *
+   * @example
+   * ```typescript
+   * const app = new OneBunApplication(AppModule, {
+   *   cors: { origin: 'https://my-frontend.example.com', credentials: true },
+   * });
+   * ```
+   */
+  cors?: import('./security/cors-middleware').CorsOptions | true;
+
+  /**
+   * Rate limiting configuration. When provided, `RateLimitMiddleware` is automatically
+   * prepended to the global middleware chain (after CORS, before other middleware).
+   *
+   * @example
+   * ```typescript
+   * const app = new OneBunApplication(AppModule, {
+   *   rateLimit: { windowMs: 60_000, max: 100 },
+   * });
+   * ```
+   */
+  rateLimit?: import('./security/rate-limit-middleware').RateLimitOptions | true;
+
+  /**
+   * Security headers configuration. When provided, `SecurityHeadersMiddleware` is
+   * automatically appended to the global middleware chain.
+   * Pass `true` to use all defaults (equivalent to no options).
+   *
+   * @example
+   * ```typescript
+   * const app = new OneBunApplication(AppModule, {
+   *   security: { strictTransportSecurity: false }, // disable HSTS for local dev
+   * });
+   * ```
+   */
+  security?: import('./security/security-headers-middleware').SecurityHeadersOptions | true;
+
+  /**
+   * Pre-register service instances for testing.
+   * These are injected before `setup()` so controllers receive mocks at construction time.
+   * @internal Use `TestingModule` instead of setting this directly.
+   */
+  _testProviders?: Array<{
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    tag: Context.Tag<any, any>;
+    value: unknown;
+  }>;
 }
 
 /**
@@ -467,8 +549,10 @@ export type QueueAdapterType = 'memory' | 'redis';
 export interface QueueApplicationOptions {
   /** Enable/disable queue (default: auto - enabled if handlers exist) */
   enabled?: boolean;
-  /** Adapter type or custom adapter instance */
-  adapter?: QueueAdapterType;
+  /** Adapter type, or custom adapter constructor (e.g. for NATS JetStream) */
+  adapter?: QueueAdapterType | QueueAdapterConstructor;
+  /** Options passed to the custom adapter constructor when adapter is a class */
+  options?: unknown;
   /** Redis-specific options (only used when adapter is 'redis') */
   redis?: {
     /** Use shared Redis provider instead of dedicated connection */
@@ -528,6 +612,39 @@ export interface WebSocketApplicationOptions {
   maxPayload?: number;
 }
 
+/**
+ * Static file serving configuration for OneBunApplication.
+ * Serves files from a directory for requests not matched by API/ws/docs/metrics routes.
+ */
+export interface StaticApplicationOptions {
+  /**
+   * Filesystem path to the directory to serve (static root).
+   * Can be absolute or relative to the process cwd.
+   */
+  root: string;
+
+  /**
+   * URL path prefix under which static files are served.
+   * Empty or '/' means "everything not matched by API routes".
+   * Example: '/app' — only paths starting with /app are served from static root
+   * (the prefix is stripped when resolving the file path).
+   */
+  pathPrefix?: string;
+
+  /**
+   * Fallback file name (e.g. 'index.html') for SPA-style client-side routing.
+   * When the requested file is not found, this file under static root is returned instead.
+   */
+  fallbackFile?: string;
+
+  /**
+   * TTL in milliseconds for caching file existence checks.
+   * Reduces disk I/O for repeated requests. Use 0 to disable caching.
+   * @defaultValue 60000
+   */
+  fileExistenceCacheTtlMs?: number;
+}
+
 /**
  * Documentation configuration for OneBunApplication
  * Enables automatic OpenAPI spec generation and Swagger UI
@@ -712,6 +829,35 @@ export interface RouteOptions {
   timeout?: number;
 }
 
+/**
+ * HTTP Execution Context provided to HTTP guards.
+ * Gives read-only access to the incoming request and routing information.
+ */
+export interface HttpExecutionContext {
+  /** Returns the incoming request object */
+  getRequest(): OneBunRequest;
+  /** Returns the handler method name (e.g. 'getUser') */
+  getHandler(): string;
+  /** Returns the controller class name (e.g. 'UserController') */
+  getController(): string;
+}
+
+/**
+ * HTTP Guard interface — implement to protect routes via `@UseGuards()`.
+ *
+ * @example
+ * ```typescript
+ * class MyGuard implements HttpGuard {
+ *   canActivate(ctx: HttpExecutionContext): boolean {
+ *     return ctx.getRequest().headers.get('x-api-key') === 'secret';
+ *   }
+ * }
+ * ```
+ */
+export interface HttpGuard {
+  canActivate(context: HttpExecutionContext): boolean | Promise<boolean>;
+}
+
 /**
  * Route metadata
  */
@@ -721,6 +867,10 @@ export interface RouteMetadata {
   handler: string;
   params?: ParamMetadata[];
   middleware?: Function[];
+  /** Guards to execute before the route handler. Supports class constructors and instances. */
+  guards?: (Function | HttpGuard)[];
+  /** Exception filters to apply when the route handler throws. */
+  filters?: import('./exception-filters/exception-filters').ExceptionFilter[];
   /**
    * Response schemas for validation
    * Key is HTTP status code (e.g., 200, 201, 404)