@martel/calyx 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [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)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martel/calyx",
-  "version": "1.6.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[] = [];
@@ -888,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 });
     }
 

package/src/index.ts

@@ -8,3 +8,5 @@ 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/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/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();
+  });
+});