@onebun/core 0.1.14 → 0.1.16

package/package.json

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

package/src/application/application.ts

@@ -24,13 +24,18 @@ import {
 } from '@onebun/requests';
 import { makeTraceService, TraceService } from '@onebun/trace';
 
-import { getControllerMetadata } from '../decorators/decorators';
+import {
+  getControllerMetadata,
+  getSseMetadata,
+  type SseDecoratorOptions,
+} from '../decorators/decorators';
 import {
   NotInitializedConfig,
   type IConfig,
   type OneBunAppConfig,
 } from '../module/config.interface';
 import { ConfigServiceImpl } from '../module/config.service';
+import { createSseStream } from '../module/controller';
 import { OneBunModule } from '../module/module';
 import { QueueService, type QueueAdapter } from '../queue';
 import { InMemoryQueueAdapter } from '../queue/adapters/memory.adapter';
@@ -371,6 +376,7 @@ export class OneBunApplication {
         {
           method: string;
           handler: Function;
+          handlerName: string;
           controller: Controller;
           params?: ParamMetadata[];
           middleware?: Function[];
@@ -436,6 +442,7 @@ export class OneBunApplication {
           routes.set(_routeKey, {
             method,
             handler,
+            handlerName: route.handler,
             controller,
             params: route.params,
             middleware: route.middleware,
@@ -899,6 +906,7 @@ export class OneBunApplication {
     async function executeHandler(
       route: {
         handler: Function;
+        handlerName?: string;
         controller: Controller;
         params?: ParamMetadata[];
         responseSchemas?: RouteMetadata['responseSchemas'];
@@ -906,9 +914,22 @@ export class OneBunApplication {
       req: Request,
       paramValues: Record<string, string | string[]>,
     ): Promise<Response> {
+      // Check if this is an SSE endpoint
+      let sseOptions: SseDecoratorOptions | undefined;
+      if (route.handlerName) {
+        sseOptions = getSseMetadata(Object.getPrototypeOf(route.controller), route.handlerName);
+      }
+
       // If no parameter metadata, just call the handler with the request
       if (!route.params || route.params.length === 0) {
-        return await route.handler(req);
+        const result = await route.handler(req);
+
+        // Handle SSE response
+        if (sseOptions !== undefined) {
+          return createSseResponseFromResult(result, sseOptions);
+        }
+
+        return result;
       }
 
       // Prepare arguments array based on parameter metadata
@@ -975,6 +996,11 @@ export class OneBunApplication {
         // Call handler with injected parameters
         const result = await route.handler(...args);
 
+        // Handle SSE response - wrap async generator in SSE Response
+        if (sseOptions !== undefined) {
+          return createSseResponseFromResult(result, sseOptions);
+        }
+
         // Initialize variables for response validation
         let validatedResult = result;
         let responseStatusCode = HttpStatusCode.OK;
@@ -1107,6 +1133,46 @@ export class OneBunApplication {
         });
       }
     }
+
+    /**
+     * Create SSE Response from handler result
+     * Handles both async generators and already-created Responses
+     */
+    function createSseResponseFromResult(
+      result: unknown,
+      options: SseDecoratorOptions,
+    ): Response {
+      // If result is already a Response (e.g., from controller.sse()), return it
+      if (result instanceof Response) {
+        return result;
+      }
+
+      // Check if result is an async iterable (generator)
+      if (result && typeof result === 'object' && Symbol.asyncIterator in result) {
+        const stream = createSseStream(
+          result as AsyncIterable<unknown>,
+          options,
+        );
+
+        return new Response(stream, {
+          status: HttpStatusCode.OK,
+          headers: {
+            // eslint-disable-next-line @typescript-eslint/naming-convention
+            'Content-Type': 'text/event-stream',
+            // eslint-disable-next-line @typescript-eslint/naming-convention
+            'Cache-Control': 'no-cache',
+            // eslint-disable-next-line @typescript-eslint/naming-convention
+            'Connection': 'keep-alive',
+          },
+        });
+      }
+
+      // Fallback: return error if result is not valid for SSE
+      throw new Error(
+        'SSE endpoint must return an async generator or a Response object. ' +
+        'Use "async *methodName()" or return this.sse(generator).',
+      );
+    }
   }
 
   /**

package/src/decorators/decorators.ts

@@ -575,6 +575,82 @@ export const Head = createRouteDecorator(HttpMethod.HEAD);
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export const All = createRouteDecorator(HttpMethod.ALL);
 
+// ============================================================================
+// SSE (Server-Sent Events) Decorator
+// ============================================================================
+
+/**
+ * Metadata key for SSE handler configuration
+ */
+export const SSE_METADATA = 'onebun:sse';
+
+/**
+ * SSE decorator options
+ */
+export interface SseDecoratorOptions {
+  /**
+   * Heartbeat interval in milliseconds.
+   * When set, the server will send a comment (": heartbeat\n\n")
+   * at this interval to keep the connection alive.
+   */
+  heartbeat?: number;
+}
+
+/**
+ * SSE (Server-Sent Events) method decorator
+ *
+ * Marks a controller method as an SSE endpoint. The method should be an async generator
+ * that yields SseEvent objects or raw data.
+ *
+ * @param options - SSE configuration options
+ * @returns Method decorator
+ *
+ * @example Simple SSE endpoint
+ * ```typescript
+ * @Get('/events')
+ * @Sse()
+ * async *events(): SseGenerator {
+ *   for (let i = 0; i < 10; i++) {
+ *     await Bun.sleep(1000);
+ *     yield { event: 'tick', data: { count: i } };
+ *   }
+ * }
+ * ```
+ *
+ * @example SSE with heartbeat for long-lived connections
+ * ```typescript
+ * @Get('/live')
+ * @Sse({ heartbeat: 15000 })  // Send heartbeat every 15 seconds
+ * async *liveUpdates(): SseGenerator {
+ *   while (true) {
+ *     const data = await this.dataService.waitForUpdate();
+ *     yield { event: 'update', data };
+ *   }
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function Sse(options?: SseDecoratorOptions): MethodDecorator {
+  return (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
+    Reflect.defineMetadata(SSE_METADATA, options ?? {}, target, propertyKey as string);
+
+    return descriptor;
+  };
+}
+
+/**
+ * Check if a method is marked as SSE endpoint
+ * @param target - Controller instance or prototype
+ * @param methodName - Method name
+ * @returns SSE options if method is SSE endpoint, undefined otherwise
+ */
+export function getSseMetadata(
+  target: object,
+  methodName: string,
+): SseDecoratorOptions | undefined {
+  return Reflect.getMetadata(SSE_METADATA, target, methodName);
+}
+
 /**
  * Module decorator metadata
  */

package/src/docs-examples.test.ts

@@ -26,62 +26,9 @@ import type {
   WsExecutionContext,
   WsServerType,
 } from './';
+import type { SseEvent, SseGenerator } from './types';
 import type { ServerWebSocket } from 'bun';
 
-import {
-  Controller,
-  Get,
-  Post,
-  Put,
-  Delete,
-  Patch,
-  Param,
-  Query,
-  Body,
-  Header,
-  Req,
-  Module,
-  Service,
-  BaseService,
-  BaseController,
-  UseMiddleware,
-  getServiceTag,
-  HttpStatusCode,
-  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,
-  matchPattern,
-  makeMockLoggerLayer,
-} from './';
 
 /**
  * @source docs/index.md#minimal-working-example
@@ -2928,3 +2875,409 @@ describe('WebSocket Chat Example (docs/examples/websocket-chat.md)', () => {
     });
   });
 });
+
+// ============================================================================
+// 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,
+  Module,
+  Service,
+  BaseService,
+  BaseController,
+  UseMiddleware,
+  getServiceTag,
+  HttpStatusCode,
+  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,
+  matchPattern,
+  makeMockLoggerLayer,
+} from './';
+
+describe('SSE (Server-Sent Events) API Documentation (docs/api/controllers.md)', () => {
+  describe('SseEvent Type (docs/api/controllers.md)', () => {
+    /**
+     * @source docs/api/controllers.md#sseevent-type
+     */
+    it('should define SseEvent interface', () => {
+      // From docs: SseEvent interface
+      const event: SseEvent = {
+        event: 'update',
+        data: { count: 1 },
+        id: '123',
+        retry: 5000,
+      };
+
+      expect(event.event).toBe('update');
+      expect(event.data).toEqual({ count: 1 });
+      expect(event.id).toBe('123');
+      expect(event.retry).toBe(5000);
+    });
+
+    it('should allow minimal SseEvent with only data', () => {
+      const event: SseEvent = {
+        data: { message: 'Hello' },
+      };
+
+      expect(event.data).toEqual({ message: 'Hello' });
+      expect(event.event).toBeUndefined();
+    });
+  });
+
+  describe('@Sse() Decorator (docs/api/controllers.md)', () => {
+    /**
+     * @source docs/api/controllers.md#sse-decorator
+     */
+    it('should mark method as SSE endpoint', () => {
+      // Test @Sse decorator independently (without @Controller wrapping)
+      class TestClass {
+        @Sse()
+        async *stream(): SseGenerator {
+          yield { event: 'start', data: { timestamp: Date.now() } };
+        }
+      }
+
+      expect(TestClass).toBeDefined();
+
+      // Verify SSE metadata is set on the prototype
+      const metadata = getSseMetadata(TestClass.prototype, 'stream');
+      expect(metadata).toBeDefined();
+    });
+
+    /**
+     * @source docs/api/controllers.md#sse-with-heartbeat
+     */
+    it('should support heartbeat option', () => {
+      // Test @Sse decorator with options independently
+      class TestClass {
+        @Sse({ heartbeat: 15000 })
+        async *live(): SseGenerator {
+          yield { event: 'connected', data: { clientId: 'test' } };
+        }
+      }
+
+      expect(TestClass).toBeDefined();
+
+      // Verify heartbeat option is set
+      const metadata = getSseMetadata(TestClass.prototype, 'live');
+      expect(metadata).toBeDefined();
+      expect(metadata?.heartbeat).toBe(15000);
+    });
+
+    /**
+     * @source docs/api/controllers.md#sse-decorator-with-controller
+     */
+    it('should work with @Controller decorator', () => {
+      // From docs: @Sse() decorator example with full controller
+      @Controller('/events')
+      class EventsController extends BaseController {
+        @Get('/stream')
+        @Sse()
+        async *stream(): SseGenerator {
+          yield { event: 'start', data: { timestamp: Date.now() } };
+        }
+
+        @Get('/live')
+        @Sse({ heartbeat: 15000 })
+        async *live(): SseGenerator {
+          yield { event: 'connected', data: { clientId: 'test' } };
+        }
+      }
+
+      expect(EventsController).toBeDefined();
+    });
+  });
+
+  describe('formatSseEvent Function', () => {
+    /**
+     * @source docs/api/controllers.md#sse-wire-format
+     */
+    it('should format event with all fields', () => {
+      const event: SseEvent = {
+        event: 'update',
+        data: { count: 1 },
+        id: '123',
+        retry: 5000,
+      };
+
+      const formatted = formatSseEvent(event);
+
+      expect(formatted).toContain('event: update\n');
+      expect(formatted).toContain('id: 123\n');
+      expect(formatted).toContain('retry: 5000\n');
+      expect(formatted).toContain('data: {"count":1}\n');
+      expect(formatted).toEndWith('\n\n');
+    });
+
+    it('should format event with only data', () => {
+      const event: SseEvent = {
+        data: { message: 'Hello' },
+      };
+
+      const formatted = formatSseEvent(event);
+
+      expect(formatted).toBe('data: {"message":"Hello"}\n\n');
+      expect(formatted).not.toContain('event:');
+      expect(formatted).not.toContain('id:');
+    });
+
+    it('should format raw data as default event', () => {
+      const rawData = { count: 42 };
+
+      const formatted = formatSseEvent(rawData);
+
+      expect(formatted).toBe('data: {"count":42}\n\n');
+    });
+
+    it('should handle multi-line data', () => {
+      const event: SseEvent = {
+        data: 'line1\nline2\nline3',
+      };
+
+      const formatted = formatSseEvent(event);
+
+      expect(formatted).toContain('data: line1\n');
+      expect(formatted).toContain('data: line2\n');
+      expect(formatted).toContain('data: line3\n');
+    });
+
+    it('should handle string data', () => {
+      const event: SseEvent = {
+        event: 'message',
+        data: 'Simple string message',
+      };
+
+      const formatted = formatSseEvent(event);
+
+      expect(formatted).toContain('event: message\n');
+      expect(formatted).toContain('data: Simple string message\n');
+    });
+  });
+
+  describe('createSseStream Function', () => {
+    /**
+     * @source docs/api/controllers.md#sse-method
+     */
+    it('should create ReadableStream from async generator', async () => {
+      async function* testGenerator(): SseGenerator {
+        yield { event: 'start', data: { count: 0 } };
+        yield { event: 'tick', data: { count: 1 } };
+        yield { event: 'end', data: { count: 2 } };
+      }
+
+      const stream = createSseStream(testGenerator());
+
+      expect(stream).toBeInstanceOf(ReadableStream);
+
+      // Read all chunks from stream
+      const reader = stream.getReader();
+      const decoder = new TextDecoder();
+      const chunks: string[] = [];
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+          break;
+        }
+        chunks.push(decoder.decode(value));
+      }
+
+      const output = chunks.join('');
+      expect(output).toContain('event: start\n');
+      expect(output).toContain('event: tick\n');
+      expect(output).toContain('event: end\n');
+    });
+
+    it('should handle heartbeat option', async () => {
+      // Use a very short heartbeat for testing
+      const heartbeatInterval = 50;
+
+      async function* slowGenerator(): SseGenerator {
+        await Bun.sleep(150);
+        yield { data: 'done' };
+      }
+
+      const stream = createSseStream(slowGenerator(), { heartbeat: heartbeatInterval });
+      const reader = stream.getReader();
+      const decoder = new TextDecoder();
+      const chunks: string[] = [];
+
+      // Read chunks with timeout
+      const startTime = Date.now();
+      while (Date.now() - startTime < 300) {
+        const result = await Promise.race([
+          reader.read(),
+          Bun.sleep(50).then(() => ({ done: false, value: undefined, timeout: true })),
+        ]);
+
+        if ('timeout' in result) {
+          continue;
+        }
+        if (result.done) {
+          break;
+        }
+        if (result.value) {
+          chunks.push(decoder.decode(result.value));
+        }
+      }
+
+      const output = chunks.join('');
+
+      // Should have heartbeat comments
+      expect(output).toContain(': heartbeat\n\n');
+      // Should have the actual event (string data is not wrapped in extra quotes)
+      expect(output).toContain('data: done');
+    });
+  });
+
+  describe('Controller.sse() Method', () => {
+    /**
+     * @source docs/api/controllers.md#sse-method
+     */
+    it('should have sse() method on BaseController', () => {
+      const controller = new BaseController();
+
+      // Access protected method via type assertion
+      expect(typeof (controller as unknown as { sse: Function }).sse).toBe('function');
+    });
+
+    /**
+     * @source docs/api/controllers.md#sse-method-example
+     */
+    it('should define controller using sse() method', () => {
+      // From docs: Using sse() method example
+      @Controller('/events')
+      class EventsController extends BaseController {
+        @Get('/manual')
+        events(): Response {
+          return this.sse(async function* () {
+            yield { event: 'start', data: { timestamp: Date.now() } };
+            yield { event: 'complete', data: { success: true } };
+          }());
+        }
+      }
+
+      expect(EventsController).toBeDefined();
+    });
+  });
+
+  describe('Complete SSE Controller Example (docs/api/controllers.md)', () => {
+    /**
+     * @source docs/api/controllers.md#server-sent-events-sse
+     */
+    it('should define complete SSE controller', () => {
+      // From docs: Complete SSE Controller example
+      @Service()
+      class DataService extends BaseService {
+        async waitForUpdate(): Promise<unknown> {
+          return { updated: true };
+        }
+      }
+
+      @Service()
+      class NotificationService extends BaseService {
+        async poll(): Promise<unknown> {
+          return { type: 'notification', message: 'New message' };
+        }
+      }
+
+      @Controller('/events')
+      class EventsController extends BaseController {
+        constructor(
+          private dataService: DataService,
+          private notificationService: NotificationService,
+        ) {
+          super();
+        }
+
+        // Simple SSE endpoint
+        @Get('/stream')
+        @Sse()
+        async *stream(): SseGenerator {
+          for (let i = 0; i < 10; i++) {
+            yield { event: 'tick', data: { count: i, timestamp: Date.now() } };
+          }
+        }
+
+        // SSE with heartbeat
+        @Get('/live')
+        @Sse({ heartbeat: 15000 })
+        async *live(): SseGenerator {
+          yield { event: 'connected', data: { clientId: crypto.randomUUID() } };
+        }
+
+        // SSE with event IDs for reconnection
+        @Get('/notifications')
+        @Sse({ heartbeat: 30000 })
+        async *notifications(): SseGenerator {
+          let eventId = 0;
+          const notification = await this.notificationService.poll();
+          eventId++;
+          yield {
+            event: 'notification',
+            data: notification,
+            id: String(eventId),
+            retry: 5000,
+          };
+        }
+
+        // Using sse() method
+        @Get('/manual')
+        events(): Response {
+          return this.sse(async function* () {
+            yield { event: 'start', data: { timestamp: Date.now() } };
+            yield { event: 'complete', data: { success: true } };
+          }());
+        }
+      }
+
+      expect(EventsController).toBeDefined();
+      expect(DataService).toBeDefined();
+      expect(NotificationService).toBeDefined();
+    });
+  });
+});

package/src/index.ts

@@ -42,6 +42,10 @@ export {
   type WebSocketApplicationOptions,
   // Docs types
   type DocsApplicationOptions,
+  // SSE types
+  type SseEvent,
+  type SseOptions,
+  type SseGenerator,
 } from './types';
 
 // Decorators and Metadata (exports Controller decorator, Module decorator, etc.)

package/src/module/controller.ts

@@ -1,4 +1,5 @@
 import type { IConfig, OneBunAppConfig } from './config.interface';
+import type { SseEvent, SseOptions } from '../types';
 import type { Context } from 'effect';
 
 import type { SyncLogger } from '@onebun/logger';
@@ -173,4 +174,202 @@ export class Controller {
       },
     });
   }
+
+  // ===========================================================================
+  // SSE (Server-Sent Events) Methods
+  // ===========================================================================
+
+  /**
+   * Create an SSE (Server-Sent Events) response from an async iterable
+   *
+   * This method provides an alternative to the @Sse() decorator for creating
+   * SSE responses programmatically.
+   *
+   * @param source - Async iterable that yields SseEvent objects or raw data
+   * @param options - SSE options (heartbeat interval, etc.)
+   * @returns A Response object with SSE content type
+   *
+   * @example Basic usage
+   * ```typescript
+   * @Get('/events')
+   * events(): Response {
+   *   return this.sse(async function* () {
+   *     for (let i = 0; i < 10; i++) {
+   *       await Bun.sleep(1000);
+   *       yield { event: 'tick', data: { count: i } };
+   *     }
+   *   }());
+   * }
+   * ```
+   *
+   * @example With heartbeat
+   * ```typescript
+   * @Get('/live')
+   * live(): Response {
+   *   const updates = this.dataService.getUpdateStream();
+   *   return this.sse(updates, { heartbeat: 15000 });
+   * }
+   * ```
+   */
+  protected sse(
+    source: AsyncIterable<SseEvent | unknown>,
+    options: SseOptions = {},
+  ): Response {
+    const stream = createSseStream(source, options);
+
+    return new Response(stream, {
+      status: HttpStatusCode.OK,
+      headers: {
+        // eslint-disable-next-line @typescript-eslint/naming-convention
+        'Content-Type': 'text/event-stream',
+        // eslint-disable-next-line @typescript-eslint/naming-convention
+        'Cache-Control': 'no-cache',
+        // eslint-disable-next-line @typescript-eslint/naming-convention
+        'Connection': 'keep-alive',
+      },
+    });
+  }
+}
+
+// =============================================================================
+// SSE Helper Functions (used by both Controller.sse() and executeHandler)
+// =============================================================================
+
+/**
+ * Format an event object into SSE wire format
+ *
+ * @param event - Event object or raw data
+ * @returns Formatted SSE string
+ *
+ * @example
+ * ```typescript
+ * formatSseEvent({ event: 'update', data: { count: 1 }, id: '123' })
+ * // Returns: "event: update\nid: 123\ndata: {"count":1}\n\n"
+ *
+ * formatSseEvent({ count: 1 })
+ * // Returns: "data: {"count":1}\n\n"
+ * ```
+ */
+export function formatSseEvent(event: SseEvent | unknown): string {
+  let result = '';
+
+  // Check if this is an SseEvent object or raw data
+  const isSseEvent =
+    typeof event === 'object' &&
+    event !== null &&
+    'data' in event &&
+    (('event' in event && typeof (event as SseEvent).event === 'string') ||
+      ('id' in event && typeof (event as SseEvent).id === 'string') ||
+      ('retry' in event && typeof (event as SseEvent).retry === 'number') ||
+      Object.keys(event).every((k) => ['event', 'data', 'id', 'retry'].includes(k)));
+
+  if (isSseEvent) {
+    const sseEvent = event as SseEvent;
+
+    // Add event name if specified
+    if (sseEvent.event) {
+      result += `event: ${sseEvent.event}\n`;
+    }
+
+    // Add event ID if specified
+    if (sseEvent.id) {
+      result += `id: ${sseEvent.id}\n`;
+    }
+
+    // Add retry interval if specified
+    if (sseEvent.retry !== undefined) {
+      result += `retry: ${sseEvent.retry}\n`;
+    }
+
+    // Add data (JSON serialized)
+    const dataStr =
+      typeof sseEvent.data === 'string' ? sseEvent.data : JSON.stringify(sseEvent.data);
+
+    // Handle multi-line data by prefixing each line with "data: "
+    const dataLines = dataStr.split('\n');
+    for (const line of dataLines) {
+      result += `data: ${line}\n`;
+    }
+  } else {
+    // Raw data - serialize as JSON
+    const dataStr = typeof event === 'string' ? event : JSON.stringify(event);
+    const dataLines = dataStr.split('\n');
+    for (const line of dataLines) {
+      result += `data: ${line}\n`;
+    }
+  }
+
+  // Add final newline to complete the event
+  result += '\n';
+
+  return result;
+}
+
+/**
+ * Create a ReadableStream for SSE from an async iterable
+ *
+ * @param source - Async iterable that yields events
+ * @param options - SSE options
+ * @returns ReadableStream for Response body
+ */
+export function createSseStream(
+  source: AsyncIterable<SseEvent | unknown>,
+  options: SseOptions = {},
+): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder();
+  let heartbeatTimer: Timer | null = null;
+  let isCancelled = false;
+
+  return new ReadableStream<Uint8Array>({
+    async start(controller) {
+      // Set up heartbeat timer if specified
+      if (options.heartbeat && options.heartbeat > 0) {
+        heartbeatTimer = setInterval(() => {
+          if (!isCancelled) {
+            try {
+              controller.enqueue(encoder.encode(': heartbeat\n\n'));
+            } catch {
+              // Controller might be closed, ignore
+            }
+          }
+        }, options.heartbeat);
+      }
+
+      try {
+        for await (const event of source) {
+          if (isCancelled) {
+            break;
+          }
+          const formatted = formatSseEvent(event);
+          controller.enqueue(encoder.encode(formatted));
+        }
+      } catch (error) {
+        // Log error but don't throw - stream should close gracefully
+        // eslint-disable-next-line no-console
+        console.error('[SSE] Stream error:', error);
+      } finally {
+        // Clean up heartbeat timer
+        if (heartbeatTimer) {
+          clearInterval(heartbeatTimer);
+          heartbeatTimer = null;
+        }
+        // Close the stream
+        if (!isCancelled) {
+          try {
+            controller.close();
+          } catch {
+            // Controller might already be closed
+          }
+        }
+      }
+    },
+
+    cancel() {
+      isCancelled = true;
+      if (heartbeatTimer) {
+        clearInterval(heartbeatTimer);
+        heartbeatTimer = null;
+      }
+    },
+  });
 }

package/src/module/module.test.ts

@@ -154,6 +154,94 @@ describe('OneBunModule', () => {
 
       expect(() => new OneBunModule(TestClass, mockLoggerLayer)).toThrow();
     });
+
+    test('should detect circular dependencies and provide detailed error message', () => {
+      const { registerDependencies } = require('../decorators/decorators');
+      const { Effect, Layer } = require('effect');
+      const { LoggerService } = require('@onebun/logger');
+
+      // Collect error messages
+      const errorMessages: string[] = [];
+
+      // Create mock logger that captures error messages
+      // Using Effect.sync to ensure the message is captured synchronously when Effect.runSync is called
+      const captureLogger = {
+        trace: () => Effect.sync(() => undefined),
+        debug: () => Effect.sync(() => undefined),
+        info: () => Effect.sync(() => undefined),
+        warn: () => Effect.sync(() => undefined),
+        error: (msg: string) =>
+          Effect.sync(() => {
+            errorMessages.push(msg);
+          }),
+        fatal: () => Effect.sync(() => undefined),
+        child: () => captureLogger,
+      };
+      const captureLoggerLayer = Layer.succeed(LoggerService, captureLogger);
+
+      // Create services - define all classes first
+      @Service()
+      class CircularServiceA {
+        getValue() {
+          return 'A';
+        }
+      }
+
+      @Service()
+      class CircularServiceB {
+        getValue() {
+          return 'B';
+        }
+      }
+
+      @Service()
+      class CircularServiceC {
+        getValue() {
+          return 'C';
+        }
+      }
+
+      // Now register circular dependencies manually: A -> B -> C -> A
+      registerDependencies(CircularServiceA, [CircularServiceC]);
+      registerDependencies(CircularServiceB, [CircularServiceA]);
+      registerDependencies(CircularServiceC, [CircularServiceB]);
+
+      @Module({
+        providers: [CircularServiceA, CircularServiceB, CircularServiceC],
+      })
+      class CircularModule {}
+
+      // Initialize module - should detect circular dependency
+      new OneBunModule(CircularModule, captureLoggerLayer);
+
+      // Verify error message was logged
+      expect(errorMessages.length).toBeGreaterThan(0);
+
+      // Find the circular dependency error message
+      const circularError = errorMessages.find((msg) =>
+        msg.includes('Circular dependency detected'),
+      );
+      expect(circularError).toBeDefined();
+
+      // Should contain module name
+      expect(circularError).toContain('CircularModule');
+
+      // Should contain "Unresolved services" section
+      expect(circularError).toContain('Unresolved services');
+
+      // Should contain at least one of the service names with their dependencies
+      const hasServiceInfo =
+        circularError!.includes('CircularServiceA') ||
+        circularError!.includes('CircularServiceB') ||
+        circularError!.includes('CircularServiceC');
+      expect(hasServiceInfo).toBe(true);
+
+      // Should contain "needs:" showing what dependencies are required
+      expect(circularError).toContain('needs:');
+
+      // Should contain "Dependency chain" showing the cycle
+      expect(circularError).toContain('Dependency chain');
+    });
   });
 
   describe('Module instance methods', () => {

package/src/module/module.ts

@@ -229,6 +229,7 @@ export class OneBunModule implements ModuleInstance {
     // Create services in dependency order
     const pendingProviders = [...metadata.providers.filter((p) => typeof p === 'function')];
     const createdServices = new Set<string>();
+    const unresolvedDeps = new Map<string, string[]>(); // Track unresolved dependencies for error reporting
     let iterations = 0;
     const maxIterations = pendingProviders.length * 2; // Prevent infinite loops
 
@@ -245,8 +246,11 @@ export class OneBunModule implements ModuleInstance {
         continue;
       }
 
-      // Use autoDetectDependencies to find dependencies from constructor
-      const detectedDeps = autoDetectDependencies(provider, availableServiceClasses);
+      // Use getConstructorParamTypes first (for @Inject and TypeScript metadata),
+      // then fallback to autoDetectDependencies (for constructor source analysis)
+      const detectedDeps =
+        getConstructorParamTypes(provider) ||
+        autoDetectDependencies(provider, availableServiceClasses);
       const dependencies: unknown[] = [];
       let allDependenciesResolved = true;
 
@@ -259,6 +263,12 @@ export class OneBunModule implements ModuleInstance {
             // Check if it's a service that hasn't been created yet
             const isServiceInModule = availableServiceClasses.has(depType.name);
             if (isServiceInModule && !createdServices.has(depType.name)) {
+              // Track unresolved dependency for error reporting
+              const deps = unresolvedDeps.get(provider.name) || [];
+              if (!deps.includes(depType.name)) {
+                deps.push(depType.name);
+                unresolvedDeps.set(provider.name, deps);
+              }
               // This dependency will be created later, defer this service
               allDependenciesResolved = false;
               pendingProviders.push(provider);
@@ -317,7 +327,25 @@ export class OneBunModule implements ModuleInstance {
     }
 
     if (iterations >= maxIterations) {
-      this.logger.error('Possible circular dependency detected in services');
+      const unresolvedServices = pendingProviders
+        .filter((p) => typeof p === 'function')
+        .map((p) => p.name);
+
+      const details = unresolvedServices
+        .map((serviceName) => {
+          const deps = unresolvedDeps.get(serviceName) || [];
+
+          return `  - ${serviceName} -> needs: [${deps.join(', ')}]`;
+        })
+        .join('\n');
+
+      const dependencyChain = this.buildDependencyChain(unresolvedDeps, unresolvedServices);
+
+      this.logger.error(
+        `Circular dependency detected in module ${this.moduleClass.name}!\n` +
+          `Unresolved services:\n${details}\n` +
+          `Dependency chain: ${dependencyChain}`,
+      );
     }
   }
 
@@ -479,6 +507,52 @@ export class OneBunModule implements ModuleInstance {
     return serviceInstance;
   }
 
+  /**
+   * Build a human-readable dependency chain for circular dependency error reporting
+   * Traverses the dependency graph to find and display the cycle
+   */
+  private buildDependencyChain(
+    unresolvedDeps: Map<string, string[]>,
+    unresolvedServices: string[],
+  ): string {
+    // Find cycle by traversing dependencies
+    const visited = new Set<string>();
+    const chain: string[] = [];
+
+    const findCycle = (service: string): boolean => {
+      if (visited.has(service)) {
+        chain.push(service);
+
+        return true;
+      }
+      visited.add(service);
+      chain.push(service);
+
+      const deps = unresolvedDeps.get(service) || [];
+      for (const dep of deps) {
+        if (unresolvedServices.includes(dep)) {
+          if (findCycle(dep)) {
+            return true;
+          }
+        }
+      }
+      chain.pop();
+
+      return false;
+    };
+
+    for (const service of unresolvedServices) {
+      visited.clear();
+      chain.length = 0;
+      if (findCycle(service)) {
+        return chain.join(' -> ');
+      }
+    }
+
+    // If no cycle found, just show all unresolved services
+    return unresolvedServices.join(' <-> ');
+  }
+
   /**
    * Setup the module and its dependencies
    */

package/src/types.ts

@@ -511,3 +511,79 @@ export interface ControllerMetadata {
   path: string;
   routes: RouteMetadata[];
 }
+
+// ============================================================================
+// SSE (Server-Sent Events) Types
+// ============================================================================
+
+/**
+ * SSE event structure
+ *
+ * Represents a single Server-Sent Event that can be sent to the client.
+ *
+ * @example
+ * ```typescript
+ * // Simple event with data
+ * yield { data: { message: 'Hello' } };
+ *
+ * // Named event with ID
+ * yield { event: 'update', data: { count: 42 }, id: '123' };
+ *
+ * // Event with retry interval
+ * yield { event: 'status', data: { online: true }, retry: 5000 };
+ * ```
+ */
+export interface SseEvent {
+  /** Event name (optional, defaults to 'message') */
+  event?: string;
+  /** Event data (will be JSON serialized) */
+  data: unknown;
+  /** Event ID for reconnection (Last-Event-ID header) */
+  id?: string;
+  /** Reconnection interval in milliseconds */
+  retry?: number;
+}
+
+/**
+ * SSE decorator options
+ *
+ * @example
+ * ```typescript
+ * @Sse({ heartbeat: 15000 })  // Send heartbeat every 15 seconds
+ * async *events(): SseGenerator {
+ *   // ...
+ * }
+ * ```
+ */
+export interface SseOptions {
+  /**
+   * Heartbeat interval in milliseconds.
+   * When set, the server will send a comment (": heartbeat\n\n")
+   * at this interval to keep the connection alive.
+   */
+  heartbeat?: number;
+}
+
+/**
+ * SSE generator type
+ *
+ * An async generator that yields SSE events or raw data.
+ * When raw data is yielded, it will be wrapped in a default event.
+ *
+ * @example
+ * ```typescript
+ * @Get('/events')
+ * @Sse()
+ * async *events(): SseGenerator {
+ *   yield { event: 'start', data: { timestamp: Date.now() } };
+ *
+ *   for (let i = 0; i < 10; i++) {
+ *     await Bun.sleep(1000);
+ *     yield { event: 'tick', data: { count: i } };
+ *   }
+ *
+ *   yield { event: 'end', data: { total: 10 } };
+ * }
+ * ```
+ */
+export type SseGenerator = AsyncGenerator<SseEvent | unknown, void, unknown>;