quantum-flow 1.8.1 → 1.10.0

package/README.md

@@ -22,6 +22,7 @@ You can use controllers and server functionality by importing controllers and cr
 - `quantum-flow/core` - Core framework components like Controller and Endpoint.
 - `quantum-flow/middlewares` - Core middlewares to use within the application.
 - `quantum-flow/ws` - Websocket decorators.
+- `quantum-flow/sse` - Server side events decorators.
 
 ---
 
@@ -138,7 +139,8 @@ server.listen().catch(console.error);
 - Use `@Multipart` for handling multipart/form-data requests.
 - Use `@Request` to access the original request object.
 - Use `@Response` to access the original object.
-- Use `@InjectWS` to access the WebsocketService.
+- Use `@InjectWS` to access the websocket service.
+- Use `@InjectSSE()` to access the server-side-event service.
 
 # AWS Lambda Support
 
@@ -168,6 +170,18 @@ export const handler = LambdaAdapter.createHandler(RootController);
 
 Enable WebSocket in the server configuration and register WebSocket controllers.
 
+## Enabling WebSocket Support in Server
+
+To enable SSE support, configure your HTTP server with the `sse: true` option and register controllers that use SSE.
+
+Example server setup:
+
+```typescript
+@Server( {websocket: { enabled: true, path: '/ws' } })
+```
+
+## Injecting WebSocket events in Controller
+
 ```typescript
 import { OnConnection, Subscribe, OnMessage } from 'quantum-flow/ws';
 @Controller('socket')
@@ -231,65 +245,127 @@ export class Socket {
 }
 ```
 
-# Decorators
+# Server-Sent Events (SSE) Support
+
+The framework supports Server-Sent Events (SSE) to enable real-time, one-way communication from the server to clients over HTTP.
+
+## Defining SSE Controllers
 
-### Use
+Use the `@Controller` decorator to define controllers with a `prefix` and optionally include sub-controllers. This allows modular organization of your API endpoints.
 
-Class decorator to add global middlewares to the server.
-Should be used only with @Server decorator
+Example:
 
 ```typescript
-@Use(middleware)
-class App {}
+@Controller({
+  prefix: 'user',
+  controllers: [UserMetadata],
+  middlewares: [function UserGlobalUse() {}],
+  interceptor: (data, req, res) => {
+    return { data, intercepted: true };
+  },
+})
+export class User {}
 ```
 
-### Catch
+## Injecting SSE Service
+
+Use the `@InjectSSE` decorator in your controller methods to create and manage SSE connections. This service allows sending events to connected clients.
 
-Class decorator to set a global error handler for the server.
+Example method using SSE:
 
 ```typescript
-@Catch((error) => {
-  return { message: 'Internal Server Error' };
-})
-class App {}
+import { InjectSSE } from 'quantum-flow/sse';
+
+@Controller('user')
+export class UserMetadata {
+  @GET('/subscribesse')
+  async subscribesse(@InjectSSE() sse) {
+    const client = sse.createConnection(res);
+
+    sse.sendToClient(client.id, {
+      event: 'welcome message',
+      data: { message: 'Connected to notifications' },
+    });
+
+    return 'hellow';
+  }
+}
 ```
 
-### Port
+## SSE Event Decorators
 
-Class decorator to set the server port.
+The framework provides decorators to handle SSE connection lifecycle events:
+
+- `@OnSSEConnection()`: Decorate a method to handle new SSE connections.
+- `@OnSSEError()`: Decorate a method to handle SSE errors.
+- `@OnSSEClose()`: Decorate a method to handle SSE connection closures.
+
+Example usage:
 
 ```typescript
-@Port(3000)
-class App {}
+import { OnSSEConnection, OnSSEError, OnSSEClose } from 'quantum-flow/sse';
+
+@Controller('user')
+export class User {
+  @OnSSEConnection()
+  async onsseconnection(@Request() req: any, @Response() res: any) {
+    console.log('SSE connection established');
+    return req.body;
+  }
+
+  @OnSSEError()
+  async onsseerror(@Request() req: any, @Response() res: any) {
+    console.log('SSE error occurred');
+    return req.body;
+  }
+
+  @OnSSEClose()
+  async onsseclose(@Request() req: any, @Response() res: any) {
+    console.log('SSE connection closed');
+    return req.body;
+  }
+}
 ```
 
-### Host
+## Sending SSE Events
 
-Class decorator to set the server host.
+Use the injected SSE service to send events to clients. You can send events to all clients or specific clients by ID.
+
+Example:
 
 ```typescript
-@Host('localhost')
-class App {}
+sse.sendToClient(clientId, {
+  event: 'eventName',
+  data: { key: 'value' },
+});
 ```
 
-### Validate
+## Enabling SSE Support in Server
 
-Method or class decorator to validate request parameters (query, body, params, headers) against a DTO class using class-validator.
+To enable SSE support, configure your HTTP server with the `sse: true` option and register controllers that use SSE.
+
+Example server setup:
 
 ```typescript
-import { IsEmail } from 'class-validator';
-class UserDTO {
-  @IsEmail()
-  email: string;
+import { Server, HttpServer } from 'quantum-flow/http';
+import { User, UserMetadata } from './controllers';
 
-  @Length(6, 20)
-  password: string;
-}
+@Server({
+  controllers: [User, UserMetadata],
+  sse: { enabled: true },
+})
+class App {}
 
-class UserController {
-  @POST('/')
-  async createUser(@Body(UserDTO) user: UserDTO, @Query() query) {
-    // Your logic here
-  }
-}
+const server = new HttpServer(App);
+server.listen().catch(console.error);
 ```
+
+## Summary
+
+- Use `@Controller` with `prefix` and `controllers` to organize your API.
+- Use `@InjectSSE` to create SSE connections in controller methods.
+- Use the SSE service's `send` method to push events to clients.
+- Use `@OnSSEConnection`, `@OnSSEError`, and `@OnSSEClose` decorators to handle SSE lifecycle events.
+- Enable SSE in your server configuration and register SSE controllers.
+
+This setup allows you to build real-time, event-driven APIs using Server-Sent Events in a clean and modular way.

package/dist/app/http/Application.d.ts

@@ -1,10 +1,11 @@
 import { ServerConfig } from '../../types/index.js';
 import http from 'http';
-import { Socket } from './Socket';
-export declare class HttpServer extends Socket {
+export declare class HttpServer {
     private app;
     private config;
     private isRunning;
+    private sse?;
+    private websocket?;
     constructor(configOrClass: new (...args: any[]) => any);
     private logConfig;
     listen(port?: number, host?: string): Promise<http.Server>;

package/dist/app/http/Application.js

@@ -7,21 +7,29 @@ exports.HttpServer = void 0;
 const _constants_1 = require("../../constants.js");
 const _utils_1 = require("../../utils/index.js");
 const http_1 = __importDefault(require("http"));
-const Socket_1 = require("./Socket");
-const WebsocketServer_1 = require("./websocket/WebsocketServer");
-const WebsocketService_1 = require("./websocket/WebsocketService");
-class HttpServer extends Socket_1.Socket {
+const server_1 = require("../../ws/server");
+const service_1 = require("../../ws/service");
+const server_2 = require("../../sse/server");
+const service_2 = require("../../sse/service");
+class HttpServer {
     app;
     config;
     isRunning = false;
+    sse;
+    websocket;
     constructor(configOrClass) {
-        super();
         this.config = (0, _utils_1.resolveConfig)(configOrClass);
         const app = http_1.default.createServer(this.requestHandler.bind(this));
+        const controllers = this.getAllControllers(this.config.controllers);
         if (this.config.websocket?.enabled) {
-            this.wss = new WebsocketServer_1.WebSocketServer(app, { path: this.config.websocket.path });
-            this.wss.registerControllers(this.getAllControllers(this.config.controllers));
-            WebsocketService_1.WebSocketService.getInstance().initialize(this.wss);
+            this.websocket = new server_1.WebSocketServer(app, { path: this.config.websocket.path });
+            this.websocket.registerControllers(controllers);
+            service_1.WebSocketService.getInstance().initialize(this.websocket);
+        }
+        if (this.config.sse?.enabled) {
+            this.sse = new server_2.SSEServer();
+            this.sse.registerControllers(controllers);
+            service_2.SSEService.getInstance().initialize(this.sse);
         }
         this.app = app;
         this.logConfig();
@@ -190,17 +198,17 @@ class HttpServer extends Socket_1.Socket {
     }
     async sendResponse(res, data, startTime) {
         const response = data?.data !== undefined ? data.data : data;
-        if (!res.headersSent) {
-            if (!res.getHeader('Content-Type')) {
-                res.setHeader('Content-Type', 'application/json');
-            }
-            if (data?.headers) {
-                Object.entries(data.headers).forEach(([key, value]) => {
-                    if (!res.getHeader(key)) {
-                        res.setHeader(key, value);
-                    }
-                });
-            }
+        if (res.headersSent)
+            return;
+        if (!res.getHeader('Content-Type')) {
+            res.setHeader('Content-Type', 'application/json');
+        }
+        if (data?.headers) {
+            Object.entries(data.headers).forEach(([key, value]) => {
+                if (!res.getHeader(key)) {
+                    res.setHeader(key, value);
+                }
+            });
         }
         res.setHeader('X-Response-Time', `${Date.now() - startTime}ms`);
         res.statusCode = data.status ?? 200;

package/dist/app/http/index.d.ts

@@ -1,3 +1,2 @@
 export * from './Application';
 export * from './decorators';
-export * from './websocket/WebsocketServer';

package/dist/app/http/index.js

@@ -16,4 +16,3 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./Application"), exports);
 __exportStar(require("./decorators"), exports);
-__exportStar(require("./websocket/WebsocketServer"), exports);

package/dist/constants.d.ts

@@ -21,3 +21,6 @@ export declare const TO_VALIDATE: string[];
 export declare const STATISTIC: Record<'controllers' | 'routes', number>;
 export declare const INCREMENT_STATISTIC: (prop: "controllers" | "routes") => void;
 export declare const CORS_METADATA = "cors:config";
+export declare const SSE_METADATA_KEY = "sse:handlers";
+export declare const SSE_TOPIC_KEY = "sse:topics";
+export declare const SSE_SERVICE_KEY = "sse:service";

package/dist/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CORS_METADATA = exports.INCREMENT_STATISTIC = exports.STATISTIC = exports.TO_VALIDATE = exports.OK_STATUSES = exports.STOPPED = exports.SANITIZE = exports.CATCH = exports.INTECEPT = exports.WS_SERVICE_KEY = exports.WS_TOPIC_KEY = exports.WS_HANDLER = exports.USE_MIDDLEWARE = exports.SERVER_CONFIG_KEY = exports.OK_METADATA_KEY = exports.ENDPOINT = exports.INTERCEPTOR = exports.CONTROLLERS = exports.MIDDLEWARES = exports.ROUTE_MIDDLEWARES = exports.ROUTE_PREFIX = exports.APP_METADATA_KEY = exports.PARAM_METADATA_KEY = void 0;
+exports.SSE_SERVICE_KEY = exports.SSE_TOPIC_KEY = exports.SSE_METADATA_KEY = exports.CORS_METADATA = exports.INCREMENT_STATISTIC = exports.STATISTIC = exports.TO_VALIDATE = exports.OK_STATUSES = exports.STOPPED = exports.SANITIZE = exports.CATCH = exports.INTECEPT = exports.WS_SERVICE_KEY = exports.WS_TOPIC_KEY = exports.WS_HANDLER = exports.USE_MIDDLEWARE = exports.SERVER_CONFIG_KEY = exports.OK_METADATA_KEY = exports.ENDPOINT = exports.INTERCEPTOR = exports.CONTROLLERS = exports.MIDDLEWARES = exports.ROUTE_MIDDLEWARES = exports.ROUTE_PREFIX = exports.APP_METADATA_KEY = exports.PARAM_METADATA_KEY = void 0;
 exports.PARAM_METADATA_KEY = 'design:parameters';
 exports.APP_METADATA_KEY = 'app:configuration';
 exports.ROUTE_PREFIX = 'route:prefix';
@@ -35,3 +35,6 @@ const INCREMENT_STATISTIC = (prop) => {
 };
 exports.INCREMENT_STATISTIC = INCREMENT_STATISTIC;
 exports.CORS_METADATA = 'cors:config';
+exports.SSE_METADATA_KEY = 'sse:handlers';
+exports.SSE_TOPIC_KEY = 'sse:topics';
+exports.SSE_SERVICE_KEY = 'sse:service';

package/dist/core/Controller.d.ts

@@ -1,4 +1,4 @@
-import { AppRequest, ControllerClass, ControllerConfig, InterceptorCB, RouteContext } from '../types/index.js';
+import { AppRequest, ControllerClass, ControllerConfig, InterceptorCB, RouteContext, SeeControllerHandlers, WsControllerHandlers } from '../types/index.js';
 import { ServerResponse } from 'http';
 import 'reflect-metadata';
 /**
@@ -25,21 +25,25 @@ import 'reflect-metadata';
 export declare function Controller(config: string | ControllerConfig, middlewares?: Array<InterceptorCB>): <T extends ControllerClass>(constructor: T) => {
     new (...args: any[]): {
         [x: string]: any;
+        ws?: WsControllerHandlers;
+        sse?: SeeControllerHandlers;
         executeControllerMethod: (controller: import("../types/index.js").ControllerInstance, propertyName: string, request: AppRequest, response: ServerResponse) => Promise<any>;
         getControllerMethods: (controller: import("../types/index.js").ControllerInstance) => import("../types/index.js").ControllerMethods;
         handleRequest: (request: AppRequest, response: ServerResponse) => Promise<any>;
         routeWalker(context: RouteContext, request: AppRequest, response: ServerResponse): Promise<any>;
-        getWebSocketController(): {
+        lookupWS(): void;
+        lookupSSE(): void;
+        getSSEController(): {
             instance: /*elided*/ any;
             handlers: {
-                connection: any;
-                message: any;
-                close: any;
-                error: any;
+                connection: any[];
+                close: any[];
+                error: any[];
             };
-            topics: any;
         };
-        getWSHandlers(type: string): any;
+        getWSHandlers(type: string): any[];
+        getSSEHandlers(type: string): any[];
         getWSTopics(): any;
+        typedHandlers: (handlers: any[], type: string) => any[];
     };
 } & T;

package/dist/core/Controller.js

@@ -64,10 +64,14 @@ function Controller(config, middlewares = []) {
             });
         }
         return class extends constructor {
+            ws;
+            sse;
             executeControllerMethod = _utils_1.executeControllerMethod;
             getControllerMethods = _utils_1.getControllerMethods;
             constructor(...args) {
                 super(...args);
+                this.lookupWS();
+                this.lookupSSE();
             }
             handleRequest = async (request, response) => {
                 const middlewares = []
@@ -200,26 +204,43 @@ function Controller(config, middlewares = []) {
                 }
                 return null;
             }
-            getWebSocketController() {
+            lookupWS() {
+                const connection = this.getWSHandlers('connection');
+                const message = this.getWSHandlers('message');
+                const error = this.getWSHandlers('error');
+                const close = this.getWSHandlers('close');
+                const topics = this.getWSHandlers('topics');
+                if ([...connection, ...message, ...error, ...close, ...topics].length === 0) {
+                    return;
+                }
+                this.ws = { handlers: { connection, message, close, error }, topics };
+            }
+            lookupSSE() {
+                const connection = this.getSSEHandlers('connection');
+                const error = this.getSSEHandlers('error');
+                const close = this.getSSEHandlers('close');
+                if ([...connection, ...error, ...close].length === 0) {
+                    return;
+                }
+                this.sse = { handlers: { connection, close, error } };
+            }
+            getSSEController() {
                 return {
                     instance: this,
                     handlers: {
-                        connection: this.getWSHandlers('connection'),
-                        message: this.getWSHandlers('message'),
-                        close: this.getWSHandlers('close'),
-                        error: this.getWSHandlers('error'),
+                        connection: this.getSSEHandlers('connection'),
+                        close: this.getSSEHandlers('close'),
+                        error: this.getSSEHandlers('error'),
                     },
-                    topics: this.getWSTopics(),
                 };
             }
             getWSHandlers(type) {
                 const handlers = Reflect.getMetadata(_constants_1.WS_HANDLER, this.constructor) || [];
-                return handlers
-                    .filter((h) => h.type === type)
-                    .map((h) => ({
-                    ...h,
-                    fn: this[h.method].bind(this),
-                }));
+                return this.typedHandlers(handlers, type);
+            }
+            getSSEHandlers(type) {
+                const handlers = Reflect.getMetadata(_constants_1.SSE_METADATA_KEY, this.constructor) || [];
+                return this.typedHandlers(handlers, type);
             }
             getWSTopics() {
                 const topics = Reflect.getMetadata(_constants_1.WS_TOPIC_KEY, this.constructor) || [];
@@ -228,6 +249,14 @@ function Controller(config, middlewares = []) {
                     fn: this[t.method].bind(this),
                 }));
             }
+            typedHandlers = (handlers, type) => {
+                return handlers
+                    .filter((h) => h.type === type)
+                    .map((h) => ({
+                    ...h,
+                    fn: this[h.method].bind(this),
+                }));
+            };
         };
     };
 }

package/dist/sse/decorators.d.ts

@@ -0,0 +1,6 @@
+export type SSEHandlerType = 'connection' | 'close' | 'error';
+export declare function OnSSE(type: SSEHandlerType): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+export declare function OnSSEConnection(): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+export declare function OnSSEClose(): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+export declare function OnSSEError(): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+export declare function InjectSSE(): (target: any, propertyKey: string | symbol, parameterIndex: number) => void;

package/dist/sse/decorators.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnSSE = OnSSE;
+exports.OnSSEConnection = OnSSEConnection;
+exports.OnSSEClose = OnSSEClose;
+exports.OnSSEError = OnSSEError;
+exports.InjectSSE = InjectSSE;
+const _constants_1 = require("../constants.js");
+const _utils_1 = require("../utils/index.js");
+function OnSSE(type) {
+    return function (target, propertyKey, descriptor) {
+        const handlers = Reflect.getMetadata(_constants_1.SSE_METADATA_KEY, target.constructor) || [];
+        handlers.push({ type, method: propertyKey });
+        Reflect.defineMetadata(_constants_1.SSE_METADATA_KEY, handlers, target.constructor);
+        return descriptor;
+    };
+}
+function OnSSEConnection() {
+    return OnSSE('connection');
+}
+function OnSSEClose() {
+    return OnSSE('close');
+}
+function OnSSEError() {
+    return OnSSE('error');
+}
+function InjectSSE() {
+    return (0, _utils_1.createParamDecorator)('sse');
+}

package/dist/sse/index.d.ts

@@ -0,0 +1,2 @@
+export { ISSEService, SSEClient, SSEEvent, SSEMessage } from '../types/index.js';
+export { InjectSSE, OnSSEClose, OnSSEConnection, OnSSEError } from './decorators';

package/dist/sse/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnSSEError = exports.OnSSEConnection = exports.OnSSEClose = exports.InjectSSE = void 0;
+var decorators_1 = require("./decorators");
+Object.defineProperty(exports, "InjectSSE", { enumerable: true, get: function () { return decorators_1.InjectSSE; } });
+Object.defineProperty(exports, "OnSSEClose", { enumerable: true, get: function () { return decorators_1.OnSSEClose; } });
+Object.defineProperty(exports, "OnSSEConnection", { enumerable: true, get: function () { return decorators_1.OnSSEConnection; } });
+Object.defineProperty(exports, "OnSSEError", { enumerable: true, get: function () { return decorators_1.OnSSEError; } });

package/dist/sse/server.d.ts

@@ -0,0 +1,14 @@
+import { ControllerType, ISSEServer, SSEClient, SSEMessage } from '../types/index.js';
+import { ServerResponse } from 'http';
+export declare class SSEServer implements ISSEServer {
+    private clients;
+    controllers: any[];
+    createConnection(res: ServerResponse): SSEClient;
+    sendToClient(clientId: string, message: SSEMessage): boolean;
+    broadcast(message: SSEMessage, excludeClientId?: string): void;
+    getStats(): {
+        clients: number;
+    };
+    registerControllers(controllers: ControllerType[]): void;
+    private triggerHandlers;
+}

package/dist/sse/server.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SSEServer = void 0;
+const uuid_1 = require("uuid");
+class SSEServer {
+    clients = new Map();
+    controllers;
+    createConnection(res) {
+        const clientId = (0, uuid_1.v4)();
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive',
+            'Access-Control-Allow-Origin': '*',
+        });
+        res.write(': connected\n\n');
+        const client = {
+            id: clientId,
+            response: res,
+            topics: new Set(),
+            data: {},
+            connectedAt: new Date(),
+        };
+        this.clients.set(clientId, client);
+        this.triggerHandlers('connection', {
+            type: 'connection',
+            client,
+            data: res,
+        });
+        res.on('close', () => {
+            this.clients.delete(clientId);
+            this.triggerHandlers('close', { type: 'close', client });
+        });
+        return client;
+    }
+    sendToClient(clientId, message) {
+        const client = this.clients.get(clientId);
+        if (!client)
+            return false;
+        try {
+            let sseMessage = '';
+            if (message.event)
+                sseMessage += `event: ${message.event}\n`;
+            if (message.id)
+                sseMessage += `id: ${message.id}\n`;
+            if (message.retry)
+                sseMessage += `retry: ${message.retry}\n`;
+            const dataStr = typeof message.data === 'string' ? message.data : JSON.stringify(message.data);
+            dataStr.split('\n').forEach((line) => {
+                sseMessage += `data: ${line}\n`;
+            });
+            sseMessage += '\n';
+            client.response.write(sseMessage);
+            return true;
+        }
+        catch (error) {
+            console.error(`SSE send error to ${clientId}:`, error);
+            return false;
+        }
+    }
+    broadcast(message, excludeClientId) {
+        this.clients.forEach((_, clientId) => {
+            if (clientId !== excludeClientId) {
+                this.sendToClient(clientId, message);
+            }
+        });
+    }
+    getStats() {
+        return { clients: this.clients.size };
+    }
+    registerControllers(controllers) {
+        this.controllers = controllers.filter((c) => c.sse);
+    }
+    async triggerHandlers(eventType, event) {
+        for (const controller of this.controllers) {
+            if (controller.sse.handlers && controller.sse.handlers[eventType]) {
+                for (const handler of controller.sse.handlers[eventType]) {
+                    console.log(handler);
+                    await handler.fn(event).catch(console.log);
+                }
+            }
+        }
+    }
+}
+exports.SSEServer = SSEServer;

package/dist/sse/service.d.ts

@@ -0,0 +1,17 @@
+import { ISSEService, SSEClient, SSEMessage } from '../types/index.js';
+import { ServerResponse } from 'http';
+import { SSEServer } from './server';
+export declare class SSEService implements ISSEService {
+    private static instance;
+    private sse;
+    private constructor();
+    static getInstance(): SSEService;
+    initialize(sse: SSEServer): void;
+    sendToClient(clientId: string, message: SSEMessage): boolean;
+    broadcast(message: SSEMessage, excludeClientId?: string): void;
+    getStats(): {
+        clients: number;
+    };
+    isAvailable(): boolean;
+    createConnection(res: ServerResponse): SSEClient;
+}

package/dist/sse/service.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SSEService = void 0;
+class SSEService {
+    static instance;
+    sse = null;
+    constructor() { }
+    static getInstance() {
+        if (!SSEService.instance) {
+            SSEService.instance = new SSEService();
+        }
+        return SSEService.instance;
+    }
+    initialize(sse) {
+        this.sse = sse;
+    }
+    sendToClient(clientId, message) {
+        if (!this.sse)
+            return false;
+        return this.sse.sendToClient(clientId, message);
+    }
+    broadcast(message, excludeClientId) {
+        if (!this.sse)
+            return;
+        this.sse.broadcast(message, excludeClientId);
+    }
+    getStats() {
+        if (!this.sse)
+            return { clients: 0 };
+        return this.sse.getStats();
+    }
+    isAvailable() {
+        return this.sse !== null;
+    }
+    createConnection(res) {
+        return this.sse.createConnection(res);
+    }
+}
+exports.SSEService = SSEService;

package/dist/types/common.d.ts

@@ -41,7 +41,7 @@ export interface IController {
 export type MiddlewareCB = (request: AppRequest, response: ServerResponse, next: (args?: any) => any) => void | Promise<AppRequest> | AppRequest;
 export type InterceptorCB = (data: any, req?: AppRequest, res?: ServerResponse) => Promise<unknown> | unknown;
 export type ErrorCB = (error: HttpError, req?: AppRequest, res?: ServerResponse) => Promise<ResponseWithStatus> | ResponseWithStatus;
-export type ParamDecoratorType = 'body' | 'params' | 'query' | 'request' | 'headers' | 'cookies' | 'response' | 'multipart' | 'event' | 'context';
+export type ParamDecoratorType = 'body' | 'params' | 'query' | 'request' | 'headers' | 'cookies' | 'response' | 'multipart' | 'event' | 'context' | 'sse' | 'ws';
 export interface ParamMetadata {
     index: number;
     type: ParamDecoratorType;

package/dist/types/controller.d.ts

@@ -1,21 +1,28 @@
-import { ErrorCB, HTTP_METHODS, InterceptorCB, MiddlewareCB } from './common';
+import { ServerResponse } from 'http';
+import { AppRequest, ErrorCB, HTTP_METHODS, InterceptorCB, MiddlewareCB } from './common';
 import { CORSConfig } from './cors';
 import { SanitizerConfig } from './sanitize';
 export type ControllerClass = {
     new (...args: any[]): any;
 };
-export type ControllerInstance = InstanceType<ControllerClass>;
 export type ControllerMethods = Array<{
     name: string;
     httpMethod: HTTP_METHODS;
     pattern: string;
     middlewares?: MiddlewareCB[];
 }>;
+export type ControllerType = {
+    handleRequest?(request: AppRequest, response: ServerResponse): Promise<any>;
+    ws?: WsControllerHandlers;
+    sse?: SeeControllerHandlers;
+    new (...args: any[]): any;
+};
+export type ControllerInstance = InstanceType<ControllerType>;
 export type ControllerMetadata = {
     routePrefix: string;
     middlewares: MiddlewareCB[];
     interceptor?: InterceptorCB;
-    subControllers: ControllerClass[];
+    subControllers: ControllerInstance[];
     errorHandler?: ErrorCB;
     cors?: CORSConfig;
     sanitizers: SanitizerConfig[];
@@ -23,7 +30,7 @@ export type ControllerMetadata = {
 export interface ControllerConfig {
     prefix: string;
     middlewares?: Array<MiddlewareCB>;
-    controllers?: ControllerClass[];
+    controllers?: ControllerInstance[];
     interceptor?: InterceptorCB;
 }
 export type RouteContext = {
@@ -38,3 +45,32 @@ export type RouteContext = {
     subPath: string;
     sanitizersChain: SanitizerConfig[];
 };
+export type SSE_HANDLER_META = {
+    type: string;
+    method: string;
+};
+export type HandlerMeta = {
+    type: 'connection';
+    topic: undefined;
+    method: 'onconnect';
+    fn: (...args: any[]) => any;
+};
+export type WsHandlerMeta = HandlerMeta & {
+    topic?: string;
+};
+export type WsControllerHandlers = {
+    handlers: {
+        connection: WsHandlerMeta[];
+        message: WsHandlerMeta[];
+        close: WsHandlerMeta[];
+        error: WsHandlerMeta[];
+    };
+    topics: HandlerMeta[];
+};
+export type SeeControllerHandlers = {
+    handlers: {
+        connection: HandlerMeta[];
+        close: HandlerMeta[];
+        error: HandlerMeta[];
+    };
+};

package/dist/types/http.d.ts

@@ -15,4 +15,7 @@ export interface ServerConfig {
         path?: string;
         lazy?: boolean;
     };
+    sse?: {
+        enabled: boolean;
+    };
 }

package/dist/types/index.d.ts

@@ -5,4 +5,5 @@ export * from './http';
 export * from './lambda';
 export * from './multipart';
 export * from './sanitize';
+export * from './sse';
 export * from './websocket';

package/dist/types/index.js

@@ -21,4 +21,5 @@ __exportStar(require("./http"), exports);
 __exportStar(require("./lambda"), exports);
 __exportStar(require("./multipart"), exports);
 __exportStar(require("./sanitize"), exports);
+__exportStar(require("./sse"), exports);
 __exportStar(require("./websocket"), exports);

package/dist/types/sse.d.ts

@@ -0,0 +1,37 @@
+import { ServerResponse } from 'http';
+export interface SSEClient {
+    id: string;
+    response: ServerResponse;
+    topics: Set<string>;
+    data: Record<string, any>;
+    connectedAt: Date;
+}
+export interface SSEMessage {
+    event?: string;
+    id?: string;
+    retry?: number;
+    data: any;
+}
+export interface SSEEvent {
+    type: 'connection' | 'close';
+    client: SSEClient;
+    data?: any;
+}
+export interface ISSEServer {
+    createConnection(res: ServerResponse): SSEClient;
+    sendToClient(clientId: string, message: SSEMessage): boolean;
+    broadcast(message: SSEMessage, excludeClientId?: string): void;
+    getStats(): {
+        clients: number;
+    };
+}
+export interface ISSEService {
+    initialize(sse: ISSEServer): void;
+    sendToClient(clientId: string, message: SSEMessage): boolean;
+    broadcast(message: SSEMessage, excludeClientId?: string): void;
+    getStats(): {
+        clients: number;
+    };
+    isAvailable(): boolean;
+    createConnection(res: ServerResponse): SSEClient;
+}

package/dist/types/sse.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/websocket.d.ts

@@ -46,4 +46,5 @@ export interface IWebSocketServer {
     getStats(): WebSocketStats;
     subscribeToTopic(client: WebSocketClient, topic: string): void;
     unsubscribeFromTopic(client: WebSocketClient, topic: string): void;
+    registerControllers(controllers: any[]): void;
 }

package/dist/utils/controller.d.ts

@@ -21,7 +21,7 @@ export declare const getResponse: (data: {
 }) => Promise<{
     status: number;
     data: any;
-}>;
+} | undefined>;
 export declare const applyMiddlewaresVsSanitizers: (request: AppRequest, response: ServerResponse, functions: {
     sanitizers: SanitizerConfig[][];
     middlewares: MiddlewareCB[][];

package/dist/utils/controller.js

@@ -3,7 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyMiddlewaresVsSanitizers = exports.getResponse = exports.NextFN = exports.findRouteInController = exports.getAllMethods = exports.getControllerMethods = exports.executeControllerMethod = void 0;
 const _constants_1 = require("../constants.js");
 const _types_1 = require("../types/index.js");
-const WebsocketService_1 = require("../app/http/websocket/WebsocketService");
+const service_1 = require("../sse/service");
+const service_2 = require("../ws/service");
 const helper_1 = require("./helper");
 const multipart_1 = require("./multipart");
 const sanitize_1 = require("./sanitize");
@@ -41,19 +42,14 @@ const executeControllerMethod = async (controller, propertyName, request, respon
     }
     const prototype = Object.getPrototypeOf(controller);
     const paramMetadata = Reflect.getMetadata(_constants_1.PARAM_METADATA_KEY, prototype, propertyName) || [];
+    const sse = Reflect.getMetadata(_constants_1.SSE_METADATA_KEY, prototype, propertyName) || [];
     if (paramMetadata.length === 0) {
         return fn.call(controller, request, response);
     }
     const { body, multipart } = getBodyAndMultipart(request);
     const args = [];
-    const wsParams = Reflect.getMetadata(_constants_1.WS_SERVICE_KEY, controller, propertyName) || [];
-    const totalParams = Math.max(paramMetadata.length ? Math.max(...paramMetadata.map((p) => p.index)) + 1 : 0, wsParams.length ? Math.max(...wsParams.map((p) => p.index)) + 1 : 0);
+    const totalParams = Math.max(paramMetadata.length ? Math.max(...paramMetadata.map((p) => p.index)) + 1 : 0);
     for (let i = 0; i < totalParams; i++) {
-        const wsParam = wsParams.find((p) => p.index === i);
-        if (wsParam) {
-            args[i] = WebsocketService_1.WebSocketService.getInstance();
-            continue;
-        }
         const param = paramMetadata.find((p) => p.index === i);
         if (!param) {
             args[i] = undefined;
@@ -65,6 +61,12 @@ const executeControllerMethod = async (controller, propertyName, request, respon
         if (param.type === 'multipart') {
             value = multipart;
         }
+        if (param.type === 'ws') {
+            value = service_2.WebSocketService.getInstance();
+        }
+        if (param.type === 'sse') {
+            value = service_1.SSEService.getInstance();
+        }
         if (param.type === 'request') {
             value = request;
         }
@@ -173,6 +175,9 @@ exports.NextFN = NextFN;
 const getResponse = async (data) => {
     try {
         let appResponse = await (0, exports.executeControllerMethod)(data.controllerInstance, data.name, data.request, data.response);
+        if (!appResponse) {
+            return;
+        }
         data.response.statusCode = appResponse.status ?? 200;
         const isError = !_constants_1.OK_STATUSES.includes(data.response.statusCode);
         const interceptors = data.interceptors.reverse();

package/dist/ws/decorators.d.ts

@@ -30,4 +30,4 @@ export declare function Subscribe(topic: string): (target: any, propertyKey: str
 /**
  * Parameter decorator to inject WebSocket service instance.
  */
-export declare function InjectWS(): (target: any, propertyKey: string, parameterIndex: number) => void;
+export declare function InjectWS(): (target: any, propertyKey: string | symbol, parameterIndex: number) => void;

package/dist/ws/decorators.js

@@ -8,6 +8,7 @@ exports.OnError = OnError;
 exports.Subscribe = Subscribe;
 exports.InjectWS = InjectWS;
 const _constants_1 = require("../constants.js");
+const _utils_1 = require("../utils/index.js");
 /**
  * Method decorator to handle WebSocket events.
  * @param type Type of WebSocket event (connection, message, close, error).
@@ -62,9 +63,5 @@ function Subscribe(topic) {
  * Parameter decorator to inject WebSocket service instance.
  */
 function InjectWS() {
-    return function (target, propertyKey, parameterIndex) {
-        const existingParams = Reflect.getMetadata(_constants_1.WS_SERVICE_KEY, target, propertyKey) || [];
-        existingParams.push({ index: parameterIndex });
-        Reflect.defineMetadata(_constants_1.WS_SERVICE_KEY, existingParams, target, propertyKey);
-    };
+    return (0, _utils_1.createParamDecorator)('ws');
 }

package/dist/ws/index.d.ts

@@ -1,2 +1,3 @@
 export { IWebSocketService, WebSocketClient, WebSocketEvent, WebSocketMessage, WebSocketStats, } from '../types/index.js';
 export * from './decorators';
+export * from './service';

package/dist/ws/index.js

@@ -15,3 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./decorators"), exports);
+__exportStar(require("./service"), exports);

package/dist/{app/http/websocket/WebsocketServer.d.ts → ws/server.d.ts}

@@ -1,6 +1,6 @@
-import { WebSocketClient } from '../../../types/index.js';
+import { ControllerType, IWebSocketServer, WebSocketClient } from '../types/index.js';
 import http from 'http';
-export declare class WebSocketServer {
+export declare class WebSocketServer implements IWebSocketServer {
     private wss;
     private clients;
     private topics;
@@ -15,7 +15,7 @@ export declare class WebSocketServer {
     private handleClose;
     private handleError;
     private triggerHandlers;
-    registerControllers(controllers: any[]): void;
+    registerControllers(controllers: ControllerType[]): void;
     subscribeToTopic(client: WebSocketClient, topic: string): void;
     unsubscribeFromTopic(client: WebSocketClient, topic: string): void;
     publishToTopic(topic: string, data: any, exclude?: string[]): void;

package/dist/{app/http/websocket/WebsocketServer.js → ws/server.js}

@@ -89,6 +89,7 @@ class WebSocketServer {
             });
         }
         catch (error) {
+            console.log(error);
             client.socket.send(JSON.stringify({
                 type: 'error',
                 data: { message: 'Invalid message format' },
@@ -120,7 +121,7 @@ class WebSocketServer {
     }
     async triggerHandlers(eventType, event, topic) {
         for (const controller of this.controllers) {
-            const controllerHandlers = controller.handlers?.[eventType] ?? [];
+            const controllerHandlers = controller.ws?.handlers?.[eventType] ?? [];
             const matchingHandlers = controllerHandlers.filter((h) => {
                 if (h.type !== eventType)
                     return false;
@@ -137,7 +138,7 @@ class WebSocketServer {
                 }
             }
             if (eventType === 'message' && topic) {
-                const matchingSubs = controller.topics.filter((s) => s.topic === topic);
+                const matchingSubs = controller.ws?.topics.filter((s) => s.topic === topic) ?? [];
                 for (const sub of matchingSubs) {
                     try {
                         await sub.fn(event);
@@ -150,12 +151,7 @@ class WebSocketServer {
         }
     }
     registerControllers(controllers) {
-        this.controllers = controllers.map((controller) => {
-            if (controller.getWebSocketController) {
-                return controller.getWebSocketController();
-            }
-            return controller;
-        });
+        this.controllers = controllers.filter((c) => !!c.ws);
     }
     subscribeToTopic(client, topic) {
         if (!this.topics.has(topic)) {
@@ -163,11 +159,7 @@ class WebSocketServer {
         }
         this.topics.get(topic).add(client.id);
         client.topics.add(topic);
-        client.socket.send(JSON.stringify({
-            type: 'subscribed',
-            topic,
-            data: { success: true },
-        }));
+        client.socket.send(JSON.stringify({ type: 'subscribed', topic, data: { success: true } }));
     }
     unsubscribeFromTopic(client, topic) {
         const topicClients = this.topics.get(topic);

package/dist/{app/http/websocket/WebsocketService.d.ts → ws/service.d.ts}

@@ -1,5 +1,5 @@
-import { IWebSocketService } from '../../../types/index.js';
-import { WebSocketServer } from './WebsocketServer';
+import { IWebSocketService } from '../types/index.js';
+import { WebSocketServer } from './server';
 export declare class WebSocketService implements IWebSocketService {
     private static instance;
     private wss;

package/dist/{app/http/Socket.d.ts → ws/socket.d.ts}

@@ -1,4 +1,4 @@
-import { WebSocketServer } from './websocket/WebsocketServer';
+import { WebSocketServer } from './server';
 export declare class Socket {
     protected wss: WebSocketServer;
     registerWebSocketControllers(controllers: any[]): this;

package/dist/{app/http/Socket.js → ws/socket.js}

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Socket = void 0;
-const WebsocketService_1 = require("./websocket/WebsocketService");
+const service_1 = require("./service");
 class Socket {
     wss;
     registerWebSocketControllers(controllers) {
@@ -14,19 +14,19 @@ class Socket {
         return this;
     }
     sendToClient(clientId, message) {
-        return WebsocketService_1.WebSocketService.getInstance().sendToClient(clientId, message);
+        return service_1.WebSocketService.getInstance().sendToClient(clientId, message);
     }
     publishToTopic(topic, data) {
-        WebsocketService_1.WebSocketService.getInstance().publishToTopic(topic, data);
+        service_1.WebSocketService.getInstance().publishToTopic(topic, data);
     }
     broadcast(message, excludeClientId) {
-        WebsocketService_1.WebSocketService.getInstance().broadcast(message, excludeClientId);
+        service_1.WebSocketService.getInstance().broadcast(message, excludeClientId);
     }
     getWebSocketStats() {
-        return WebsocketService_1.WebSocketService.getInstance().getStats();
+        return service_1.WebSocketService.getInstance().getStats();
     }
     isWebSocketAvailable() {
-        return WebsocketService_1.WebSocketService.getInstance().isAvailable();
+        return service_1.WebSocketService.getInstance().isAvailable();
     }
 }
 exports.Socket = Socket;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quantum-flow",
-  "version": "1.8.1",
+  "version": "1.10.0",
   "description": "Decorator-based API framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -40,6 +40,11 @@
       "import": "./dist/ws/index.js",
       "require": "./dist/ws/index.js",
       "types": "./dist/ws/index.d.ts"
+    },
+    "./sse": {
+      "import": "./dist/sse/index.js",
+      "require": "./dist/sse/index.js",
+      "types": "./dist/sse/index.d.ts"
     }
   },
   "repository": {