@onebun/core 0.1.24 → 0.2.1

package/src/decorators/decorators.test.ts

@@ -49,6 +49,9 @@ import {
   Module,
   getModuleMetadata,
   ApiResponse,
+  UploadedFile,
+  UploadedFiles,
+  FormField,
 } from './decorators';
 
 describe('decorators', () => {
@@ -1077,4 +1080,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,6 +3,8 @@ import { type, type Type } from 'arktype';
 
 import {
   type ControllerMetadata,
+  type FileUploadOptions,
+  type FilesUploadOptions,
   HttpMethod,
   type ParamDecoratorOptions,
   type ParamMetadata,
@@ -493,6 +495,18 @@ export const Body = createParamDecorator(ParamType.BODY);
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export const Header = createParamDecorator(ParamType.HEADER);
 
+/**
+ * Cookie parameter decorator.
+ * Extracts a cookie value by name using BunRequest.cookies (CookieMap).
+ * Optional by default, use { required: true } for required cookies.
+ * @example \@Cookie('session_id') - optional
+ * @example \@Cookie('session_id', { required: true }) - required
+ * @example \@Cookie('session_id', schema) - optional with validation
+ * @example \@Cookie('session_id', schema, { required: true }) - required with validation
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const Cookie = createParamDecorator(ParamType.COOKIE);
+
 /**
  * Request object decorator
  * @example \@Req()
@@ -507,6 +521,119 @@ export const Req = createParamDecorator(ParamType.REQUEST);
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export const Res = createParamDecorator(ParamType.RESPONSE);
 
+// =============================================================================
+// File Upload Decorators
+// =============================================================================
+
+/**
+ * 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,
+    };
+
+    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);
+  };
+}
+
 /**
  * Middleware decorator
  * @example \@UseMiddleware(authMiddleware)