@onebun/core 0.2.0 → 0.2.2

package/src/file/index.ts

@@ -0,0 +1,8 @@
+/**
+ * File Upload Module
+ *
+ * Provides OneBunFile class, MimeType enum, and file validation helpers.
+ */
+export {
+  OneBunFile, MimeType, matchMimeType, validateFile, type FileValidationOptions, 
+} from './onebun-file';

package/src/file/onebun-file.test.ts

@@ -0,0 +1,315 @@
+import {
+  describe,
+  it,
+  expect,
+} from 'bun:test';
+
+import {
+  OneBunFile,
+  MimeType,
+  matchMimeType,
+  validateFile,
+} from './onebun-file';
+
+// =============================================================================
+// OneBunFile Class Tests
+// =============================================================================
+
+describe('OneBunFile', () => {
+  describe('constructor', () => {
+    it('should create from File object', () => {
+      const file = new File(['hello world'], 'test.txt', { type: 'text/plain' });
+      const oneBunFile = new OneBunFile(file);
+
+      expect(oneBunFile.name).toBe('test.txt');
+      expect(oneBunFile.size).toBe(11);
+      expect(oneBunFile.type).toStartWith('text/plain');
+      expect(oneBunFile.lastModified).toBeGreaterThan(0);
+    });
+
+    it('should preserve file metadata', () => {
+      const file = new File(['data'], 'image.png', {
+        type: 'image/png',
+        lastModified: 1700000000000,
+      });
+      const oneBunFile = new OneBunFile(file);
+
+      expect(oneBunFile.name).toBe('image.png');
+      expect(oneBunFile.type).toBe('image/png');
+      expect(oneBunFile.lastModified).toBe(1700000000000);
+    });
+  });
+
+  describe('fromBase64', () => {
+    it('should create from raw base64 string', () => {
+      const base64 = btoa('hello world');
+      const file = OneBunFile.fromBase64(base64, 'test.txt', 'text/plain');
+
+      expect(file.name).toBe('test.txt');
+      expect(file.size).toBe(11);
+      expect(file.type).toStartWith('text/plain');
+    });
+
+    it('should create with default name and mime type', () => {
+      const base64 = btoa('data');
+      const file = OneBunFile.fromBase64(base64);
+
+      expect(file.name).toBe('upload');
+      expect(file.type).toBe('application/octet-stream');
+    });
+
+    it('should handle data URI format', () => {
+      const base64 = btoa('png-data');
+      const dataUri = `data:image/png;base64,${base64}`;
+      const file = OneBunFile.fromBase64(dataUri, 'photo.png');
+
+      expect(file.type).toBe('image/png');
+      expect(file.name).toBe('photo.png');
+    });
+
+    it('should detect mime type from data URI even when explicit type is given', () => {
+      const base64 = btoa('svg-data');
+      const dataUri = `data:image/svg+xml;base64,${base64}`;
+      // Data URI mime type should override the explicit one
+      const file = OneBunFile.fromBase64(dataUri, 'image.svg', 'text/plain');
+
+      expect(file.type).toBe('image/svg+xml');
+    });
+  });
+
+  describe('toBase64', () => {
+    it('should convert file to base64', async () => {
+      const content = 'hello world';
+      const file = new File([content], 'test.txt', { type: 'text/plain' });
+      const oneBunFile = new OneBunFile(file);
+
+      const base64 = await oneBunFile.toBase64();
+      expect(base64).toBe(btoa(content));
+    });
+
+    it('should cache base64 result', async () => {
+      const file = new File(['test'], 'test.txt', { type: 'text/plain' });
+      const oneBunFile = new OneBunFile(file);
+
+      const first = await oneBunFile.toBase64();
+      const second = await oneBunFile.toBase64();
+      expect(first).toBe(second);
+    });
+
+    it('should return cached base64 for fromBase64 files', async () => {
+      const original = btoa('cached data');
+      const file = OneBunFile.fromBase64(original, 'test.txt');
+
+      const result = await file.toBase64();
+      expect(result).toBe(original);
+    });
+  });
+
+  describe('toBuffer', () => {
+    it('should convert file to Buffer', async () => {
+      const content = 'buffer test';
+      const file = new File([content], 'test.txt', { type: 'text/plain' });
+      const oneBunFile = new OneBunFile(file);
+
+      const buffer = await oneBunFile.toBuffer();
+      expect(buffer).toBeInstanceOf(Buffer);
+      expect(buffer.toString()).toBe(content);
+    });
+  });
+
+  describe('toArrayBuffer', () => {
+    it('should convert file to ArrayBuffer', async () => {
+      const content = 'arraybuffer test';
+      const file = new File([content], 'test.txt', { type: 'text/plain' });
+      const oneBunFile = new OneBunFile(file);
+
+      const ab = await oneBunFile.toArrayBuffer();
+      expect(ab).toBeInstanceOf(ArrayBuffer);
+      expect(ab.byteLength).toBe(content.length);
+    });
+  });
+
+  describe('toBlob', () => {
+    it('should return underlying Blob', () => {
+      const file = new File(['blob test'], 'test.txt', { type: 'text/plain' });
+      const oneBunFile = new OneBunFile(file);
+
+      const blob = oneBunFile.toBlob();
+      expect(blob).toBeInstanceOf(Blob);
+      expect(blob.size).toBe(9);
+    });
+  });
+});
+
+// =============================================================================
+// MimeType Enum Tests
+// =============================================================================
+
+describe('MimeType', () => {
+  it('should have wildcard values', () => {
+    expect(String(MimeType.ANY)).toBe('*/*');
+    expect(String(MimeType.ANY_IMAGE)).toBe('image/*');
+    expect(String(MimeType.ANY_VIDEO)).toBe('video/*');
+    expect(String(MimeType.ANY_AUDIO)).toBe('audio/*');
+    expect(String(MimeType.ANY_TEXT)).toBe('text/*');
+    expect(String(MimeType.ANY_APPLICATION)).toBe('application/*');
+  });
+
+  it('should have image types', () => {
+    expect(String(MimeType.PNG)).toBe('image/png');
+    expect(String(MimeType.JPEG)).toBe('image/jpeg');
+    expect(String(MimeType.GIF)).toBe('image/gif');
+    expect(String(MimeType.WEBP)).toBe('image/webp');
+    expect(String(MimeType.SVG)).toBe('image/svg+xml');
+    expect(String(MimeType.AVIF)).toBe('image/avif');
+  });
+
+  it('should have document types', () => {
+    expect(String(MimeType.PDF)).toBe('application/pdf');
+    expect(String(MimeType.JSON)).toBe('application/json');
+    expect(String(MimeType.CSV)).toBe('text/csv');
+    expect(String(MimeType.ZIP)).toBe('application/zip');
+  });
+
+  it('should have media types', () => {
+    expect(String(MimeType.MP4)).toBe('video/mp4');
+    expect(String(MimeType.MP3)).toBe('audio/mpeg');
+    expect(String(MimeType.WAV)).toBe('audio/wav');
+  });
+
+  it('should have text types', () => {
+    expect(String(MimeType.PLAIN)).toBe('text/plain');
+    expect(String(MimeType.HTML)).toBe('text/html');
+    expect(String(MimeType.CSS)).toBe('text/css');
+  });
+
+  it('should have binary type', () => {
+    expect(String(MimeType.OCTET_STREAM)).toBe('application/octet-stream');
+  });
+});
+
+// =============================================================================
+// matchMimeType Tests
+// =============================================================================
+
+describe('matchMimeType', () => {
+  it('should match exact MIME types', () => {
+    expect(matchMimeType('image/png', 'image/png')).toBe(true);
+    expect(matchMimeType('text/plain', 'text/plain')).toBe(true);
+    expect(matchMimeType('application/pdf', 'application/pdf')).toBe(true);
+  });
+
+  it('should not match different MIME types', () => {
+    expect(matchMimeType('image/png', 'image/jpeg')).toBe(false);
+    expect(matchMimeType('text/plain', 'text/html')).toBe(false);
+    expect(matchMimeType('image/png', 'video/mp4')).toBe(false);
+  });
+
+  it('should match wildcard subtypes', () => {
+    expect(matchMimeType('image/png', 'image/*')).toBe(true);
+    expect(matchMimeType('image/jpeg', 'image/*')).toBe(true);
+    expect(matchMimeType('image/webp', 'image/*')).toBe(true);
+    expect(matchMimeType('video/mp4', 'video/*')).toBe(true);
+    expect(matchMimeType('audio/mpeg', 'audio/*')).toBe(true);
+  });
+
+  it('should not match wrong type with wildcard', () => {
+    expect(matchMimeType('video/mp4', 'image/*')).toBe(false);
+    expect(matchMimeType('text/plain', 'image/*')).toBe(false);
+  });
+
+  it('should match universal wildcard', () => {
+    expect(matchMimeType('image/png', '*/*')).toBe(true);
+    expect(matchMimeType('video/mp4', '*/*')).toBe(true);
+    expect(matchMimeType('application/json', '*/*')).toBe(true);
+  });
+
+  it('should work with MimeType enum values', () => {
+    expect(matchMimeType('image/png', MimeType.ANY_IMAGE)).toBe(true);
+    expect(matchMimeType('image/png', MimeType.PNG)).toBe(true);
+    expect(matchMimeType('image/png', MimeType.JPEG)).toBe(false);
+    expect(matchMimeType('application/pdf', MimeType.ANY_APPLICATION)).toBe(true);
+  });
+});
+
+// =============================================================================
+// validateFile Tests
+// =============================================================================
+
+describe('validateFile', () => {
+  it('should pass validation when no constraints', () => {
+    const file = new File(['data'], 'test.txt', { type: 'text/plain' });
+    const oneBunFile = new OneBunFile(file);
+
+    expect(() => validateFile(oneBunFile, {})).not.toThrow();
+  });
+
+  it('should pass when file is within size limit', () => {
+    const file = new File(['small'], 'test.txt', { type: 'text/plain' });
+    const oneBunFile = new OneBunFile(file);
+
+    expect(() => validateFile(oneBunFile, { maxSize: 1024 })).not.toThrow();
+  });
+
+  it('should throw when file exceeds size limit', () => {
+    const file = new File(['x'.repeat(100)], 'test.txt', { type: 'text/plain' });
+    const oneBunFile = new OneBunFile(file);
+
+    expect(() => validateFile(oneBunFile, { maxSize: 10 })).toThrow(
+      /exceeds maximum size/,
+    );
+  });
+
+  it('should include field name in size error', () => {
+    const file = new File(['x'.repeat(100)], 'test.txt', { type: 'text/plain' });
+    const oneBunFile = new OneBunFile(file);
+
+    expect(() => validateFile(oneBunFile, { maxSize: 10 }, 'avatar')).toThrow(
+      /File "avatar" exceeds maximum size/,
+    );
+  });
+
+  it('should pass when MIME type matches', () => {
+    const file = new File(['data'], 'test.png', { type: 'image/png' });
+    const oneBunFile = new OneBunFile(file);
+
+    expect(() => validateFile(oneBunFile, { mimeTypes: ['image/*'] })).not.toThrow();
+  });
+
+  it('should pass when MIME type matches one of multiple', () => {
+    const file = new File(['data'], 'test.png', { type: 'image/png' });
+    const oneBunFile = new OneBunFile(file);
+
+    expect(() =>
+      validateFile(oneBunFile, { mimeTypes: ['application/pdf', 'image/png'] }),
+    ).not.toThrow();
+  });
+
+  it('should throw when MIME type does not match', () => {
+    const file = new File(['data'], 'test.txt', { type: 'text/plain' });
+    const oneBunFile = new OneBunFile(file);
+
+    expect(() => validateFile(oneBunFile, { mimeTypes: ['image/*'] })).toThrow(
+      /invalid MIME type/,
+    );
+  });
+
+  it('should include field name in MIME error', () => {
+    const file = new File(['data'], 'test.txt', { type: 'text/plain' });
+    const oneBunFile = new OneBunFile(file);
+
+    expect(() =>
+      validateFile(oneBunFile, { mimeTypes: ['image/*'] }, 'document'),
+    ).toThrow(/File "document" has invalid MIME type/);
+  });
+
+  it('should validate both size and MIME type', () => {
+    const file = new File(['x'.repeat(100)], 'big.txt', { type: 'text/plain' });
+    const oneBunFile = new OneBunFile(file);
+
+    // Fails on size first
+    expect(() =>
+      validateFile(oneBunFile, { maxSize: 10, mimeTypes: ['image/*'] }),
+    ).toThrow(/exceeds maximum size/);
+  });
+});

package/src/file/onebun-file.ts

@@ -0,0 +1,304 @@
+/**
+ * OneBunFile - Unified file wrapper for file uploads
+ *
+ * Provides a consistent interface for files uploaded via:
+ * - multipart/form-data (standard file upload)
+ * - JSON body with base64-encoded data
+ *
+ * @example
+ * ```typescript
+ * // Access file metadata
+ * console.log(file.name);  // "photo.png"
+ * console.log(file.size);  // 1024
+ * console.log(file.type);  // "image/png"
+ *
+ * // Convert to base64
+ * const base64 = await file.toBase64();
+ *
+ * // Write to disk
+ * await file.writeTo('./uploads/photo.png');
+ *
+ * // Get as Buffer
+ * const buffer = await file.toBuffer();
+ * ```
+ */
+export class OneBunFile {
+  /** File name (e.g., "photo.png") */
+  readonly name: string;
+  /** File size in bytes */
+  readonly size: number;
+  /** MIME type (e.g., "image/png") */
+  readonly type: string;
+  /** Last modified timestamp */
+  readonly lastModified: number;
+
+  private readonly _blob: Blob;
+  private _base64Cache?: string;
+
+  /**
+   * Create from a Web API File (typically from multipart/form-data)
+   */
+  constructor(file: File) {
+    this.name = file.name;
+    this.size = file.size;
+    this.type = file.type;
+    this.lastModified = file.lastModified;
+    this._blob = file;
+  }
+
+  /**
+   * Create OneBunFile from a base64-encoded string
+   *
+   * @param data - Base64-encoded file data (with or without data URI prefix)
+   * @param filename - File name (default: "upload")
+   * @param mimeType - MIME type (default: "application/octet-stream")
+   * @returns OneBunFile instance
+   *
+   * @example
+   * ```typescript
+   * // From raw base64
+   * const file = OneBunFile.fromBase64('iVBORw0KGgo...', 'photo.png', 'image/png');
+   *
+   * // From data URI
+   * const file = OneBunFile.fromBase64('data:image/png;base64,iVBORw0KGgo...', 'photo.png');
+   * ```
+   */
+  static fromBase64(
+    data: string,
+    filename: string = 'upload',
+    mimeType: string = MimeType.OCTET_STREAM,
+  ): OneBunFile {
+    // Handle data URI format: "data:image/png;base64,iVBORw0KGgo..."
+    let base64Data = data;
+    let detectedMimeType = mimeType;
+
+    const dataUriMatch = data.match(/^data:([^;]+);base64,(.+)$/);
+    if (dataUriMatch) {
+      detectedMimeType = dataUriMatch[1];
+      base64Data = dataUriMatch[2];
+    }
+
+    const binaryString = atob(base64Data);
+    const bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+      bytes[i] = binaryString.charCodeAt(i);
+    }
+
+    const file = new File([bytes], filename, {
+      type: detectedMimeType,
+      lastModified: Date.now(),
+    });
+
+    const oneBunFile = new OneBunFile(file);
+    // Cache the base64 since we already have it
+    oneBunFile._base64Cache = base64Data;
+
+    return oneBunFile;
+  }
+
+  /**
+   * Convert file content to a base64-encoded string.
+   * Result is cached after the first call.
+   *
+   * @returns Base64-encoded string (without data URI prefix)
+   */
+  async toBase64(): Promise<string> {
+    if (this._base64Cache) {
+      return this._base64Cache;
+    }
+
+    const arrayBuffer = await this._blob.arrayBuffer();
+    const bytes = new Uint8Array(arrayBuffer);
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+      binary += String.fromCharCode(bytes[i]);
+    }
+    this._base64Cache = btoa(binary);
+
+    return this._base64Cache;
+  }
+
+  /**
+   * Convert file content to a Buffer
+   */
+  async toBuffer(): Promise<Buffer> {
+    const arrayBuffer = await this._blob.arrayBuffer();
+
+    return Buffer.from(arrayBuffer);
+  }
+
+  /**
+   * Convert file content to an ArrayBuffer
+   */
+  async toArrayBuffer(): Promise<ArrayBuffer> {
+    return await this._blob.arrayBuffer();
+  }
+
+  /**
+   * Get the underlying Blob
+   */
+  toBlob(): Blob {
+    return this._blob;
+  }
+
+  /**
+   * Write file to disk using Bun.write()
+   *
+   * @param path - Destination file path
+   *
+   * @example
+   * ```typescript
+   * await file.writeTo('./uploads/photo.png');
+   * await file.writeTo(`./uploads/${file.name}`);
+   * ```
+   */
+  async writeTo(path: string): Promise<void> {
+    await Bun.write(path, this._blob);
+  }
+}
+
+// =============================================================================
+// MimeType Enum
+// =============================================================================
+
+/**
+ * Common MIME types for use with file upload decorators.
+ * Includes wildcard groups for matching entire categories.
+ *
+ * @example
+ * ```typescript
+ * // Accept only images
+ * \@UploadedFile('avatar', { mimeTypes: [MimeType.ANY_IMAGE] })
+ *
+ * // Accept specific types
+ * \@UploadedFile('avatar', { mimeTypes: [MimeType.PNG, MimeType.JPEG, MimeType.WEBP] })
+ *
+ * // Mix enum values and string literals
+ * \@UploadedFile('doc', { mimeTypes: [MimeType.PDF, 'application/msword'] })
+ * ```
+ */
+export enum MimeType {
+  // Wildcard groups
+  ANY = '*/*',
+  ANY_IMAGE = 'image/*',
+  ANY_VIDEO = 'video/*',
+  ANY_AUDIO = 'audio/*',
+  ANY_TEXT = 'text/*',
+  ANY_APPLICATION = 'application/*',
+
+  // Images
+  PNG = 'image/png',
+  JPEG = 'image/jpeg',
+  GIF = 'image/gif',
+  WEBP = 'image/webp',
+  SVG = 'image/svg+xml',
+  ICO = 'image/x-icon',
+  BMP = 'image/bmp',
+  AVIF = 'image/avif',
+
+  // Documents
+  PDF = 'application/pdf',
+   
+  JSON = 'application/json',
+  XML = 'application/xml',
+  ZIP = 'application/zip',
+  GZIP = 'application/gzip',
+  CSV = 'text/csv',
+  XLSX = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  DOCX = 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+
+  // Video
+  MP4 = 'video/mp4',
+  WEBM = 'video/webm',
+
+  // Audio
+  MP3 = 'audio/mpeg',
+  WAV = 'audio/wav',
+  OGG = 'audio/ogg',
+
+  // Text
+  PLAIN = 'text/plain',
+  HTML = 'text/html',
+  CSS = 'text/css',
+  JAVASCRIPT = 'text/javascript',
+
+  // Binary
+  OCTET_STREAM = 'application/octet-stream',
+}
+
+// =============================================================================
+// File Validation Helpers
+// =============================================================================
+
+/**
+ * Check if a MIME type matches a pattern (supports wildcards).
+ *
+ * @param actual - The actual MIME type of the file (e.g., "image/png")
+ * @param pattern - The pattern to match against (e.g., "image/*", "image/png", "*\/*")
+ * @returns true if the actual MIME type matches the pattern
+ *
+ * @example
+ * ```typescript
+ * matchMimeType('image/png', 'image/*')    // true
+ * matchMimeType('image/png', 'image/png')  // true
+ * matchMimeType('image/png', 'video/*')    // false
+ * matchMimeType('image/png', '*\/*')       // true
+ * ```
+ */
+export function matchMimeType(actual: string, pattern: string): boolean {
+  if (pattern === '*/*') {
+    return true;
+  }
+
+  const [patternType, patternSubtype] = pattern.split('/');
+  const [actualType, actualSubtype] = actual.split('/');
+
+  if (patternSubtype === '*') {
+    return patternType === actualType;
+  }
+
+  return patternType === actualType && patternSubtype === actualSubtype;
+}
+
+/**
+ * Options for file validation
+ */
+export interface FileValidationOptions {
+  /** Maximum file size in bytes */
+  maxSize?: number;
+  /** Allowed MIME types (supports wildcards like 'image/*') */
+  mimeTypes?: string[];
+}
+
+/**
+ * Validate a file against size and MIME type constraints.
+ * Throws an Error with a descriptive message if validation fails.
+ *
+ * @param file - The OneBunFile to validate
+ * @param options - Validation options
+ * @param fieldName - Field name for error messages
+ */
+export function validateFile(
+  file: OneBunFile,
+  options: FileValidationOptions,
+  fieldName?: string,
+): void {
+  const prefix = fieldName ? `File "${fieldName}"` : 'File';
+
+  // Validate file size
+  if (options.maxSize !== undefined && file.size > options.maxSize) {
+    throw new Error(
+      `${prefix} exceeds maximum size. Got ${file.size} bytes, max is ${options.maxSize} bytes`,
+    );
+  }
+
+  // Validate MIME type
+  if (options.mimeTypes && options.mimeTypes.length > 0) {
+    const matches = options.mimeTypes.some((pattern) => matchMimeType(file.type, pattern));
+    if (!matches) {
+      throw new Error(
+        `${prefix} has invalid MIME type "${file.type}". Allowed: ${options.mimeTypes.join(', ')}`,
+      );
+    }
+  }
+}

package/src/index.ts

@@ -36,8 +36,14 @@ export {
   type ParamDecoratorOptions,
   type ParamMetadata,
   type ResponseSchemaMetadata,
+  type RouteOptions,
   type RouteMetadata,
   type ControllerMetadata,
+  type MiddlewareClass,
+  type OnModuleConfigure,
+  // File upload types
+  type FileUploadOptions,
+  type FilesUploadOptions,
   // WebSocket types are exported from ./websocket
   type WsStorageType,
   type WsStorageOptions,
@@ -53,6 +59,11 @@ export {
 // Decorators and Metadata (exports Controller decorator, Module decorator, etc.)
 export * from './decorators';
 
+// File Upload (OneBunFile class, MimeType enum, helpers)
+export {
+  OneBunFile, MimeType, matchMimeType, validateFile, 
+} from './file';
+
 // Module System - explicitly re-export to avoid Controller conflict
 export {
   OneBunModule,
@@ -78,6 +89,8 @@ export {
   type OnModuleDestroy,
   type BeforeApplicationDestroy,
   type OnApplicationDestroy,
+  // Middleware
+  BaseMiddleware,
   // Lifecycle hooks helper functions
   hasOnModuleInit,
   hasOnApplicationInit,
@@ -89,6 +102,13 @@ export {
   callOnModuleDestroy,
   callBeforeApplicationDestroy,
   callOnApplicationDestroy,
+  // SSE helpers
+  formatSseEvent,
+  createSseStream,
+  // Server & SSE default constants
+  DEFAULT_IDLE_TIMEOUT,
+  DEFAULT_SSE_HEARTBEAT_MS,
+  DEFAULT_SSE_TIMEOUT,
 } from './module';
 
 // Application