@martel/calyx 1.11.0 → 1.12.0

package/src/security/index.ts

@@ -1,3 +1,4 @@
 export * from './hashing.service.ts';
 export * from './cors.middleware.ts';
 export * from './helmet.middleware.ts';
+export * from './throttler.module.ts';

package/src/security/throttler.module.ts

@@ -0,0 +1,108 @@
+import { Module, DynamicModule, Injectable, Inject } from '../core/decorators.ts';
+import { CanActivate, ExecutionContext } from '../lifecycle/interfaces.ts';
+import { HttpException } from '../http/exceptions.ts';
+
+export const THROTTLE_LIMIT_KEY = 'throttler:limit';
+export const THROTTLE_SKIP_KEY = 'throttler:skip';
+
+export const Throttle = (limit: number, ttl: number) => (target: any, key?: string | symbol, descriptor?: any) => {
+  if (descriptor) {
+    Reflect.defineMetadata(THROTTLE_LIMIT_KEY, { limit, ttl }, descriptor.value);
+    return descriptor;
+  }
+  Reflect.defineMetadata(THROTTLE_LIMIT_KEY, { limit, ttl }, target);
+  return target;
+};
+
+export const SkipThrottle = (skip = true) => (target: any, key?: string | symbol, descriptor?: any) => {
+  if (descriptor) {
+    Reflect.defineMetadata(THROTTLE_SKIP_KEY, skip, descriptor.value);
+    return descriptor;
+  }
+  Reflect.defineMetadata(THROTTLE_SKIP_KEY, skip, target);
+  return target;
+};
+
+export interface ThrottlerModuleOptions {
+  limit?: number;
+  ttl?: number;
+}
+
+@Injectable()
+export class ThrottlerStorage {
+  private records = new Map<string, { count: number; expiresAt: number }>();
+
+  increment(key: string, ttlSeconds: number): { count: number; expiresAt: number } {
+    const now = Date.now();
+    const record = this.records.get(key);
+    if (!record || record.expiresAt < now) {
+      const newRecord = { count: 1, expiresAt: now + ttlSeconds * 1000 };
+      this.records.set(key, newRecord);
+      return newRecord;
+    }
+    record.count++;
+    return record;
+  }
+}
+
+@Injectable()
+export class ThrottlerGuard implements CanActivate {
+  constructor(
+    @Inject('THROTTLER_OPTIONS')
+    private readonly options: ThrottlerModuleOptions,
+    private readonly storage: ThrottlerStorage
+  ) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const handler = context.getHandler();
+    const controller = context.getClass();
+
+    const skipHandler = Reflect.getMetadata(THROTTLE_SKIP_KEY, handler);
+    if (skipHandler === true) return true;
+    const skipController = Reflect.getMetadata(THROTTLE_SKIP_KEY, controller);
+    if (skipController === true) return true;
+
+    const limitMeta = Reflect.getMetadata(THROTTLE_LIMIT_KEY, handler) ||
+                      Reflect.getMetadata(THROTTLE_LIMIT_KEY, controller) ||
+                      this.options;
+
+    const limit = limitMeta.limit ?? 10;
+    const ttl = limitMeta.ttl ?? 60;
+
+    const type = context.getType();
+    if (type !== 'http') return true;
+
+    const req = context.switchToHttp().getRequest<Request>();
+    const ip = req.headers.get('x-forwarded-for') || '';
+    const url = new URL(req.url);
+    const key = `throttle::${ip}::${url.pathname}`;
+
+    const record = this.storage.increment(key, ttl);
+    if (record.count > limit) {
+      throw new HttpException({
+        statusCode: 429,
+        message: 'ThrottlerException: Too Many Requests',
+      }, 429);
+    }
+
+    return true;
+  }
+}
+
+@Module({})
+export class ThrottlerModule {
+  static register(options: ThrottlerModuleOptions = {}): DynamicModule {
+    return {
+      module: ThrottlerModule,
+      providers: [
+        {
+          provide: 'THROTTLER_OPTIONS',
+          useValue: options,
+        },
+        ThrottlerStorage,
+        ThrottlerGuard,
+      ],
+      exports: [ThrottlerStorage, ThrottlerGuard],
+    };
+  }
+}

package/src/terminus/terminus.ts

@@ -0,0 +1,61 @@
+import { Injectable, Module, SetMetadata } from '../core/decorators.ts';
+import { HttpException } from '../http/exceptions.ts';
+
+export const HEALTH_CHECK_KEY = 'terminus:healthcheck';
+export const HealthCheck = () => SetMetadata(HEALTH_CHECK_KEY, true);
+
+@Injectable()
+export class HealthCheckService {
+  async check(indicators: (() => Promise<any> | any)[]): Promise<any> {
+    const info: Record<string, any> = {};
+    const error: Record<string, any> = {};
+    let isHealthy = true;
+
+    for (const indicator of indicators) {
+      try {
+        const result = await indicator();
+        Object.assign(info, result);
+      } catch (err: any) {
+        isHealthy = false;
+        Object.assign(error, err.payload || { [err.message || 'unknown']: { status: 'down' } });
+      }
+    }
+
+    const status = isHealthy ? 'ok' : 'error';
+    const responsePayload = {
+      status,
+      info: isHealthy ? info : {},
+      error: !isHealthy ? error : {},
+      details: { ...info, ...error },
+    };
+
+    if (!isHealthy) {
+      throw new HttpException(responsePayload, 503);
+    }
+    return responsePayload;
+  }
+}
+
+@Injectable()
+export class HttpHealthIndicator {
+  async pingCheck(key: string, url: string): Promise<any> {
+    try {
+      const res = await fetch(url);
+      if (!res.ok) {
+        throw new Error(`Response status code ${res.status}`);
+      }
+      return { [key]: { status: 'up' } };
+    } catch (err: any) {
+      const payload = { [key]: { status: 'down', message: err.message } };
+      const error: any = new Error(`Health check failed for URL: ${url}`);
+      error.payload = payload;
+      throw error;
+    }
+  }
+}
+
+@Module({
+  providers: [HealthCheckService, HttpHealthIndicator],
+  exports: [HealthCheckService, HttpHealthIndicator],
+})
+export class TerminusModule {}

package/src/validation/http-pipes.ts

@@ -0,0 +1,128 @@
+import { PipeTransform, ArgumentMetadata } from '../lifecycle/interfaces.ts';
+import { Injectable } from '../core/decorators.ts';
+import { HttpException } from '../http/exceptions.ts';
+
+@Injectable()
+export class ParseIntPipe implements PipeTransform<string | number, number> {
+  transform(value: string | number, metadata: ArgumentMetadata): number {
+    const val = typeof value === 'string' ? parseInt(value, 10) : value;
+    if (isNaN(val)) {
+      throw new HttpException(`Validation failed (numeric string is expected) for parameter "${metadata.data ?? ''}"`, 400);
+    }
+    return val;
+  }
+}
+
+@Injectable()
+export class ParseFloatPipe implements PipeTransform<string | number, number> {
+  transform(value: string | number, metadata: ArgumentMetadata): number {
+    const val = typeof value === 'string' ? parseFloat(value) : value;
+    if (isNaN(val)) {
+      throw new HttpException(`Validation failed (float string is expected) for parameter "${metadata.data ?? ''}"`, 400);
+    }
+    return val;
+  }
+}
+
+@Injectable()
+export class ParseBoolPipe implements PipeTransform<string | boolean, boolean> {
+  transform(value: string | boolean, metadata: ArgumentMetadata): boolean {
+    if (value === true || value === 'true') return true;
+    if (value === false || value === 'false') return false;
+    throw new HttpException(`Validation failed (boolean string is expected) for parameter "${metadata.data ?? ''}"`, 400);
+  }
+}
+
+export interface ParseArrayOptions {
+  items?: any;
+  separator?: string;
+  optional?: boolean;
+}
+
+@Injectable()
+export class ParseArrayPipe implements PipeTransform {
+  constructor(private readonly options: ParseArrayOptions = {}) {}
+
+  transform(value: any, metadata: ArgumentMetadata): any[] {
+    if (value === undefined || value === null) {
+      if (this.options.optional) return [];
+      throw new HttpException(`Validation failed (array is expected) for parameter "${metadata.data ?? ''}"`, 400);
+    }
+    const separator = this.options.separator ?? ',';
+    let arr: any[] = [];
+    if (typeof value === 'string') {
+      arr = value.split(separator);
+    } else if (Array.isArray(value)) {
+      arr = value;
+    } else {
+      throw new HttpException(`Validation failed (array is expected) for parameter "${metadata.data ?? ''}"`, 400);
+    }
+
+    if (this.options.items) {
+      const type = this.options.items;
+      arr = arr.map((item) => {
+        if (type === Number) {
+          const val = Number(item);
+          if (isNaN(val)) throw new HttpException(`Validation failed (array of numbers is expected) for parameter "${metadata.data ?? ''}"`, 400);
+          return val;
+        }
+        if (type === Boolean) {
+          if (item === true || item === 'true') return true;
+          if (item === false || item === 'false') return false;
+          throw new HttpException(`Validation failed (array of booleans is expected) for parameter "${metadata.data ?? ''}"`, 400);
+        }
+        return item;
+      });
+    }
+    return arr;
+  }
+}
+
+@Injectable()
+export class ParseUUIDPipe implements PipeTransform<string, string> {
+  private static readonly uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+  transform(value: string, metadata: ArgumentMetadata): string {
+    if (typeof value !== 'string' || !ParseUUIDPipe.uuidRegex.test(value)) {
+      throw new HttpException(`Validation failed (uuid string is expected) for parameter "${metadata.data ?? ''}"`, 400);
+    }
+    return value;
+  }
+}
+
+@Injectable()
+export class ParseEnumPipe implements PipeTransform {
+  constructor(private readonly enumType: any) {}
+
+  transform(value: any, metadata: ArgumentMetadata): any {
+    const values = Object.values(this.enumType);
+    if (!values.includes(value)) {
+      throw new HttpException(`Validation failed (enum value is expected) for parameter "${metadata.data ?? ''}"`, 400);
+    }
+    return value;
+  }
+}
+
+@Injectable()
+export class ParseFilePipe implements PipeTransform {
+  constructor(private readonly validators: any[] = []) {}
+
+  transform(value: any, metadata: ArgumentMetadata): any {
+    if (!value || (typeof value === 'object' && !value.buffer)) {
+      throw new HttpException(`Validation failed (file is expected) for parameter "${metadata.data ?? ''}"`, 400);
+    }
+    return value;
+  }
+}
+
+@Injectable()
+export class DefaultValuePipe implements PipeTransform {
+  constructor(private readonly defaultValue: any) {}
+
+  transform(value: any, metadata: ArgumentMetadata): any {
+    if (value === undefined || value === null || value === '') {
+      return this.defaultValue;
+    }
+    return value;
+  }
+}

package/src/validation/index.ts

@@ -1,3 +1,4 @@
 export * from './decorators.ts';
 export * from './compiler.ts';
 export * from './pipe.ts';
+export * from './http-pipes.ts';

package/src/websockets/decorators.ts

@@ -28,12 +28,22 @@ export function SubscribeMessage(event: string): MethodDecorator {
   };
 }
 
-export function MessageBody(): ParameterDecorator {
+export function MessageBody(first?: any, ...pipes: any[]): ParameterDecorator {
   return (target, propertyKey, parameterIndex) => {
     if (!propertyKey) return;
     const constructor = target.constructor;
+
+    let name: string | undefined = undefined;
+    let parsedPipes: any[] = [];
+    if (typeof first === 'string') {
+      name = first;
+      parsedPipes = pipes;
+    } else if (first !== undefined) {
+      parsedPipes = [first, ...pipes];
+    }
+
     const existing = Reflect.getOwnMetadata('calyx:message_body', constructor) || [];
-    existing.push({ propertyKey, parameterIndex });
+    existing.push({ propertyKey, parameterIndex, name, pipes: parsedPipes });
     Reflect.defineMetadata('calyx:message_body', existing, constructor);
   };
 }

package/tests/nestjs-parity.test.ts

@@ -0,0 +1,272 @@
+import { expect, test, describe } from 'bun:test';
+import {
+  Test,
+  LazyModuleLoader,
+  Injectable,
+  Module,
+  ParseIntPipe,
+  ParseBoolPipe,
+  CalyxResponse,
+  SchedulerRegistry,
+  ScheduleModule,
+  Cron,
+  Interval,
+  CacheKey,
+  CacheTTL,
+  Client,
+  ClientsModule,
+  HealthCheckService,
+  TerminusModule,
+  CqrsModule,
+  CommandBus,
+  QueryBus,
+  EventBus,
+  CommandHandler,
+  QueryHandler,
+  EventsHandler,
+  ICommand,
+  IQuery,
+  IEvent,
+  ICommandHandler,
+  IQueryHandler,
+  IEventHandler,
+} from '../src/index.ts';
+
+@Injectable()
+class DummyService {
+  getValue() { return 'dummy'; }
+}
+
+@Injectable()
+class AliasService {
+  constructor(public readonly dummy: DummyService) {}
+}
+
+@Module({
+  providers: [
+    DummyService,
+    {
+      provide: 'ALIAS_TOKEN',
+      useExisting: DummyService,
+    },
+    AliasService,
+  ],
+})
+class TestParityModule {}
+
+describe('NestJS Parity Extensions', () => {
+
+  test('DI: useExisting alias provider resolution', async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [TestParityModule],
+    }).compile();
+
+    const dummy = moduleRef.get(DummyService);
+    const alias = moduleRef.get('ALIAS_TOKEN');
+    expect(dummy).toBe(alias);
+    expect(dummy.getValue()).toBe('dummy');
+    await moduleRef.close();
+  });
+
+  test('DI: Test/TestingModule overrides', async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [TestParityModule],
+    })
+    .overrideProvider(DummyService)
+    .useValue({ getValue: () => 'mocked' })
+    .compile();
+
+    const dummy = moduleRef.get(DummyService);
+    expect(dummy.getValue()).toBe('mocked');
+    await moduleRef.close();
+  });
+
+  test('DI: LazyModuleLoader', async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [],
+      providers: [LazyModuleLoader],
+    }).compile();
+
+    const loader = moduleRef.get(LazyModuleLoader);
+    const lazyModuleRef = await loader.load(() => Promise.resolve(TestParityModule));
+    expect(lazyModuleRef).toBeDefined();
+
+    const dummy = lazyModuleRef.get(DummyService);
+    expect(dummy.getValue()).toBe('dummy');
+    await moduleRef.close();
+  });
+
+  test('Pipes: built-in parsing pipes', () => {
+    const intPipe = new ParseIntPipe();
+    expect(intPipe.transform('42', { type: 'query', data: 'id' })).toBe(42);
+    expect(() => intPipe.transform('abc', { type: 'query', data: 'id' })).toThrow();
+
+    const boolPipe = new ParseBoolPipe();
+    expect(boolPipe.transform('true', { type: 'query', data: 'flag' })).toBe(true);
+    expect(boolPipe.transform('false', { type: 'query', data: 'flag' })).toBe(false);
+    expect(() => boolPipe.transform('abc', { type: 'query', data: 'flag' })).toThrow();
+  });
+
+  test('CalyxResponse compatibility methods', () => {
+    const res = new CalyxResponse();
+    res.header('X-Test', 'value')
+       .type('text/html')
+       .cookie('cookie_name', 'cookie_val')
+       .append('X-Test', 'another');
+
+    expect(res.get('x-test')).toBe('value, another');
+    expect(res.get('content-type')).toBe('text/html');
+  });
+
+  test('SchedulerRegistry named dynamic tasks', async () => {
+    @Injectable()
+    class ScheduledTasks {
+      @Cron('* * * * * *', { name: 'my-cron' })
+      runCron() {}
+
+      @Interval('my-interval', 1000)
+      runInterval() {}
+    }
+
+    @Module({
+      imports: [ScheduleModule.forRoot()],
+      providers: [ScheduledTasks],
+    })
+    class RootScheduleModule {}
+
+    const moduleRef = await Test.createTestingModule({
+      imports: [RootScheduleModule],
+    }).compile();
+
+    const app = moduleRef.createCalyxApplication();
+    await app.init();
+
+    const registry = moduleRef.get(SchedulerRegistry);
+    expect(registry.getCronJob('my-cron')).toBeDefined();
+    expect(registry.getInterval('my-interval')).toBeDefined();
+
+    registry.deleteCronJob('my-cron');
+    registry.deleteInterval('my-interval');
+
+    expect(() => registry.getCronJob('my-cron')).toThrow();
+    expect(() => registry.getInterval('my-interval')).toThrow();
+
+    await app.close();
+    await moduleRef.close();
+  });
+
+  test('CacheInterceptor key/ttl retrieval', () => {
+    class Target {
+      @CacheKey('custom_key')
+      @CacheTTL(100)
+      handler() {}
+    }
+
+    const t = new Target();
+    const key = Reflect.getMetadata('cache_metadata_key', t.handler);
+    const ttl = Reflect.getMetadata('cache_metadata_ttl', t.handler);
+
+    expect(key).toBe('custom_key');
+    expect(ttl).toBe(100);
+  });
+
+  test('Microservice clients: @Client and ClientsModule', async () => {
+    class Target {
+      @Client({ options: { host: '127.0.0.1', port: 1234 } })
+      client: any;
+    }
+
+    const target = new Target();
+    expect(target.client).toBeDefined();
+
+    const moduleRef = await Test.createTestingModule({
+      imports: [
+        ClientsModule.register([
+          { name: 'TEST_SERVICE', options: { host: 'localhost', port: 5000 } },
+        ]),
+      ],
+    }).compile();
+
+    const service = moduleRef.get('TEST_SERVICE');
+    expect(service).toBeDefined();
+    await moduleRef.close();
+  });
+
+  test('CQRS command/query/event buses', async () => {
+    class MyCommand implements ICommand {}
+    class MyQuery implements IQuery {}
+    class MyEvent implements IEvent {}
+
+    let commandHandled = false;
+    let queryHandled = false;
+    let eventHandledCount = 0;
+
+    @CommandHandler(MyCommand)
+    class MyCommandHandler implements ICommandHandler<MyCommand> {
+      async execute(command: MyCommand) {
+        commandHandled = true;
+        return 'command-result';
+      }
+    }
+
+    @QueryHandler(MyQuery)
+    class MyQueryHandler implements IQueryHandler<MyQuery> {
+      async execute(query: MyQuery) {
+        queryHandled = true;
+        return 'query-result';
+      }
+    }
+
+    @EventsHandler(MyEvent)
+    class MyEventHandler implements IEventHandler<MyEvent> {
+      handle(event: MyEvent) {
+        eventHandledCount++;
+      }
+    }
+
+    const moduleRef = await Test.createTestingModule({
+      imports: [CqrsModule],
+      providers: [MyCommandHandler, MyQueryHandler, MyEventHandler],
+    }).compile();
+
+    const commandBus = moduleRef.get(CommandBus);
+    const queryBus = moduleRef.get(QueryBus);
+    const eventBus = moduleRef.get(EventBus);
+
+    const cqrsModule = moduleRef.get(CqrsModule);
+    (cqrsModule as any).onModuleInit();
+
+    const cmdRes = await commandBus.execute(new MyCommand());
+    expect(cmdRes).toBe('command-result');
+    expect(commandHandled).toBe(true);
+
+    const qryRes = await queryBus.execute(new MyQuery());
+    expect(qryRes).toBe('query-result');
+    expect(queryHandled).toBe(true);
+
+    eventBus.publish(new MyEvent());
+    expect(eventHandledCount).toBe(1);
+
+    await moduleRef.close();
+  });
+
+  test('Terminus health check service', async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [TerminusModule],
+    }).compile();
+
+    const health = moduleRef.get(HealthCheckService);
+    const res = await health.check([
+      () => ({ db: { status: 'up' } }),
+    ]);
+
+    expect(res.status).toBe('ok');
+    expect(res.details.db.status).toBe('up');
+
+    expect(health.check([
+      () => { throw new Error('DB connection lost'); }
+    ])).rejects.toThrow();
+
+    await moduleRef.close();
+  });
+});