@onebun/core 0.2.0 → 0.2.2

package/src/types.ts

@@ -1,3 +1,4 @@
+import type { BaseMiddleware } from './module/middleware';
 import type { Type } from 'arktype';
 import type { Effect, Layer } from 'effect';
 
@@ -12,6 +13,31 @@ import type { Logger, LoggerOptions } from '@onebun/logger';
  */
 export type OneBunRequest = import('bun').BunRequest;
 
+/**
+ * A middleware class constructor.
+ *
+ * Pass class references (not instances) to `@UseMiddleware()`,
+ * `ApplicationOptions.middleware`, and `OnModuleConfigure.configureMiddleware()`.
+ * The framework will instantiate them once at startup with DI support.
+ *
+ * @example
+ * ```typescript
+ * @UseMiddleware(AuthMiddleware)
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type MiddlewareClass = new (...args: any[]) => BaseMiddleware;
+
+/**
+ * Resolved middleware function — a bound `use()` method of an instantiated
+ * `BaseMiddleware`. Used internally by the execution pipeline.
+ * @internal
+ */
+export type ResolvedMiddleware = (
+  req: OneBunRequest,
+  next: () => Promise<OneBunResponse>,
+) => Promise<OneBunResponse> | OneBunResponse;
+
 /**
  * HTTP Response type used in OneBun controllers.
  * Standard Web API Response.
@@ -50,6 +76,37 @@ export interface ModuleProviders {
   exports?: Function[];
 }
 
+/**
+ * Interface for modules that configure middleware.
+ * Implement this interface on your `@Module()` class to apply middleware
+ * to all controllers within the module (including imported child modules).
+ *
+ * Module-level middleware runs after global middleware but before
+ * controller-level and route-level middleware.
+ *
+ * Execution order: global → module → controller → route → handler
+ *
+ * @example
+ * ```typescript
+ * @Module({
+ *   controllers: [UserController],
+ *   imports: [AuthModule],
+ * })
+ * export class UserModule implements OnModuleConfigure {
+ *   configureMiddleware(): MiddlewareClass[] {
+ *     return [TenantMiddleware, AuditMiddleware];
+ *   }
+ * }
+ * ```
+ */
+export interface OnModuleConfigure {
+  /**
+   * Return an array of middleware class constructors to apply to all controllers
+   * in this module and its imported child modules.
+   */
+  configureMiddleware(): MiddlewareClass[];
+}
+
 /**
  * Module instance interface
  */
@@ -98,6 +155,19 @@ export interface ModuleInstance {
    * Get service instance by class
    */
   getServiceByClass?<T>(serviceClass: new (...args: unknown[]) => T): T | undefined;
+
+  /**
+   * Get accumulated module-level middleware (resolved bound functions)
+   * for a given controller class.
+   * Includes middleware from ancestor modules (root → child → … → owner module).
+   */
+  getModuleMiddleware?(controllerClass: Function): Function[];
+
+  /**
+   * Resolve middleware class constructors into bound `use()` functions
+   * using this module's DI scope (services + logger + config).
+   */
+  resolveMiddleware?(classes: Function[]): Function[];
 }
 
 /**
@@ -128,6 +198,14 @@ export interface ApplicationOptions {
    */
   host?: string;
 
+  /**
+   * Maximum idle time (in seconds) before the server closes a connection.
+   * A connection is idle when no data is sent or received.
+   * Set to 0 to disable the timeout entirely.
+   * @defaultValue 120
+   */
+  idleTimeout?: number;
+
   /**
    * Base path prefix for all routes
    * @example '/api/v1'
@@ -342,6 +420,25 @@ export interface ApplicationOptions {
    */
   docs?: DocsApplicationOptions;
 
+  /**
+   * Application-wide middleware applied to every route before module-level,
+   * controller-level and route-level middleware. Useful for cross-cutting
+   * concerns like request logging, authentication, CORS, or request validation.
+   *
+   * Pass class constructors (not instances). The framework will instantiate
+   * them once at startup with full DI support from the root module.
+   *
+   * Execution order: global → module → controller → route → handler
+   *
+   * @example
+   * ```typescript
+   * const app = new OneBunApplication(AppModule, {
+   *   middleware: [CorsMiddleware, RequestIdMiddleware],
+   * });
+   * ```
+   */
+  middleware?: MiddlewareClass[];
+
   /**
    * Enable graceful shutdown on SIGTERM/SIGINT
    * When enabled, the application will cleanly shutdown on process signals,
@@ -523,6 +620,9 @@ export enum ParamType {
   COOKIE = 'cookie',
   REQUEST = 'request',
   RESPONSE = 'response',
+  FILE = 'file',
+  FILES = 'files',
+  FORM_FIELD = 'formField',
 }
 
 /**
@@ -538,6 +638,26 @@ export interface ParamDecoratorOptions {
   required?: boolean;
 }
 
+/**
+ * Options for file upload decorators (@UploadedFile, @UploadedFiles)
+ */
+export interface FileUploadOptions {
+  /** Maximum file size in bytes */
+  maxSize?: number;
+  /** Allowed MIME types, supports wildcards like 'image/*'. Use MimeType enum for convenience. */
+  mimeTypes?: string[];
+  /** Whether the file is required (default: true for @UploadedFile/@UploadedFiles) */
+  required?: boolean;
+}
+
+/**
+ * Options for multiple file upload decorator (@UploadedFiles)
+ */
+export interface FilesUploadOptions extends FileUploadOptions {
+  /** Maximum number of files allowed */
+  maxCount?: number;
+}
+
 /**
  * Parameter metadata
  */
@@ -550,6 +670,10 @@ export interface ParamMetadata {
    * ArkType schema for validation
    */
   schema?: Type<unknown>;
+  /**
+   * File upload options (only for FILE/FILES param types)
+   */
+  fileOptions?: FileUploadOptions & { maxCount?: number };
 }
 
 /**
@@ -561,6 +685,26 @@ export interface ResponseSchemaMetadata {
   description?: string;
 }
 
+/**
+ * Options for HTTP method decorators (@Get, @Post, @Put, @Delete, @Patch, etc.)
+ */
+export interface RouteOptions {
+  /**
+   * Per-request idle timeout in seconds.
+   * Overrides the global `idleTimeout` from `ApplicationOptions` for this route.
+   * Set to 0 to disable the timeout entirely (useful for long-running requests).
+   * @example
+   * ```typescript
+   * @Get('/long-task', { timeout: 300 }) // 5 minutes
+   * async longTask() { ... }
+   *
+   * @Get('/stream', { timeout: 0 }) // no timeout
+   * async stream() { ... }
+   * ```
+   */
+  timeout?: number;
+}
+
 /**
  * Route metadata
  */
@@ -575,6 +719,11 @@ export interface RouteMetadata {
    * Key is HTTP status code (e.g., 200, 201, 404)
    */
   responseSchemas?: ResponseSchemaMetadata[];
+  /**
+   * Per-request idle timeout in seconds.
+   * When set, calls `server.timeout(req, seconds)` for this route.
+   */
+  timeout?: number;
 }
 
 /**
@@ -583,6 +732,11 @@ export interface RouteMetadata {
 export interface ControllerMetadata {
   path: string;
   routes: RouteMetadata[];
+  /**
+   * Controller-level middleware class constructors applied to all routes.
+   * Set by applying @UseMiddleware() as a class decorator.
+   */
+  middleware?: MiddlewareClass[];
 }
 
 // ============================================================================
@@ -635,6 +789,21 @@ export interface SseOptions {
    * at this interval to keep the connection alive.
    */
   heartbeat?: number;
+
+  /**
+   * Callback invoked when the client disconnects or aborts the SSE connection.
+   * Useful for cleanup logic when using `controller.sse()` programmatically.
+   *
+   * For `@Sse()` decorator usage, prefer `try/finally` in the generator instead.
+   *
+   * @example
+   * ```typescript
+   * return this.sse(this.generateEvents(), {
+   *   onAbort: () => this.eventService.unsubscribe(),
+   * });
+   * ```
+   */
+  onAbort?: () => void;
 }
 
 /**