@martel/calyx 1.6.0 → 1.8.0

package/src/openapi/swagger.module.ts

@@ -0,0 +1,174 @@
+import { CalyxApplication } from '../http/application.ts';
+
+export class DocumentBuilder {
+  private document: any = {
+    openapi: '3.0.0',
+    info: {
+      title: 'Calyx Application',
+      version: '1.0.0',
+      description: '',
+    },
+    paths: {},
+    components: {
+      schemas: {},
+    },
+  };
+
+  setTitle(title: string) {
+    this.document.info.title = title;
+    return this;
+  }
+
+  setVersion(version: string) {
+    this.document.info.version = version;
+    return this;
+  }
+
+  setDescription(description: string) {
+    this.document.info.description = description;
+    return this;
+  }
+
+  build() {
+    return this.document;
+  }
+}
+
+export class SwaggerModule {
+  static createDocument(app: CalyxApplication, config: any): any {
+    const document = { ...config };
+    if (!document.paths) document.paths = {};
+    if (!document.components) document.components = {};
+    if (!document.components.schemas) document.components.schemas = {};
+
+    const routes = app.getRoutes();
+
+    for (const route of routes) {
+      const { method, path, handler } = route;
+
+      const swaggerPath = path.replace(/:([a-zA-Z0-9_]+)/g, '{$1}');
+
+      if (!document.paths[swaggerPath]) {
+        document.paths[swaggerPath] = {};
+      }
+
+      const operationMeta =
+        Reflect.getMetadata('calyx:api_operation', handler.controllerClass.prototype, handler.methodName) || {};
+      const tags =
+        Reflect.getMetadata('calyx:api_tags', handler.controllerClass.prototype, handler.methodName) ||
+        Reflect.getMetadata('calyx:api_tags', handler.controllerClass) ||
+        [];
+      const responsesMeta =
+        Reflect.getMetadata('calyx:api_responses', handler.controllerClass.prototype, handler.methodName) || [];
+
+      const pathParams = [...path.matchAll(/:([a-zA-Z0-9_]+)/g)].map((m) => m[1]);
+
+      const parameters = pathParams.map((name) => ({
+        name,
+        in: 'path',
+        required: true,
+        schema: { type: 'string' },
+      }));
+
+      const responses: Record<string, any> = {};
+      if (responsesMeta.length > 0) {
+        for (const res of responsesMeta) {
+          responses[String(res.status)] = {
+            description: res.description,
+          };
+          if (res.type) {
+            const schemaName = res.type.name;
+            responses[String(res.status)].content = {
+              'application/json': {
+                schema: { $ref: `#/components/schemas/${schemaName}` },
+              },
+            };
+            if (!document.components.schemas[schemaName]) {
+              const props = Reflect.getMetadata('calyx:api_properties', res.type) || [];
+              const schemaProps: Record<string, any> = {};
+              for (const p of props) {
+                schemaProps[p.propertyKey] = {
+                  type: p.type ? p.type.name.toLowerCase() : 'string',
+                  description: p.description,
+                };
+              }
+              document.components.schemas[schemaName] = {
+                type: 'object',
+                properties: schemaProps,
+              };
+            }
+          }
+        }
+      } else {
+        responses['200'] = { description: 'OK' };
+      }
+
+      document.paths[swaggerPath][method.toLowerCase()] = {
+        summary: operationMeta.summary || '',
+        description: operationMeta.description || '',
+        tags,
+        parameters,
+        responses,
+      };
+    }
+
+    return document;
+  }
+
+  static setup(path: string, app: CalyxApplication, document: any) {
+    const jsonPath = `/${path}-json`.replace(/\/\/+/g, '/');
+    const uiPath = `/${path}`.replace(/\/\/+/g, '/');
+
+    app.use((req: any, res: any, next: any) => {
+      const url = new URL(req.url);
+      if (url.pathname === jsonPath && req.method === 'GET') {
+        res.status(200);
+        res.set('content-type', 'application/json');
+        res.send(JSON.stringify(document));
+        return;
+      }
+      next();
+    });
+
+    const html = `
+      <!DOCTYPE html>
+      <html lang="en">
+      <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>Calyx Swagger UI</title>
+        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.11.0/swagger-ui.css" />
+      </head>
+      <body>
+        <div id="swagger-ui"></div>
+        <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.11.0/swagger-ui-bundle.js"></script>
+        <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.11.0/swagger-ui-standalone-preset.js"></script>
+        <script>
+          window.onload = () => {
+            window.ui = SwaggerUIBundle({
+              url: '${jsonPath}',
+              dom_id: '#swagger-ui',
+              presets: [
+                SwaggerUIBundle.presets.apis,
+                SwaggerUIStandalonePreset
+              ],
+              layout: "BaseLayout"
+            });
+          };
+        </script>
+      </body>
+      </html>
+    `;
+
+    app.use((req: any, res: any, next: any) => {
+      const url = new URL(req.url);
+      if (url.pathname === uiPath && req.method === 'GET') {
+        res.status(200);
+        res.set('content-type', 'text/html');
+        res.send(html);
+        return;
+      }
+      next();
+    });
+  }
+}

package/src/validation/compiler.ts

@@ -0,0 +1,124 @@
+import 'reflect-metadata';
+import { ValidationRule } from './decorators.ts';
+
+export class ValidationCompiler {
+  private static readonly compiledValidators = new Map<any, (obj: any) => string[] | null>();
+
+  static compile(dtoClass: any): (obj: any) => string[] | null {
+    if (this.compiledValidators.has(dtoClass)) {
+      return this.compiledValidators.get(dtoClass)!;
+    }
+
+    const rules: ValidationRule[] = Reflect.getMetadata('calyx:validation_rules', dtoClass) || [];
+
+    const rulesByProp = new Map<string, ValidationRule[]>();
+    for (const rule of rules) {
+      let list = rulesByProp.get(rule.propertyKey);
+      if (!list) {
+        list = [];
+        rulesByProp.set(rule.propertyKey, list);
+      }
+      list.push(rule);
+    }
+
+    const codeParts: string[] = ['const errors = [];'];
+
+    for (const [prop, propRules] of rulesByProp.entries()) {
+      const isOptional = propRules.some((r) => r.type === 'optional');
+
+      const propCode: string[] = [];
+      for (const rule of propRules) {
+        if (rule.type === 'optional') continue;
+
+        if (rule.type === 'string') {
+          propCode.push(`if (typeof obj.${prop} !== 'string') errors.push('${prop} must be a string');`);
+        } else if (rule.type === 'number') {
+          propCode.push(`if (typeof obj.${prop} !== 'number' || isNaN(obj.${prop})) errors.push('${prop} must be a number');`);
+        } else if (rule.type === 'email') {
+          propCode.push(
+            `if (typeof obj.${prop} !== 'string' || !obj.${prop}.includes('@')) errors.push('${prop} must be a valid email');`
+          );
+        }
+      }
+
+      if (isOptional) {
+        codeParts.push(`if (obj.${prop} !== undefined && obj.${prop} !== null) {
+          ${propCode.join('\n')}
+        }`);
+      } else {
+        codeParts.push(`if (obj.${prop} === undefined || obj.${prop} === null) {
+          errors.push('${prop} should not be empty');
+        } else {
+          ${propCode.join('\n')}
+        }`);
+      }
+    }
+
+    codeParts.push('return errors.length > 0 ? errors : null;');
+
+    const fnBody = codeParts.join('\n');
+    try {
+      const validator = new Function('obj', fnBody) as (obj: any) => string[] | null;
+      this.compiledValidators.set(dtoClass, validator);
+      return validator;
+    } catch (err) {
+      console.error('Failed to compile validation JIT for class:', dtoClass.name || dtoClass);
+      console.error('Code body:', fnBody);
+      throw err;
+    }
+  }
+}
+
+export class SerializationCompiler {
+  private static readonly compiledSerializers = new Map<any, (obj: any) => string>();
+
+  static compile(dtoClass: any): (obj: any) => string {
+    if (this.compiledSerializers.has(dtoClass)) {
+      return this.compiledSerializers.get(dtoClass)!;
+    }
+
+    const excludes: Set<string> = Reflect.getMetadata('calyx:exclude_properties', dtoClass) || new Set();
+
+    const rules: ValidationRule[] = Reflect.getMetadata('calyx:validation_rules', dtoClass) || [];
+    const exposedKeys = new Set(rules.map((r) => r.propertyKey));
+
+    const exposes: Set<string> = Reflect.getMetadata('calyx:expose_properties', dtoClass) || new Set();
+    for (const exp of exposes) {
+      exposedKeys.add(exp);
+    }
+
+    const keys = Array.from(exposedKeys).filter((k) => !excludes.has(k));
+
+    const jsonParts: string[] = [];
+    for (const key of keys) {
+      const propRules = rules.filter((r) => r.propertyKey === key);
+      const isNumber = propRules.some((r) => r.type === 'number');
+      const isString = propRules.some((r) => r.type === 'string');
+
+      if (isNumber) {
+        jsonParts.push(`"${key}":\${obj.${key} === undefined || obj.${key} === null ? null : obj.${key}}`);
+      } else if (isString) {
+        jsonParts.push(
+          `"${key}":\${obj.${key} === undefined || obj.${key} === null ? null : JSON.stringify(obj.${key})}`
+        );
+      } else {
+        jsonParts.push(
+          `"${key}":\${obj.${key} === undefined || obj.${key} === null ? null : JSON.stringify(obj.${key})}`
+        );
+      }
+    }
+
+    const fnBody = `
+      return \`{${jsonParts.join(',')}}\`;
+    `;
+
+    try {
+      const serializer = new Function('obj', fnBody) as (obj: any) => string;
+      this.compiledSerializers.set(dtoClass, serializer);
+      return serializer;
+    } catch (err) {
+      console.error('Failed to compile JIT response serializer for class:', dtoClass.name || dtoClass);
+      throw err;
+    }
+  }
+}

package/src/validation/decorators.ts

@@ -0,0 +1,47 @@
+import 'reflect-metadata';
+
+export interface ValidationRule {
+  type: string;
+  propertyKey: string;
+  args?: any[];
+}
+
+function registerValidationRule(type: string, target: any, propertyKey: string, args?: any[]) {
+  const existing: ValidationRule[] = Reflect.getOwnMetadata('calyx:validation_rules', target.constructor) || [];
+  existing.push({ type, propertyKey, args });
+  Reflect.defineMetadata('calyx:validation_rules', existing, target.constructor);
+}
+
+export function IsString(): PropertyDecorator {
+  return (target, propertyKey) => registerValidationRule('string', target, String(propertyKey));
+}
+
+export function IsNumber(): PropertyDecorator {
+  return (target, propertyKey) => registerValidationRule('number', target, String(propertyKey));
+}
+
+export function IsOptional(): PropertyDecorator {
+  return (target, propertyKey) => registerValidationRule('optional', target, String(propertyKey));
+}
+
+export function IsEmail(): PropertyDecorator {
+  return (target, propertyKey) => registerValidationRule('email', target, String(propertyKey));
+}
+
+export function Expose(): PropertyDecorator {
+  return (target, propertyKey) => {
+    const constructor = target.constructor;
+    const existing = Reflect.getOwnMetadata('calyx:expose_properties', constructor) || new Set();
+    existing.add(String(propertyKey));
+    Reflect.defineMetadata('calyx:expose_properties', existing, constructor);
+  };
+}
+
+export function Exclude(): PropertyDecorator {
+  return (target, propertyKey) => {
+    const constructor = target.constructor;
+    const existing = Reflect.getOwnMetadata('calyx:exclude_properties', constructor) || new Set();
+    existing.add(String(propertyKey));
+    Reflect.defineMetadata('calyx:exclude_properties', existing, constructor);
+  };
+}

package/src/validation/index.ts

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

package/src/validation/pipe.ts

@@ -0,0 +1,31 @@
+import { PipeTransform, ArgumentMetadata } from '../lifecycle/interfaces.ts';
+import { Injectable } from '../core/decorators.ts';
+import { HttpException } from '../http/exceptions.ts';
+import { ValidationCompiler } from './compiler.ts';
+
+@Injectable()
+export class ValidationPipe implements PipeTransform {
+  async transform(value: any, metadata: ArgumentMetadata) {
+    const metatype = metadata.metatype;
+    if (!metatype || this.toValidate(metatype)) {
+      return value;
+    }
+
+    const validate = ValidationCompiler.compile(metatype);
+    const errors = validate(value);
+    if (errors) {
+      throw new HttpException({
+        statusCode: 400,
+        message: 'Validation failed',
+        errors,
+      }, 400);
+    }
+
+    return value;
+  }
+
+  private toValidate(metatype: Function): boolean {
+    const types: Function[] = [String, Boolean, Number, Array, Object];
+    return types.includes(metatype);
+  }
+}

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

@@ -0,0 +1,112 @@
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { Module, CalyxFactory } from '../src/index.ts';
+import {
+  Resolver,
+  Query,
+  ResolveField,
+  Args,
+  Parent,
+  ObjectType,
+  Field,
+  GraphQLModule,
+} from '../src/graphql/index.ts';
+
+// 1. GraphQL Object Type DTO
+@ObjectType()
+class Author {
+  @Field()
+  id!: number;
+
+  @Field()
+  name!: string;
+}
+
+@ObjectType()
+class PostGql {
+  @Field()
+  id!: number;
+
+  @Field()
+  title!: string;
+
+  @Field(() => Author)
+  author!: Author;
+}
+
+// 2. Resolver Class
+@Resolver(PostGql)
+class PostResolver {
+  @Query(() => PostGql)
+  getPost(@Args('id') id: number) {
+    return {
+      id,
+      title: `Calyx: GraphQL JIT Performance`,
+      authorId: 456, // to be resolved by ResolveField
+    };
+  }
+
+  @ResolveField(() => Author)
+  author(@Parent() post: any) {
+    return {
+      id: post.authorId,
+      name: 'Jane Doe',
+    };
+  }
+}
+
+@Module({
+  imports: [GraphQLModule],
+  providers: [PostResolver],
+})
+class TestApp {}
+
+describe('Native Code-First GraphQL Module', () => {
+  let app: any;
+  let baseUrl: string;
+  const PORT = 3928;
+
+  beforeAll(async () => {
+    app = await CalyxFactory.create(TestApp);
+    await app.listen(PORT);
+    baseUrl = `http://localhost:${PORT}`;
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('should execute Query and ResolveField successfully using native graphql adapter', async () => {
+    const res = await fetch(`${baseUrl}/graphql`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        query: `
+          query {
+            getPost(id: 123) {
+              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: 123,
+        title: 'Calyx: GraphQL JIT Performance',
+        author: {
+          id: 456,
+          name: 'Jane Doe',
+        },
+      },
+    });
+  });
+});

package/tests/openapi.test.ts

@@ -0,0 +1,95 @@
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import {
+  Module,
+  Controller,
+  Get,
+  Param,
+  CalyxFactory,
+  ApiTags,
+  ApiOperation,
+  ApiResponse,
+  ApiProperty,
+  DocumentBuilder,
+  SwaggerModule,
+} from '../src/index.ts';
+
+// 1. Model class
+class Item {
+  @ApiProperty({ description: 'The unique identifier', type: Number })
+  id!: number;
+
+  @ApiProperty({ description: 'The item name', type: String })
+  name!: string;
+}
+
+@ApiTags('Items')
+@Controller('items')
+class ItemsController {
+  @Get(':id')
+  @ApiOperation({ summary: 'Get item by id', description: 'Returns a single item' })
+  @ApiResponse({ status: 200, description: 'Item found successfully', type: Item })
+  getItem(@Param('id') id: string) {
+    return { id: 1, name: 'Gadget' };
+  }
+}
+
+@Module({
+  controllers: [ItemsController],
+})
+class TestApp {}
+
+describe('OpenAPI (Swagger) Generation', () => {
+  let app: any;
+  let baseUrl: string;
+  const PORT = 3932;
+
+  beforeAll(async () => {
+    app = await CalyxFactory.create(TestApp);
+    
+    // Build OpenAPI config
+    const config = new DocumentBuilder()
+      .setTitle('My Test API')
+      .setDescription('OpenAPI description')
+      .setVersion('2.0.0')
+      .build();
+    
+    const document = SwaggerModule.createDocument(app, config);
+    SwaggerModule.setup('api', app, document);
+
+    await app.listen(PORT);
+    baseUrl = `http://localhost:${PORT}`;
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('should serve OpenAPI JSON specification with paths and components', async () => {
+    const res = await fetch(`${baseUrl}/api-json`);
+    expect(res.status).toBe(200);
+    const spec = await res.json();
+
+    expect(spec.openapi).toBe('3.0.0');
+    expect(spec.info.title).toBe('My Test API');
+    expect(spec.info.version).toBe('2.0.0');
+    expect(spec.paths['/items/{id}']).toBeDefined();
+    
+    const getOp = spec.paths['/items/{id}'].get;
+    expect(getOp.summary).toBe('Get item by id');
+    expect(getOp.tags).toContain('Items');
+    expect(getOp.parameters[0].name).toBe('id');
+    expect(getOp.parameters[0].in).toBe('path');
+    
+    expect(spec.components.schemas.Item).toBeDefined();
+    expect(spec.components.schemas.Item.properties.name.type).toBe('string');
+    expect(spec.components.schemas.Item.properties.id.type).toBe('number');
+  });
+
+  test('should serve Swagger UI html wrapper', async () => {
+    const res = await fetch(`${baseUrl}/api`);
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    expect(html).toContain('swagger-ui');
+    expect(html).toContain('window.ui = SwaggerUIBundle');
+  });
+});