quantum-flow 1.0.1

package/src/app/http/websocket/WebsocetService.ts

@@ -0,0 +1,44 @@
+import { IWebSocketService } from '@types';
+import { WebSocketServer } from './WebsocketServer';
+
+export class WebSocketService implements IWebSocketService {
+  private static instance: WebSocketService;
+  private wss: WebSocketServer | null = null;
+
+  private constructor() {}
+
+  static getInstance(): WebSocketService {
+    if (!WebSocketService.instance) {
+      WebSocketService.instance = new WebSocketService();
+    }
+    return WebSocketService.instance;
+  }
+
+  initialize(wss: WebSocketServer) {
+    this.wss = wss;
+  }
+
+  sendToClient(clientId: string, message: any): boolean {
+    if (!this.wss) return false;
+    return this.wss.sendToClient(clientId, message);
+  }
+
+  publishToTopic(topic: string, data: any, exclude?: string[]) {
+    if (!this.wss) return;
+    this.wss.publishToTopic(topic, data, exclude);
+  }
+
+  broadcast(message: any, excludeClientId?: string) {
+    if (!this.wss) return;
+    this.wss.broadcast(message, excludeClientId);
+  }
+
+  getStats() {
+    if (!this.wss) return { clients: 0, topics: [] };
+    return this.wss.getStats();
+  }
+
+  isAvailable(): boolean {
+    return this.wss !== null;
+  }
+}

package/src/app/http/websocket/WebsocketServer.ts

@@ -0,0 +1,262 @@
+import { WebSocketClient, WebSocketEvent, WebSocketMessage } from '@types';
+import http from 'http';
+import { v4 as uuidv4 } from 'uuid';
+import WebSocket from 'ws';
+
+export class WebSocketServer {
+  private wss: WebSocket.Server | null = null;
+  private clients: Map<string, WebSocketClient> = new Map();
+  private topics: Map<string, Set<string>> = new Map();
+  private controllers: any[] = [];
+  private options: any;
+
+  constructor(server: http.Server, options?: any) {
+    this.options = options;
+
+    server.on('upgrade', (request, socket, head) => {
+      if (this.shouldHandleWebSocket(request.url)) {
+        this.ensureServer(server);
+        this.wss?.handleUpgrade(request, socket, head, (ws) => {
+          this.wss?.emit('connection', ws, request);
+        });
+      } else {
+        socket.destroy();
+      }
+    });
+  }
+
+  private shouldHandleWebSocket(url: string = ''): boolean {
+    const path = this.options?.path || '/ws';
+    return url.startsWith(path);
+  }
+
+  private ensureServer(server: http.Server) {
+    if (!this.wss) {
+      this.wss = new WebSocket.Server({
+        server,
+        path: this.options?.path || '/ws',
+        noServer: true,
+      });
+
+      this.wss.on('connection', (socket, request) => {
+        this.handleConnection(socket, request);
+      });
+    }
+  }
+
+  private async handleConnection(socket: WebSocket, request: http.IncomingMessage) {
+    const clientId = uuidv4();
+    const client: WebSocketClient = {
+      id: clientId,
+      socket,
+      topics: new Set(),
+      data: {},
+      connectedAt: new Date(),
+    };
+
+    this.clients.set(clientId, client);
+
+    socket.on('message', (data: WebSocket.Data) => {
+      this.handleMessage(client, data);
+    });
+
+    socket.on('close', () => {
+      this.handleClose(client);
+    });
+
+    socket.on('error', (error: any) => {
+      this.handleError(client, error);
+    });
+
+    await this.triggerHandlers('connection', { type: 'connection', client });
+  }
+
+  private async handleMessage(client: WebSocketClient, data: WebSocket.Data) {
+    try {
+      const message = JSON.parse(data.toString()) as WebSocketMessage;
+
+      if (message.type === 'subscribe' && message.topic) {
+        this.subscribeToTopic(client, message.topic);
+        return;
+      }
+
+      if (message.type === 'unsubscribe' && message.topic) {
+        this.unsubscribeFromTopic(client, message.topic);
+        return;
+      }
+
+      if (message.type === 'topic_message' && message.topic) {
+        await this.triggerHandlers(
+          'message',
+          {
+            type: 'message',
+            client,
+            message,
+          },
+          message.topic,
+        );
+
+        this.publishToTopic(message.topic, message.data, [client.id]);
+        return;
+      }
+
+      await this.triggerHandlers('message', {
+        type: 'message',
+        client,
+        message,
+      });
+    } catch (error) {
+      client.socket.send(
+        JSON.stringify({
+          type: 'error',
+          data: { message: 'Invalid message format' },
+        }),
+      );
+    }
+  }
+
+  private async handleClose(client: WebSocketClient) {
+    client.topics.forEach((topic) => {
+      const topicClients = this.topics.get(topic);
+      if (topicClients) {
+        topicClients.delete(client.id);
+        if (topicClients.size === 0) {
+          this.topics.delete(topic);
+        }
+      }
+    });
+
+    this.clients.delete(client.id);
+
+    await this.triggerHandlers('close', {
+      type: 'close',
+      client,
+    });
+  }
+
+  private async handleError(client: WebSocketClient, error: Error) {
+    await this.triggerHandlers('error', {
+      type: 'error',
+      client,
+      data: error,
+    });
+  }
+
+  private async triggerHandlers(eventType: string, event: WebSocketEvent, topic?: string) {
+    for (const controller of this.controllers) {
+      const handlers = Reflect.getMetadata('websocket:handler', controller.constructor) || [];
+
+      const matchingHandlers = handlers.filter(
+        (h: any) => h.type === eventType && (!h.topic || h.topic === topic),
+      );
+
+      for (const handler of matchingHandlers) {
+        try {
+          await controller[handler.method](event);
+        } catch (error) {
+          console.error(`Error in WebSocket handler ${handler.method}:`, error);
+        }
+      }
+
+      const subscriptions = Reflect.getMetadata('websocket:topic', controller.constructor) || [];
+
+      if (eventType === 'message' && topic) {
+        const matchingSubs = subscriptions.filter((s: any) => s.topic === topic);
+
+        for (const sub of matchingSubs) {
+          try {
+            await controller[sub.method](event);
+          } catch (error) {
+            console.error(`Error in subscription ${sub.method}:`, error);
+          }
+        }
+      }
+    }
+  }
+
+  public registerControllers(controllers: any[]) {
+    this.controllers = controllers;
+  }
+
+  public subscribeToTopic(client: WebSocketClient, topic: string) {
+    if (!this.topics.has(topic)) {
+      this.topics.set(topic, new Set());
+    }
+    this.topics.get(topic)!.add(client.id);
+    client.topics.add(topic);
+
+    client.socket.send(
+      JSON.stringify({
+        type: 'subscribed',
+        topic,
+        data: { success: true },
+      }),
+    );
+  }
+
+  public unsubscribeFromTopic(client: WebSocketClient, topic: string) {
+    const topicClients = this.topics.get(topic);
+    if (topicClients) {
+      topicClients.delete(client.id);
+      if (topicClients.size === 0) {
+        this.topics.delete(topic);
+      }
+    }
+    client.topics.delete(topic);
+
+    client.socket.send(
+      JSON.stringify({
+        type: 'unsubscribed',
+        topic,
+        data: { success: true },
+      }),
+    );
+  }
+
+  public publishToTopic(topic: string, data: any, exclude?: string[]) {
+    const topicClients = this.topics.get(topic);
+    if (!topicClients) return;
+
+    const message = JSON.stringify({
+      type: 'message',
+      topic,
+      data,
+      timestamp: new Date().toISOString(),
+    });
+
+    topicClients.forEach((clientId) => {
+      const client = this.clients.get(clientId);
+      if (client && exclude?.includes(client.id)) {
+        client.socket.send(message);
+      }
+    });
+  }
+
+  public sendToClient(clientId: string, message: any): boolean {
+    const client = this.clients.get(clientId);
+    if (client) {
+      client.socket.send(JSON.stringify(message));
+      return true;
+    }
+    return false;
+  }
+
+  public broadcast(message: any, excludeClientId?: string) {
+    const messageStr = JSON.stringify(message);
+    this.clients.forEach((client, clientId) => {
+      if (clientId !== excludeClientId) {
+        client.socket.send(messageStr);
+      }
+    });
+  }
+
+  public getStats() {
+    return {
+      clients: this.clients.size,
+      topics: Array.from(this.topics.entries()).map(([topic, clients]) => ({
+        topic,
+        subscribers: clients.size,
+      })),
+    };
+  }
+}

package/src/constants.ts

@@ -0,0 +1,25 @@
+export const PARAM_METADATA_KEY = 'design:parameters';
+export const APP_METADATA_KEY = 'app:configuration';
+export const ROUTE_PREFIX = 'route:profix';
+export const MIDDLEWARES = 'route:middlewares';
+export const CONTROLLERS = 'app:controllers';
+export const INTERCEPTORS = 'app:interceptors';
+export const ENDPOINT = 'route:endpoints';
+export const OK_METADATA_KEY = 'custom:ok';
+
+export const SERVER_CONFIG_KEY = 'server:config';
+export const SERVER_MODULES_KEY = 'server:modules';
+
+export const WS_METADATA_KEY = 'websocket:handler';
+export const WS_TOPIC_KEY = 'websocket:topic';
+export const WS_SERVICE_KEY = 'websocket:service';
+
+export const STOPPED = `
+╔════════════════════════════════════════╗
+║  👋 Server stopped                      ║
+║  📊 Status: STOPPED                      ║
+╚════════════════════════════════════════╝
+          `;
+
+export const OK_STATUSES = [200, 201, 202, 203, 204, 205, 206, 207, 208, 226];
+export const TO_VALIDATE = ['headers', 'params', 'multipart', 'query', 'body'];

package/src/core/Controller.ts

@@ -0,0 +1,229 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import {
+  CONTROLLERS,
+  ENDPOINT,
+  INTERCEPTORS,
+  MIDDLEWARES,
+  OK_METADATA_KEY,
+  OK_STATUSES,
+  ROUTE_PREFIX,
+} from '@constants';
+import { Interceptor, Middleware } from '@types';
+import { executeControllerMethod, getControllerMethods, matchRoute } from '@utils';
+import { ServerResponse } from 'http';
+import 'reflect-metadata';
+
+type ControllerClass = { new (...args: any[]): any };
+type ControllerInstance = InstanceType<ControllerClass>;
+
+interface ControllerConfig {
+  prefix: string;
+  middlewares?: Array<Middleware>;
+  controllers?: ControllerClass[];
+  interceptors?: Array<(...args: any[]) => any> | ((...args: any[]) => any);
+}
+
+export function Controller(
+  config: string | ControllerConfig,
+  middlewares: Array<Interceptor> = [],
+) {
+  // Handle both string and config object
+  const routePrefix = typeof config === 'string' ? config : config.prefix;
+  const controllers = typeof config === 'object' ? config.controllers : undefined;
+  const controllerMiddlewares =
+    typeof config === 'object' ? [...(config.middlewares || []), ...middlewares] : middlewares;
+
+  const interceptors =
+    typeof config === 'object'
+      ? config.interceptors
+        ? ([] as any).concat(config.interceptors)
+        : []
+      : [];
+
+  return function <T extends ControllerClass>(constructor: T) {
+    const proto = constructor.prototype;
+
+    Reflect.defineMetadata(ROUTE_PREFIX, routePrefix, proto);
+    Reflect.defineMetadata(MIDDLEWARES, controllerMiddlewares, proto);
+    Reflect.defineMetadata(CONTROLLERS, controllers || [], proto);
+    Reflect.defineMetadata(INTERCEPTORS, interceptors, proto);
+
+    for (const key of Object.getOwnPropertyNames(proto)) {
+      if (key === 'constructor') continue;
+
+      const descriptor = Object.getOwnPropertyDescriptor(proto, key);
+      if (!descriptor || typeof descriptor.value !== 'function') continue;
+
+      const original = descriptor.value;
+
+      Object.defineProperty(proto, key, {
+        ...descriptor,
+        value: async function (...args: any[]) {
+          try {
+            return await original.apply(this, args);
+          } catch (err: any) {
+            return {
+              status: err.status ?? 400,
+              message: err.message,
+              data: err,
+            };
+          }
+        },
+      });
+    }
+
+    return class extends constructor {
+      executeControllerMethod = executeControllerMethod;
+      getControllerMethods = getControllerMethods;
+      constructor(...args: any[]) {
+        super(...args);
+      }
+
+      async getResponse(data: {
+        controllerInstance: ControllerInstance;
+        name: string;
+        payload: any;
+        interceptors: Array<(...args: any[]) => any | Promise<any>>;
+        response?: ServerResponse;
+      }) {
+        try {
+          let response = await this.executeControllerMethod(
+            data.controllerInstance,
+            data.name,
+            data.payload,
+            data.response,
+          );
+
+          let status = response.status ?? 200;
+
+          const isError = !OK_STATUSES.includes(status);
+
+          for (let index = 0; index < data.interceptors?.length && !isError; index++) {
+            const interceptor = data.interceptors[index];
+            response = await interceptor(response);
+          }
+
+          const propertyName = data.name;
+          const prototype = Object.getPrototypeOf(data.controllerInstance);
+
+          const methodOkStatus = Reflect.getMetadata(
+            OK_METADATA_KEY,
+            data.controllerInstance,
+            propertyName,
+          );
+
+          if (methodOkStatus) {
+            !isError && (status = methodOkStatus);
+          } else {
+            const classOkStatus = Reflect.getMetadata(OK_METADATA_KEY, prototype);
+            !isError && classOkStatus && (status = classOkStatus);
+          }
+
+          return { status, data: response };
+        } catch (err) {
+          console.error(err);
+          throw err;
+        }
+      }
+
+      handleRequest = async (request: any, response?: ServerResponse) => {
+        const method = request.method;
+        const path = (request.url.path ?? request.url.pathname ?? '').replace(/^\/+/, '');
+
+        const baseInterceptors = Reflect.getMetadata(INTERCEPTORS, proto);
+
+        const routePrefix: string = Reflect.getMetadata(ROUTE_PREFIX, proto) || '';
+        const middlewares: Array<(Request: any) => any> =
+          Reflect.getMetadata(MIDDLEWARES, proto) || [];
+        const subControllers: ControllerClass[] = Reflect.getMetadata(CONTROLLERS, proto) || [];
+
+        // Try sub-controllers
+        for (const SubController of subControllers) {
+          const controllerInstance = new SubController(SubController);
+          if (!controllerInstance) continue;
+
+          const subInterceptors = Reflect.getMetadata(INTERCEPTORS, controllerInstance);
+
+          const controllerPrefix: string =
+            Reflect.getMetadata(ROUTE_PREFIX, SubController.prototype) || '';
+          const controllerMiddlewares: Array<(Request: any) => any> =
+            Reflect.getMetadata(MIDDLEWARES, SubController.prototype) || [];
+
+          const methods = this.getControllerMethods(controllerInstance);
+
+          for (const methodInfo of methods) {
+            if (methodInfo.httpMethod === method || methodInfo.httpMethod === 'USE') {
+              // Build full pattern: main prefix + controller prefix + method pattern
+              const fullPattern = [routePrefix, controllerPrefix, methodInfo.pattern]
+                .filter(Boolean)
+                .join('/')
+                .replace(/\/+/g, '/');
+
+              const pathParams = matchRoute(fullPattern, path);
+              if (pathParams) {
+                let payload = { ...request, params: pathParams };
+
+                // Apply all middlewares in order: main controller -> sub-controller -> method
+                for (const middleware of [
+                  ...middlewares,
+                  ...controllerMiddlewares,
+                  ...(methodInfo.middlewares || []),
+                ]) {
+                  const middlawareResponde = await middleware(payload, response);
+                  payload = { ...payload, ...middlawareResponde };
+                }
+
+                return this.getResponse({
+                  interceptors: [...subInterceptors, ...baseInterceptors],
+                  controllerInstance,
+                  name: methodInfo.name,
+                  payload,
+                  response,
+                });
+              }
+            }
+          }
+        }
+
+        const propertyNames = Object.getOwnPropertyNames(proto);
+
+        for (const propertyName of propertyNames) {
+          const fn = (this as any)[propertyName];
+          if (typeof fn !== 'function') continue;
+
+          const endpointMeta = Reflect.getMetadata(ENDPOINT, proto, propertyName) || [];
+
+          const [httpMethod, routePattern] = endpointMeta;
+
+          if (httpMethod === method || httpMethod === 'USE') {
+            const fullPattern = [routePrefix, routePattern]
+              .filter(Boolean)
+              .join('/')
+              .replace(/\/+/g, '/');
+
+            const pathParams = matchRoute(fullPattern, path);
+            if (pathParams) {
+              let payload = { ...request, params: pathParams };
+
+              // Apply controller-level middlewares
+              for (const middleware of middlewares) {
+                const middlewareResponse = await middleware(payload);
+                payload = { ...payload, middlewareResponse };
+              }
+
+              return this.getResponse({
+                interceptors: baseInterceptors,
+                controllerInstance: this,
+                name: propertyName,
+                payload,
+                response,
+              });
+            }
+          }
+        }
+
+        return { status: 404, message: 'Method Not Found' };
+      };
+    };
+  };
+}

package/src/core/Endpoint.ts

@@ -0,0 +1,39 @@
+import { ENDPOINT } from '@constants';
+import { Middleware } from '@types';
+
+export function Endpoint(method: string, pathPattern?: string, middlewares?: Middleware[]) {
+  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
+    const originalMethod = descriptor.value;
+
+    if (!originalMethod) {
+      console.warn('❌ originalMethod is undefined!');
+      return descriptor;
+    }
+
+    if (method && pathPattern) {
+      Reflect.defineMetadata(ENDPOINT, [method, pathPattern], target, propertyKey);
+      Reflect.defineMetadata('middlewares', middlewares || [], target, propertyKey);
+    }
+
+    return descriptor;
+  };
+}
+
+export const GET = (pathPattern?: string, middelwares?: Middleware[]) => {
+  return Endpoint('GET', pathPattern, middelwares);
+};
+export const POST = (pathPattern?: string, middelwares?: Middleware[]) => {
+  return Endpoint('POST', pathPattern, middelwares);
+};
+export const PUT = (pathPattern?: string, middelwares?: Middleware[]) => {
+  return Endpoint('PUT', pathPattern, middelwares);
+};
+export const PATCH = (pathPattern?: string, middelwares?: Middleware[]) => {
+  return Endpoint('PATCH', pathPattern, middelwares);
+};
+export const DELETE = (pathPattern?: string, middelwares?: Middleware[]) => {
+  return Endpoint('DELETE', pathPattern, middelwares);
+};
+export const USE = (pathPattern?: string, middelwares?: Middleware[]) => {
+  return Endpoint('USE', pathPattern, middelwares);
+};

package/src/core/index.ts

@@ -0,0 +1,14 @@
+export {
+  EndpointResponse,
+  IController,
+  Interceptor,
+  Middleware,
+  Request,
+  Router,
+  WebSocketClient,
+  WebSocketEvent,
+  WebSocketMessage,
+} from '@types';
+export * from './Controller';
+export * from './Endpoint';
+export * from './utils';

package/src/core/utils/extractors.ts

@@ -0,0 +1,32 @@
+import { PARAM_METADATA_KEY } from '@constants';
+import { ParamDecoratorType } from '@types';
+
+export interface ParamMetadata {
+  index: number;
+  type: ParamDecoratorType;
+  dto?: any;
+  name?: string;
+}
+
+function createParamDecorator(type: ParamDecoratorType, dto?: any, name?: string) {
+  return function (target: any, propertyKey: string | symbol, parameterIndex: number) {
+    const existingParams: ParamMetadata[] =
+      Reflect.getMetadata(PARAM_METADATA_KEY, target, propertyKey) || [];
+
+    existingParams.push({ index: parameterIndex, type, dto, name });
+    existingParams.sort((a, b) => a.index - b.index);
+
+    Reflect.defineMetadata(PARAM_METADATA_KEY, existingParams, target, propertyKey);
+
+    const saved = Reflect.getMetadata(PARAM_METADATA_KEY, target, propertyKey);
+  };
+}
+
+export const Body = (dto?: any) => createParamDecorator('body', dto);
+export const Params = (name?: string) => createParamDecorator('params', undefined, name);
+export const Query = (name?: string) => createParamDecorator('query', undefined, name);
+export const Request = () => createParamDecorator('request');
+export const Headers = (name?: string) => createParamDecorator('headers', undefined, name);
+export const Cookies = (name?: string) => createParamDecorator('cookies', undefined, name);
+export const Multipart = (name?: string) => createParamDecorator('multipart', undefined, name);
+export const Response = () => createParamDecorator('response');

package/src/core/utils/helpers.ts

@@ -0,0 +1,22 @@
+import { OK_METADATA_KEY } from '@constants';
+
+export function Status(status: number) {
+  return function (
+    target: any,
+    propertyKey?: string | symbol,
+    descriptor?: TypedPropertyDescriptor<any>,
+  ): void {
+    if (!propertyKey) {
+      Reflect.defineMetadata(OK_METADATA_KEY, status, target.prototype || target);
+      return;
+    }
+
+    if (descriptor) {
+      Reflect.defineMetadata(OK_METADATA_KEY, status, target, propertyKey);
+    }
+  };
+}
+
+export const Ok200 = () => Status(200);
+export const Ok201 = () => Status(201);
+export const Ok204 = () => Status(204);

package/src/core/utils/index.ts

@@ -0,0 +1,3 @@
+export * from './extractors';
+export * from './helpers';
+export * from './websocket';