@onebun/core 0.2.0 → 0.2.2

package/src/decorators/decorators.test.ts

@@ -20,8 +20,14 @@ import {
   BaseService,
   Service,
 } from '../module';
+import { BaseMiddleware } from '../module/middleware';
 import { makeMockLoggerLayer } from '../testing';
-import { HttpMethod, ParamType } from '../types';
+import {
+  HttpMethod,
+  ParamType,
+  type OneBunRequest,
+  type OneBunResponse,
+} from '../types';
 
 import {
   injectable,
@@ -49,6 +55,10 @@ import {
   Module,
   getModuleMetadata,
   ApiResponse,
+  UploadedFile,
+  UploadedFiles,
+  FormField,
+  getControllerMiddleware,
 } from './decorators';
 
 describe('decorators', () => {
@@ -675,42 +685,51 @@ describe('decorators', () => {
   });
 
   describe('UseMiddleware decorator', () => {
-    const middleware1 = () => {};
-    const middleware2 = () => {};
+    class Middleware1 extends BaseMiddleware {
+      async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+        return await next(); 
+      }
+    }
+
+    class Middleware2 extends BaseMiddleware {
+      async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+        return await next(); 
+      }
+    }
 
-    test('should register middleware for method', () => {
+    test('should register middleware class for method', () => {
       @Controller()
       class TestController {
         @Get()
-        @UseMiddleware(middleware1)
+        @UseMiddleware(Middleware1)
         test() {}
       }
 
       const metadata = getControllerMetadata(TestController);
       const route = metadata?.routes[0];
-      expect(route?.middleware).toContain(middleware1);
+      expect(route?.middleware).toContain(Middleware1);
     });
 
-    test('should register multiple middleware functions', () => {
+    test('should register multiple middleware classes', () => {
       @Controller()
       class TestController {
         @Get()
-        @UseMiddleware(middleware1, middleware2)
+        @UseMiddleware(Middleware1, Middleware2)
         test() {}
       }
 
       const metadata = getControllerMetadata(TestController);
       const route = metadata?.routes[0];
-      expect(route?.middleware).toContain(middleware1);
-      expect(route?.middleware).toContain(middleware2);
+      expect(route?.middleware).toContain(Middleware1);
+      expect(route?.middleware).toContain(Middleware2);
     });
 
     test('should append to existing middleware', () => {
       @Controller()
       class TestController {
         @Get()
-        @UseMiddleware(middleware1)
-        @UseMiddleware(middleware2)
+        @UseMiddleware(Middleware1)
+        @UseMiddleware(Middleware2)
         test() {}
       }
 
@@ -718,6 +737,41 @@ describe('decorators', () => {
       const route = metadata?.routes[0];
       expect(route?.middleware).toHaveLength(2);
     });
+
+    test('should register middleware as class decorator', () => {
+      @Controller()
+      @UseMiddleware(Middleware1, Middleware2)
+      class TestController {
+        @Get()
+        test() {}
+      }
+
+      const controllerMw = getControllerMiddleware(TestController);
+      expect(controllerMw).toHaveLength(2);
+      expect(controllerMw).toContain(Middleware1);
+      expect(controllerMw).toContain(Middleware2);
+    });
+
+    test('should keep class and method middleware separate', () => {
+      @Controller()
+      @UseMiddleware(Middleware1)
+      class TestController {
+        @Get()
+        @UseMiddleware(Middleware2)
+        test() {}
+      }
+
+      // Class-level
+      const controllerMw = getControllerMiddleware(TestController);
+      expect(controllerMw).toHaveLength(1);
+      expect(controllerMw[0]).toBe(Middleware1);
+
+      // Route-level
+      const metadata = getControllerMetadata(TestController);
+      const route = metadata?.routes[0];
+      expect(route?.middleware).toHaveLength(1);
+      expect(route?.middleware?.[0]).toBe(Middleware2);
+    });
   });
 
   describe('Module decorator', () => {
@@ -1077,4 +1131,140 @@ describe('decorators', () => {
       expect(isGlobalModule(NonGlobalModuleC)).toBe(false);
     });
   });
+
+  // ============================================================================
+  // File Upload Decorators
+  // ============================================================================
+
+  describe('File Upload Decorators', () => {
+    test('@UploadedFile should store FILE param metadata', () => {
+      @Controller('/test')
+      class TestController extends BaseController {
+        @Post('/upload')
+        upload(@UploadedFile('avatar') _file: unknown) {}
+      }
+
+      const metadata = getControllerMetadata(TestController);
+      expect(metadata).toBeDefined();
+      const route = metadata!.routes[0];
+      expect(route.params).toBeDefined();
+      expect(route.params!.length).toBe(1);
+      expect(route.params![0].type).toBe(ParamType.FILE);
+      expect(route.params![0].name).toBe('avatar');
+      expect(route.params![0].index).toBe(0);
+      expect(route.params![0].isRequired).toBe(true);
+    });
+
+    test('@UploadedFile should store file options', () => {
+      @Controller('/test')
+      class TestController extends BaseController {
+        @Post('/upload')
+        upload(
+          @UploadedFile('avatar', { maxSize: 1024, mimeTypes: ['image/*'], required: false }) _file: unknown,
+        ) {}
+      }
+
+      const metadata = getControllerMetadata(TestController);
+      const param = metadata!.routes[0].params![0];
+      expect(param.isRequired).toBe(false);
+      expect(param.fileOptions).toBeDefined();
+      expect(param.fileOptions!.maxSize).toBe(1024);
+      expect(param.fileOptions!.mimeTypes).toEqual(['image/*']);
+    });
+
+    test('@UploadedFile without options should be required by default', () => {
+      @Controller('/test')
+      class TestController extends BaseController {
+        @Post('/upload')
+        upload(@UploadedFile('file') _file: unknown) {}
+      }
+
+      const metadata = getControllerMetadata(TestController);
+      const param = metadata!.routes[0].params![0];
+      expect(param.isRequired).toBe(true);
+      expect(param.fileOptions).toBeUndefined();
+    });
+
+    test('@UploadedFiles should store FILES param metadata', () => {
+      @Controller('/test')
+      class TestController extends BaseController {
+        @Post('/upload')
+        upload(@UploadedFiles('docs', { maxCount: 5, maxSize: 2048 }) _files: unknown) {}
+      }
+
+      const metadata = getControllerMetadata(TestController);
+      const param = metadata!.routes[0].params![0];
+      expect(param.type).toBe(ParamType.FILES);
+      expect(param.name).toBe('docs');
+      expect(param.isRequired).toBe(true);
+      expect(param.fileOptions!.maxCount).toBe(5);
+      expect(param.fileOptions!.maxSize).toBe(2048);
+    });
+
+    test('@UploadedFiles without field name should have empty name', () => {
+      @Controller('/test')
+      class TestController extends BaseController {
+        @Post('/upload')
+        upload(@UploadedFiles() _files: unknown) {}
+      }
+
+      const metadata = getControllerMetadata(TestController);
+      const param = metadata!.routes[0].params![0];
+      expect(param.type).toBe(ParamType.FILES);
+      expect(param.name).toBe('');
+    });
+
+    test('@FormField should store FORM_FIELD param metadata', () => {
+      @Controller('/test')
+      class TestController extends BaseController {
+        @Post('/upload')
+        upload(@FormField('name') _name: unknown) {}
+      }
+
+      const metadata = getControllerMetadata(TestController);
+      const param = metadata!.routes[0].params![0];
+      expect(param.type).toBe(ParamType.FORM_FIELD);
+      expect(param.name).toBe('name');
+      expect(param.isRequired).toBe(false);
+    });
+
+    test('@FormField with required option', () => {
+      @Controller('/test')
+      class TestController extends BaseController {
+        @Post('/upload')
+        upload(@FormField('name', { required: true }) _name: unknown) {}
+      }
+
+      const metadata = getControllerMetadata(TestController);
+      const param = metadata!.routes[0].params![0];
+      expect(param.isRequired).toBe(true);
+    });
+
+    test('should support mixing file and form field decorators', () => {
+      @Controller('/test')
+      class TestController extends BaseController {
+        @Post('/profile')
+        createProfile(
+          @UploadedFile('avatar') _avatar: unknown,
+          @FormField('name', { required: true }) _name: unknown,
+          @FormField('email') _email: unknown,
+        ) {}
+      }
+
+      const metadata = getControllerMetadata(TestController);
+      const params = metadata!.routes[0].params!;
+      expect(params.length).toBe(3);
+
+      const fileParam = params.find((p) => p.type === ParamType.FILE);
+      const nameParam = params.find((p) => p.name === 'name');
+      const emailParam = params.find((p) => p.name === 'email');
+
+      expect(fileParam).toBeDefined();
+      expect(nameParam).toBeDefined();
+      expect(nameParam!.type).toBe(ParamType.FORM_FIELD);
+      expect(nameParam!.isRequired).toBe(true);
+      expect(emailParam).toBeDefined();
+      expect(emailParam!.isRequired).toBe(false);
+    });
+  });
 });

package/src/decorators/decorators.ts

@@ -3,10 +3,13 @@ import { type, type Type } from 'arktype';
 
 import {
   type ControllerMetadata,
+  type FileUploadOptions,
+  type FilesUploadOptions,
   HttpMethod,
   type ParamDecoratorOptions,
   type ParamMetadata,
   ParamType,
+  type RouteOptions,
 } from '../types';
 
 import { getConstructorParamTypes as getDesignParamTypes, Reflect } from './metadata';
@@ -198,6 +201,18 @@ export function controllerDecorator(basePath: string = '') {
       META_CONSTRUCTOR_PARAMS.set(WrappedController, existingDeps);
     }
 
+    // Copy controller-level middleware from original class to wrapped class
+    // This ensures @UseMiddleware works regardless of decorator order
+    const existingControllerMiddleware: Function[] | undefined =
+      Reflect.getMetadata(CONTROLLER_MIDDLEWARE_METADATA, target);
+    if (existingControllerMiddleware) {
+      Reflect.defineMetadata(
+        CONTROLLER_MIDDLEWARE_METADATA,
+        existingControllerMiddleware,
+        WrappedController,
+      );
+    }
+
     return WrappedController as T;
   };
 }
@@ -264,7 +279,7 @@ const RESPONSE_SCHEMAS_METADATA = 'onebun:responseSchemas';
  * Base route decorator factory
  */
 function createRouteDecorator(method: HttpMethod) {
-  return (path: string = '') =>
+  return (path: string = '', options?: RouteOptions) =>
     (target: object, propertyKey: string, descriptor: PropertyDescriptor) => {
       const controllerClass = target.constructor as Function;
 
@@ -307,6 +322,7 @@ function createRouteDecorator(method: HttpMethod) {
           schema: rs.schema,
           description: rs.description,
         })),
+        ...(options?.timeout !== undefined ? { timeout: options.timeout } : {}),
       });
 
       META_CONTROLLERS.set(controllerClass, metadata);
@@ -519,13 +535,186 @@ export const Req = createParamDecorator(ParamType.REQUEST);
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export const Res = createParamDecorator(ParamType.RESPONSE);
 
+// =============================================================================
+// File Upload Decorators
+// =============================================================================
+
 /**
- * Middleware decorator
- * @example \@UseMiddleware(authMiddleware)
+ * Single file upload decorator.
+ * Extracts a single file from the request (multipart/form-data or JSON base64).
+ * Required by default.
+ *
+ * @param fieldName - Form field name to extract file from
+ * @param options - File upload options (maxSize, mimeTypes, required)
+ *
+ * @example \@UploadedFile('avatar')
+ * @example \@UploadedFile('avatar', { maxSize: 5 * 1024 * 1024 })
+ * @example \@UploadedFile('avatar', { mimeTypes: [MimeType.PNG, MimeType.JPEG] })
+ * @example \@UploadedFile('avatar', { maxSize: 5 * 1024 * 1024, mimeTypes: [MimeType.ANY_IMAGE] })
  */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function UploadedFile(fieldName?: string, options?: FileUploadOptions): ParameterDecorator {
+  return (target: object, propertyKey: string | symbol | undefined, parameterIndex: number) => {
+    const params: ParamMetadata[] =
+      Reflect.getMetadata(PARAMS_METADATA, target, propertyKey) || [];
+
+    const isRequired = options?.required ?? true;
+
+    const metadata: ParamMetadata = {
+      type: ParamType.FILE,
+      name: fieldName || '',
+      index: parameterIndex,
+      isRequired,
+      fileOptions: options ? {
+        maxSize: options.maxSize,
+        mimeTypes: options.mimeTypes,
+        required: options.required,
+      } : undefined,
+    };
 
-export function UseMiddleware(...middleware: Function[]): MethodDecorator {
-  return (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
+    params.push(metadata);
+    Reflect.defineMetadata(PARAMS_METADATA, params, target, propertyKey as string);
+  };
+}
+
+/**
+ * Multiple file upload decorator.
+ * Extracts multiple files from the request (multipart/form-data or JSON base64).
+ * Required by default (at least one file expected).
+ *
+ * @param fieldName - Form field name to extract files from. If omitted, extracts all files.
+ * @param options - File upload options (maxSize, mimeTypes, maxCount, required)
+ *
+ * @example \@UploadedFiles('documents')
+ * @example \@UploadedFiles('documents', { maxCount: 5 })
+ * @example \@UploadedFiles(undefined, { maxCount: 10 }) - all files
+ * @example \@UploadedFiles('images', { mimeTypes: [MimeType.ANY_IMAGE], maxSize: 10 * 1024 * 1024 })
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function UploadedFiles(fieldName?: string, options?: FilesUploadOptions): ParameterDecorator {
+  return (target: object, propertyKey: string | symbol | undefined, parameterIndex: number) => {
+    const params: ParamMetadata[] =
+      Reflect.getMetadata(PARAMS_METADATA, target, propertyKey) || [];
+
+    const isRequired = options?.required ?? true;
+
+    const metadata: ParamMetadata = {
+      type: ParamType.FILES,
+      name: fieldName || '',
+      index: parameterIndex,
+      isRequired,
+      fileOptions: options ? {
+        maxSize: options.maxSize,
+        mimeTypes: options.mimeTypes,
+        required: options.required,
+        maxCount: options.maxCount,
+      } : undefined,
+    };
+
+    params.push(metadata);
+    Reflect.defineMetadata(PARAMS_METADATA, params, target, propertyKey as string);
+  };
+}
+
+/**
+ * Form field decorator.
+ * Extracts a non-file field from the request (multipart/form-data or JSON body).
+ * Optional by default.
+ *
+ * @param fieldName - Form field name to extract
+ * @param options - Options (required)
+ *
+ * @example \@FormField('name')
+ * @example \@FormField('name', { required: true })
+ * @example \@FormField('email')
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function FormField(fieldName: string, options?: ParamDecoratorOptions): ParameterDecorator {
+  return (target: object, propertyKey: string | symbol | undefined, parameterIndex: number) => {
+    const params: ParamMetadata[] =
+      Reflect.getMetadata(PARAMS_METADATA, target, propertyKey) || [];
+
+    const isRequired = options?.required ?? false;
+
+    const metadata: ParamMetadata = {
+      type: ParamType.FORM_FIELD,
+      name: fieldName,
+      index: parameterIndex,
+      isRequired,
+    };
+
+    params.push(metadata);
+    Reflect.defineMetadata(PARAMS_METADATA, params, target, propertyKey as string);
+  };
+}
+
+/**
+ * Metadata key for controller-level middleware
+ */
+const CONTROLLER_MIDDLEWARE_METADATA = 'onebun:controller_middleware';
+
+/**
+ * Middleware decorator — can be applied to both controllers (class) and individual routes (method).
+ *
+ * Pass middleware **class constructors** (extending `BaseMiddleware`), not instances.
+ * The framework instantiates them once at startup with full DI support.
+ *
+ * When applied to a class, the middleware is added to **every** route in that controller
+ * and runs after global and module-level middleware but before route-level middleware.
+ *
+ * When applied to a method, the middleware runs after controller-level middleware.
+ *
+ * Execution order: global → controller → route → handler
+ *
+ * @example Class-level (all routes)
+ * ```typescript
+ * \@Controller('/admin')
+ * \@UseMiddleware(AuthMiddleware)
+ * class AdminController extends BaseController { ... }
+ * ```
+ *
+ * @example Method-level (single route)
+ * ```typescript
+ * \@Post('/action')
+ * \@UseMiddleware(LogMiddleware)
+ * action() { ... }
+ * ```
+ *
+ * @example Combined
+ * ```typescript
+ * \@Controller('/admin')
+ * \@UseMiddleware(AuthMiddleware)       // runs on every route
+ * class AdminController extends BaseController {
+ *   \@Get('/dashboard')
+ *   \@UseMiddleware(CacheMiddleware)    // runs only on this route, after auth
+ *   getDashboard() { ... }
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function UseMiddleware(...middleware: Function[]): any {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return function useMiddlewareDecorator(...args: any[]): any {
+    // ---- Class decorator: target is a constructor function ----
+    if (args.length === 1 && typeof args[0] === 'function') {
+      const target = args[0] as Function;
+      const existing: Function[] =
+        Reflect.getMetadata(CONTROLLER_MIDDLEWARE_METADATA, target) || [];
+      Reflect.defineMetadata(
+        CONTROLLER_MIDDLEWARE_METADATA,
+        [...existing, ...middleware],
+        target,
+      );
+
+      return target;
+    }
+
+    // ---- Method decorator: (target, propertyKey, descriptor) ----
+    const [target, propertyKey, descriptor] = args as [
+      object,
+      string | symbol,
+      PropertyDescriptor,
+    ];
     const existingMiddleware: Function[] =
       Reflect.getMetadata(MIDDLEWARE_METADATA, target, propertyKey) || [];
     Reflect.defineMetadata(
@@ -539,6 +728,17 @@ export function UseMiddleware(...middleware: Function[]): MethodDecorator {
   };
 }
 
+/**
+ * Get controller-level middleware class constructors for a controller class.
+ * Returns middleware registered via @UseMiddleware() applied to the class.
+ *
+ * @param target - Controller class (constructor)
+ * @returns Array of middleware class constructors
+ */
+export function getControllerMiddleware(target: Function): Function[] {
+  return Reflect.getMetadata(CONTROLLER_MIDDLEWARE_METADATA, target) || [];
+}
+
 /**
  * HTTP GET decorator
  */
@@ -604,8 +804,17 @@ export interface SseDecoratorOptions {
    * Heartbeat interval in milliseconds.
    * When set, the server will send a comment (": heartbeat\n\n")
    * at this interval to keep the connection alive.
+   * @defaultValue 30000 (30 seconds) when using @Sse() decorator
    */
   heartbeat?: number;
+
+  /**
+   * Per-request idle timeout in seconds for this SSE connection.
+   * Overrides the global `idleTimeout` from `ApplicationOptions`.
+   * Set to 0 to disable the timeout entirely.
+   * @defaultValue 600 (10 minutes) for SSE endpoints
+   */
+  timeout?: number;
 }
 
 /**
@@ -651,7 +860,10 @@ export function Sse(options?: SseDecoratorOptions): MethodDecorator {
 }
 
 /**
- * Check if a method is marked as SSE endpoint
+ * Check if a method is marked as SSE endpoint.
+ * Traverses the prototype chain so that metadata stored on the original class
+ * prototype is found even when `@Controller` wraps the class.
+ *
  * @param target - Controller instance or prototype
  * @param methodName - Method name
  * @returns SSE options if method is SSE endpoint, undefined otherwise
@@ -660,7 +872,16 @@ export function getSseMetadata(
   target: object,
   methodName: string,
 ): SseDecoratorOptions | undefined {
-  return Reflect.getMetadata(SSE_METADATA, target, methodName);
+  let proto: object | null = target;
+  while (proto) {
+    const metadata = Reflect.getMetadata(SSE_METADATA, proto, methodName);
+    if (metadata !== undefined) {
+      return metadata;
+    }
+    proto = Object.getPrototypeOf(proto);
+  }
+
+  return undefined;
 }
 
 /**