@martel/calyx 0.1.0 → 1.1.0

package/src/http/decorators.ts

@@ -26,12 +26,13 @@ export const All = createRouteDecorator('ALL');
 
 export interface ParameterConfig {
   index: number;
-  type: 'req' | 'res' | 'param' | 'query' | 'body' | 'headers';
+  type: 'req' | 'res' | 'param' | 'query' | 'body' | 'headers' | 'custom';
   name?: string;
   pipes?: any[];
+  factory?: (data: any, ctx: any) => any;
 }
 
-function createParamDecorator(type: ParameterConfig['type'], name?: string, pipes: any[] = []): ParameterDecorator {
+function createHttpParamDecorator(type: ParameterConfig['type'], name?: string, pipes: any[] = []): ParameterDecorator {
   return (target, propertyKey, parameterIndex) => {
     if (!propertyKey) return;
     const existingParams: ParameterConfig[] =
@@ -55,30 +56,30 @@ function parseParamArgs(first?: any, ...rest: any[]) {
   return { name, pipes };
 }
 
-export const Req = () => createParamDecorator('req');
+export const Req = () => createHttpParamDecorator('req');
 export const Request = Req;
 
-export const Res = () => createParamDecorator('res');
+export const Res = (options?: { passthrough: boolean }) => createHttpParamDecorator('res', options?.passthrough ? 'passthrough' : undefined);
 export const Response = Res;
 
 export const Param = (first?: any, ...pipes: any[]) => {
   const { name, pipes: parsedPipes } = parseParamArgs(first, ...pipes);
-  return createParamDecorator('param', name, parsedPipes);
+  return createHttpParamDecorator('param', name, parsedPipes);
 };
 
 export const Query = (first?: any, ...pipes: any[]) => {
   const { name, pipes: parsedPipes } = parseParamArgs(first, ...pipes);
-  return createParamDecorator('query', name, parsedPipes);
+  return createHttpParamDecorator('query', name, parsedPipes);
 };
 
 export const Body = (first?: any, ...pipes: any[]) => {
   const { name, pipes: parsedPipes } = parseParamArgs(first, ...pipes);
-  return createParamDecorator('body', name, parsedPipes);
+  return createHttpParamDecorator('body', name, parsedPipes);
 };
 
 export const Headers = (first?: any, ...pipes: any[]) => {
   const { name, pipes: parsedPipes } = parseParamArgs(first, ...pipes);
-  return createParamDecorator('headers', name, parsedPipes);
+  return createHttpParamDecorator('headers', name, parsedPipes);
 };
 
 export function HttpCode(code: number): MethodDecorator {
@@ -101,3 +102,23 @@ export function Redirect(url: string, statusCode = 302): MethodDecorator {
     Reflect.defineMetadata(METADATA_KEYS.REDIRECT, { url, statusCode }, target, propertyKey);
   };
 }
+
+export function createParamDecorator<Data = any, Return = any>(
+  factory: (data: Data, ctx: any) => Return
+): (data?: Data, ...pipes: any[]) => ParameterDecorator {
+  return (data?: Data, ...pipes: any[]): ParameterDecorator => {
+    return (target, propertyKey, parameterIndex) => {
+      if (!propertyKey) return;
+      const existingParams: ParameterConfig[] =
+        Reflect.getOwnMetadata(METADATA_KEYS.HTTP_PARAMS, target, propertyKey) || [];
+      existingParams.push({
+        index: parameterIndex,
+        type: 'custom',
+        name: data as any,
+        pipes,
+        factory,
+      });
+      Reflect.defineMetadata(METADATA_KEYS.HTTP_PARAMS, existingParams, target, propertyKey);
+    };
+  };
+}

package/src/http/factory.ts

@@ -1,8 +1,8 @@
-import { calyxApplication } from './application.ts';
+import { CalyxApplication } from './application.ts';
 
-export class calyxFactory {
-  static async create(rootModule: any): Promise<calyxApplication> {
-    const app = new calyxApplication(rootModule);
+export class CalyxFactory {
+  static async create(rootModule: any): Promise<CalyxApplication> {
+    const app = new CalyxApplication(rootModule);
     return app;
   }
 }

package/src/http/router.ts

@@ -13,8 +13,14 @@ class RouterNode<T> {
 
 export class RadixRouter<T> {
   private root = new RouterNode<T>();
+  private staticRoutes = new Map<string, T>();
 
   insert(method: string, path: string, handler: T) {
+    const hasParams = path.includes(':') || path.includes('*');
+    if (!hasParams) {
+      this.staticRoutes.set(method.toUpperCase() + ' ' + path, handler);
+    }
+
     const segments = path.split('/').filter(Boolean);
     let node = this.root;
 
@@ -46,6 +52,12 @@ export class RadixRouter<T> {
   }
 
   match(method: string, path: string): RouteMatch<T> | null {
+    const key = method.toUpperCase() + ' ' + path;
+    const staticHandler = this.staticRoutes.get(key);
+    if (staticHandler) {
+      return { handler: staticHandler, params: {} };
+    }
+
     const segments = path.split('/').filter(Boolean);
     const params: Record<string, string> = {};
     const matchNode = this.matchSegment(this.root, segments, 0, params);

package/src/lifecycle/context.ts

@@ -1,7 +1,7 @@
 import { ArgumentsHost, HttpArgumentsHost, ExecutionContext } from './interfaces.ts';
 import { Type } from '../core/metadata.ts';
 
-export class calyxArgumentsHost implements ArgumentsHost {
+export class CalyxArgumentsHost implements ArgumentsHost {
   constructor(private readonly req: Request, private readonly res: any) {}
 
   getArgs<T extends any[] = any[]>(): T {
@@ -21,7 +21,7 @@ export class calyxArgumentsHost implements ArgumentsHost {
   }
 }
 
-export class calyxExecutionContext extends calyxArgumentsHost implements ExecutionContext {
+export class CalyxExecutionContext extends CalyxArgumentsHost implements ExecutionContext {
   constructor(
     req: Request,
     res: any,

package/src/lifecycle/interfaces.ts

@@ -47,3 +47,23 @@ export interface PipeTransform<T = any, R = any> {
 export interface ExceptionFilter<T = any> {
   catch(exception: T, host: ArgumentsHost): any;
 }
+
+export interface OnModuleInit {
+  onModuleInit(): any | Promise<any>;
+}
+
+export interface OnApplicationBootstrap {
+  onApplicationBootstrap(): any | Promise<any>;
+}
+
+export interface OnModuleDestroy {
+  onModuleDestroy(): any | Promise<any>;
+}
+
+export interface BeforeApplicationShutdown {
+  beforeApplicationShutdown(signal?: string): any | Promise<any>;
+}
+
+export interface OnApplicationShutdown {
+  onApplicationShutdown(signal?: string): any | Promise<any>;
+}

package/tests/cli.test.ts

@@ -0,0 +1,93 @@
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { spawnSync } from 'child_process';
+import { existsSync, rmSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+const testAppName = 'scratch/my-cli-test-app';
+
+describe('Calyx CLI Integration Tests', () => {
+  beforeAll(() => {
+    if (existsSync(testAppName)) {
+      rmSync(testAppName, { recursive: true, force: true });
+    }
+  });
+
+  afterAll(() => {
+    if (existsSync(testAppName)) {
+      rmSync(testAppName, { recursive: true, force: true });
+    }
+  });
+
+  test('should display version details on info command', () => {
+    const proc = spawnSync('bun', ['./src/cli/index.ts', 'info'], { encoding: 'utf-8' });
+    expect(proc.status).toBe(0);
+    expect(proc.stdout).toContain('Calyx CLI Information');
+    expect(proc.stdout).toContain('Calyx Version: 0.1.0');
+  });
+
+  test('should scaffold a new application on new command', () => {
+    console.log('Scaffolding app, this may take a few seconds to run bun install...');
+    const proc = spawnSync('bun', ['./src/cli/index.ts', 'new', testAppName], { stdio: 'inherit' });
+    expect(proc.status).toBe(0);
+
+    expect(existsSync(join(testAppName, 'package.json'))).toBe(true);
+    expect(existsSync(join(testAppName, 'tsconfig.json'))).toBe(true);
+    expect(existsSync(join(testAppName, 'src/main.ts'))).toBe(true);
+    expect(existsSync(join(testAppName, 'src/app.module.ts'))).toBe(true);
+    expect(existsSync(join(testAppName, 'src/app.controller.ts'))).toBe(true);
+    expect(existsSync(join(testAppName, 'src/app.service.ts'))).toBe(true);
+    expect(existsSync(join(testAppName, 'node_modules'))).toBe(true);
+  });
+
+  test('should generate controllers, services, and modules with auto-registration', () => {
+    // Generate a controller
+    const genCtrl = spawnSync('bun', ['../../src/cli/index.ts', 'g', 'controller', 'users'], {
+      cwd: testAppName,
+      encoding: 'utf-8',
+    });
+    expect(genCtrl.status).toBe(0);
+    expect(existsSync(join(testAppName, 'src/users/users.controller.ts'))).toBe(true);
+
+    // Verify registration inside app.module.ts
+    const moduleContent = readFileSync(join(testAppName, 'src/app.module.ts'), 'utf-8');
+    expect(moduleContent).toContain("import { UsersController } from './users/users.controller';");
+    expect(moduleContent).toContain('controllers: [AppController, UsersController]');
+
+    // Generate a service
+    const genSvc = spawnSync('bun', ['../../src/cli/index.ts', 'g', 'service', 'users'], {
+      cwd: testAppName,
+      encoding: 'utf-8',
+    });
+    expect(genSvc.status).toBe(0);
+    expect(existsSync(join(testAppName, 'src/users/users.service.ts'))).toBe(true);
+
+    const moduleContent2 = readFileSync(join(testAppName, 'src/app.module.ts'), 'utf-8');
+    expect(moduleContent2).toContain("import { UsersService } from './users/users.service';");
+    expect(moduleContent2).toContain('providers: [AppService, UsersService]');
+  });
+
+  test('should build the application using Bun compiler', () => {
+    // Manually modify package.json to point to local CLI script for Windows/Link test compatibility
+    const pkgPath = join(testAppName, 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    pkg.scripts.build = "bun ../../src/cli/index.ts build";
+    writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
+
+    // Manually add path mapping to tsconfig.json for TypeScript source resolution during tests
+    const tsconfigPath = join(testAppName, 'tsconfig.json');
+    const tsconfig = JSON.parse(readFileSync(tsconfigPath, 'utf-8'));
+    tsconfig.compilerOptions.paths = {
+      "@martel/calyx": ["../../src/index.ts"]
+    };
+    writeFileSync(tsconfigPath, JSON.stringify(tsconfig, null, 2));
+
+    const buildProc = spawnSync('bun', ['run', 'build'], {
+      cwd: testAppName,
+      encoding: 'utf-8',
+    });
+    console.log('Build STDOUT:', buildProc.stdout);
+    console.log('Build STDERR:', buildProc.stderr);
+    expect(buildProc.status).toBe(0);
+    expect(existsSync(join(testAppName, 'dist/main.js'))).toBe(true);
+  });
+});

package/tests/di.test.ts

@@ -6,7 +6,7 @@ import {
   Optional,
   Global,
   forwardRef,
-  calyxContainer,
+  CalyxContainer,
   ModuleRef,
 } from '../src/index.ts';
 
@@ -29,7 +29,7 @@ describe('Dependency Injection System', () => {
     })
     class RootModule {}
 
-    const container = new calyxContainer();
+    const container = new CalyxContainer();
     container.bootstrap(RootModule);
 
     const target = container.getGlobalOrAnyInstance(TargetService);
@@ -57,7 +57,7 @@ describe('Dependency Injection System', () => {
     })
     class RootModule {}
 
-    const container = new calyxContainer();
+    const container = new CalyxContainer();
     container.bootstrap(RootModule);
 
     const consumer = container.getGlobalOrAnyInstance(ConfigConsumer);
@@ -94,7 +94,7 @@ describe('Dependency Injection System', () => {
     })
     class RootModule {}
 
-    const container = new calyxContainer();
+    const container = new CalyxContainer();
     container.bootstrap(RootModule);
 
     const consumer = container.getGlobalOrAnyInstance(Consumer);
@@ -127,7 +127,7 @@ describe('Dependency Injection System', () => {
     })
     class RootModule {}
 
-    const container = new calyxContainer();
+    const container = new CalyxContainer();
     container.bootstrap(RootModule);
 
     const consumer = container.getGlobalOrAnyInstance(Consumer);
@@ -145,7 +145,7 @@ describe('Dependency Injection System', () => {
     })
     class RootModule {}
 
-    const container = new calyxContainer();
+    const container = new CalyxContainer();
     container.bootstrap(RootModule);
 
     const consumer = container.getGlobalOrAnyInstance(Consumer);
@@ -163,7 +163,7 @@ describe('Dependency Injection System', () => {
     })
     class RootModule {}
 
-    const container = new calyxContainer();
+    const container = new CalyxContainer();
     expect(() => container.bootstrap(RootModule)).toThrow(/Cannot resolve dependency/);
   });
 
@@ -183,7 +183,7 @@ describe('Dependency Injection System', () => {
     })
     class RootModule {}
 
-    const container = new calyxContainer();
+    const container = new CalyxContainer();
     expect(() => container.bootstrap(RootModule)).toThrow(/Circular dependency detected/);
   });
 
@@ -210,7 +210,7 @@ describe('Dependency Injection System', () => {
     })
     class AppModule {}
 
-    const container = new calyxContainer();
+    const container = new CalyxContainer();
     container.bootstrap(AppModule);
 
     const appService = container.getGlobalOrAnyInstance(AppService);
@@ -243,7 +243,7 @@ describe('Dependency Injection System', () => {
     })
     class AppModule {}
 
-    const container = new calyxContainer();
+    const container = new CalyxContainer();
     container.bootstrap(AppModule);
 
     const appService = container.getGlobalOrAnyInstance(AppService);
@@ -272,7 +272,7 @@ describe('Dependency Injection System', () => {
     })
     class RootModule {}
 
-    const container = new calyxContainer();
+    const container = new CalyxContainer();
     container.bootstrap(RootModule);
 
     const consumer = container.getGlobalOrAnyInstance(ConsumerService);

package/tests/dynamic-module.test.ts

@@ -3,7 +3,7 @@ import {
   Module,
   Injectable,
   Inject,
-  calyxContainer,
+  CalyxContainer,
   DynamicModule,
 } from '../src/index.ts';
 
@@ -42,7 +42,7 @@ class AppModule {}
 
 describe('Dynamic Modules', () => {
   test('should resolve providers defined dynamically in a DynamicModule', () => {
-    const container = new calyxContainer();
+    const container = new CalyxContainer();
     container.bootstrap(AppModule);
 
     const appService = container.getGlobalOrAnyInstance(AppService);

package/tests/lifecycle.test.ts

@@ -18,11 +18,11 @@ import {
   ExceptionFilter,
   ArgumentsHost,
   ExecutionContext,
-  calyxFactory,
+  CalyxFactory,
   HttpException,
   ForbiddenException,
   BadRequestException,
-  calyxResponse,
+  CalyxResponse,
 } from '../src/index.ts';
 
 // 1. Guard
@@ -67,7 +67,7 @@ class CustomError extends Error {
 @Catch(CustomError)
 class CustomExceptionFilter implements ExceptionFilter {
   catch(exception: CustomError, host: ArgumentsHost) {
-    const res = host.switchToHttp().getResponse<calyxResponse>();
+    const res = host.switchToHttp().getResponse<CalyxResponse>();
     res.status(418).json({
       customFilter: true,
       errorMessage: exception.message,
@@ -112,7 +112,7 @@ describe('Request Lifecycle Pipeline (Guards, Interceptors, Pipes, Filters)', ()
   const PORT = 3848;
 
   beforeAll(async () => {
-    app = await calyxFactory.create(AppModule);
+    app = await CalyxFactory.create(AppModule);
     await app.listen(PORT);
     baseUrl = `http://localhost:${PORT}`;
   });

package/tests/phase1.test.ts

@@ -0,0 +1,143 @@
+import { describe, test, expect } from 'bun:test';
+import {
+  Module,
+  Injectable,
+  Inject,
+  Controller,
+  Get,
+  CalyxContainer,
+  CalyxFactory,
+  createParamDecorator,
+  ExecutionContext,
+  OnModuleInit,
+  OnApplicationBootstrap,
+  OnModuleDestroy,
+  BeforeApplicationShutdown,
+  OnApplicationShutdown,
+} from '../src/index.ts';
+
+describe('Phase 1: Extended DI & Lifecycle Features', () => {
+  
+  // 1. Property Injection Test
+  test('should resolve property-level injections', () => {
+    const VALUE_TOKEN = 'VALUE_TOKEN';
+
+    @Injectable()
+    class ValueService {
+      constructor() {}
+      getData() { return 'property_value'; }
+    }
+
+    @Injectable()
+    class ConsumerService {
+      @Inject(VALUE_TOKEN)
+      public customVal!: string;
+
+      @Inject()
+      public service!: ValueService;
+    }
+
+    @Module({
+      providers: [
+        ConsumerService,
+        ValueService,
+        {
+          provide: VALUE_TOKEN,
+          useValue: 'injected_string',
+        },
+      ],
+    })
+    class RootModule {}
+
+    const container = new CalyxContainer();
+    container.bootstrap(RootModule);
+
+    const consumer = container.getGlobalOrAnyInstance(ConsumerService);
+    expect(consumer.customVal).toBe('injected_string');
+    expect(consumer.service).toBeInstanceOf(ValueService);
+    expect(consumer.service.getData()).toBe('property_value');
+  });
+
+  // 2. Custom Param Decorators Test
+  test('should support custom route parameter decorators', async () => {
+    const CustomUser = createParamDecorator((data: string, ctx: ExecutionContext) => {
+      const req = ctx.switchToHttp().getRequest<Request>();
+      const customHeader = req.headers.get('x-user-id');
+      return {
+        id: customHeader,
+        role: data,
+      };
+    });
+
+    @Controller('test-custom-param')
+    class TestController {
+      @Get()
+      getUser(@CustomUser('admin') user: any) {
+        return user;
+      }
+    }
+
+    @Module({
+      controllers: [TestController],
+    })
+    class RootModule {}
+
+    const app = await CalyxFactory.create(RootModule);
+    await app.listen(3990);
+
+    try {
+      const res = await fetch('http://localhost:3990/test-custom-param', {
+        headers: { 'x-user-id': 'user_123' },
+      });
+      expect(res.status).toBe(200);
+      const body = await res.json();
+      expect(body).toEqual({ id: 'user_123', role: 'admin' });
+    } finally {
+      await app.close();
+    }
+  });
+
+  // 3. Lifecycle Hooks Test
+  test('should run all lifecycle hooks in order', async () => {
+    const hookSequence: string[] = [];
+
+    @Injectable()
+    class LifecycleService implements OnModuleInit, OnApplicationBootstrap, OnModuleDestroy, BeforeApplicationShutdown, OnApplicationShutdown {
+      onModuleInit() {
+        hookSequence.push('init');
+      }
+      onApplicationBootstrap() {
+        hookSequence.push('bootstrap');
+      }
+      onModuleDestroy() {
+        hookSequence.push('destroy');
+      }
+      beforeApplicationShutdown(signal?: string) {
+        hookSequence.push(`beforeShutdown_${signal}`);
+      }
+      onApplicationShutdown(signal?: string) {
+        hookSequence.push(`shutdown_${signal}`);
+      }
+    }
+
+    @Module({
+      providers: [LifecycleService],
+    })
+    class RootModule {}
+
+    const app = await CalyxFactory.create(RootModule);
+    await app.listen(3991);
+    
+    expect(hookSequence).toEqual(['init', 'bootstrap']);
+
+    await app.close('SIGTERM');
+
+    expect(hookSequence).toEqual([
+      'init',
+      'bootstrap',
+      'destroy',
+      'beforeShutdown_SIGTERM',
+      'shutdown_SIGTERM'
+    ]);
+  });
+});

package/tests/phase2.test.ts

@@ -0,0 +1,107 @@
+import { describe, test, expect } from 'bun:test';
+import { of, delay } from 'rxjs';
+import {
+  Module,
+  Controller,
+  Get,
+  Res,
+  CalyxFactory,
+  CalyxResponse,
+} from '../src/index.ts';
+
+describe('Phase 2: Execution Context, RxJS, and Passthrough Response', () => {
+
+  // 1. RxJS Observable Test
+  test('should automatically subscribe and resolve RxJS Observables', async () => {
+    @Controller('rxjs')
+    class RxjsController {
+      @Get('sync')
+      getSync() {
+        return of({ value: 'hello_rxjs' });
+      }
+
+      @Get('async')
+      getAsync() {
+        // Return an observable that resolves after 10ms
+        return of({ value: 'hello_async_rxjs' }).pipe(delay(10));
+      }
+    }
+
+    @Module({
+      controllers: [RxjsController],
+    })
+    class RootModule {}
+
+    const app = await CalyxFactory.create(RootModule);
+    await app.listen(3992);
+
+    try {
+      // Test sync observable
+      const resSync = await fetch('http://localhost:3992/rxjs/sync');
+      expect(resSync.status).toBe(200);
+      expect(await resSync.json()).toEqual({ value: 'hello_rxjs' });
+
+      // Test async observable
+      const resAsync = await fetch('http://localhost:3992/rxjs/async');
+      expect(resAsync.status).toBe(200);
+      expect(await resAsync.json()).toEqual({ value: 'hello_async_rxjs' });
+    } finally {
+      await app.close();
+    }
+  });
+
+  // 2. Passthrough Response vs Standard Response
+  test('should differentiate between passthrough and standard @Res injection', async () => {
+    @Controller('res-test')
+    class ResController {
+      @Get('standard')
+      getStandard(@Res() res: CalyxResponse) {
+        res.status(202).json({ manual: true });
+        // The return value should be ignored
+        return { ignored: true };
+      }
+
+      @Get('standard-norender')
+      getStandardNoRender(@Res() res: CalyxResponse) {
+        // User does not call res.send or res.json, return is ignored, returns empty
+        return { ignored: true };
+      }
+
+      @Get('passthrough')
+      getPassthrough(@Res({ passthrough: true }) res: CalyxResponse) {
+        res.status(206);
+        res.set('x-custom-pass', 'yes');
+        // Return value should be automatically serialized and sent
+        return { automatic: true };
+      }
+    }
+
+    @Module({
+      controllers: [ResController],
+    })
+    class RootModule {}
+
+    const app = await CalyxFactory.create(RootModule);
+    await app.listen(3993);
+
+    try {
+      // Standard @Res - manual response
+      const resStd = await fetch('http://localhost:3993/res-test/standard');
+      expect(resStd.status).toBe(202);
+      expect(await resStd.json()).toEqual({ manual: true });
+
+      // Standard @Res without render - ignored return value
+      const resNoRender = await fetch('http://localhost:3993/res-test/standard-norender');
+      expect(resNoRender.status).toBe(200);
+      expect(await resNoRender.text()).toBe('');
+
+      // Passthrough @Res - sets code/headers, serializes return value
+      const resPass = await fetch('http://localhost:3993/res-test/passthrough');
+      expect(resPass.status).toBe(206);
+      expect(resPass.headers.get('x-custom-pass')).toBe('yes');
+      expect(await resPass.json()).toEqual({ automatic: true });
+    } finally {
+      await app.close();
+    }
+  });
+});