@martel/calyx 1.10.1 → 1.12.0

package/src/microservices/clients.module.ts

@@ -0,0 +1,47 @@
+import { Module, DynamicModule } from '../core/decorators.ts';
+import { ClientTcp } from './client-tcp.ts';
+
+export function Client(options: any): PropertyDecorator {
+  return (target: any, propertyKey: string | symbol) => {
+    let clientInstance: any = null;
+    Object.defineProperty(target, propertyKey, {
+      get() {
+        if (!clientInstance) {
+          clientInstance = new ClientTcp(options?.options || options || {});
+        }
+        return clientInstance;
+      },
+      configurable: true,
+      enumerable: true,
+    });
+  };
+}
+
+export interface ClientProviderConfig {
+  name: string;
+  transport?: any;
+  options?: {
+    host?: string;
+    port?: number;
+  };
+}
+
+@Module({})
+export class ClientsModule {
+  static register(clients: ClientProviderConfig[]): DynamicModule {
+    const providers = clients.map((client) => {
+      return {
+        provide: client.name,
+        useFactory: () => {
+          return new ClientTcp(client.options || {});
+        },
+      };
+    });
+
+    return {
+      module: ClientsModule,
+      providers,
+      exports: clients.map((c) => c.name),
+    };
+  }
+}

package/src/microservices/index.ts

@@ -4,3 +4,4 @@ export * from './client-tcp.ts';
 export * from './decorators.ts';
 export * from './server-tcp.ts';
 export * from './microservice.ts';
+export * from './clients.module.ts';

package/src/microservices/microservice.ts

@@ -31,7 +31,7 @@ export class CalyxMicroservice {
   async listen(): Promise<any> {
     if (this.isListening) return;
 
-    this.container.bootstrap(this.rootModule);
+    await this.container.bootstrap(this.rootModule);
     this.server.registerHandlers(this.container, this.globalGuards, this.globalInterceptors);
 
     const hostInfo = await this.server.listen();

package/src/openapi/swagger.module.ts

@@ -73,20 +73,41 @@ export class SwaggerModule {
       if (document.components.schemas[schemaName]) return;
 
       const props = Reflect.getMetadata('calyx:api_properties', typeClass) || [];
+      const rules = Reflect.getMetadata('calyx:validation_rules', typeClass) || [];
       const schemaProps: Record<string, any> = {};
       const requiredProps: string[] = [];
 
-      for (const p of props) {
-        let pType = 'string';
-        if (p.type) {
-          pType = p.type.name ? p.type.name.toLowerCase() : String(p.type).toLowerCase();
+      const allKeys = new Set<string>();
+      for (const p of props) allKeys.add(p.propertyKey);
+      for (const r of rules) allKeys.add(r.propertyKey);
+
+      for (const key of allKeys) {
+        const p = props.find((x: any) => x.propertyKey === key) || {};
+        const propertyRules = rules.filter((r: any) => r.propertyKey === key);
+
+        let pType = p.type ? (p.type.name ? p.type.name.toLowerCase() : String(p.type).toLowerCase()) : 'string';
+        let format: string | undefined = undefined;
+
+        if (propertyRules.some((r: any) => r.type === 'number')) {
+          pType = 'number';
+        } else if (propertyRules.some((r: any) => r.type === 'string')) {
+          pType = 'string';
+        } else if (propertyRules.some((r: any) => r.type === 'email')) {
+          pType = 'string';
+          format = 'email';
         }
-        schemaProps[p.propertyKey] = {
+
+        schemaProps[key] = {
           type: pType === 'number' || pType === 'boolean' || pType === 'object' || pType === 'array' ? pType : 'string',
-          description: p.description,
+          description: p.description || '',
+          ...(format ? { format } : {}),
         };
-        if (p.required) {
-          requiredProps.push(p.propertyKey);
+
+        const isOptional = propertyRules.some((r: any) => r.type === 'optional');
+        const isRequired = p.required ?? !isOptional;
+
+        if (isRequired) {
+          requiredProps.push(key);
         }
       }
 

package/src/schedule/decorators.ts

@@ -1,28 +1,32 @@
 import 'reflect-metadata';
 
-export function Cron(expression: string): MethodDecorator {
+export function Cron(expression: string, options?: { name?: string }): MethodDecorator {
   return (target, propertyKey) => {
     const constructor = target.constructor;
     const existing = Reflect.getOwnMetadata('calyx:cron', constructor) || [];
-    existing.push({ expression, propertyKey });
+    existing.push({ expression, propertyKey, name: options?.name });
     Reflect.defineMetadata('calyx:cron', existing, constructor);
   };
 }
 
-export function Interval(ms: number): MethodDecorator {
+export function Interval(nameOrMs: string | number, ms?: number): MethodDecorator {
   return (target, propertyKey) => {
     const constructor = target.constructor;
+    const name = typeof nameOrMs === 'string' ? nameOrMs : undefined;
+    const intervalMs = typeof nameOrMs === 'number' ? nameOrMs : ms!;
     const existing = Reflect.getOwnMetadata('calyx:interval', constructor) || [];
-    existing.push({ ms, propertyKey });
+    existing.push({ ms: intervalMs, propertyKey, name });
     Reflect.defineMetadata('calyx:interval', existing, constructor);
   };
 }
 
-export function Timeout(ms: number): MethodDecorator {
+export function Timeout(nameOrMs: string | number, ms?: number): MethodDecorator {
   return (target, propertyKey) => {
     const constructor = target.constructor;
+    const name = typeof nameOrMs === 'string' ? nameOrMs : undefined;
+    const timeoutMs = typeof nameOrMs === 'number' ? nameOrMs : ms!;
     const existing = Reflect.getOwnMetadata('calyx:timeout', constructor) || [];
-    existing.push({ ms, propertyKey });
+    existing.push({ ms: timeoutMs, propertyKey, name });
     Reflect.defineMetadata('calyx:timeout', existing, constructor);
   };
 }

package/src/schedule/index.ts

@@ -1,3 +1,4 @@
 export * from './decorators.ts';
 export * from './schedule.module.ts';
+export * from './scheduler-registry.ts';
 export * from './cron.matcher.ts';

package/src/schedule/schedule.module.ts

@@ -1,12 +1,13 @@
 import { Module, DynamicModule } from '../core/decorators.ts';
+import { SchedulerRegistry } from './scheduler-registry.ts';
 
 @Module({})
 export class ScheduleModule {
   static forRoot(): DynamicModule {
     return {
       module: ScheduleModule,
-      providers: [],
-      exports: [],
+      providers: [SchedulerRegistry],
+      exports: [SchedulerRegistry],
       global: true,
     };
   }

package/src/schedule/scheduler-registry.ts

@@ -0,0 +1,50 @@
+import { Injectable } from '../core/decorators.ts';
+
+@Injectable()
+export class SchedulerRegistry {
+  private cronJobs = new Map<string, any>();
+  private intervals = new Map<string, any>();
+  private timeouts = new Map<string, any>();
+
+  // Cron
+  getCronJob(name: string) {
+    const job = this.cronJobs.get(name);
+    if (!job) throw new Error(`No Cron Job was found with the given name (${name})`);
+    return job;
+  }
+  getCronJobs(): Map<string, any> { return this.cronJobs; }
+  addCronJob(name: string, job: any) { this.cronJobs.set(name, job); }
+  deleteCronJob(name: string) {
+    const job = this.cronJobs.get(name);
+    if (job && typeof job.stop === 'function') job.stop();
+    this.cronJobs.delete(name);
+  }
+
+  // Interval
+  getInterval(name: string) {
+    const interval = this.intervals.get(name);
+    if (!interval) throw new Error(`No Interval was found with the given name (${name})`);
+    return interval;
+  }
+  getIntervals(): string[] { return Array.from(this.intervals.keys()); }
+  addInterval(name: string, intervalId: any) { this.intervals.set(name, intervalId); }
+  deleteInterval(name: string) {
+    const interval = this.intervals.get(name);
+    if (interval) clearInterval(interval);
+    this.intervals.delete(name);
+  }
+
+  // Timeout
+  getTimeout(name: string) {
+    const timeout = this.timeouts.get(name);
+    if (!timeout) throw new Error(`No Timeout was found with the given name (${name})`);
+    return timeout;
+  }
+  getTimeouts(): string[] { return Array.from(this.timeouts.keys()); }
+  addTimeout(name: string, timeoutId: any) { this.timeouts.set(name, timeoutId); }
+  deleteTimeout(name: string) {
+    const timeout = this.timeouts.get(name);
+    if (timeout) clearTimeout(timeout);
+    this.timeouts.delete(name);
+  }
+}

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/graphql.test.ts

@@ -349,3 +349,104 @@ describe('Native Code-First GraphQL Module', () => {
     ws.close();
   });
 });
+
+describe('Schema-First GraphQL Module', () => {
+  let app: any;
+  let baseUrl: string;
+  const PORT = 3929;
+
+  const typeDefs = `
+    type Author {
+      id: Int!
+      name: String!
+    }
+
+    type PostGql {
+      id: Int!
+      title: String!
+      author: Author!
+    }
+
+    type Query {
+      getPost(id: Int!): PostGql
+    }
+  `;
+
+  @Resolver(PostGql)
+  class SchemaFirstResolver {
+    @Query()
+    getPost(@Args('id') id: number) {
+      return {
+        id,
+        title: 'Schema-First Works!',
+        authorId: 888,
+      };
+    }
+
+    @ResolveField()
+    author(@Parent() post: any) {
+      return {
+        id: post.authorId,
+        name: 'Bob',
+      };
+    }
+  }
+
+  @Module({
+    imports: [
+      GraphQLModule.forRoot({
+        typeDefs,
+        context: async ({ req }) => {
+          return { customVal: 'injected' };
+        },
+      }),
+    ],
+    providers: [SchemaFirstResolver],
+  })
+  class SchemaFirstApp {}
+
+  beforeAll(async () => {
+    app = await CalyxFactory.create(SchemaFirstApp);
+    await app.listen(PORT);
+    baseUrl = `http://baseUrl:${PORT}`;
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('should parse typeDefs and bind query/field resolver methods', async () => {
+    const res = await fetch(`http://localhost:${PORT}/graphql`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        query: `
+          query {
+            getPost(id: 42) {
+              id
+              title
+              author {
+                id
+                name
+              }
+            }
+          }
+        `,
+      }),
+    });
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.errors).toBeUndefined();
+    expect(body.data).toEqual({
+      getPost: {
+        id: 42,
+        title: 'Schema-First Works!',
+        author: {
+          id: 888,
+          name: 'Bob',
+        },
+      },
+    });
+  });
+});