@martel/calyx 1.5.0 → 1.7.0

package/src/websockets/decorators.ts

@@ -0,0 +1,49 @@
+import 'reflect-metadata';
+
+export interface GatewayMetadata {
+  port?: number;
+  namespace?: string;
+  cors?: any;
+}
+
+export function WebSocketGateway(portOrOptions?: number | GatewayMetadata): ClassDecorator {
+  return (target) => {
+    let metadata: GatewayMetadata = {};
+    if (typeof portOrOptions === 'number') {
+      metadata.port = portOrOptions;
+    } else if (portOrOptions) {
+      metadata = portOrOptions;
+    }
+    Reflect.defineMetadata('calyx:websocket_gateway', metadata, target);
+    Reflect.defineMetadata('calyx:injectable', true, target);
+  };
+}
+
+export function SubscribeMessage(event: string): MethodDecorator {
+  return (target, propertyKey) => {
+    const constructor = target.constructor;
+    const existing = Reflect.getOwnMetadata('calyx:subscribe_message', constructor) || [];
+    existing.push({ event, propertyKey });
+    Reflect.defineMetadata('calyx:subscribe_message', existing, constructor);
+  };
+}
+
+export function MessageBody(): ParameterDecorator {
+  return (target, propertyKey, parameterIndex) => {
+    if (!propertyKey) return;
+    const constructor = target.constructor;
+    const existing = Reflect.getOwnMetadata('calyx:message_body', constructor) || [];
+    existing.push({ propertyKey, parameterIndex });
+    Reflect.defineMetadata('calyx:message_body', existing, constructor);
+  };
+}
+
+export function ConnectedSocket(): ParameterDecorator {
+  return (target, propertyKey, parameterIndex) => {
+    if (!propertyKey) return;
+    const constructor = target.constructor;
+    const existing = Reflect.getOwnMetadata('calyx:connected_socket', constructor) || [];
+    existing.push({ propertyKey, parameterIndex });
+    Reflect.defineMetadata('calyx:connected_socket', existing, constructor);
+  };
+}

package/src/websockets/gateway.ts

@@ -0,0 +1,11 @@
+export interface OnGatewayInit {
+  afterInit(server: any): void;
+}
+
+export interface OnGatewayConnection {
+  handleConnection(client: any, ...args: any[]): void;
+}
+
+export interface OnGatewayDisconnect {
+  handleDisconnect(client: any): void;
+}

package/src/websockets/index.ts

@@ -0,0 +1,2 @@
+export * from './decorators.ts';
+export * from './gateway.ts';

package/tests/cache.test.ts

@@ -0,0 +1,93 @@
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import {
+  Module,
+  Controller,
+  Get,
+  CalyxFactory,
+  CacheModule,
+  CacheService,
+  CacheInterceptor,
+  UseInterceptors,
+} from '../src/index.ts';
+
+let calculateCalls = 0;
+
+@Controller('math')
+class MathController {
+  constructor(private readonly cache: CacheService) {}
+
+  @Get('slow-calc')
+  @UseInterceptors(CacheInterceptor)
+  slowCalculation() {
+    calculateCalls++;
+    return { result: 42, count: calculateCalls };
+  }
+}
+
+@Module({
+  imports: [CacheModule.register({ defaultTtl: 1 })], // 1 second TTL
+  controllers: [MathController],
+})
+class TestApp {}
+
+describe('SQLite Caching (CacheModule, CacheService, CacheInterceptor)', () => {
+  let app: any;
+  let baseUrl: string;
+  const PORT = 3918;
+
+  beforeAll(async () => {
+    calculateCalls = 0;
+    app = await CalyxFactory.create(TestApp);
+    await app.listen(PORT);
+    baseUrl = `http://localhost:${PORT}`;
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('should set, get, and del values directly using CacheService', async () => {
+    const cacheService = app.container.getGlobalOrAnyInstance(CacheService);
+
+    await cacheService.set('foo', 'bar');
+    expect(await cacheService.get('foo')).toBe('bar');
+
+    await cacheService.del('foo');
+    expect(await cacheService.get('foo')).toBeUndefined();
+  });
+
+  test('should expire cached key after TTL expires', async () => {
+    const cacheService = app.container.getGlobalOrAnyInstance(CacheService);
+
+    await cacheService.set('expire_test', { val: 123 }, 1); // 1 second TTL
+    expect(await cacheService.get('expire_test')).toEqual({ val: 123 });
+
+    // Wait 1.1s
+    await new Promise((resolve) => setTimeout(resolve, 1100));
+    expect(await cacheService.get('expire_test')).toBeUndefined();
+  });
+
+  test('should cache GET route response and short-circuit subsequent requests', async () => {
+    // 1. First call -> should execute handler
+    const res1 = await fetch(`${baseUrl}/math/slow-calc`);
+    expect(res1.status).toBe(200);
+    const body1 = await res1.json();
+    expect(body1).toEqual({ result: 42, count: 1 });
+    expect(calculateCalls).toBe(1);
+
+    // 2. Second call -> should return cached response (calculateCalls remains 1)
+    const res2 = await fetch(`${baseUrl}/math/slow-calc`);
+    expect(res2.status).toBe(200);
+    const body2 = await res2.json();
+    expect(body2).toEqual({ result: 42, count: 1 });
+    expect(calculateCalls).toBe(1);
+
+    // 3. Wait 1.1s for cache to expire, then call again -> should execute handler again
+    await new Promise((resolve) => setTimeout(resolve, 1100));
+    const res3 = await fetch(`${baseUrl}/math/slow-calc`);
+    expect(res3.status).toBe(200);
+    const body3 = await res3.json();
+    expect(body3).toEqual({ result: 42, count: 2 });
+    expect(calculateCalls).toBe(2);
+  });
+});

package/tests/microservices.test.ts

@@ -0,0 +1,105 @@
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { of, Observable } from 'rxjs';
+import {
+  Module,
+  Controller,
+  CalyxFactory,
+  MessagePattern,
+  EventPattern,
+  ClientTcp,
+  Transport,
+} from '../src/index.ts';
+
+let eventReceived = false;
+let eventPayload: any = null;
+
+@Controller()
+class MathController {
+  @MessagePattern('sum')
+  accumulate(data: number[]): number {
+    return (data || []).reduce((a, b) => a + b, 0);
+  }
+
+  @MessagePattern('stream')
+  streamData(data: string): Observable<string> {
+    return of(`echo1: ${data}`, `echo2: ${data}`);
+  }
+
+  @MessagePattern('error_test')
+  throwError(data: any) {
+    throw new Error('This is a simulated RPC error');
+  }
+
+  @EventPattern('log_event')
+  handleLogEvent(data: any) {
+    eventReceived = true;
+    eventPayload = data;
+  }
+}
+
+@Module({
+  controllers: [MathController],
+})
+class MicroserviceModule {}
+
+describe('TCP Microservices (ClientTcp, ServerTcp, MessagePattern, EventPattern)', () => {
+  let server: any;
+  let client: ClientTcp;
+  const PORT = 3899;
+
+  beforeAll(async () => {
+    // 1. Create and start microservice server
+    server = await CalyxFactory.createMicroservice(MicroserviceModule, {
+      transport: Transport.TCP,
+      options: { port: PORT },
+    });
+    await server.listen();
+
+    // 2. Initialize client
+    client = new ClientTcp({ port: PORT });
+  });
+
+  afterAll(async () => {
+    client.close();
+    await server.close();
+  });
+
+  test('should exchange request-response message and calculate sum', async () => {
+    const res = await client.send<number, number[]>('sum', [1, 2, 3, 4]).toPromise();
+    expect(res).toBe(10);
+  });
+
+  test('should handle streaming response from RxJS Observable', async () => {
+    const results: string[] = [];
+    await new Promise<void>((resolve, reject) => {
+      client.send<string, string>('stream', 'hello').subscribe({
+        next: (val) => results.push(val),
+        error: (err) => reject(err),
+        complete: () => resolve(),
+      });
+    });
+    expect(results).toEqual(['echo1: hello', 'echo2: hello']);
+  });
+
+  test('should propagate error message from RPC back to client', async () => {
+    try {
+      await client.send('error_test', {}).toPromise();
+      expect().fail('Expected send to throw error');
+    } catch (err: any) {
+      expect(err.message).toBe('This is a simulated RPC error');
+    }
+  });
+
+  test('should dispatch event pattern messages asynchronously', async () => {
+    eventReceived = false;
+    eventPayload = null;
+
+    await client.emit('log_event', { status: 'ok', code: 200 }).toPromise();
+
+    // Wait a tick for TCP event handling
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(eventReceived).toBe(true);
+    expect(eventPayload).toEqual({ status: 'ok', code: 200 });
+  });
+});

package/tests/rpc-ws-context.test.ts

@@ -0,0 +1,135 @@
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { of, Observable } from 'rxjs';
+import {
+  Module,
+  CalyxFactory,
+  WebSocketGateway,
+  SubscribeMessage,
+  MessageBody,
+  UseGuards,
+  UseInterceptors,
+  CanActivate,
+  ExecutionContext,
+  NestInterceptor,
+  CallHandler,
+  ClientTcp,
+  Transport,
+  MessagePattern,
+  Controller,
+} from '../src/index.ts';
+
+class SecurityGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    const type = context.getType();
+    if (type === 'ws') {
+      const data = context.switchToWs().getData();
+      return data.user === 'admin';
+    }
+    if (type === 'rpc') {
+      const data = context.switchToRpc().getData();
+      return data.role === 'admin';
+    }
+    return false;
+  }
+}
+
+class LoggingInterceptor implements NestInterceptor {
+  async intercept(context: ExecutionContext, next: CallHandler): Promise<any> {
+    const type = context.getType();
+    const result = await next.handle();
+    return { type, original: result };
+  }
+}
+
+@WebSocketGateway(3915)
+class SecureGateway {
+  @SubscribeMessage('ping')
+  @UseGuards(SecurityGuard)
+  @UseInterceptors(LoggingInterceptor)
+  handlePing(@MessageBody() data: any) {
+    return 'pong';
+  }
+}
+
+@Controller()
+class SecureController {
+  @MessagePattern('ping_rpc')
+  @UseGuards(SecurityGuard)
+  @UseInterceptors(LoggingInterceptor)
+  handlePingRpc(data: any) {
+    return 'pong_rpc';
+  }
+}
+
+@Module({
+  controllers: [SecureController],
+  providers: [SecureGateway],
+})
+class TestApp {}
+
+describe('Guards and Interceptors for WS and RPC contexts', () => {
+  let wsApp: any;
+  let rpcApp: any;
+  let client: ClientTcp;
+  const PORT = 3889;
+  const RPC_PORT = 3916;
+
+  beforeAll(async () => {
+    // 1. Start standard app for HTTP/WS
+    wsApp = await CalyxFactory.create(TestApp);
+    await wsApp.listen(PORT);
+
+    // 2. Start dedicated microservice for RPC
+    rpcApp = await CalyxFactory.createMicroservice(TestApp, {
+      transport: Transport.TCP,
+      options: { port: RPC_PORT },
+    });
+    await rpcApp.listen();
+
+    client = new ClientTcp({ port: RPC_PORT });
+  });
+
+  afterAll(async () => {
+    client.close();
+    await rpcApp.close();
+    await wsApp.close();
+  });
+
+  test('should pass or deny WS events using context switching in guards/interceptors', async () => {
+    const ws = new WebSocket('ws://localhost:3915');
+
+    await new Promise<void>((resolve, reject) => {
+      ws.onopen = () => resolve();
+      ws.onerror = (err) => reject(err);
+    });
+
+    ws.send(JSON.stringify({ event: 'ping', data: { user: 'admin' } }));
+    const successRes = await new Promise<any>((resolve) => {
+      ws.onmessage = (event) => resolve(JSON.parse(event.data));
+    });
+    expect(successRes).toEqual({ type: 'ws', original: 'pong' });
+
+    let receivedMessage = false;
+    ws.onmessage = () => {
+      receivedMessage = true;
+    };
+    ws.send(JSON.stringify({ event: 'ping', data: { user: 'guest' } }));
+    
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    expect(receivedMessage).toBe(false);
+
+    ws.close();
+  });
+
+  test('should pass or deny RPC messages using context switching in guards/interceptors', async () => {
+    const successRes = await client.send('ping_rpc', { role: 'admin' }).toPromise();
+    expect(successRes).toEqual({ type: 'rpc', original: 'pong_rpc' });
+
+    try {
+      await client.send('ping_rpc', { role: 'guest' }).toPromise();
+      expect().fail('Expected send to throw error');
+    } catch (err: any) {
+      expect(err.message).toBe('Forbidden resource');
+    }
+  });
+});

package/tests/validation-serialization.test.ts

@@ -0,0 +1,134 @@
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import {
+  Module,
+  Controller,
+  Post,
+  Body,
+  CalyxFactory,
+  IsString,
+  IsNumber,
+  IsEmail,
+  IsOptional,
+  Exclude,
+  Expose,
+  ValidationPipe,
+  UsePipes,
+} from '../src/index.ts';
+
+// 1. DTO for Request Validation
+class CreateUserDto {
+  @IsString()
+  name!: string;
+
+  @IsNumber()
+  age!: number;
+
+  @IsEmail()
+  email!: string;
+
+  @IsOptional()
+  @IsString()
+  bio?: string;
+}
+
+// 2. DTO for Response Serialization
+class UserResponseDto {
+  @Expose()
+  id: number;
+
+  @Expose()
+  username: string;
+
+  @Exclude()
+  passwordHash: string;
+
+  constructor(id: number, username: string, passwordHash: string) {
+    this.id = id;
+    this.username = username;
+    this.passwordHash = passwordHash;
+  }
+}
+
+@Controller('users')
+class UsersController {
+  @Post('validate')
+  @UsePipes(ValidationPipe)
+  createUser(@Body() dto: CreateUserDto) {
+    return { received: true, dto };
+  }
+
+  @Post('serialize')
+  getUserResponse() {
+    return new UserResponseDto(123, 'alice', 'super_secret_sha256_hash');
+  }
+}
+
+@Module({
+  controllers: [UsersController],
+})
+class TestApp {}
+
+describe('JIT Validation and Response Serialization', () => {
+  let app: any;
+  let baseUrl: string;
+  const PORT = 3922;
+
+  beforeAll(async () => {
+    app = await CalyxFactory.create(TestApp);
+    await app.listen(PORT);
+    baseUrl = `http://localhost:${PORT}`;
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('should pass validation for valid payload', async () => {
+    const res = await fetch(`${baseUrl}/users/validate`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        name: 'Bob',
+        age: 25,
+        email: 'bob@example.com',
+      }),
+    });
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    expect(body.received).toBe(true);
+    expect(body.dto).toEqual({
+      name: 'Bob',
+      age: 25,
+      email: 'bob@example.com',
+    });
+  });
+
+  test('should fail validation and return 400 with list of errors for invalid payload', async () => {
+    const res = await fetch(`${baseUrl}/users/validate`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        name: 123, // Should be string
+        email: 'invalid-email', // Missing @
+      }),
+    });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.message).toBe('Validation failed');
+    expect(body.errors).toContain('name must be a string');
+    expect(body.errors).toContain('age should not be empty');
+    expect(body.errors).toContain('email must be a valid email');
+  });
+
+  test('should serialize response using JIT serializer and exclude excluded fields', async () => {
+    const res = await fetch(`${baseUrl}/users/serialize`, {
+      method: 'POST',
+    });
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    // Excluded fields should be missing, exposed should be present
+    expect(body.id).toBe(123);
+    expect(body.username).toBe('alice');
+    expect(body.passwordHash).toBeUndefined();
+  });
+});

package/tests/websockets.test.ts

@@ -0,0 +1,125 @@
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import {
+  Module,
+  CalyxFactory,
+  WebSocketGateway,
+  SubscribeMessage,
+  MessageBody,
+  ConnectedSocket,
+} from '../src/index.ts';
+
+let clientConnected = false;
+let clientDisconnected = false;
+let messageReceived: any = null;
+
+// 1. Shared Port Gateway
+@WebSocketGateway()
+class SharedEventsGateway {
+  handleConnection(client: any) {
+    clientConnected = true;
+  }
+
+  handleDisconnect(client: any) {
+    clientDisconnected = true;
+  }
+
+  @SubscribeMessage('events')
+  onEvents(@MessageBody() data: any, @ConnectedSocket() client: any) {
+    messageReceived = data;
+    return { event: 'events', data: `echo: ${data}` };
+  }
+}
+
+// 2. Dedicated Port Gateway
+let dedicatedConnected = false;
+@WebSocketGateway(3912)
+class DedicatedEventsGateway {
+  handleConnection(client: any) {
+    dedicatedConnected = true;
+  }
+
+  @SubscribeMessage('dedicated_event')
+  onDedicatedEvent(@MessageBody() data: any) {
+    return { event: 'dedicated_response', data: `dedicated echo: ${data}` };
+  }
+}
+
+@Module({
+  providers: [SharedEventsGateway, DedicatedEventsGateway],
+})
+class TestApp {}
+
+describe('WebSocket Gateways (Bun.serve, SubscribeMessage, MessageBody, ConnectedSocket)', () => {
+  let app: any;
+  const PORT = 3889;
+
+  beforeAll(async () => {
+    app = await CalyxFactory.create(TestApp);
+    await app.listen(PORT);
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('should connect and handle message exchange on shared port', async () => {
+    clientConnected = false;
+    clientDisconnected = false;
+    messageReceived = null;
+
+    const ws = new WebSocket(`ws://localhost:${PORT}`);
+
+    // Wait for connection to open
+    await new Promise<void>((resolve, reject) => {
+      ws.onopen = () => resolve();
+      ws.onerror = (err) => reject(err);
+    });
+
+    expect(clientConnected).toBe(true);
+
+    // Send a message
+    ws.send(JSON.stringify({ event: 'events', data: 'hello calyx' }));
+
+    // Wait for response message
+    const response = await new Promise<any>((resolve) => {
+      ws.onmessage = (event) => {
+        resolve(JSON.parse(event.data));
+      };
+    });
+
+    expect(messageReceived).toBe('hello calyx');
+    expect(response).toEqual({ event: 'events', data: 'echo: hello calyx' });
+
+    // Close connection
+    ws.close();
+
+    // Wait a tick for disconnect event
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(clientDisconnected).toBe(true);
+  });
+
+  test('should connect and handle message exchange on dedicated port', async () => {
+    dedicatedConnected = false;
+
+    const ws = new WebSocket('ws://localhost:3912');
+
+    await new Promise<void>((resolve, reject) => {
+      ws.onopen = () => resolve();
+      ws.onerror = (err) => reject(err);
+    });
+
+    expect(dedicatedConnected).toBe(true);
+
+    ws.send(JSON.stringify({ event: 'dedicated_event', data: 'secure channel' }));
+
+    const response = await new Promise<any>((resolve) => {
+      ws.onmessage = (event) => {
+        resolve(JSON.parse(event.data));
+      };
+    });
+
+    expect(response).toEqual({ event: 'dedicated_response', data: 'dedicated echo: secure channel' });
+
+    ws.close();
+  });
+});