@martel/calyx 1.5.0 → 1.7.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [1.7.0](https://github.com/bmartel/calyx/compare/v1.6.0...v1.7.0) (2026-07-01)
+
+
+### Features
+
+* **cache,validation:** implement SQLite CacheModule, JIT ValidationPipe, and JIT Response Serializer ([1d37b68](https://github.com/bmartel/calyx/commit/1d37b68c2a7ba52e7878810b63f75ee31becc433))
+
+# [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)
 
 

package/package.json

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

package/src/cache/cache.interceptor.ts

@@ -0,0 +1,32 @@
+import { NestInterceptor, ExecutionContext, CallHandler } from '../lifecycle/interfaces.ts';
+import { Injectable } from '../core/decorators.ts';
+import { CacheService } from './cache.service.ts';
+
+@Injectable()
+export class CacheInterceptor implements NestInterceptor {
+  constructor(private readonly cacheService: CacheService) {}
+
+  async intercept(context: ExecutionContext, next: CallHandler): Promise<any> {
+    const type = context.getType();
+    if (type !== 'http') {
+      return next.handle();
+    }
+
+    const req = context.switchToHttp().getRequest<Request>();
+    if (req.method !== 'GET') {
+      return next.handle();
+    }
+
+    const url = new URL(req.url);
+    const key = `http_cache::${url.pathname}${url.search}`;
+
+    const cached = await this.cacheService.get(key);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    const result = await next.handle();
+    await this.cacheService.set(key, result);
+    return result;
+  }
+}

package/src/cache/cache.module.ts

@@ -0,0 +1,31 @@
+import { Module, DynamicModule } from '../core/decorators.ts';
+import { CacheService } from './cache.service.ts';
+import { CacheInterceptor } from './cache.interceptor.ts';
+
+export interface CacheModuleOptions {
+  dbPath?: string;
+  defaultTtl?: number;
+  isGlobal?: boolean;
+}
+
+@Module({
+  providers: [CacheService, CacheInterceptor],
+  exports: [CacheService, CacheInterceptor],
+})
+export class CacheModule {
+  static register(options: CacheModuleOptions = {}): DynamicModule {
+    const cacheServiceInstance = new CacheService(options);
+
+    const cacheServiceProvider = {
+      provide: CacheService,
+      useValue: cacheServiceInstance,
+    };
+
+    return {
+      module: CacheModule,
+      providers: [cacheServiceProvider, CacheInterceptor],
+      exports: [CacheService, CacheInterceptor],
+      global: options.isGlobal ?? false,
+    };
+  }
+}

package/src/cache/cache.service.ts

@@ -0,0 +1,86 @@
+import { Database } from 'bun:sqlite';
+import { Injectable } from '../core/decorators.ts';
+
+@Injectable()
+export class CacheService {
+  private db!: Database;
+  private pruneTimer: any;
+  private readonly dbPath: string;
+  private readonly defaultTtl: number;
+
+  constructor(options: { dbPath?: string; defaultTtl?: number } = {}) {
+    this.dbPath = options.dbPath ?? ':memory:';
+    this.defaultTtl = options.defaultTtl ?? 5;
+  }
+
+  onModuleInit() {
+    this.db = new Database(this.dbPath);
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS cache (
+        key TEXT PRIMARY KEY,
+        value TEXT,
+        expires_at INTEGER
+      )
+    `);
+    this.db.run(`CREATE INDEX IF NOT EXISTS idx_expires_at ON cache (expires_at)`);
+
+    this.pruneTimer = setInterval(() => this.prune(), 30000);
+  }
+
+  onModuleDestroy() {
+    if (this.pruneTimer) {
+      clearInterval(this.pruneTimer);
+    }
+    if (this.db) {
+      this.db.close();
+    }
+  }
+
+  async get<T = any>(key: string): Promise<T | undefined> {
+    const row = this.db.query('SELECT value, expires_at FROM cache WHERE key = $key').get({ $key: key }) as any;
+    if (!row) return undefined;
+
+    if (row.expires_at !== null && row.expires_at < Date.now()) {
+      this.db.query('DELETE FROM cache WHERE key = $key').run({ $key: key });
+      return undefined;
+    }
+
+    try {
+      return JSON.parse(row.value) as T;
+    } catch {
+      return row.value as unknown as T;
+    }
+  }
+
+  async set<T = any>(key: string, value: T, ttl?: number): Promise<void> {
+    const ttlSeconds = ttl !== undefined ? ttl : this.defaultTtl;
+    const expiresAt = ttlSeconds > 0 ? Date.now() + ttlSeconds * 1000 : null;
+    const valStr = JSON.stringify(value);
+
+    this.db.query(`
+      INSERT INTO cache (key, value, expires_at)
+      VALUES ($key, $val, $expiresAt)
+      ON CONFLICT(key) DO UPDATE SET value = $val, expires_at = $expiresAt
+    `).run({
+      $key: key,
+      $val: valStr,
+      $expiresAt: expiresAt,
+    });
+  }
+
+  async del(key: string): Promise<void> {
+    this.db.query('DELETE FROM cache WHERE key = $key').run({ $key: key });
+  }
+
+  async reset(): Promise<void> {
+    this.db.run('DELETE FROM cache');
+  }
+
+  private prune() {
+    try {
+      this.db.query('DELETE FROM cache WHERE expires_at IS NOT NULL AND expires_at < $now').run({ $now: Date.now() });
+    } catch {
+      // ignore
+    }
+  }
+}

package/src/cache/index.ts

@@ -0,0 +1,3 @@
+export * from './cache.service.ts';
+export * from './cache.interceptor.ts';
+export * from './cache.module.ts';

package/src/http/application.ts

@@ -10,6 +10,7 @@ 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';
+import { SerializationCompiler } from '../validation/compiler.ts';
 
 class ObjectPool<T> {
   private pool: T[] = [];
@@ -99,6 +100,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);
@@ -149,6 +153,9 @@ export class CalyxApplication {
     // Register Scheduled tasks
     this.registerScheduledTasks();
 
+    // Register WebSocket Gateways
+    this.registerWebSocketGateways();
+
     // Call OnModuleInit hooks
     await this.runOnModuleInit();
 
@@ -882,6 +889,15 @@ export class CalyxApplication {
 
     if (typeof result === 'object') {
       responseHeaders['content-type'] = 'application/json';
+      const constructor = result.constructor;
+      if (constructor) {
+        const hasRules = Reflect.hasMetadata('calyx:validation_rules', constructor);
+        const hasExpose = Reflect.hasMetadata('calyx:expose_properties', constructor);
+        if (hasRules || hasExpose) {
+          const serialize = SerializationCompiler.compile(constructor);
+          return new Response(serialize(result), { status, headers: responseHeaders });
+        }
+      }
       return new Response(JSON.stringify(result), { status, headers: responseHeaders });
     }
 
@@ -928,11 +944,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;
   }
 
@@ -1103,5 +1151,185 @@ export class CalyxApplication {
       }
     }
   }
+
+  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

@@ -6,3 +6,7 @@ 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';
+export * from './cache/index.ts';
+export * from './validation/index.ts';

package/src/lifecycle/context.ts

@@ -4,6 +4,10 @@ import { Type } from '../core/metadata.ts';
 export class CalyxArgumentsHost implements ArgumentsHost {
   protected req!: Request;
   protected res!: any;
+  protected type: 'http' | 'ws' | 'rpc' = 'http';
+  protected wsClient: any = null;
+  protected rpcContext: any = null;
+  protected data: any = null;
 
   constructor(req?: Request, res?: any) {
     if (req && res) {
@@ -12,16 +16,47 @@ export class CalyxArgumentsHost implements ArgumentsHost {
   }
 
   reset(req: Request, res: any) {
+    this.type = 'http';
     this.req = req;
     this.res = res;
+    this.wsClient = null;
+    this.rpcContext = null;
+    this.data = null;
+  }
+
+  resetWs(client: any, data: any) {
+    this.type = 'ws';
+    this.wsClient = client;
+    this.data = data;
+    this.req = null as any;
+    this.res = null;
+    this.rpcContext = null;
+  }
+
+  resetRpc(ctx: any, data: any) {
+    this.type = 'rpc';
+    this.rpcContext = ctx;
+    this.data = data;
+    this.req = null as any;
+    this.res = null;
+    this.wsClient = null;
   }
 
   clear() {
     this.req = null as any;
     this.res = null;
+    this.wsClient = null;
+    this.rpcContext = null;
+    this.data = null;
   }
 
   getArgs<T extends any[] = any[]>(): T {
+    if (this.type === 'ws') {
+      return [this.wsClient, this.data] as unknown as T;
+    }
+    if (this.type === 'rpc') {
+      return [this.data, this.rpcContext] as unknown as T;
+    }
     return [this.req, this.res] as unknown as T;
   }
 
@@ -36,6 +71,24 @@ export class CalyxArgumentsHost implements ArgumentsHost {
       getNext: <T = any>() => (() => {}) as unknown as T,
     };
   }
+
+  switchToWs(): any {
+    return {
+      getClient: <T = any>() => this.wsClient as T,
+      getData: <T = any>() => this.data as T,
+    };
+  }
+
+  switchToRpc(): any {
+    return {
+      getContext: <T = any>() => this.rpcContext as T,
+      getData: <T = any>() => this.data as T,
+    };
+  }
+
+  getType<TContextType extends string = string>(): TContextType {
+    return this.type as TContextType;
+  }
 }
 
 export class CalyxExecutionContext extends CalyxArgumentsHost implements ExecutionContext {
@@ -65,6 +118,28 @@ export class CalyxExecutionContext extends CalyxArgumentsHost implements Executi
     this.handlerMethod = handlerMethod;
   }
 
+  resetContextWs(
+    client: any,
+    data: any,
+    targetClass: Type<any>,
+    handlerMethod: Function
+  ) {
+    this.resetWs(client, data);
+    this.targetClass = targetClass;
+    this.handlerMethod = handlerMethod;
+  }
+
+  resetContextRpc(
+    ctx: any,
+    data: any,
+    targetClass: Type<any>,
+    handlerMethod: Function
+  ) {
+    this.resetRpc(ctx, data);
+    this.targetClass = targetClass;
+    this.handlerMethod = handlerMethod;
+  }
+
   clearContext() {
     this.clear();
     this.targetClass = null as any;

package/src/lifecycle/interfaces.ts

@@ -4,6 +4,9 @@ export interface ArgumentsHost {
   getArgs<T extends any[] = any[]>(): T;
   getArgByIndex<T = any>(index: number): T;
   switchToHttp(): HttpArgumentsHost;
+  switchToWs(): any;
+  switchToRpc(): any;
+  getType<TContextType extends string = string>(): TContextType;
 }
 
 export interface HttpArgumentsHost {

package/src/microservices/client-proxy.ts

@@ -0,0 +1,7 @@
+import { Observable } from 'rxjs';
+
+export abstract class ClientProxy {
+  abstract send<TResult = any, TInput = any>(pattern: any, data: TInput): Observable<TResult>;
+  abstract emit<TResult = any, TInput = any>(pattern: any, data: TInput): Observable<TResult>;
+  abstract close(): void;
+}