@onebun/core 0.2.0 → 0.2.2

package/src/docs-examples.test.ts

@@ -38,9 +38,95 @@ import type {
   SseGenerator,
   OneBunRequest,
   OneBunResponse,
+  MiddlewareClass,
+  OnModuleConfigure,
 } from './types';
 import type { ServerWebSocket } from 'bun';
 
+import {
+  Controller,
+  Get,
+  Post,
+  Put,
+  Delete,
+  Patch,
+  Param,
+  Query,
+  Body,
+  Header,
+  Req,
+  Cookie,
+  Module,
+  Service,
+  BaseService,
+  BaseController,
+  UseMiddleware,
+  getControllerMiddleware,
+  getServiceTag,
+  getControllerMetadata,
+  HttpStatusCode,
+  ParamType,
+  NotFoundError,
+  InternalServerError,
+  OneBunBaseError,
+  Env,
+  validate,
+  validateOrThrow,
+  MultiServiceApplication,
+  OneBunApplication,
+  createServiceDefinition,
+  createServiceClient,
+  WebSocketGateway,
+  BaseWebSocketGateway,
+  OnConnect,
+  OnDisconnect,
+  OnJoinRoom,
+  OnLeaveRoom,
+  OnMessage,
+  Client,
+  Socket,
+  MessageData,
+  RoomName,
+  PatternParams,
+  WsServer,
+  UseWsGuards,
+  WsAuthGuard,
+  WsPermissionGuard,
+  WsAnyPermissionGuard,
+  createGuard,
+  createInMemoryWsStorage,
+  SharedRedisProvider,
+  Sse,
+  getSseMetadata,
+  formatSseEvent,
+  createSseStream,
+  createWsServiceDefinition,
+  createWsClient,
+  createNativeWsClient,
+  matchPattern,
+  makeMockLoggerLayer,
+  hasOnModuleInit,
+  hasOnApplicationInit,
+  hasOnModuleDestroy,
+  hasBeforeApplicationDestroy,
+  hasOnApplicationDestroy,
+  callOnModuleInit,
+  callOnApplicationInit,
+  callOnModuleDestroy,
+  callBeforeApplicationDestroy,
+  callOnApplicationDestroy,
+  UploadedFile,
+  UploadedFiles,
+  FormField,
+  OneBunFile,
+  MimeType,
+  matchMimeType,
+  BaseMiddleware,
+  DEFAULT_IDLE_TIMEOUT,
+  DEFAULT_SSE_HEARTBEAT_MS,
+  DEFAULT_SSE_TIMEOUT,
+} from './';
+
 
 /**
  * @source docs/index.md#minimal-working-example
@@ -241,8 +327,8 @@ describe('Core README Examples', () => {
     it('should use middleware decorator', () => {
       // From README: Middleware example
       function loggerMiddleware(
-        _req: Request,
-        next: () => Promise<Response>,
+        _req: OneBunRequest,
+        next: () => Promise<OneBunResponse>,
       ): Promise<Response> {
         // eslint-disable-next-line no-console
         console.log('Request received');
@@ -251,8 +337,8 @@ describe('Core README Examples', () => {
       }
 
       function authMiddleware(
-        req: Request,
-        next: () => Promise<Response>,
+        req: OneBunRequest,
+        next: () => Promise<OneBunResponse>,
       ): Promise<Response> {
         const token = req.headers.get('Authorization');
         if (!token) {
@@ -485,8 +571,8 @@ describe('Decorators API Documentation Examples', () => {
     it('should apply middleware to route handler', () => {
       // From docs: @UseMiddleware() example
       const authMiddleware = async (
-        req: Request,
-        next: () => Promise<Response>,
+        req: OneBunRequest,
+        next: () => Promise<OneBunResponse>,
       ) => {
         const token = req.headers.get('Authorization');
         if (!token) {
@@ -497,8 +583,8 @@ describe('Decorators API Documentation Examples', () => {
       };
 
       const logMiddleware = async (
-        _req: Request,
-        next: () => Promise<Response>,
+        _req: OneBunRequest,
+        next: () => Promise<OneBunResponse>,
       ) => {
         // eslint-disable-next-line no-console
         console.log('Request logged');
@@ -523,6 +609,60 @@ describe('Decorators API Documentation Examples', () => {
 
       expect(UserController).toBeDefined();
     });
+
+    it('should apply middleware to all routes when used as class decorator (docs/api/decorators.md)', () => {
+      // From docs: @UseMiddleware() class-level example
+      const authMiddleware = async (
+        req: OneBunRequest,
+        next: () => Promise<OneBunResponse>,
+      ) => {
+        const token = req.headers.get('Authorization');
+        if (!token) {
+          return new Response('Unauthorized', { status: 401 });
+        }
+
+        return await next();
+      };
+
+      const auditLogMiddleware = async (
+        _req: OneBunRequest,
+        next: () => Promise<OneBunResponse>,
+      ) => await next();
+
+      @Controller('/admin')
+      @UseMiddleware(authMiddleware) // Applied to ALL routes in this controller
+      class AdminController extends BaseController {
+        @Get('/dashboard')
+        getDashboard() {
+          return this.success({ stats: {} });
+        }
+
+        @Put('/settings')
+        @UseMiddleware(auditLogMiddleware) // Additional middleware for this route
+        updateSettings() {
+          return this.success({ updated: true });
+        }
+      }
+
+      expect(AdminController).toBeDefined();
+
+      // Verify controller-level middleware is stored
+      const ctrlMiddleware = getControllerMiddleware(AdminController);
+      expect(ctrlMiddleware).toHaveLength(1);
+      expect(ctrlMiddleware[0]).toBe(authMiddleware);
+
+      // Verify route-level middleware is stored on the method
+      const metadata = getControllerMetadata(AdminController);
+      expect(metadata).toBeDefined();
+
+      const settingsRoute = metadata!.routes.find((r) => r.path === '/settings');
+      expect(settingsRoute?.middleware).toHaveLength(1);
+      expect(settingsRoute!.middleware![0]).toBe(auditLogMiddleware);
+
+      // The dashboard route should have no route-level middleware (only controller-level)
+      const dashboardRoute = metadata!.routes.find((r) => r.path === '/dashboard');
+      expect(dashboardRoute?.middleware?.length ?? 0).toBe(0);
+    });
   });
 });
 
@@ -784,175 +924,599 @@ describe('Controllers API Documentation Examples', () => {
   });
 });
 
-describe('Services API Documentation Examples', () => {
-  describe('BaseService (docs/api/services.md)', () => {
-    it('should create basic service', () => {
-      // From docs: Basic Service example
-      @Service()
-      class CounterService extends BaseService {
-        private count = 0;
-
-        increment(): number {
-          this.count++;
-          this.logger.debug('Counter incremented', { count: this.count });
+describe('Middleware API Documentation Examples (docs/api/controllers.md)', () => {
+  describe('BaseMiddleware (docs/api/controllers.md#basemiddleware)', () => {
+    it('should define a middleware class extending BaseMiddleware', () => {
+      // From docs: BaseMiddleware example
+      class RequestLogMiddleware extends BaseMiddleware {
+        async use(req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+          this.logger.info(`${req.method} ${new URL(req.url).pathname}`);
+          const response = await next();
+          response.headers.set('X-Request-Duration', String(Date.now()));
 
-          return this.count;
+          return response;
         }
+      }
 
-        decrement(): number {
-          this.count--;
+      expect(RequestLogMiddleware.prototype).toBeInstanceOf(BaseMiddleware);
+      // eslint-disable-next-line jest/unbound-method
+      expect(RequestLogMiddleware.prototype.use).toBeInstanceOf(Function);
+    });
+  });
 
-          return this.count;
-        }
+  describe('Route-Level Middleware (docs/api/controllers.md#route-level-middleware)', () => {
+    it('should apply middleware to individual routes', () => {
+      // From docs: Route-Level Middleware example
+      class AuthMiddleware extends BaseMiddleware {
+        async use(req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+          const token = req.headers.get('Authorization');
+          if (!token) {
+            return new Response('Unauthorized', { status: 401 });
+          }
 
-        getValue(): number {
-          return this.count;
+          return await next();
         }
       }
 
-      expect(CounterService).toBeDefined();
-    });
-
-    it('should create service with dependencies', () => {
-      // From docs: Service with Dependencies example
-      @Service()
-      class UserRepository extends BaseService {}
+      @Controller('/api')
+      class ApiController extends BaseController {
+        @Get('/public')
+        publicEndpoint() {
+          return { message: 'Anyone can see this' };
+        }
 
-      @Service()
-      class UserService extends BaseService {
-        // Dependencies are auto-injected via constructor
-        // Logger and config are available immediately after super()
-        constructor(private repository: UserRepository) {
-          super();
+        @Post('/protected')
+        @UseMiddleware(AuthMiddleware)
+        protectedEndpoint() {
+          return { message: 'Auth required' };
         }
       }
 
-      expect(UserService).toBeDefined();
-    });
-  });
+      const metadata = getControllerMetadata(ApiController);
+      expect(metadata).toBeDefined();
 
-  describe('getServiceTag (docs/api/services.md)', () => {
-    /**
-     * @source docs/api/services.md#service-tags-advanced
-     */
-    it('should get service tag from class', () => {
-      @Service()
-      class MyService extends BaseService {}
+      const publicRoute = metadata!.routes.find((r) => r.path === '/public');
+      expect(publicRoute?.middleware?.length ?? 0).toBe(0);
 
-      const tag = getServiceTag(MyService);
-      expect(tag).toBeDefined();
+      const protectedRoute = metadata!.routes.find((r) => r.path === '/protected');
+      expect(protectedRoute?.middleware).toHaveLength(1);
+      expect(protectedRoute!.middleware![0]).toBe(AuthMiddleware);
     });
   });
 
-  describe('BaseService Methods (docs/api/services.md)', () => {
-    /**
-     * @source docs/api/services.md#class-definition
-     */
-    it('should have runEffect method', () => {
-      // From docs: BaseService has runEffect method for Effect.js integration
-      // Note: Cannot instantiate service without OneBunApplication context
-      // Check prototype instead
-      expect(typeof BaseService.prototype['runEffect']).toBe('function');
-    });
+  describe('Controller-Level Middleware (docs/api/controllers.md#controller-level-middleware)', () => {
+    it('should apply middleware to all routes via class decorator', () => {
+      // From docs: Controller-Level Middleware example
+      class AuthMiddleware extends BaseMiddleware {
+        async use(req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+          const token = req.headers.get('Authorization');
+          if (!token) {
+            return new Response('Unauthorized', { status: 401 });
+          }
 
-    /**
-     * @source docs/api/services.md#class-definition
-     */
-    it('should have formatError method', () => {
-      // From docs: BaseService has formatError method
-      // Note: Cannot instantiate service without OneBunApplication context
-      // Check prototype instead
-      expect(typeof BaseService.prototype['formatError']).toBe('function');
-    });
-  });
+          return await next();
+        }
+      }
 
-  describe('Service Logger (docs/api/services.md)', () => {
-    /**
-     * @source docs/api/services.md#log-levels
-     */
-    it('should support all log levels', () => {
-      @Service()
-      class EmailService extends BaseService {
-        async send() {
-          // From docs: Log Levels
-          this.logger.trace('Very detailed info');  // Level 0
-          this.logger.debug('Debug information');   // Level 1
-          this.logger.info('General information');  // Level 2
-          this.logger.warn('Warning message');      // Level 3
-          this.logger.error('Error occurred');      // Level 4
-          this.logger.fatal('Fatal error');         // Level 5
+      @Controller('/admin')
+      @UseMiddleware(AuthMiddleware)
+      class AdminController extends BaseController {
+        @Get('/dashboard')
+        getDashboard() {
+          return { stats: { users: 100 } };
+        }
+
+        @Put('/settings')
+        updateSettings() {
+          return { updated: true };
         }
       }
 
-      expect(EmailService).toBeDefined();
+      // Controller-level middleware is stored separately
+      const ctrlMiddleware = getControllerMiddleware(AdminController);
+      expect(ctrlMiddleware).toHaveLength(1);
+      expect(ctrlMiddleware[0]).toBe(AuthMiddleware);
     });
-  });
-});
-
-describe('Lifecycle Hooks API Documentation Examples (docs/api/services.md)', () => {
-  describe('OnModuleInit Interface', () => {
-    /**
-     * @source docs/api/services.md#lifecycle-hooks
-     */
-    it('should implement OnModuleInit interface', () => {
-      // From docs: OnModuleInit example
-      @Service()
-      class DatabaseService extends BaseService implements OnModuleInit {
-        private connection: unknown = null;
 
-        async onModuleInit(): Promise<void> {
-          // Called after service instantiation and DI
-          this.connection = { connected: true };
-          this.logger.info('Database connected');
+    it('should combine controller-level and route-level middleware', () => {
+      // From docs: Combined controller + route middleware example
+      class AuthMiddleware extends BaseMiddleware {
+        async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+          return await next();
         }
+      }
 
-        isConnected(): boolean {
-          return this.connection !== null;
+      class AuditLogMiddleware extends BaseMiddleware {
+        async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+          return await next();
         }
       }
 
-      expect(DatabaseService).toBeDefined();
-      // Verify method exists
-      const service = new DatabaseService();
-      expect(typeof service.onModuleInit).toBe('function');
-    });
-  });
+      @Controller('/admin')
+      @UseMiddleware(AuthMiddleware) // Runs first on all routes
+      class AdminController extends BaseController {
+        @Get('/dashboard')
+        getDashboard() {
+          return { stats: {} };
+        }
 
-  describe('OnApplicationInit Interface', () => {
-    /**
-     * @source docs/api/services.md#lifecycle-hooks
-     */
-    it('should implement OnApplicationInit interface', () => {
-      // From docs: OnApplicationInit example
-      @Service()
-      class CacheService extends BaseService implements OnApplicationInit {
-        async onApplicationInit(): Promise<void> {
-          // Called after all modules initialized, before HTTP server starts
-          this.logger.info('Warming up cache');
+        @Put('/settings')
+        @UseMiddleware(AuditLogMiddleware) // Runs second, only on this route
+        updateSettings() {
+          return { updated: true };
         }
       }
 
-      expect(CacheService).toBeDefined();
-      const service = new CacheService();
-      expect(typeof service.onApplicationInit).toBe('function');
+      // Controller-level middleware
+      const ctrlMiddleware = getControllerMiddleware(AdminController);
+      expect(ctrlMiddleware).toHaveLength(1);
+      expect(ctrlMiddleware[0]).toBe(AuthMiddleware);
+
+      // Route-level middleware only on /settings
+      const metadata = getControllerMetadata(AdminController);
+      const settingsRoute = metadata!.routes.find((r) => r.path === '/settings');
+      expect(settingsRoute?.middleware).toHaveLength(1);
+      expect(settingsRoute!.middleware![0]).toBe(AuditLogMiddleware);
+
+      const dashboardRoute = metadata!.routes.find((r) => r.path === '/dashboard');
+      expect(dashboardRoute?.middleware?.length ?? 0).toBe(0);
     });
   });
 
-  describe('OnModuleDestroy Interface', () => {
-    /**
-     * @source docs/api/services.md#lifecycle-hooks
-     */
-    it('should implement OnModuleDestroy interface', () => {
-      // From docs: OnModuleDestroy example
-      @Service()
-      class ConnectionService extends BaseService implements OnModuleDestroy {
-        async onModuleDestroy(): Promise<void> {
-          // Called during shutdown, after HTTP server stops
-          this.logger.info('Closing connections');
+  describe('Application-Wide Middleware (docs/api/controllers.md#application-wide-middleware)', () => {
+    it('should accept middleware classes in ApplicationOptions', () => {
+      // From docs: Application-Wide Middleware example
+      class RequestIdMiddleware extends BaseMiddleware {
+        async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+          const response = await next();
+          response.headers.set('X-Request-ID', crypto.randomUUID());
+
+          return response;
         }
       }
 
-      expect(ConnectionService).toBeDefined();
+      class CorsMiddleware extends BaseMiddleware {
+        async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+          const response = await next();
+          response.headers.set('Access-Control-Allow-Origin', '*');
+
+          return response;
+        }
+      }
+
+      // Verify that middleware option is accepted by OneBunApplication
+      // (We don't start the app, just verify the type/constructor accepts it)
+      @Module({
+        controllers: [],
+        providers: [],
+      })
+      class AppModule {}
+
+      const app = new OneBunApplication(AppModule, {
+        port: 0,
+        middleware: [RequestIdMiddleware, CorsMiddleware],
+      });
+
+      expect(app).toBeDefined();
+    });
+  });
+
+  describe('Middleware Execution Order (docs/api/controllers.md#middleware-execution-order)', () => {
+    it('should support all four middleware levels together', () => {
+      // From docs: Combining All Levels example
+      class RequestIdMiddleware extends BaseMiddleware {
+        async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+          return await next(); 
+        }
+      }
+
+      class TimingMiddleware extends BaseMiddleware {
+        async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+          return await next(); 
+        }
+      }
+
+      class JwtAuthMiddleware extends BaseMiddleware {
+        async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+          return await next(); 
+        }
+      }
+
+      class JsonOnlyMiddleware extends BaseMiddleware {
+        async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+          return await next(); 
+        }
+      }
+
+      @Controller('/admin')
+      @UseMiddleware(JwtAuthMiddleware)
+      class AdminController extends BaseController {
+        @Get('/stats')
+        getStats() {
+          return { stats: {} };
+        }
+
+        @Post('/users')
+        @UseMiddleware(JsonOnlyMiddleware)
+        createUser() {
+          return { created: true };
+        }
+      }
+
+      // Verify controller middleware
+      const ctrlMiddleware = getControllerMiddleware(AdminController);
+      expect(ctrlMiddleware).toHaveLength(1);
+      expect(ctrlMiddleware[0]).toBe(JwtAuthMiddleware);
+
+      // Verify route-level middleware on /users only
+      const metadata = getControllerMetadata(AdminController);
+      const statsRoute = metadata!.routes.find((r) => r.path === '/stats');
+      expect(statsRoute?.middleware?.length ?? 0).toBe(0);
+
+      const usersRoute = metadata!.routes.find((r) => r.path === '/users');
+      expect(usersRoute?.middleware).toHaveLength(1);
+      expect(usersRoute!.middleware![0]).toBe(JsonOnlyMiddleware);
+
+      // Global middleware would be set via ApplicationOptions.middleware
+      @Module({
+        controllers: [AdminController],
+        providers: [],
+      })
+      class AppModule {}
+
+      const app = new OneBunApplication(AppModule, {
+        port: 0,
+        middleware: [RequestIdMiddleware, TimingMiddleware],
+      });
+
+      expect(app).toBeDefined();
+    });
+  });
+
+  describe('Real-World Middleware Examples (docs/api/controllers.md#real-world-examples)', () => {
+    it('should define custom authentication middleware', () => {
+      // From docs: Custom Authentication Middleware example
+      class JwtAuthMiddleware extends BaseMiddleware {
+        async use(req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+          const authHeader = req.headers.get('Authorization');
+          if (!authHeader?.startsWith('Bearer ')) {
+            this.logger.warn('Missing or invalid Authorization header');
+
+            return new Response(JSON.stringify({
+              success: false,
+              code: 401,
+              message: 'Missing or invalid Authorization header',
+            }), {
+              status: 401,
+              // eslint-disable-next-line @typescript-eslint/naming-convention
+              headers: { 'Content-Type': 'application/json' },
+            });
+          }
+
+          // Validate the token (your logic here)
+          this.logger.debug(`Validating JWT token: ${authHeader.slice(7).substring(0, 8)}...`);
+
+          return await next();
+        }
+      }
+
+      expect(JwtAuthMiddleware.prototype).toBeInstanceOf(BaseMiddleware);
+    });
+
+    it('should define request validation middleware', () => {
+      // From docs: Request Validation Middleware example
+      class JsonOnlyMiddleware extends BaseMiddleware {
+        async use(req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+          if (req.method !== 'GET' && req.method !== 'DELETE') {
+            const contentType = req.headers.get('Content-Type');
+            if (!contentType?.includes('application/json')) {
+              this.logger.warn(`Invalid Content-Type: ${contentType}`);
+
+              return new Response(JSON.stringify({
+                success: false,
+                code: 415,
+                message: 'Content-Type must be application/json',
+              }), {
+                status: 415,
+                // eslint-disable-next-line @typescript-eslint/naming-convention
+                headers: { 'Content-Type': 'application/json' },
+              });
+            }
+          }
+
+          return await next();
+        }
+      }
+
+      expect(JsonOnlyMiddleware.prototype).toBeInstanceOf(BaseMiddleware);
+    });
+
+    it('should define timing/logging middleware', () => {
+      // From docs: Timing / Logging Middleware example
+      class TimingMiddleware extends BaseMiddleware {
+        async use(req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+          const start = performance.now();
+          const response = await next();
+          const duration = (performance.now() - start).toFixed(2);
+          response.headers.set('X-Response-Time', `${duration}ms`);
+          this.logger.info(`${req.method} ${new URL(req.url).pathname} — ${duration}ms`);
+
+          return response;
+        }
+      }
+
+      expect(TimingMiddleware.prototype).toBeInstanceOf(BaseMiddleware);
+    });
+  });
+
+  describe('Module-Level Middleware (docs/api/controllers.md#module-level-middleware)', () => {
+    it('should define module-level middleware via OnModuleConfigure interface', () => {
+      // From docs: Module-Level Middleware example
+      class TenantMiddleware extends BaseMiddleware {
+        async use(req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+          const tenantId = req.headers.get('X-Tenant-ID');
+          if (!tenantId) {
+            return new Response('Missing X-Tenant-ID', { status: 400 });
+          }
+
+          return await next();
+        }
+      }
+
+      @Controller('/users')
+      class UserController extends BaseController {
+        @Get('/')
+        getUsers() {
+          return [];
+        }
+      }
+
+      @Module({
+        controllers: [UserController],
+      })
+      class UserModule implements OnModuleConfigure {
+        configureMiddleware(): MiddlewareClass[] {
+          return [TenantMiddleware];
+        }
+      }
+
+      // Verify the module class has configureMiddleware
+      const instance = new UserModule();
+      const middleware = instance.configureMiddleware();
+      expect(middleware).toHaveLength(1);
+      expect(middleware[0]).toBe(TenantMiddleware);
+    });
+
+    it('should inherit module middleware in child modules', () => {
+      // From docs: Module middleware inheritance example
+      class RequestIdMiddleware extends BaseMiddleware {
+        async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+          return await next();
+        }
+      }
+
+      class TenantMiddleware extends BaseMiddleware {
+        async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+          return await next();
+        }
+      }
+
+      @Controller('/users')
+      class UserController extends BaseController {
+        @Get('/')
+        getUsers() {
+          return [];
+        }
+      }
+
+      @Module({
+        controllers: [UserController],
+      })
+      class UserModule implements OnModuleConfigure {
+        configureMiddleware(): MiddlewareClass[] {
+          return [TenantMiddleware];
+        }
+      }
+
+      @Controller('/health')
+      class HealthController extends BaseController {
+        @Get('/')
+        health() {
+          return { ok: true };
+        }
+      }
+
+      @Module({
+        imports: [UserModule],
+        controllers: [HealthController],
+      })
+      class AppModule implements OnModuleConfigure {
+        configureMiddleware(): MiddlewareClass[] {
+          return [RequestIdMiddleware];
+        }
+      }
+
+      // Verify both modules have configureMiddleware
+      const appInstance = new AppModule();
+      expect(appInstance.configureMiddleware()).toHaveLength(1);
+      expect(appInstance.configureMiddleware()[0]).toBe(RequestIdMiddleware);
+
+      const userInstance = new UserModule();
+      expect(userInstance.configureMiddleware()).toHaveLength(1);
+      expect(userInstance.configureMiddleware()[0]).toBe(TenantMiddleware);
+    });
+  });
+});
+
+describe('Services API Documentation Examples', () => {
+  describe('BaseService (docs/api/services.md)', () => {
+    it('should create basic service', () => {
+      // From docs: Basic Service example
+      @Service()
+      class CounterService extends BaseService {
+        private count = 0;
+
+        increment(): number {
+          this.count++;
+          this.logger.debug('Counter incremented', { count: this.count });
+
+          return this.count;
+        }
+
+        decrement(): number {
+          this.count--;
+
+          return this.count;
+        }
+
+        getValue(): number {
+          return this.count;
+        }
+      }
+
+      expect(CounterService).toBeDefined();
+    });
+
+    it('should create service with dependencies', () => {
+      // From docs: Service with Dependencies example
+      @Service()
+      class UserRepository extends BaseService {}
+
+      @Service()
+      class UserService extends BaseService {
+        // Dependencies are auto-injected via constructor
+        // Logger and config are available immediately after super()
+        constructor(private repository: UserRepository) {
+          super();
+        }
+      }
+
+      expect(UserService).toBeDefined();
+    });
+  });
+
+  describe('getServiceTag (docs/api/services.md)', () => {
+    /**
+     * @source docs/api/services.md#service-tags-advanced
+     */
+    it('should get service tag from class', () => {
+      @Service()
+      class MyService extends BaseService {}
+
+      const tag = getServiceTag(MyService);
+      expect(tag).toBeDefined();
+    });
+  });
+
+  describe('BaseService Methods (docs/api/services.md)', () => {
+    /**
+     * @source docs/api/services.md#class-definition
+     */
+    it('should have runEffect method', () => {
+      // From docs: BaseService has runEffect method for Effect.js integration
+      // Note: Cannot instantiate service without OneBunApplication context
+      // Check prototype instead
+      expect(typeof BaseService.prototype['runEffect']).toBe('function');
+    });
+
+    /**
+     * @source docs/api/services.md#class-definition
+     */
+    it('should have formatError method', () => {
+      // From docs: BaseService has formatError method
+      // Note: Cannot instantiate service without OneBunApplication context
+      // Check prototype instead
+      expect(typeof BaseService.prototype['formatError']).toBe('function');
+    });
+  });
+
+  describe('Service Logger (docs/api/services.md)', () => {
+    /**
+     * @source docs/api/services.md#log-levels
+     */
+    it('should support all log levels', () => {
+      @Service()
+      class EmailService extends BaseService {
+        async send() {
+          // From docs: Log Levels
+          this.logger.trace('Very detailed info');  // Level 0
+          this.logger.debug('Debug information');   // Level 1
+          this.logger.info('General information');  // Level 2
+          this.logger.warn('Warning message');      // Level 3
+          this.logger.error('Error occurred');      // Level 4
+          this.logger.fatal('Fatal error');         // Level 5
+        }
+      }
+
+      expect(EmailService).toBeDefined();
+    });
+  });
+});
+
+describe('Lifecycle Hooks API Documentation Examples (docs/api/services.md)', () => {
+  describe('OnModuleInit Interface', () => {
+    /**
+     * @source docs/api/services.md#lifecycle-hooks
+     */
+    it('should implement OnModuleInit interface', () => {
+      // From docs: OnModuleInit example
+      @Service()
+      class DatabaseService extends BaseService implements OnModuleInit {
+        private connection: unknown = null;
+
+        async onModuleInit(): Promise<void> {
+          // Called after service instantiation and DI
+          this.connection = { connected: true };
+          this.logger.info('Database connected');
+        }
+
+        isConnected(): boolean {
+          return this.connection !== null;
+        }
+      }
+
+      expect(DatabaseService).toBeDefined();
+      // Verify method exists
+      const service = new DatabaseService();
+      expect(typeof service.onModuleInit).toBe('function');
+    });
+  });
+
+  describe('OnApplicationInit Interface', () => {
+    /**
+     * @source docs/api/services.md#lifecycle-hooks
+     */
+    it('should implement OnApplicationInit interface', () => {
+      // From docs: OnApplicationInit example
+      @Service()
+      class CacheService extends BaseService implements OnApplicationInit {
+        async onApplicationInit(): Promise<void> {
+          // Called after all modules initialized, before HTTP server starts
+          this.logger.info('Warming up cache');
+        }
+      }
+
+      expect(CacheService).toBeDefined();
+      const service = new CacheService();
+      expect(typeof service.onApplicationInit).toBe('function');
+    });
+  });
+
+  describe('OnModuleDestroy Interface', () => {
+    /**
+     * @source docs/api/services.md#lifecycle-hooks
+     */
+    it('should implement OnModuleDestroy interface', () => {
+      // From docs: OnModuleDestroy example
+      @Service()
+      class ConnectionService extends BaseService implements OnModuleDestroy {
+        async onModuleDestroy(): Promise<void> {
+          // Called during shutdown, after HTTP server stops
+          this.logger.info('Closing connections');
+        }
+      }
+
+      expect(ConnectionService).toBeDefined();
       const service = new ConnectionService();
       expect(typeof service.onModuleDestroy).toBe('function');
     });
@@ -3376,123 +3940,50 @@ describe('WebSocket Chat Example (docs/examples/websocket-chat.md)', () => {
       @WebSocketGateway({ path: '/chat' })
       class ChatGateway extends BaseWebSocketGateway {
         constructor(private chatService: ChatService) {
-          super();
-        }
-
-        @OnMessage('chat:message')
-        handleMessage(@MessageData() data: { text: string }) {
-          return { event: 'received', data };
-        }
-      }
-
-      @Module({
-        controllers: [ChatGateway],
-        providers: [ChatService],
-      })
-      class ChatModule {}
-
-      // From docs: Typed Client (native) example
-      const definition = createWsServiceDefinition(ChatModule);
-      const client = createWsClient(definition, {
-        url: 'ws://localhost:3000/chat',
-        protocol: 'native',
-        auth: {
-          token: 'user-jwt-token',
-        },
-        reconnect: true,
-        reconnectInterval: 2000,
-        maxReconnectAttempts: 5,
-      });
-
-      // Lifecycle events
-      expect(typeof client.on).toBe('function');
-
-      // Connect/disconnect
-      expect(typeof client.connect).toBe('function');
-      expect(typeof client.disconnect).toBe('function');
-
-      // Gateway access
-      expect(client.ChatGateway).toBeDefined();
-    });
-  });
-});
-
-// ============================================================================
-// SSE (Server-Sent Events) Documentation Tests
-// ============================================================================
-
-import { Sse, getSseMetadata } from './decorators/decorators';
-import { formatSseEvent, createSseStream } from './module/controller';
-
-import {
-  Controller,
-  Get,
-  Post,
-  Put,
-  Delete,
-  Patch,
-  Param,
-  Query,
-  Body,
-  Header,
-  Req,
-  Cookie,
-  Module,
-  Service,
-  BaseService,
-  BaseController,
-  UseMiddleware,
-  getServiceTag,
-  getControllerMetadata,
-  HttpStatusCode,
-  ParamType,
-  NotFoundError,
-  InternalServerError,
-  OneBunBaseError,
-  Env,
-  validate,
-  validateOrThrow,
-  MultiServiceApplication,
-  OneBunApplication,
-  createServiceDefinition,
-  createServiceClient,
-  WebSocketGateway,
-  BaseWebSocketGateway,
-  OnConnect,
-  OnDisconnect,
-  OnJoinRoom,
-  OnLeaveRoom,
-  OnMessage,
-  Client,
-  Socket,
-  MessageData,
-  RoomName,
-  PatternParams,
-  WsServer,
-  UseWsGuards,
-  WsAuthGuard,
-  WsPermissionGuard,
-  WsAnyPermissionGuard,
-  createGuard,
-  createInMemoryWsStorage,
-  SharedRedisProvider,
-  createWsServiceDefinition,
-  createWsClient,
-  createNativeWsClient,
-  matchPattern,
-  makeMockLoggerLayer,
-  hasOnModuleInit,
-  hasOnApplicationInit,
-  hasOnModuleDestroy,
-  hasBeforeApplicationDestroy,
-  hasOnApplicationDestroy,
-  callOnModuleInit,
-  callOnApplicationInit,
-  callOnModuleDestroy,
-  callBeforeApplicationDestroy,
-  callOnApplicationDestroy,
-} from './';
+          super();
+        }
+
+        @OnMessage('chat:message')
+        handleMessage(@MessageData() data: { text: string }) {
+          return { event: 'received', data };
+        }
+      }
+
+      @Module({
+        controllers: [ChatGateway],
+        providers: [ChatService],
+      })
+      class ChatModule {}
+
+      // From docs: Typed Client (native) example
+      const definition = createWsServiceDefinition(ChatModule);
+      const client = createWsClient(definition, {
+        url: 'ws://localhost:3000/chat',
+        protocol: 'native',
+        auth: {
+          token: 'user-jwt-token',
+        },
+        reconnect: true,
+        reconnectInterval: 2000,
+        maxReconnectAttempts: 5,
+      });
+
+      // Lifecycle events
+      expect(typeof client.on).toBe('function');
+
+      // Connect/disconnect
+      expect(typeof client.connect).toBe('function');
+      expect(typeof client.disconnect).toBe('function');
+
+      // Gateway access
+      expect(client.ChatGateway).toBeDefined();
+    });
+  });
+});
 
+// ============================================================================
+// SSE (Server-Sent Events) Documentation Tests
+// ============================================================================
 
 describe('SSE (Server-Sent Events) API Documentation (docs/api/controllers.md)', () => {
   describe('SseEvent Type (docs/api/controllers.md)', () => {
@@ -3728,6 +4219,91 @@ describe('SSE (Server-Sent Events) API Documentation (docs/api/controllers.md)',
       // Should have the actual event (string data is not wrapped in extra quotes)
       expect(output).toContain('data: done');
     });
+
+    it('should call iterator.return() on cancel, triggering generator finally block', async () => {
+      let finallyCalled = false;
+
+      async function* testGenerator(): SseGenerator {
+        try {
+          yield { event: 'start', data: { count: 0 } };
+          // Simulate a long-running generator
+          yield { event: 'tick', data: { count: 1 } };
+          yield { event: 'tick', data: { count: 2 } };
+        } finally {
+          finallyCalled = true;
+        }
+      }
+
+      const stream = createSseStream(testGenerator());
+      const reader = stream.getReader();
+
+      // Read first chunk
+      const first = await reader.read();
+      expect(first.done).toBe(false);
+
+      // Cancel the stream (simulates client disconnect)
+      await reader.cancel();
+
+      // The generator's finally block should have been triggered
+      // Give a tick for the async return to settle
+      await Bun.sleep(10);
+      expect(finallyCalled).toBe(true);
+    });
+
+    it('should fire onAbort callback on cancel', async () => {
+      let abortCalled = false;
+
+      async function* testGenerator(): SseGenerator {
+        yield { event: 'start', data: { count: 0 } };
+        yield { event: 'tick', data: { count: 1 } };
+      }
+
+      const stream = createSseStream(testGenerator(), {
+        onAbort() {
+          abortCalled = true; 
+        },
+      });
+      const reader = stream.getReader();
+
+      // Read first chunk
+      await reader.read();
+
+      // Cancel the stream
+      await reader.cancel();
+
+      expect(abortCalled).toBe(true);
+    });
+
+    it('should abort upstream fetch via try/finally when client disconnects (SSE proxy pattern)', async () => {
+      let upstreamAborted = false;
+      const ac = new AbortController();
+
+      async function* proxyGenerator(): SseGenerator {
+        try {
+          ac.signal.addEventListener('abort', () => {
+            upstreamAborted = true;
+          });
+          yield { event: 'proxied', data: { from: 'upstream' } };
+          // Simulate waiting for more upstream data
+          yield { event: 'proxied', data: { from: 'upstream-2' } };
+        } finally {
+          // This is the idiomatic pattern: abort the upstream connection in finally
+          ac.abort();
+        }
+      }
+
+      const stream = createSseStream(proxyGenerator());
+      const reader = stream.getReader();
+
+      // Read first event
+      await reader.read();
+
+      // Client disconnects
+      await reader.cancel();
+
+      await Bun.sleep(10);
+      expect(upstreamAborted).toBe(true);
+    });
   });
 
   describe('Controller.sse() Method', () => {
@@ -3759,6 +4335,79 @@ describe('SSE (Server-Sent Events) API Documentation (docs/api/controllers.md)',
 
       expect(EventsController).toBeDefined();
     });
+
+    it('should accept factory function with AbortSignal for SSE proxy pattern', async () => {
+      let signalAborted = false;
+
+      @Controller('/events')
+      class ProxyController extends BaseController {
+        @Get('/proxy')
+        proxy(): Response {
+          return this.sse((signal) => this.proxyUpstream(signal));
+        }
+
+        private async *proxyUpstream(signal: AbortSignal): SseGenerator {
+          signal.addEventListener('abort', () => {
+            signalAborted = true; 
+          });
+          yield { event: 'proxied', data: { from: 'upstream' } };
+          yield { event: 'proxied', data: { from: 'upstream-2' } };
+        }
+      }
+
+      const controller = new ProxyController();
+      // Access protected method via type assertion
+      const sseMethod = (controller as unknown as {
+        sse: (source: (signal: AbortSignal) => AsyncIterable<unknown>, options?: unknown) => Response;
+      }).sse.bind(controller);
+
+      const response = sseMethod((signal) => (async function* () {
+        signal.addEventListener('abort', () => {
+          signalAborted = true; 
+        });
+        yield { event: 'proxied', data: { from: 'upstream' } };
+      })());
+
+      expect(response).toBeInstanceOf(Response);
+      expect(response.headers.get('Content-Type')).toBe('text/event-stream');
+
+      const reader = response.body!.getReader();
+
+      // Read first event
+      await reader.read();
+
+      // Client disconnects
+      await reader.cancel();
+
+      await Bun.sleep(10);
+      expect(signalAborted).toBe(true);
+    });
+
+    it('should support onAbort callback with sse() helper', async () => {
+      let abortCalled = false;
+
+      const controller = new BaseController();
+      const sseMethod = (controller as unknown as {
+        sse: (source: AsyncIterable<unknown>, options?: { onAbort?: () => void }) => Response;
+      }).sse.bind(controller);
+
+      const response = sseMethod(
+        (async function* () {
+          yield { event: 'tick', data: { count: 0 } };
+        })(),
+        {
+          onAbort() {
+            abortCalled = true; 
+          }, 
+        },
+      );
+
+      const reader = response.body!.getReader();
+      await reader.read();
+      await reader.cancel();
+
+      expect(abortCalled).toBe(true);
+    });
   });
 
   describe('Complete SSE Controller Example (docs/api/controllers.md)', () => {
@@ -3838,6 +4487,148 @@ describe('SSE (Server-Sent Events) API Documentation (docs/api/controllers.md)',
   });
 });
 
+// ============================================================================
+// Server & SSE Default Constants
+// ============================================================================
+
+describe('Server & SSE Default Constants (docs/api/core.md, docs/api/controllers.md)', () => {
+  it('should export DEFAULT_IDLE_TIMEOUT as 120 seconds', () => {
+    expect(DEFAULT_IDLE_TIMEOUT).toBe(120);
+  });
+
+  it('should export DEFAULT_SSE_HEARTBEAT_MS as 30000 milliseconds', () => {
+    expect(DEFAULT_SSE_HEARTBEAT_MS).toBe(30_000);
+  });
+
+  it('should export DEFAULT_SSE_TIMEOUT as 600 seconds (10 minutes)', () => {
+    expect(DEFAULT_SSE_TIMEOUT).toBe(600);
+  });
+});
+
+// ============================================================================
+// Per-request timeout via route decorators (docs/api/decorators.md)
+// ============================================================================
+
+describe('Per-request timeout via route decorators (docs/api/decorators.md)', () => {
+  it('should store timeout in route metadata when specified via @Get options', () => {
+    @Controller('/tasks')
+    class TaskController extends BaseController {
+      @Get('/process', { timeout: 300 })
+      async process() {
+        return new Response('OK');
+      }
+    }
+
+    const metadata = getControllerMetadata(TaskController);
+    expect(metadata).toBeDefined();
+    const route = metadata!.routes.find((r) => r.handler === 'process');
+    expect(route).toBeDefined();
+    expect(route!.timeout).toBe(300);
+  });
+
+  it('should store timeout: 0 (disable) in route metadata', () => {
+    @Controller('/export')
+    class ExportController extends BaseController {
+      @Get('/all', { timeout: 0 })
+      async exportAll() {
+        return new Response('OK');
+      }
+    }
+
+    const metadata = getControllerMetadata(ExportController);
+    expect(metadata).toBeDefined();
+    const route = metadata!.routes.find((r) => r.handler === 'exportAll');
+    expect(route).toBeDefined();
+    expect(route!.timeout).toBe(0);
+  });
+
+  it('should not include timeout in metadata when not specified', () => {
+    @Controller('/simple')
+    class SimpleController extends BaseController {
+      @Get('/hello')
+      async hello() {
+        return new Response('OK');
+      }
+    }
+
+    const metadata = getControllerMetadata(SimpleController);
+    expect(metadata).toBeDefined();
+    const route = metadata!.routes.find((r) => r.handler === 'hello');
+    expect(route).toBeDefined();
+    expect(route!.timeout).toBeUndefined();
+  });
+
+  it('should support timeout on @Post, @Put, @Delete, @Patch', () => {
+    @Controller('/api')
+    class CrudController extends BaseController {
+      @Post('/create', { timeout: 60 })
+      async create() {
+        return new Response('OK'); 
+      }
+
+      @Put('/update', { timeout: 120 })
+      async update() {
+        return new Response('OK'); 
+      }
+
+      @Delete('/remove', { timeout: 30 })
+      async remove() {
+        return new Response('OK'); 
+      }
+
+      @Patch('/patch', { timeout: 45 })
+      async patch() {
+        return new Response('OK'); 
+      }
+    }
+
+    const metadata = getControllerMetadata(CrudController);
+    expect(metadata).toBeDefined();
+
+    expect(metadata!.routes.find((r) => r.handler === 'create')!.timeout).toBe(60);
+    expect(metadata!.routes.find((r) => r.handler === 'update')!.timeout).toBe(120);
+    expect(metadata!.routes.find((r) => r.handler === 'remove')!.timeout).toBe(30);
+    expect(metadata!.routes.find((r) => r.handler === 'patch')!.timeout).toBe(45);
+  });
+
+  it('should store timeout in SSE decorator options', () => {
+    @Controller('/events')
+    class SseTimeoutController extends BaseController {
+      @Get('/stream')
+      @Sse({ timeout: 3600, heartbeat: 10000 })
+      async *stream(): SseGenerator {
+        yield { event: 'tick', data: { count: 0 } };
+      }
+    }
+
+    const sseOptions = getSseMetadata(
+      SseTimeoutController.prototype,
+      'stream',
+    );
+    expect(sseOptions).toBeDefined();
+    expect(sseOptions!.timeout).toBe(3600);
+    expect(sseOptions!.heartbeat).toBe(10000);
+  });
+
+  it('should support timeout: 0 in @Sse to disable timeout', () => {
+    @Controller('/events')
+    class InfiniteSseController extends BaseController {
+      @Get('/infinite')
+      @Sse({ timeout: 0 })
+      async *infinite(): SseGenerator {
+        yield { event: 'start', data: {} };
+      }
+    }
+
+    const sseOptions = getSseMetadata(
+      InfiniteSseController.prototype,
+      'infinite',
+    );
+    expect(sseOptions).toBeDefined();
+    expect(sseOptions!.timeout).toBe(0);
+  });
+});
+
 // ============================================================================
 // Cookie, Headers, @Req with OneBunRequest
 // ============================================================================
@@ -4128,3 +4919,297 @@ describe('Working with Cookies (docs/api/controllers.md)', () => {
     expect(AuthController).toBeDefined();
   });
 });
+
+// ============================================================================
+// File Upload Documentation Tests
+// ============================================================================
+
+describe('File Upload API Documentation (docs/api/decorators.md)', () => {
+  /**
+   * @source docs/api/decorators.md#uploadedfile
+   */
+  describe('Single File Upload (docs/api/decorators.md#uploadedfile)', () => {
+    it('should define controller with @UploadedFile decorator', () => {
+      @Controller('/api/files')
+      class FileController extends BaseController {
+        @Post('/avatar')
+        async uploadAvatar(
+          @UploadedFile('avatar', {
+            maxSize: 5 * 1024 * 1024,
+            mimeTypes: [MimeType.ANY_IMAGE],
+          }) file: OneBunFile,
+        ): Promise<Response> {
+          await file.writeTo(`./uploads/${file.name}`);
+
+          return this.success({ filename: file.name, size: file.size });
+        }
+      }
+
+      expect(FileController).toBeDefined();
+      const metadata = getControllerMetadata(FileController);
+      expect(metadata).toBeDefined();
+      expect(metadata!.routes).toHaveLength(1);
+
+      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].isRequired).toBe(true);
+      expect(route.params![0].fileOptions).toBeDefined();
+      expect(route.params![0].fileOptions!.maxSize).toBe(5 * 1024 * 1024);
+      expect(route.params![0].fileOptions!.mimeTypes).toEqual([MimeType.ANY_IMAGE]);
+    });
+  });
+
+  /**
+   * @source docs/api/decorators.md#uploadedfiles
+   */
+  describe('Multiple File Upload (docs/api/decorators.md#uploadedfiles)', () => {
+    it('should define controller with @UploadedFiles decorator', () => {
+      @Controller('/api/files')
+      class FileController extends BaseController {
+        @Post('/documents')
+        async uploadDocs(
+          @UploadedFiles('docs', { maxCount: 10 }) files: OneBunFile[],
+        ): Promise<Response> {
+          for (const file of files) {
+            await file.writeTo(`./uploads/${file.name}`);
+          }
+
+          return this.success({ count: files.length });
+        }
+      }
+
+      expect(FileController).toBeDefined();
+      const metadata = getControllerMetadata(FileController);
+      expect(metadata).toBeDefined();
+
+      const route = metadata!.routes[0];
+      expect(route.params).toBeDefined();
+      expect(route.params![0].type).toBe(ParamType.FILES);
+      expect(route.params![0].name).toBe('docs');
+      expect(route.params![0].fileOptions!.maxCount).toBe(10);
+    });
+
+    it('should support @UploadedFiles without field name (all files)', () => {
+      @Controller('/api/files')
+      class FileController extends BaseController {
+        @Post('/batch')
+        async uploadBatch(
+          @UploadedFiles(undefined, { maxCount: 20 }) files: OneBunFile[],
+        ): Promise<Response> {
+          return this.success({ count: files.length });
+        }
+      }
+
+      expect(FileController).toBeDefined();
+      const metadata = getControllerMetadata(FileController);
+      const route = metadata!.routes[0];
+      expect(route.params![0].type).toBe(ParamType.FILES);
+      expect(route.params![0].name).toBe('');
+    });
+  });
+
+  /**
+   * @source docs/api/decorators.md#formfield
+   */
+  describe('Form Field (docs/api/decorators.md#formfield)', () => {
+    it('should define controller with @FormField decorator', () => {
+      @Controller('/api/files')
+      class FileController extends BaseController {
+        @Post('/profile')
+        async createProfile(
+          @UploadedFile('avatar', { mimeTypes: [MimeType.ANY_IMAGE] }) avatar: OneBunFile,
+          @FormField('name', { required: true }) name: string,
+          @FormField('email') email: string,
+        ): Promise<Response> {
+          await avatar.writeTo(`./uploads/${avatar.name}`);
+
+          return this.success({ name, email, avatar: avatar.name });
+        }
+      }
+
+      expect(FileController).toBeDefined();
+      const metadata = getControllerMetadata(FileController);
+      const route = metadata!.routes[0];
+      expect(route.params).toBeDefined();
+      expect(route.params!.length).toBe(3);
+
+      // @UploadedFile
+      const fileParam = route.params!.find((p) => p.type === ParamType.FILE);
+      expect(fileParam).toBeDefined();
+      expect(fileParam!.name).toBe('avatar');
+
+      // @FormField (required)
+      const nameParam = route.params!.find((p) => p.name === 'name');
+      expect(nameParam).toBeDefined();
+      expect(nameParam!.type).toBe(ParamType.FORM_FIELD);
+      expect(nameParam!.isRequired).toBe(true);
+
+      // @FormField (optional)
+      const emailParam = route.params!.find((p) => p.name === 'email');
+      expect(emailParam).toBeDefined();
+      expect(emailParam!.type).toBe(ParamType.FORM_FIELD);
+      expect(emailParam!.isRequired).toBe(false);
+    });
+  });
+
+  /**
+   * @source docs/api/decorators.md#onebunfile
+   */
+  describe('OneBunFile Class (docs/api/decorators.md#onebunfile)', () => {
+    it('should create OneBunFile from File and support all methods', async () => {
+      const content = 'test file content';
+      const file = new File([content], 'test.txt', { type: 'text/plain' });
+      const oneBunFile = new OneBunFile(file);
+
+      expect(oneBunFile.name).toBe('test.txt');
+      expect(oneBunFile.size).toBe(content.length);
+      expect(oneBunFile.type).toStartWith('text/plain');
+
+      const base64 = await oneBunFile.toBase64();
+      expect(base64).toBe(btoa(content));
+
+      const buffer = await oneBunFile.toBuffer();
+      expect(buffer.toString()).toBe(content);
+
+      const blob = oneBunFile.toBlob();
+      expect(blob.size).toBe(content.length);
+    });
+
+    it('should create OneBunFile from base64', async () => {
+      const content = 'base64 content';
+      const base64 = btoa(content);
+      const file = OneBunFile.fromBase64(base64, 'decoded.txt', 'text/plain');
+
+      expect(file.name).toBe('decoded.txt');
+      expect(file.type).toStartWith('text/plain');
+
+      const roundTripped = await file.toBase64();
+      expect(roundTripped).toBe(base64);
+    });
+  });
+
+  /**
+   * @source docs/api/decorators.md#mimetype-enum
+   */
+  describe('MimeType Enum (docs/api/decorators.md#mimetype-enum)', () => {
+    it('should provide common MIME type constants', () => {
+      // Wildcards
+      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/*');
+
+      // Specific types
+      expect(String(MimeType.PNG)).toBe('image/png');
+      expect(String(MimeType.PDF)).toBe('application/pdf');
+      expect(String(MimeType.MP4)).toBe('video/mp4');
+
+      // Wildcard matching
+      expect(matchMimeType('image/png', MimeType.ANY_IMAGE)).toBe(true);
+      expect(matchMimeType('video/mp4', MimeType.ANY_IMAGE)).toBe(false);
+    });
+  });
+
+  /**
+   * @source docs/api/decorators.md#json-base64-upload-format
+   */
+  describe('JSON Base64 Upload (docs/api/decorators.md#json-base64-upload-format)', () => {
+    it('should parse full JSON base64 format', () => {
+      const base64 = btoa('png image data');
+      const file = OneBunFile.fromBase64(base64, 'photo.png', 'image/png');
+
+      expect(file.name).toBe('photo.png');
+      expect(file.type).toBe('image/png');
+    });
+
+    it('should parse data URI format', () => {
+      const base64 = btoa('svg data');
+      const dataUri = `data:image/svg+xml;base64,${base64}`;
+      const file = OneBunFile.fromBase64(dataUri, 'icon.svg');
+
+      expect(file.type).toBe('image/svg+xml');
+      expect(file.name).toBe('icon.svg');
+    });
+  });
+});
+
+describe('File Upload API Documentation (docs/api/controllers.md)', () => {
+  /**
+   * @source docs/api/controllers.md#single-file-upload
+   */
+  it('should define single file upload controller', () => {
+    @Controller('/api/files')
+    class FileController extends BaseController {
+      @Post('/avatar')
+      async uploadAvatar(
+        @UploadedFile('avatar', {
+          maxSize: 5 * 1024 * 1024,
+          mimeTypes: [MimeType.ANY_IMAGE],
+        }) file: OneBunFile,
+      ): Promise<Response> {
+        await file.writeTo(`./uploads/${file.name}`);
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const _base64 = await file.toBase64();
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const _buffer = await file.toBuffer();
+
+        return this.success({
+          filename: file.name,
+          size: file.size,
+          type: file.type,
+        });
+      }
+    }
+
+    expect(FileController).toBeDefined();
+  });
+
+  /**
+   * @source docs/api/controllers.md#multiple-file-upload
+   */
+  it('should define multiple file upload controller', () => {
+    @Controller('/api/files')
+    class FileController extends BaseController {
+      @Post('/documents')
+      async uploadDocuments(
+        @UploadedFiles('docs', {
+          maxCount: 10,
+          maxSize: 10 * 1024 * 1024,
+          mimeTypes: [MimeType.PDF, MimeType.DOCX],
+        }) files: OneBunFile[],
+      ): Promise<Response> {
+        for (const file of files) {
+          await file.writeTo(`./uploads/${file.name}`);
+        }
+
+        return this.success({ uploaded: files.length });
+      }
+    }
+
+    expect(FileController).toBeDefined();
+  });
+
+  /**
+   * @source docs/api/controllers.md#file-with-form-fields
+   */
+  it('should define file with form fields controller', () => {
+    @Controller('/api/files')
+    class FileController extends BaseController {
+      @Post('/profile')
+      async createProfile(
+        @UploadedFile('avatar', { mimeTypes: [MimeType.ANY_IMAGE] }) avatar: OneBunFile,
+        @FormField('name', { required: true }) name: string,
+        @FormField('email') email: string,
+      ): Promise<Response> {
+        await avatar.writeTo(`./uploads/${avatar.name}`);
+
+        return this.success({ name, email, avatar: avatar.name });
+      }
+    }
+
+    expect(FileController).toBeDefined();
+  });
+});