@martel/calyx 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [1.6.0](https://github.com/bmartel/calyx/compare/v1.5.0...v1.6.0) (2026-07-01)
+
+
+### Features
+
+* **websockets,microservices:** implement WebSocketGateways, TCP Microservices, and context switching for Guards/Interceptors ([a8cde0d](https://github.com/bmartel/calyx/commit/a8cde0d68411a3ab736fe1df00ae04672588b1af))
+
+# [1.5.0](https://github.com/bmartel/calyx/compare/v1.4.0...v1.5.0) (2026-07-01)
+
+
+### Features
+
+* **security,schedule:** implement ConfigModule, EventEmitterModule, HashingService, CORS, Helmet, and Task Scheduler ([6cfa8ca](https://github.com/bmartel/calyx/commit/6cfa8ca9459d73c7a7b1087953991d675d3a55db))
+
 # [1.4.0](https://github.com/bmartel/calyx/compare/v1.3.0...v1.4.0) (2026-07-01)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martel/calyx",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "High-performance Bun-native NestJS-compatible framework",
   "main": "src/index.ts",
   "bin": {

package/src/config/config.module.ts

@@ -0,0 +1,61 @@
+import { existsSync, readFileSync } from 'fs';
+import { Module, DynamicModule } from '../core/decorators.ts';
+import { ConfigService } from './config.service.ts';
+
+export interface ConfigModuleOptions {
+  isGlobal?: boolean;
+  load?: (() => Record<string, any>)[];
+  envFilePath?: string;
+}
+
+@Module({
+  providers: [ConfigService],
+  exports: [ConfigService],
+})
+export class ConfigModule {
+  static forRoot(options: ConfigModuleOptions = {}): DynamicModule {
+    const configData: Record<string, string> = { ...(process.env as Record<string, string>) };
+
+    if (options.envFilePath && existsSync(options.envFilePath)) {
+      try {
+        const text = readFileSync(options.envFilePath, 'utf-8');
+        if (text) {
+          const lines = text.split('\n');
+          for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith('#')) continue;
+            const eqIdx = trimmed.indexOf('=');
+            if (eqIdx !== -1) {
+              const key = trimmed.substring(0, eqIdx).trim();
+              const val = trimmed.substring(eqIdx + 1).trim();
+              configData[key] = val.replace(/^['"]|['"]$/g, '');
+            }
+          }
+        }
+      } catch (err) {
+        // ignore read error
+      }
+    }
+
+    if (options.load) {
+      for (const factory of options.load) {
+        const data = factory();
+        for (const [key, val] of Object.entries(data)) {
+          configData[key] = String(val);
+        }
+      }
+    }
+
+    const configServiceProvider = {
+      provide: ConfigService,
+      useValue: new ConfigService(configData),
+    };
+
+    return {
+      module: ConfigModule,
+      providers: [configServiceProvider],
+      exports: [ConfigService],
+      global: options.isGlobal ?? false,
+    };
+  }
+}

package/src/config/config.service.ts

@@ -0,0 +1,24 @@
+import { Injectable } from '../core/decorators.ts';
+
+@Injectable()
+export class ConfigService {
+  private readonly env: Record<string, string> = {};
+
+  constructor(internalConfig?: Record<string, string>) {
+    this.env = internalConfig ?? (process.env as Record<string, string>);
+  }
+
+  get<T = string>(path: string, defaultValue?: T): T {
+    const val = this.env[path];
+    if (val === undefined) {
+      return defaultValue as T;
+    }
+    if (val === 'true') return true as unknown as T;
+    if (val === 'false') return false as unknown as T;
+    const num = Number(val);
+    if (!isNaN(num) && val.trim() !== '') {
+      return num as unknown as T;
+    }
+    return val as unknown as T;
+  }
+}

package/src/config/index.ts

@@ -0,0 +1,2 @@
+export * from './config.service.ts';
+export * from './config.module.ts';

package/src/event-emitter/decorators.ts

@@ -0,0 +1,10 @@
+import 'reflect-metadata';
+
+export function OnEvent(event: string): MethodDecorator {
+  return (target, propertyKey) => {
+    const constructor = target.constructor;
+    const existing = Reflect.getOwnMetadata('calyx:on_event', constructor) || [];
+    existing.push({ event, propertyKey });
+    Reflect.defineMetadata('calyx:on_event', existing, constructor);
+  };
+}

package/src/event-emitter/event-emitter.module.ts

@@ -0,0 +1,17 @@
+import { Module, DynamicModule } from '../core/decorators.ts';
+import { EventEmitter } from './event-emitter.ts';
+
+@Module({
+  providers: [EventEmitter],
+  exports: [EventEmitter],
+})
+export class EventEmitterModule {
+  static forRoot(): DynamicModule {
+    return {
+      module: EventEmitterModule,
+      providers: [EventEmitter],
+      exports: [EventEmitter],
+      global: true,
+    };
+  }
+}

package/src/event-emitter/event-emitter.ts

@@ -0,0 +1,61 @@
+import { Injectable } from '../core/decorators.ts';
+
+@Injectable()
+export class EventEmitter {
+  private readonly listeners = new Map<string, Function[]>();
+  private readonly wildcardListeners: { pattern: RegExp; fn: Function }[] = [];
+
+  on(event: string, fn: Function) {
+    if (event.includes('*')) {
+      const regexStr = '^' + event.replace(/\./g, '\\.').replace(/\*/g, '.*') + '$';
+      this.wildcardListeners.push({ pattern: new RegExp(regexStr), fn });
+    } else {
+      let list = this.listeners.get(event);
+      if (!list) {
+        list = [];
+        this.listeners.set(event, list);
+      }
+      list.push(fn);
+    }
+  }
+
+  emit(event: string, ...args: any[]) {
+    const list = this.listeners.get(event);
+    if (list) {
+      for (const fn of list) {
+        fn(...args);
+      }
+    }
+
+    for (const item of this.wildcardListeners) {
+      if (item.pattern.test(event)) {
+        item.fn(...args);
+      }
+    }
+  }
+
+  async emitAsync(event: string, ...args: any[]): Promise<any[]> {
+    const promises: Promise<any>[] = [];
+
+    const list = this.listeners.get(event);
+    if (list) {
+      for (const fn of list) {
+        const res = fn(...args);
+        if (res instanceof Promise) {
+          promises.push(res);
+        }
+      }
+    }
+
+    for (const item of this.wildcardListeners) {
+      if (item.pattern.test(event)) {
+        const res = item.fn(...args);
+        if (res instanceof Promise) {
+          promises.push(res);
+        }
+      }
+    }
+
+    return Promise.all(promises);
+  }
+}

package/src/event-emitter/index.ts

@@ -0,0 +1,3 @@
+export * from './event-emitter.ts';
+export * from './decorators.ts';
+export * from './event-emitter.module.ts';

package/src/http/application.ts

@@ -6,6 +6,10 @@ import { HttpException, NotFoundException } from './exceptions.ts';
 import { ArgumentsHost, ExecutionContext } from '../lifecycle/interfaces.ts';
 import { CalyxArgumentsHost, CalyxExecutionContext } from '../lifecycle/context.ts';
 import { CalyxMiddlewareConsumer, MiddlewareConfiguration, RequestMethodMap, CompiledLifecycleItem as CompiledMiddlewareItem } from './middleware.ts';
+import { EventEmitter } from '../event-emitter/event-emitter.ts';
+import { cors, CorsOptions } from '../security/cors.middleware.ts';
+import { helmet, HelmetOptions } from '../security/helmet.middleware.ts';
+import { CronMatcher } from '../schedule/cron.matcher.ts';
 
 class ObjectPool<T> {
   private pool: T[] = [];
@@ -95,6 +99,9 @@ export class CalyxApplication {
   private middlewareConfigurations: MiddlewareConfiguration[] = [];
   private hostPool = new ObjectPool<CalyxArgumentsHost>(() => new CalyxArgumentsHost());
   private contextPool = new ObjectPool<CalyxExecutionContext>(() => new CalyxExecutionContext());
+  private sharedWebSockets: any[] = [];
+  private hasWebSockets = false;
+  private serverPort = 3000;
 
   use(...middlewares: any[]) {
     this.globalMiddlewares.push(...middlewares);
@@ -109,6 +116,16 @@ export class CalyxApplication {
     this.globalInterceptors.push(...interceptors);
   }
 
+  enableCors(options?: CorsOptions) {
+    this.use(cors(options));
+    return this;
+  }
+
+  useHelmet(options?: HelmetOptions) {
+    this.use(helmet(options));
+    return this;
+  }
+
   useGlobalPipes(...pipes: any[]) {
     this.globalPipes.push(...pipes);
   }
@@ -129,6 +146,15 @@ export class CalyxApplication {
     // Build the routing table from registered controllers
     this.buildRoutes();
 
+    // Register Event listeners
+    this.registerEventListeners();
+
+    // Register Scheduled tasks
+    this.registerScheduledTasks();
+
+    // Register WebSocket Gateways
+    this.registerWebSocketGateways();
+
     // Call OnModuleInit hooks
     await this.runOnModuleInit();
 
@@ -908,11 +934,43 @@ export class CalyxApplication {
   }
 
   async listen(port: number): Promise<any> {
+    this.serverPort = port;
     await this.init();
-    this.server = Bun.serve({
+
+    const fetchHandler = (req: Request, server: any) => {
+      if (this.hasWebSockets && req.headers.get('upgrade') === 'websocket') {
+        const success = server.upgrade(req);
+        if (success) return undefined;
+      }
+      return this.handleRequest(req);
+    };
+
+    const serveOptions: any = {
       port,
-      fetch: (req) => this.handleRequest(req),
-    });
+      fetch: fetchHandler,
+    };
+
+    if (this.hasWebSockets) {
+      serveOptions.websocket = {
+        open: (ws: any) => {
+          for (const gateway of this.sharedWebSockets) {
+            this.dispatchWsConnection(gateway, ws);
+          }
+        },
+        message: (ws: any, message: any) => {
+          for (const gateway of this.sharedWebSockets) {
+            this.dispatchWsMessage(gateway, ws, message);
+          }
+        },
+        close: (ws: any) => {
+          for (const gateway of this.sharedWebSockets) {
+            this.dispatchWsDisconnect(gateway, ws);
+          }
+        }
+      };
+    }
+
+    this.server = Bun.serve(serveOptions);
     return this.server;
   }
 
@@ -989,4 +1047,279 @@ export class CalyxApplication {
       }
     }
   }
+
+  private registerEventListeners() {
+    let eventEmitter: EventEmitter;
+    try {
+      eventEmitter = this.container.getGlobalOrAnyInstance(EventEmitter);
+    } catch {
+      return;
+    }
+
+    const instances = this.container.getProviderAndControllerInstances();
+    for (const instance of instances) {
+      if (!instance || !instance.constructor) continue;
+      const listeners: { event: string; propertyKey: string | symbol }[] =
+        Reflect.getMetadata('calyx:on_event', instance.constructor) || [];
+
+      for (const listener of listeners) {
+        eventEmitter.on(listener.event, (...args: any[]) => {
+          return instance[listener.propertyKey](...args);
+        });
+      }
+    }
+  }
+
+  private registerScheduledTasks() {
+    let hasScheduleModule = false;
+    for (const moduleClass of this.container.getModules().keys()) {
+      if (moduleClass.name === 'ScheduleModule') {
+        hasScheduleModule = true;
+        break;
+      }
+    }
+    if (!hasScheduleModule) {
+      return;
+    }
+
+    const instances = this.container.getProviderAndControllerInstances();
+    for (const instance of instances) {
+      if (!instance || !instance.constructor) continue;
+
+      const crons: { expression: string; propertyKey: string | symbol }[] =
+        Reflect.getMetadata('calyx:cron', instance.constructor) || [];
+      for (const cron of crons) {
+        const parts = cron.expression.split(' ');
+        const isSecondLevel = parts.length === 6;
+
+        let lastRan = 0;
+        const tick = () => {
+          const now = new Date();
+          const nowMs = now.getTime();
+          const timeUnit = isSecondLevel ? Math.floor(nowMs / 1000) : Math.floor(nowMs / 60000);
+          if (timeUnit === lastRan) return;
+
+          if (CronMatcher.match(cron.expression, now)) {
+            lastRan = timeUnit;
+            try {
+              instance[cron.propertyKey]();
+            } catch (err) {
+              console.error(`Error executing cron task ${String(cron.propertyKey)}:`, err);
+            }
+          }
+        };
+
+        const intervalMs = isSecondLevel ? 1000 : 20000;
+        const timer = setInterval(tick, intervalMs);
+        this.cleanupListeners.push(() => clearInterval(timer));
+      }
+
+      const intervals: { ms: number; propertyKey: string | symbol }[] =
+        Reflect.getMetadata('calyx:interval', instance.constructor) || [];
+      for (const interval of intervals) {
+        const timer = setInterval(() => {
+          try {
+            instance[interval.propertyKey]();
+          } catch (err) {
+            console.error(`Error executing interval task ${String(interval.propertyKey)}:`, err);
+          }
+        }, interval.ms);
+        this.cleanupListeners.push(() => clearInterval(timer));
+      }
+
+      const timeouts: { ms: number; propertyKey: string | symbol }[] =
+        Reflect.getMetadata('calyx:timeout', instance.constructor) || [];
+      for (const timeout of timeouts) {
+        const timer = setTimeout(() => {
+          try {
+            instance[timeout.propertyKey]();
+          } catch (err) {
+            console.error(`Error executing timeout task ${String(timeout.propertyKey)}:`, err);
+          }
+        }, timeout.ms);
+        this.cleanupListeners.push(() => clearTimeout(timer));
+      }
+    }
+  }
+
+  private registerWebSocketGateways() {
+    const instances = this.container.getProviderAndControllerInstances();
+    for (const instance of instances) {
+      if (!instance || !instance.constructor) continue;
+      const metadata = Reflect.getMetadata('calyx:websocket_gateway', instance.constructor);
+      if (!metadata) continue;
+
+      const handlers = new Map<string, { propertyKey: string | symbol; paramMapping: any[] }>();
+
+      const subMessages: { event: string; propertyKey: string | symbol }[] =
+        Reflect.getMetadata('calyx:subscribe_message', instance.constructor) || [];
+
+      const bodyParams: { propertyKey: string | symbol; parameterIndex: number }[] =
+        Reflect.getMetadata('calyx:message_body', instance.constructor) || [];
+
+      const socketParams: { propertyKey: string | symbol; parameterIndex: number }[] =
+        Reflect.getMetadata('calyx:connected_socket', instance.constructor) || [];
+
+      for (const sub of subMessages) {
+        const paramMapping: any[] = [];
+        
+        for (const bp of bodyParams) {
+          if (bp.propertyKey === sub.propertyKey) {
+            paramMapping[bp.parameterIndex] = 'body';
+          }
+        }
+        for (const sp of socketParams) {
+          if (sp.propertyKey === sub.propertyKey) {
+            paramMapping[sp.parameterIndex] = 'socket';
+          }
+        }
+
+        const classGuards = Reflect.getMetadata(METADATA_KEYS.GUARDS, instance.constructor) || [];
+        const methodGuards = Reflect.getMetadata(METADATA_KEYS.GUARDS, instance.constructor.prototype, sub.propertyKey) || [];
+        const guards = this.compileLifecycleItems(this.rootModule, [...this.globalGuards, ...classGuards, ...methodGuards]);
+
+        const classInterceptors = Reflect.getMetadata(METADATA_KEYS.INTERCEPTORS, instance.constructor) || [];
+        const methodInterceptors = Reflect.getMetadata(METADATA_KEYS.INTERCEPTORS, instance.constructor.prototype, sub.propertyKey) || [];
+        const interceptors = this.compileLifecycleItems(this.rootModule, [...this.globalInterceptors, ...classInterceptors, ...methodInterceptors]);
+
+        handlers.set(sub.event, {
+          propertyKey: sub.propertyKey,
+          paramMapping,
+          guards,
+          interceptors,
+          gatewayClass: instance.constructor,
+        });
+      }
+
+      const gatewayInfo = {
+        instance,
+        metadata,
+        handlers,
+      };
+
+      if (metadata.port && metadata.port !== this.serverPort) {
+        this.startDedicatedWebSocketServer(gatewayInfo);
+      } else {
+        this.sharedWebSockets.push(gatewayInfo);
+        this.hasWebSockets = true;
+      }
+    }
+  }
+
+  private startDedicatedWebSocketServer(gateway: any) {
+    const port = gateway.metadata.port;
+    const self = this;
+    const wsServer = Bun.serve({
+      port,
+      fetch(req, server) {
+        if (server.upgrade(req)) {
+          return undefined;
+        }
+        return new Response('Expected upgrade to websocket', { status: 400 });
+      },
+      websocket: {
+        open: (ws: any) => {
+          self.dispatchWsConnection(gateway, ws);
+        },
+        message: (ws: any, message: any) => {
+          self.dispatchWsMessage(gateway, ws, message);
+        },
+        close: (ws: any) => {
+          self.dispatchWsDisconnect(gateway, ws);
+        }
+      }
+    });
+
+    this.cleanupListeners.push(() => wsServer.stop());
+
+    if (typeof gateway.instance.afterInit === 'function') {
+      gateway.instance.afterInit(wsServer);
+    }
+  }
+
+  private dispatchWsConnection(gateway: any, ws: any) {
+    if (typeof gateway.instance.handleConnection === 'function') {
+      gateway.instance.handleConnection(ws);
+    }
+  }
+
+  private dispatchWsDisconnect(gateway: any, ws: any) {
+    if (typeof gateway.instance.handleDisconnect === 'function') {
+      gateway.instance.handleDisconnect(ws);
+    }
+  }
+
+  private async dispatchWsMessage(gateway: any, ws: any, message: any) {
+    let messageStr = '';
+    if (typeof message === 'string') {
+      messageStr = message;
+    } else if (message instanceof Uint8Array || message instanceof ArrayBuffer) {
+      messageStr = new TextDecoder().decode(message);
+    } else {
+      return;
+    }
+
+    try {
+      const parsed = JSON.parse(messageStr);
+      const event = parsed.event;
+      const data = parsed.data;
+
+      const handlerInfo = gateway.handlers.get(event);
+      if (handlerInfo) {
+        const args: any[] = [];
+        for (let i = 0; i < handlerInfo.paramMapping.length; i++) {
+          const type = handlerInfo.paramMapping[i];
+          if (type === 'body') {
+            args[i] = data;
+          } else if (type === 'socket') {
+            args[i] = ws;
+          }
+        }
+
+        const context = this.contextPool.acquire();
+        context.resetContextWs(ws, data, handlerInfo.gatewayClass, gateway.instance[handlerInfo.propertyKey]);
+
+        try {
+          for (const guard of handlerInfo.guards) {
+            const canActive = await guard.instance.canActivate(context);
+            if (!canActive) {
+              return; // Block event
+            }
+          }
+
+          const nextCall = {
+            handle: async () => {
+              return gateway.instance[handlerInfo.propertyKey](...args);
+            }
+          };
+
+          let chain = nextCall.handle;
+          for (let i = handlerInfo.interceptors.length - 1; i >= 0; i--) {
+            const interceptor = handlerInfo.interceptors[i];
+            const currentChain = chain;
+            chain = async () => {
+              return interceptor.instance.intercept(context, {
+                handle: () => currentChain()
+              });
+            };
+          }
+
+          const result = await chain();
+
+          if (result !== undefined) {
+            ws.send(JSON.stringify(result));
+          }
+        } catch (err: any) {
+          // ignore or log
+        } finally {
+          context.clearContext();
+          this.contextPool.release(context);
+        }
+      }
+    } catch {
+      // ignore non-json
+    }
+  }
 }
+
+

package/src/http/factory.ts

@@ -1,8 +1,15 @@
 import { CalyxApplication } from './application.ts';
+import { CalyxMicroservice } from '../microservices/microservice.ts';
+import { MicroserviceOptions } from '../microservices/interfaces.ts';
 
 export class CalyxFactory {
   static async create(rootModule: any): Promise<CalyxApplication> {
     const app = new CalyxApplication(rootModule);
     return app;
   }
+
+  static async createMicroservice(rootModule: any, options?: MicroserviceOptions): Promise<CalyxMicroservice> {
+    const app = new CalyxMicroservice(rootModule, options);
+    return app;
+  }
 }

package/src/index.ts

@@ -2,3 +2,9 @@ import 'reflect-metadata';
 export * from './core/index.ts';
 export * from './http/index.ts';
 export * from './lifecycle/index.ts';
+export * from './config/index.ts';
+export * from './event-emitter/index.ts';
+export * from './security/index.ts';
+export * from './schedule/index.ts';
+export * from './websockets/index.ts';
+export * from './microservices/index.ts';