@onebun/core 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onebun/core",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Core package for OneBun framework - decorators, DI, modules, controllers",
   "license": "LGPL-3.0",
   "author": "RemRyahirev",

package/src/application/application.ts

@@ -30,6 +30,7 @@ import {
   getSseMetadata,
   type SseDecoratorOptions,
 } from '../decorators/decorators';
+import { OneBunFile, validateFile } from '../file/onebun-file';
 import {
   NotInitializedConfig,
   type IConfig,
@@ -911,6 +912,43 @@ export class OneBunApplication {
       throw error;
     }
 
+    /**
+     * Extract an OneBunFile from a JSON value.
+     * Supports two formats:
+     * - String: raw base64 data
+     * - Object: { data: string, filename?: string, mimeType?: string }
+     */
+    function extractFileFromJsonValue(value: unknown): OneBunFile | undefined {
+      if (typeof value === 'string' && value.length > 0) {
+        return OneBunFile.fromBase64(value);
+      }
+
+      if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const obj = value as Record<string, unknown>;
+        if (typeof obj.data === 'string' && obj.data.length > 0) {
+          return OneBunFile.fromBase64(
+            obj.data,
+            typeof obj.filename === 'string' ? obj.filename : undefined,
+            typeof obj.mimeType === 'string' ? obj.mimeType : undefined,
+          );
+        }
+      }
+
+      return undefined;
+    }
+
+    /**
+     * Extract a file from a JSON body by field name
+     */
+    function extractFileFromJson(
+      jsonBody: Record<string, unknown>,
+      fieldName: string,
+    ): OneBunFile | undefined {
+      const fieldValue = jsonBody[fieldName];
+
+      return extractFileFromJsonValue(fieldValue);
+    }
+
     /**
      * Execute route handler with parameter injection and validation.
      * Path parameters come from BunRequest.params (populated by Bun routes API).
@@ -951,6 +989,52 @@ export class OneBunApplication {
       // Sort params by index to ensure correct order
       const sortedParams = [...(route.params || [])].sort((a, b) => a.index - b.index);
 
+      // Pre-parse body for file upload params (FormData or JSON, cached for all params)
+      const needsFileData = sortedParams.some(
+        (p) =>
+          p.type === ParamType.FILE ||
+          p.type === ParamType.FILES ||
+          p.type === ParamType.FORM_FIELD,
+      );
+
+      // Validate that @Body and file decorators are not used on the same method
+      if (needsFileData) {
+        const hasBody = sortedParams.some((p) => p.type === ParamType.BODY);
+        if (hasBody) {
+          throw new Error(
+            'Cannot use @Body() together with @UploadedFile/@UploadedFiles/@FormField on the same method. ' +
+            'Both consume the request body. Use file decorators for multipart/base64 uploads.',
+          );
+        }
+      }
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      let formData: any = null;
+      let jsonBody: Record<string, unknown> | null = null;
+      let isMultipart = false;
+
+      if (needsFileData) {
+        const contentType = req.headers.get('content-type') || '';
+
+        if (contentType.includes('multipart/form-data')) {
+          isMultipart = true;
+          try {
+            formData = await req.formData();
+          } catch {
+            formData = null;
+          }
+        } else if (contentType.includes('application/json')) {
+          try {
+            const parsed = await req.json();
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+              jsonBody = parsed as Record<string, unknown>;
+            }
+          } catch {
+            jsonBody = null;
+          }
+        }
+      }
+
       for (const param of sortedParams) {
         switch (param.type) {
           case ParamType.PATH:
@@ -989,6 +1073,100 @@ export class OneBunApplication {
             args[param.index] = undefined;
             break;
 
+          case ParamType.FILE: {
+            let file: OneBunFile | undefined;
+
+            if (isMultipart && formData && param.name) {
+              const entry = formData.get(param.name);
+              if (entry instanceof File) {
+                file = new OneBunFile(entry);
+              }
+            } else if (jsonBody && param.name) {
+              file = extractFileFromJson(jsonBody, param.name);
+            }
+
+            if (file && param.fileOptions) {
+              validateFile(file, param.fileOptions, param.name);
+            }
+
+            args[param.index] = file;
+            break;
+          }
+
+          case ParamType.FILES: {
+            let files: OneBunFile[] = [];
+
+            if (isMultipart && formData) {
+              if (param.name) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const entries: any[] = formData.getAll(param.name);
+                files = entries
+                  .filter((entry: unknown): entry is File => entry instanceof File)
+                  .map((f: File) => new OneBunFile(f));
+              } else {
+                // Get all files from all fields
+                for (const [, value] of formData.entries()) {
+                  if (value instanceof File) {
+                    files.push(new OneBunFile(value));
+                  }
+                }
+              }
+            } else if (jsonBody) {
+              if (param.name) {
+                const fieldValue = jsonBody[param.name];
+                if (Array.isArray(fieldValue)) {
+                  files = fieldValue
+                    .map((item) => extractFileFromJsonValue(item))
+                    .filter((f): f is OneBunFile => f !== undefined);
+                }
+              } else {
+                // Extract all file-like values from JSON
+                for (const [, value] of Object.entries(jsonBody)) {
+                  const file = extractFileFromJsonValue(value);
+                  if (file) {
+                    files.push(file);
+                  }
+                }
+              }
+            }
+
+            // Validate maxCount
+            if (param.fileOptions?.maxCount !== undefined && files.length > param.fileOptions.maxCount) {
+              throw new Error(
+                `Too many files for "${param.name || 'upload'}". Got ${files.length}, max is ${param.fileOptions.maxCount}`,
+              );
+            }
+
+            // Validate each file
+            if (param.fileOptions) {
+              for (const file of files) {
+                validateFile(file, param.fileOptions, param.name);
+              }
+            }
+
+            args[param.index] = files;
+            break;
+          }
+
+          case ParamType.FORM_FIELD: {
+            let value: string | undefined;
+
+            if (isMultipart && formData && param.name) {
+              const entry = formData.get(param.name);
+              if (typeof entry === 'string') {
+                value = entry;
+              }
+            } else if (jsonBody && param.name) {
+              const jsonValue = jsonBody[param.name];
+              if (jsonValue !== undefined && jsonValue !== null) {
+                value = String(jsonValue);
+              }
+            }
+
+            args[param.index] = value;
+            break;
+          }
+
           default:
             args[param.index] = undefined;
         }
@@ -998,6 +1176,16 @@ export class OneBunApplication {
           throw new Error(`Required parameter ${param.name || param.index} is missing`);
         }
 
+        // For FILES type, also check for empty array when required
+        if (
+          param.isRequired &&
+          param.type === ParamType.FILES &&
+          Array.isArray(args[param.index]) &&
+          (args[param.index] as unknown[]).length === 0
+        ) {
+          throw new Error(`Required parameter ${param.name || param.index} is missing`);
+        }
+
         // Apply arktype schema validation if provided
         if (param.schema && args[param.index] !== undefined) {
           try {

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,
@@ -519,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)