quantum-flow 1.8.0 → 1.10.0

package/README.md

@@ -21,6 +21,8 @@ You can use controllers and server functionality by importing controllers and cr
 - `quantum-flow/aws` - Main application source code AWS Lambda.
 - `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.
 
 ---
 
@@ -33,7 +35,6 @@ import {
   Body,
   Controller,
   Headers,
-  InjectWS,
   IWebSocketService,
   Params,
   PUT,
@@ -45,6 +46,7 @@ import {
 } from 'quantum-flow/core';
 import {IsString} from  'class-validator'
 import { Catch, Cors, Sanitize, Use } from 'quantum-flow/middlewares';
+import { InjectWS } from 'quantum-flow/ws';
 
 class UserDto {
   constructor() {}
@@ -137,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
 
@@ -167,18 +170,26 @@ 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')
 export class Socket {
   @OnConnection()
   onConnection(event: WebSocketEvent) {
     // Send greeting ONLY to this client
-    event.client.socket.send(
-      JSON.stringify({
-        type: 'welcome',
-        data: { message: 'Welcome!' },
-      }),
-    );
+    event.client.socket.send(JSON.stringify({ type: 'welcome', data: { message: 'Welcome!' } }));
   }
 
   /**
@@ -200,14 +211,6 @@ export class Socket {
     // That's it, the message will be sent to subscribers automatically!
   }
 
-  /**
-   * 3. @Subscribe for another room
-   */
-  @Subscribe('news')
-  onNewsMessage(event: WebSocketEvent) {
-    // Automatic broadcast to all subscribed to 'news'
-  }
-
   /**
    * 4. @OnMessage for commands (without WebSocketService)
    */
@@ -242,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.
 
-### Use
+## Defining SSE Controllers
 
-Class decorator to add global middlewares to the server.
-Should be used only with @Server decorator
+Use the `@Controller` decorator to define controllers with a `prefix` and optionally include sub-controllers. This allows modular organization of your API endpoints.
+
+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
 
-Class decorator to set a global error handler for the server.
+Use the `@InjectSSE` decorator in your controller methods to create and manage SSE connections. This service allows sending events to connected clients.
+
+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
+
+The framework provides decorators to handle SSE connection lifecycle events:
 
-Class decorator to set the server port.
+- `@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
+
+Use the injected SSE service to send events to clients. You can send events to all clients or specific clients by ID.
 
-Class decorator to set the server host.
+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/core/{utils/extractors.js → decorators.js}

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Response = exports.Multipart = exports.Cookies = exports.Headers = exports.Request = exports.Query = exports.Params = exports.Body = void 0;
-const _utils_1 = require("../../utils/index.js");
+const _utils_1 = require("../utils/index.js");
 /**
  * Parameter decorator to extract and validate the request body.
  * @param dto Optional DTO class for validation and transformation.

package/dist/core/index.d.ts

@@ -6,5 +6,5 @@
  */
 export { AppRequest, CORSConfig, EndpointResponse, ErrorCB, HttpError, IController, InterceptorCB, IWebSocketService, MiddlewareCB, MultipartFile, ResponseWithStatus, WebSocketClient, WebSocketEvent, WebSocketMessage, } from '../types/index.js';
 export * from './Controller';
+export * from './decorators';
 export * from './Endpoint';
-export * from './utils';

package/dist/core/index.js

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

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;
+}