quantum-flow 1.0.1 → 1.0.5

package/README.md

@@ -1,37 +1,265 @@
-# Your Package Name
+# Project Overview
 
-Description of your package.
+This project is a decorator-based API framework supporting both HTTP and WebSocket servers. It is designed to simplify the creation of scalable and maintainable APIs with features such as controllers, middlewares, interceptors, error handling, and WebSocket support. Additionally, it supports AWS Lambda integration for serverless deployments.
 
-## Installation
+# Installation
+
+To install dependencies and build the project, run:
 
 ```bash
-npm install your-package-name
+yarn install
+# or npm install
+
+yarn build
+# or npm run build
 ```
 
-## Usage
+# Usage
+
+## Defining Controllers
+
+Use the `@Controller` decorator to define controllers with options such as prefix, sub-controllers, middlewares, and interceptors.
 
 ```typescript
-import { greet } from 'your-package-name';
+import { Controller } from 'quantum-flow/core';
 
-console.log(greet('World'));
+@Controller({
+  prefix: 'api',
+  controllers: [UserController, SocketController],
+  interceptors: [(resp) => resp],
+})
+class RootController {}
 ```
 
-## Build
+## Creating a Server
 
-To build the package, run:
+Use the `@Server` decorator with configuration options like port, host, controllers, and WebSocket enablement.
 
-```bash
-npm run build
+```typescript
+import { Server, Port, Host, Use, Intercept, Catch, HttpServer } from 'quantum-flow/http';
+
+@Server({
+  controllers: [RootController],
+})
+@Port(3000)
+@Host('localhost')
+@Use((res: any) => res)
+@Intercept((data, req, res) => data)
+@Catch((error) => error)
+class App {}
+
+const server = new HttpServer(App);
+
+server.listen().catch(console.error);
 ```
 
-## Test
+## Middlewares, Interceptors, and Error Handlers
 
-To run tests, run:
+- Use `@Use` to apply middlewares.
+- Use `@Intercept` to apply interceptors.
+- Use `@Catch` to handle errors.
+- Use `@Port` and `@Host` to configure server port and host.
 
-```bash
-npm run test
+## Request decorators
+
+- Use `@Body` to handle request bodies.
+- Use `@Headers` to access request headers.
+- Use `@Query` to handle query parameters.
+- Use `@Params` to access route parameters.
+- Use `@Host` to configure the server host.
+- Use `@Port` to configure the server port.
+- Use `@Multipart` for handling multipart/form-data requests.
+- Use `@Request` to access the entire request object.
+- Use `@Response` to access the response object.
+
+# AWS Lambda Support
+
+Use `LambdaAdapter` to convert API Gateway events to requests and responses. Create Lambda handlers from controllers.
+
+```typescript
+Example Lambda handler creation
+import { LambdaAdapter } from 'quantum-flow/aws';
+export const handler = LambdaAdapter.createHandler(RootController);
+```
+
+# WebSocket Support
+
+Enable WebSocket in the server configuration and register WebSocket controllers.
+
+```typescript
+@Controller('socket')
+export class Socket {
+  @OnConnection()
+  onConnection(event: WebSocketEvent) {
+    console.log(`✅ Connected: ${event.client.id}`);
+
+    // Send greeting ONLY to this client
+    event.client.socket.send(
+      JSON.stringify({
+        type: 'welcome',
+        data: { message: 'Welcome!' },
+      }),
+    );
+  }
+
+  /**
+   * 2. @Subscribe - AUTOMATIC broadcast to all subscribers
+   * No need to use WebSocketService!
+   */
+  @Subscribe('chat')
+  onChatMessage(event: WebSocketEvent) {
+    // This method is called for EACH subscriber
+    // The message is ALREADY automatically broadcast to all!
+
+    const msg = event.message?.data;
+    console.log(`💬 Message in chat: ${msg?.text}`);
+
+    // You can add logic, but no need to broadcast
+    if (msg?.text.includes('bad')) {
+      // If return empty, the message will not be sent
+      return;
+    }
+
+    // That's it, the message will be sent to subscribers automatically!
+  }
+
+  /**
+   * 3. @Subscribe for another room
+   */
+  @Subscribe('news')
+  onNewsMessage(event: WebSocketEvent) {
+    console.log(`📰 News: ${event.message?.data.title}`);
+    // Automatic broadcast to all subscribed to 'news'
+  }
+
+  /**
+   * 4. @OnMessage for commands (without WebSocketService)
+   */
+  @OnMessage('ping')
+  onPing(event: WebSocketEvent) {
+    // Send response only to this client
+    event.client.socket.send(
+      JSON.stringify({
+        type: 'pong',
+        data: { time: Date.now() },
+      }),
+    );
+  }
+
+  /**
+   * 5. @OnMessage for subscription
+   */
+  @OnMessage('subscribe')
+  onSubscribe(event: WebSocketEvent) {
+    const topic = event.message?.data.topic;
+    console.log(`📌 Client ${event.client.id} subscribed to ${topic}`);
+
+    // Server will save the subscription automatically, no need to do anything!
+    // Just confirm
+    event.client.socket.send(
+      JSON.stringify({
+        type: 'subscribed',
+        topic,
+        data: { success: true },
+      }),
+    );
+  }
+}
+@Server({
+  controllers: [Socket],
+  websocket: { enabled: true },
+})
+@Use(middleware)
+class App {}
+```
+
+# Usage
+
+You can use controllers and server functionality by importing controllers and creating server instances as shown in the examples above. Use your preferred testing framework to write unit and integration tests.
+
+# Project Structure
+
+- `quantum-flow/http` - Main application source code for HTTP servers.
+- `quantum-flow/aws` - Main application source code AWS Lambda.
+- `quantum-flow/core` - Core framework components like Controller and Endpoint.
+
+---
+
+# Decorators
+
+### Server
+
+Class decorator to configure the server with options like controllers, global middlewares, and interceptors.
+
+```typescript
+@Server({ controllers: [RootController] })
+class App {}
+```
+
+### Use
+
+Class decorator to add global middlewares to the server.
+
+```typescript
+@Use(middleware)
+class App {}
 ```
 
-## License
+### Intercept
+
+Class decorator to add global interceptors to the server.
+
+```typescript
+@Intercept(interceptor)
+class App {}
+```
 
-MIT
+### Catch
+
+Class decorator to set a global error handler for the server.
+
+```typescript
+@Catch((error) => {
+  return { message: 'Internal Server Error' };
+})
+class App {}
+```
+
+### Port
+
+Class decorator to set the server port.
+
+```typescript
+@Port(3000)
+class App {}
+```
+
+### Host
+
+Class decorator to set the server host.
+
+```typescript
+@Host('localhost')
+class App {}
+```
+
+### Validate
+
+Method or class decorator to validate request parameters (query, body, params, headers) against a DTO class using class-validator.
+
+```typescript
+class UserDTO {
+  @IsEmail()
+  email: string;
+
+  @Length(6, 20)
+  password: string;
+}
+
+class UserController {
+  @POST('/')
+  async createUser(@Body(UserDTO) user: UserDTO, @Query() query) {
+    // Your logic here
+  }
+}
+```

package/dist/app/aws/lambda.d.ts

@@ -1,5 +1,5 @@
 import { APIGatewayProxyEvent, APIGatewayProxyResult, Context, Handler } from 'aws-lambda';
-import { LambdaRequest, LambdaResponse } from '@types';
+import { LambdaRequest, LambdaResponse } from '../../types/index.js';
 export declare class LambdaAdapter {
     private static getHeaderValue;
     static toRequest(event: APIGatewayProxyEvent, context: Context): LambdaRequest;

package/dist/app/aws/lambda.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LambdaAdapter = void 0;
-const _constants_1 = require("@constants");
-const _utils_1 = require("@utils");
+const _constants_1 = require("../../constants.js");
+const _utils_1 = require("../../utils/index.js");
 class LambdaAdapter {
     static getHeaderValue(headers, headerName) {
         const value = headers?.[headerName] || headers?.[headerName.toLowerCase()];

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

@@ -1,4 +1,4 @@
-import { ServerConfig } from '@types';
+import { ServerConfig } from '../../types/index.js';
 import http from 'http';
 import { Socket } from './Socket';
 export declare class HttpServer extends Socket {

package/dist/app/http/Application.js

@@ -4,8 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpServer = void 0;
-const _constants_1 = require("@constants");
-const _utils_1 = require("@utils");
+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 WebsocetService_1 = require("./websocket/WebsocetService");

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

@@ -1,4 +1,4 @@
-import { Conf, Interceptor } from '@types';
+import { Conf, Interceptor } from '../../types/index.js';
 export declare function Server(config?: Conf): (target: any) => any;
 export declare function Use(middleware: any): (target: any) => any;
 export declare function Intercept(interceptor: Interceptor): (target: any) => any;

package/dist/app/http/decorators.js

@@ -6,7 +6,7 @@ exports.Intercept = Intercept;
 exports.Catch = Catch;
 exports.Port = Port;
 exports.Host = Host;
-const _constants_1 = require("@constants");
+const _constants_1 = require("../../constants.js");
 function Server(config = {}) {
     return function (target) {
         const existingConfig = Reflect.getMetadata(_constants_1.SERVER_CONFIG_KEY, target) || {};

package/dist/app/http/websocket/WebsocetService.d.ts

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

package/dist/app/http/websocket/WebsocketServer.d.ts

@@ -1,4 +1,4 @@
-import { WebSocketClient } from '@types';
+import { WebSocketClient } from '../../../types/index.js';
 import http from 'http';
 export declare class WebSocketServer {
     private wss;

package/dist/core/Controller.d.ts

@@ -1,4 +1,4 @@
-import { Interceptor, Middleware } from '@types';
+import { Interceptor, Middleware } from '../types/index.js';
 import { ServerResponse } from 'http';
 import 'reflect-metadata';
 type ControllerClass = {
@@ -11,11 +11,32 @@ interface ControllerConfig {
     controllers?: ControllerClass[];
     interceptors?: Array<(...args: any[]) => any> | ((...args: any[]) => any);
 }
+/**
+ * Class decorator to define a controller with optional configuration.
+ *
+ * This decorator can be used with a string prefix or a configuration object.
+ * It sets up metadata for route prefix, middlewares, sub-controllers, and interceptors.
+ *
+ * It wraps all controller methods to handle errors gracefully by catching exceptions
+ * and returning a standardized error response.
+ *
+ * The decorated controller class is extended with methods to:
+ * - execute controller methods with proper context and error handling
+ * - retrieve controller methods metadata
+ * - handle incoming requests by matching routes, applying middlewares and interceptors,
+ *   and returning appropriate responses
+ *
+ * @param config - Either a string representing the route prefix or a configuration object
+ *                 containing prefix, middlewares, sub-controllers, and interceptors.
+ * @param middlewares - Additional interceptors to apply at the controller level.
+ *
+ * @returns A class decorator function that enhances the controller class.
+ */
 export declare function Controller(config: string | ControllerConfig, middlewares?: Array<Interceptor>): <T extends ControllerClass>(constructor: T) => {
     new (...args: any[]): {
         [x: string]: any;
-        executeControllerMethod: (controller: import("@types").ControllerInstance, propertyName: string, payload: any, response?: ServerResponse) => Promise<any>;
-        getControllerMethods: (controller: import("@types").ControllerInstance) => {
+        executeControllerMethod: (controller: import("../types/index.js").ControllerInstance, propertyName: string, payload: any, response?: ServerResponse) => Promise<any>;
+        getControllerMethods: (controller: import("../types/index.js").ControllerInstance) => {
             name: string;
             httpMethod: string;
             pattern: string;

package/dist/core/Controller.js

@@ -2,9 +2,30 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Controller = Controller;
 /* eslint-disable @typescript-eslint/no-explicit-any */
-const _constants_1 = require("@constants");
-const _utils_1 = require("@utils");
+const _constants_1 = require("../constants.js");
+const _utils_1 = require("../utils/index.js");
 require("reflect-metadata");
+/**
+ * Class decorator to define a controller with optional configuration.
+ *
+ * This decorator can be used with a string prefix or a configuration object.
+ * It sets up metadata for route prefix, middlewares, sub-controllers, and interceptors.
+ *
+ * It wraps all controller methods to handle errors gracefully by catching exceptions
+ * and returning a standardized error response.
+ *
+ * The decorated controller class is extended with methods to:
+ * - execute controller methods with proper context and error handling
+ * - retrieve controller methods metadata
+ * - handle incoming requests by matching routes, applying middlewares and interceptors,
+ *   and returning appropriate responses
+ *
+ * @param config - Either a string representing the route prefix or a configuration object
+ *                 containing prefix, middlewares, sub-controllers, and interceptors.
+ * @param middlewares - Additional interceptors to apply at the controller level.
+ *
+ * @returns A class decorator function that enhances the controller class.
+ */
 function Controller(config, middlewares = []) {
     // Handle both string and config object
     const routePrefix = typeof config === 'string' ? config : config.prefix;
@@ -78,7 +99,7 @@ function Controller(config, middlewares = []) {
             }
             handleRequest = async (request, response) => {
                 const method = request.method;
-                const path = (request.url.path ?? request.url.pathname ?? '').replace(/^\/+/, '');
+                const path = (request.url.path ?? request.url.pathname ?? '').replace(/^\/+/g, '');
                 const baseInterceptors = Reflect.getMetadata(_constants_1.INTERCEPTORS, proto);
                 const routePrefix = Reflect.getMetadata(_constants_1.ROUTE_PREFIX, proto) || '';
                 const middlewares = Reflect.getMetadata(_constants_1.MIDDLEWARES, proto) || [];
@@ -98,7 +119,7 @@ function Controller(config, middlewares = []) {
                             const fullPattern = [routePrefix, controllerPrefix, methodInfo.pattern]
                                 .filter(Boolean)
                                 .join('/')
-                                .replace(/\/+/g, '/');
+                                .replace(/\/+ /g, '/');
                             const pathParams = (0, _utils_1.matchRoute)(fullPattern, path);
                             if (pathParams) {
                                 let payload = { ...request, params: pathParams };
@@ -133,7 +154,7 @@ function Controller(config, middlewares = []) {
                         const fullPattern = [routePrefix, routePattern]
                             .filter(Boolean)
                             .join('/')
-                            .replace(/\/+/g, '/');
+                            .replace(/\/+ /g, '/');
                         const pathParams = (0, _utils_1.matchRoute)(fullPattern, path);
                         if (pathParams) {
                             let payload = { ...request, params: pathParams };

package/dist/core/Endpoint.d.ts

@@ -1,8 +1,64 @@
-import { Middleware } from '@types';
+import { Middleware } from '../types/index.js';
+/**
+ * Method decorator to define HTTP method and route pattern metadata on controller methods.
+ *
+ * This decorator maps a controller method to an HTTP endpoint by specifying the HTTP method
+ * (e.g., GET, POST) and an optional route pattern.
+ *
+ * It also allows attaching middlewares that will be applied when the endpoint is accessed.
+ *
+ * @param method - The HTTP method (e.g., 'GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'USE').
+ * @param pathPattern - Optional route pattern string to match the endpoint path.
+ * @param middlewares - Optional array of middlewares to apply to this endpoint.
+ *
+ * @returns A method decorator function.
+ */
 export declare function Endpoint(method: string, pathPattern?: string, middlewares?: Middleware[]): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
-export declare const GET: (pathPattern?: string, middelwares?: Middleware[]) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
-export declare const POST: (pathPattern?: string, middelwares?: Middleware[]) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
-export declare const PUT: (pathPattern?: string, middelwares?: Middleware[]) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
-export declare const PATCH: (pathPattern?: string, middelwares?: Middleware[]) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
-export declare const DELETE: (pathPattern?: string, middelwares?: Middleware[]) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
-export declare const USE: (pathPattern?: string, middelwares?: Middleware[]) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Shortcut decorator for HTTP GET method.
+ *
+ * @param pathPattern - Optional route pattern string.
+ * @param middlewares - Optional array of middlewares.
+ * @returns Method decorator for GET endpoint.
+ */
+export declare const GET: (pathPattern?: string, middlewares?: Middleware[]) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Shortcut decorator for HTTP POST method.
+ *
+ * @param pathPattern - Optional route pattern string.
+ * @param middlewares - Optional array of middlewares.
+ * @returns Method decorator for POST endpoint.
+ */
+export declare const POST: (pathPattern?: string, middlewares?: Middleware[]) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Shortcut decorator for HTTP PUT method.
+ *
+ * @param pathPattern - Optional route pattern string.
+ * @param middlewares - Optional array of middlewares.
+ * @returns Method decorator for PUT endpoint.
+ */
+export declare const PUT: (pathPattern?: string, middlewares?: Middleware[]) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Shortcut decorator for HTTP PATCH method.
+ *
+ * @param pathPattern - Optional route pattern string.
+ * @param middlewares - Optional array of middlewares.
+ * @returns Method decorator for PATCH endpoint.
+ */
+export declare const PATCH: (pathPattern?: string, middlewares?: Middleware[]) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Shortcut decorator for HTTP DELETE method.
+ *
+ * @param pathPattern - Optional route pattern string.
+ * @param middlewares - Optional array of middlewares.
+ * @returns Method decorator for DELETE endpoint.
+ */
+export declare const DELETE: (pathPattern?: string, middlewares?: Middleware[]) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Shortcut decorator for middleware usage on routes.
+ *
+ * @param pathPattern - Optional route pattern string.
+ * @param middlewares - Optional array of middlewares.
+ * @returns Method decorator for middleware usage.
+ */
+export declare const USE: (pathPattern?: string, middlewares?: Middleware[]) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/dist/core/Endpoint.js

@@ -2,7 +2,21 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.USE = exports.DELETE = exports.PATCH = exports.PUT = exports.POST = exports.GET = void 0;
 exports.Endpoint = Endpoint;
-const _constants_1 = require("@constants");
+const _constants_1 = require("../constants.js");
+/**
+ * Method decorator to define HTTP method and route pattern metadata on controller methods.
+ *
+ * This decorator maps a controller method to an HTTP endpoint by specifying the HTTP method
+ * (e.g., GET, POST) and an optional route pattern.
+ *
+ * It also allows attaching middlewares that will be applied when the endpoint is accessed.
+ *
+ * @param method - The HTTP method (e.g., 'GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'USE').
+ * @param pathPattern - Optional route pattern string to match the endpoint path.
+ * @param middlewares - Optional array of middlewares to apply to this endpoint.
+ *
+ * @returns A method decorator function.
+ */
 function Endpoint(method, pathPattern, middlewares) {
     return function (target, propertyKey, descriptor) {
         const originalMethod = descriptor.value;
@@ -17,27 +31,69 @@ function Endpoint(method, pathPattern, middlewares) {
         return descriptor;
     };
 }
-const GET = (pathPattern, middelwares) => {
-    return Endpoint('GET', pathPattern, middelwares);
+/**
+ * Shortcut decorator for HTTP GET method.
+ *
+ * @param pathPattern - Optional route pattern string.
+ * @param middlewares - Optional array of middlewares.
+ * @returns Method decorator for GET endpoint.
+ */
+const GET = (pathPattern, middlewares) => {
+    return Endpoint('GET', pathPattern, middlewares);
 };
 exports.GET = GET;
-const POST = (pathPattern, middelwares) => {
-    return Endpoint('POST', pathPattern, middelwares);
+/**
+ * Shortcut decorator for HTTP POST method.
+ *
+ * @param pathPattern - Optional route pattern string.
+ * @param middlewares - Optional array of middlewares.
+ * @returns Method decorator for POST endpoint.
+ */
+const POST = (pathPattern, middlewares) => {
+    return Endpoint('POST', pathPattern, middlewares);
 };
 exports.POST = POST;
-const PUT = (pathPattern, middelwares) => {
-    return Endpoint('PUT', pathPattern, middelwares);
+/**
+ * Shortcut decorator for HTTP PUT method.
+ *
+ * @param pathPattern - Optional route pattern string.
+ * @param middlewares - Optional array of middlewares.
+ * @returns Method decorator for PUT endpoint.
+ */
+const PUT = (pathPattern, middlewares) => {
+    return Endpoint('PUT', pathPattern, middlewares);
 };
 exports.PUT = PUT;
-const PATCH = (pathPattern, middelwares) => {
-    return Endpoint('PATCH', pathPattern, middelwares);
+/**
+ * Shortcut decorator for HTTP PATCH method.
+ *
+ * @param pathPattern - Optional route pattern string.
+ * @param middlewares - Optional array of middlewares.
+ * @returns Method decorator for PATCH endpoint.
+ */
+const PATCH = (pathPattern, middlewares) => {
+    return Endpoint('PATCH', pathPattern, middlewares);
 };
 exports.PATCH = PATCH;
-const DELETE = (pathPattern, middelwares) => {
-    return Endpoint('DELETE', pathPattern, middelwares);
+/**
+ * Shortcut decorator for HTTP DELETE method.
+ *
+ * @param pathPattern - Optional route pattern string.
+ * @param middlewares - Optional array of middlewares.
+ * @returns Method decorator for DELETE endpoint.
+ */
+const DELETE = (pathPattern, middlewares) => {
+    return Endpoint('DELETE', pathPattern, middlewares);
 };
 exports.DELETE = DELETE;
-const USE = (pathPattern, middelwares) => {
-    return Endpoint('USE', pathPattern, middelwares);
+/**
+ * Shortcut decorator for middleware usage on routes.
+ *
+ * @param pathPattern - Optional route pattern string.
+ * @param middlewares - Optional array of middlewares.
+ * @returns Method decorator for middleware usage.
+ */
+const USE = (pathPattern, middlewares) => {
+    return Endpoint('USE', pathPattern, middlewares);
 };
 exports.USE = USE;

package/dist/core/index.d.ts

@@ -1,4 +1,10 @@
-export { EndpointResponse, IController, Interceptor, Middleware, Request, Router, WebSocketClient, WebSocketEvent, WebSocketMessage, } from '@types';
+/**
+ * Re-exports core decorators and types related to controllers and endpoints.
+ *
+ * This module provides centralized exports for controller and endpoint decorators,
+ * as well as related types and utility functions used throughout the core framework.
+ */
+export { EndpointResponse, IController, Interceptor, Middleware, Request, Router, WebSocketClient, WebSocketEvent, WebSocketMessage, } from '../types/index.js';
 export * from './Controller';
 export * from './Endpoint';
 export * from './utils';