@martel/calyx 0.1.0

package/src/http/exceptions.ts

@@ -0,0 +1,47 @@
+export class HttpException extends Error {
+  constructor(
+    public readonly response: string | object,
+    public readonly status: number
+  ) {
+    super(typeof response === 'string' ? response : JSON.stringify(response));
+    this.name = 'HttpException';
+  }
+
+  getResponse() {
+    return this.response;
+  }
+
+  getStatus() {
+    return this.status;
+  }
+}
+
+export class BadRequestException extends HttpException {
+  constructor(message: string | object = 'Bad Request') {
+    super(message, 400);
+  }
+}
+
+export class UnauthorizedException extends HttpException {
+  constructor(message: string | object = 'Unauthorized') {
+    super(message, 401);
+  }
+}
+
+export class ForbiddenException extends HttpException {
+  constructor(message: string | object = 'Forbidden') {
+    super(message, 403);
+  }
+}
+
+export class NotFoundException extends HttpException {
+  constructor(message: string | object = 'Not Found') {
+    super(message, 404);
+  }
+}
+
+export class InternalServerErrorException extends HttpException {
+  constructor(message: string | object = 'Internal Server Error') {
+    super(message, 500);
+  }
+}

package/src/http/factory.ts

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

package/src/http/index.ts

@@ -0,0 +1,5 @@
+export * from './decorators.ts';
+export * from './router.ts';
+export * from './exceptions.ts';
+export * from './application.ts';
+export * from './factory.ts';

package/src/http/router.ts

@@ -0,0 +1,97 @@
+export interface RouteMatch<T> {
+  handler: T;
+  params: Record<string, string>;
+}
+
+class RouterNode<T> {
+  children = new Map<string, RouterNode<T>>();
+  paramChild: RouterNode<T> | null = null;
+  paramName: string | null = null;
+  wildcardChild: RouterNode<T> | null = null;
+  handlers = new Map<string, T>();
+}
+
+export class RadixRouter<T> {
+  private root = new RouterNode<T>();
+
+  insert(method: string, path: string, handler: T) {
+    const segments = path.split('/').filter(Boolean);
+    let node = this.root;
+
+    for (const segment of segments) {
+      if (segment.startsWith(':')) {
+        const paramName = segment.slice(1);
+        if (!node.paramChild) {
+          node.paramChild = new RouterNode<T>();
+          node.paramName = paramName;
+        }
+        node = node.paramChild;
+      } else if (segment === '*') {
+        if (!node.wildcardChild) {
+          node.wildcardChild = new RouterNode<T>();
+        }
+        node = node.wildcardChild;
+        break; // Wildcard matches everything rest and is terminal
+      } else {
+        let child = node.children.get(segment);
+        if (!child) {
+          child = new RouterNode<T>();
+          node.children.set(segment, child);
+        }
+        node = child;
+      }
+    }
+
+    node.handlers.set(method.toUpperCase(), handler);
+  }
+
+  match(method: string, path: string): RouteMatch<T> | null {
+    const segments = path.split('/').filter(Boolean);
+    const params: Record<string, string> = {};
+    const matchNode = this.matchSegment(this.root, segments, 0, params);
+
+    if (!matchNode) return null;
+
+    const handler = matchNode.handlers.get(method.toUpperCase()) ?? matchNode.handlers.get('ALL');
+    if (!handler) return null;
+
+    return { handler, params };
+  }
+
+  private matchSegment(
+    node: RouterNode<T>,
+    segments: string[],
+    index: number,
+    params: Record<string, string>
+  ): RouterNode<T> | null {
+    if (index === segments.length) {
+      // If we've reached the end of segments, the current node must have handlers
+      return node.handlers.size > 0 ? node : null;
+    }
+
+    const segment = segments[index];
+
+    // 1. Try static match
+    const staticChild = node.children.get(segment);
+    if (staticChild) {
+      const match = this.matchSegment(staticChild, segments, index + 1, params);
+      if (match) return match;
+    }
+
+    // 2. Try parameter match
+    if (node.paramChild && node.paramName) {
+      params[node.paramName] = segment;
+      const match = this.matchSegment(node.paramChild, segments, index + 1, params);
+      if (match) return match;
+      delete params[node.paramName]; // backtrack
+    }
+
+    // 3. Try wildcard match
+    if (node.wildcardChild) {
+      params['*'] = segments.slice(index).join('/');
+      return node.wildcardChild;
+    }
+
+    return null;
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+import 'reflect-metadata';
+export * from './core/index.ts';
+export * from './http/index.ts';
+export * from './lifecycle/index.ts';

package/src/lifecycle/context.ts

@@ -0,0 +1,41 @@
+import { ArgumentsHost, HttpArgumentsHost, ExecutionContext } from './interfaces.ts';
+import { Type } from '../core/metadata.ts';
+
+export class calyxArgumentsHost implements ArgumentsHost {
+  constructor(private readonly req: Request, private readonly res: any) {}
+
+  getArgs<T extends any[] = any[]>(): T {
+    return [this.req, this.res] as unknown as T;
+  }
+
+  getArgByIndex<T = any>(index: number): T {
+    return this.getArgs()[index];
+  }
+
+  switchToHttp(): HttpArgumentsHost {
+    return {
+      getRequest: <T = any>() => this.req as unknown as T,
+      getResponse: <T = any>() => this.res as unknown as T,
+      getNext: <T = any>() => (() => {}) as unknown as T,
+    };
+  }
+}
+
+export class calyxExecutionContext extends calyxArgumentsHost implements ExecutionContext {
+  constructor(
+    req: Request,
+    res: any,
+    private readonly targetClass: Type<any>,
+    private readonly handlerMethod: Function
+  ) {
+    super(req, res);
+  }
+
+  getClass<T = any>(): Type<T> {
+    return this.targetClass as unknown as Type<T>;
+  }
+
+  getHandler(): Function {
+    return this.handlerMethod;
+  }
+}

package/src/lifecycle/decorators.ts

@@ -0,0 +1,37 @@
+import 'reflect-metadata';
+import { METADATA_KEYS } from '../core/metadata.ts';
+import { CanActivate, NestInterceptor, PipeTransform, ExceptionFilter } from './interfaces.ts';
+
+function createClassOrMethodDecorator(key: string, values: any[]): any {
+  return (target: any, propertyKey?: string | symbol) => {
+    if (propertyKey) {
+      const existing = Reflect.getOwnMetadata(key, target, propertyKey) || [];
+      Reflect.defineMetadata(key, [...existing, ...values], target, propertyKey);
+    } else {
+      const existing = Reflect.getOwnMetadata(key, target) || [];
+      Reflect.defineMetadata(key, [...existing, ...values], target);
+    }
+  };
+}
+
+export function UseGuards(...guards: any[]) {
+  return createClassOrMethodDecorator(METADATA_KEYS.GUARDS, guards);
+}
+
+export function UseInterceptors(...interceptors: any[]) {
+  return createClassOrMethodDecorator(METADATA_KEYS.INTERCEPTORS, interceptors);
+}
+
+export function UsePipes(...pipes: any[]) {
+  return createClassOrMethodDecorator(METADATA_KEYS.PIPES, pipes);
+}
+
+export function UseFilters(...filters: any[]) {
+  return createClassOrMethodDecorator(METADATA_KEYS.FILTERS, filters);
+}
+
+export function Catch(...exceptions: any[]): ClassDecorator {
+  return (target) => {
+    Reflect.defineMetadata(METADATA_KEYS.CATCH, exceptions, target);
+  };
+}

package/src/lifecycle/index.ts

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

package/src/lifecycle/interfaces.ts

@@ -0,0 +1,49 @@
+import { Type } from '../core/metadata.ts';
+
+export interface ArgumentsHost {
+  getArgs<T extends any[] = any[]>(): T;
+  getArgByIndex<T = any>(index: number): T;
+  switchToHttp(): HttpArgumentsHost;
+}
+
+export interface HttpArgumentsHost {
+  getRequest<T = any>(): T;
+  getResponse<T = any>(): T;
+  getNext<T = any>(): T;
+}
+
+export interface ExecutionContext extends ArgumentsHost {
+  getClass<T = any>(): Type<T>;
+  getHandler(): Function;
+}
+
+export interface CanActivate {
+  canActivate(
+    context: ExecutionContext
+  ): boolean | Promise<boolean>;
+}
+
+export interface CallHandler<T = any> {
+  handle(): Promise<T>;
+}
+
+export interface NestInterceptor<T = any, R = any> {
+  intercept(
+    context: ExecutionContext,
+    next: CallHandler<T>
+  ): R | Promise<R>;
+}
+
+export interface ArgumentMetadata {
+  readonly type: 'body' | 'query' | 'param' | 'custom';
+  readonly metatype?: Type<any> | undefined;
+  readonly data?: string | undefined;
+}
+
+export interface PipeTransform<T = any, R = any> {
+  transform(value: T, metadata: ArgumentMetadata): R | Promise<R>;
+}
+
+export interface ExceptionFilter<T = any> {
+  catch(exception: T, host: ArgumentsHost): any;
+}

package/tests/di.test.ts

@@ -0,0 +1,283 @@
+import { describe, test, expect } from 'bun:test';
+import {
+  Module,
+  Injectable,
+  Inject,
+  Optional,
+  Global,
+  forwardRef,
+  calyxContainer,
+  ModuleRef,
+} from '../src/index.ts';
+
+describe('Dependency Injection System', () => {
+  test('should resolve basic singleton provider', () => {
+    @Injectable()
+    class DependencyService {
+      getValue() {
+        return 'dependency';
+      }
+    }
+
+    @Injectable()
+    class TargetService {
+      constructor(public dep: DependencyService) {}
+    }
+
+    @Module({
+      providers: [DependencyService, TargetService],
+    })
+    class RootModule {}
+
+    const container = new calyxContainer();
+    container.bootstrap(RootModule);
+
+    const target = container.getGlobalOrAnyInstance(TargetService);
+    expect(target).toBeInstanceOf(TargetService);
+    expect(target.dep).toBeInstanceOf(DependencyService);
+    expect(target.dep.getValue()).toBe('dependency');
+  });
+
+  test('should resolve custom useValue provider', () => {
+    const CONFIG_TOKEN = 'CONFIG';
+
+    @Injectable()
+    class ConfigConsumer {
+      constructor(@Inject(CONFIG_TOKEN) public config: { port: number }) {}
+    }
+
+    @Module({
+      providers: [
+        ConfigConsumer,
+        {
+          provide: CONFIG_TOKEN,
+          useValue: { port: 3000 },
+        },
+      ],
+    })
+    class RootModule {}
+
+    const container = new calyxContainer();
+    container.bootstrap(RootModule);
+
+    const consumer = container.getGlobalOrAnyInstance(ConfigConsumer);
+    expect(consumer.config).toEqual({ port: 3000 });
+  });
+
+  test('should resolve custom useClass provider', () => {
+    const BASE_SERVICE_TOKEN = 'BASE_SERVICE';
+
+    interface BaseService {
+      hello(): string;
+    }
+
+    @Injectable()
+    class ImplementationService implements BaseService {
+      hello() {
+        return 'hello from implementation';
+      }
+    }
+
+    @Injectable()
+    class Consumer {
+      constructor(@Inject(BASE_SERVICE_TOKEN) public service: BaseService) {}
+    }
+
+    @Module({
+      providers: [
+        Consumer,
+        {
+          provide: BASE_SERVICE_TOKEN,
+          useClass: ImplementationService,
+        },
+      ],
+    })
+    class RootModule {}
+
+    const container = new calyxContainer();
+    container.bootstrap(RootModule);
+
+    const consumer = container.getGlobalOrAnyInstance(Consumer);
+    expect(consumer.service).toBeInstanceOf(ImplementationService);
+    expect(consumer.service.hello()).toBe('hello from implementation');
+  });
+
+  test('should resolve custom useFactory provider with injection', () => {
+    const FACTORY_TOKEN = 'FACTORY_RESULT';
+    const DEP_TOKEN = 'DEP_VALUE';
+
+    @Injectable()
+    class Consumer {
+      constructor(@Inject(FACTORY_TOKEN) public value: string) {}
+    }
+
+    @Module({
+      providers: [
+        Consumer,
+        {
+          provide: DEP_TOKEN,
+          useValue: 'Hello',
+        },
+        {
+          provide: FACTORY_TOKEN,
+          useFactory: (dep: string) => `${dep} Factory`,
+          inject: [DEP_TOKEN],
+        },
+      ],
+    })
+    class RootModule {}
+
+    const container = new calyxContainer();
+    container.bootstrap(RootModule);
+
+    const consumer = container.getGlobalOrAnyInstance(Consumer);
+    expect(consumer.value).toBe('Hello Factory');
+  });
+
+  test('should resolve optional parameter to undefined if missing', () => {
+    @Injectable()
+    class Consumer {
+      constructor(@Optional() @Inject('MISSING_TOKEN') public optionalVal: any) {}
+    }
+
+    @Module({
+      providers: [Consumer],
+    })
+    class RootModule {}
+
+    const container = new calyxContainer();
+    container.bootstrap(RootModule);
+
+    const consumer = container.getGlobalOrAnyInstance(Consumer);
+    expect(consumer.optionalVal).toBeUndefined();
+  });
+
+  test('should throw error when missing non-optional dependency', () => {
+    @Injectable()
+    class Consumer {
+      constructor(@Inject('MISSING_TOKEN') public val: any) {}
+    }
+
+    @Module({
+      providers: [Consumer],
+    })
+    class RootModule {}
+
+    const container = new calyxContainer();
+    expect(() => container.bootstrap(RootModule)).toThrow(/Cannot resolve dependency/);
+  });
+
+  test('should detect circular dependencies and throw error', () => {
+    @Injectable()
+    class ServiceA {
+      constructor(@Inject(forwardRef(() => ServiceB)) public b: any) {}
+    }
+
+    @Injectable()
+    class ServiceB {
+      constructor(@Inject(forwardRef(() => ServiceA)) public a: any) {}
+    }
+
+    @Module({
+      providers: [ServiceA, ServiceB],
+    })
+    class RootModule {}
+
+    const container = new calyxContainer();
+    expect(() => container.bootstrap(RootModule)).toThrow(/Circular dependency detected/);
+  });
+
+  test('should isolate module scopes and resolve exported providers', () => {
+    @Injectable()
+    class SharedService {
+      id = Math.random();
+    }
+
+    @Module({
+      providers: [SharedService],
+      exports: [SharedService],
+    })
+    class LibModule {}
+
+    @Injectable()
+    class AppService {
+      constructor(public shared: SharedService) {}
+    }
+
+    @Module({
+      imports: [LibModule],
+      providers: [AppService],
+    })
+    class AppModule {}
+
+    const container = new calyxContainer();
+    container.bootstrap(AppModule);
+
+    const appService = container.getGlobalOrAnyInstance(AppService);
+    expect(appService.shared).toBeInstanceOf(SharedService);
+  });
+
+  test('should make global module providers available everywhere', () => {
+    @Injectable()
+    class GlobalService {
+      getValue() {
+        return 'global';
+      }
+    }
+
+    @Global()
+    @Module({
+      providers: [GlobalService],
+      exports: [GlobalService],
+    })
+    class GlobalLibModule {}
+
+    @Injectable()
+    class AppService {
+      constructor(public glob: GlobalService) {}
+    }
+
+    @Module({
+      imports: [GlobalLibModule], // If it is global, importing it registers it globally
+      providers: [AppService],
+    })
+    class AppModule {}
+
+    const container = new calyxContainer();
+    container.bootstrap(AppModule);
+
+    const appService = container.getGlobalOrAnyInstance(AppService);
+    expect(appService.glob.getValue()).toBe('global');
+  });
+
+  test('should support ModuleRef dynamic resolution', () => {
+    @Injectable()
+    class DummyService {
+      sayHi() {
+        return 'hi';
+      }
+    }
+
+    @Injectable()
+    class ConsumerService {
+      constructor(public moduleRef: ModuleRef) {}
+
+      getDummy() {
+        return this.moduleRef.get(DummyService);
+      }
+    }
+
+    @Module({
+      providers: [DummyService, ConsumerService],
+    })
+    class RootModule {}
+
+    const container = new calyxContainer();
+    container.bootstrap(RootModule);
+
+    const consumer = container.getGlobalOrAnyInstance(ConsumerService);
+    expect(consumer.moduleRef).toBeInstanceOf(ModuleRef);
+    expect(consumer.getDummy()).toBeInstanceOf(DummyService);
+    expect(consumer.getDummy().sayHi()).toBe('hi');
+  });
+});

package/tests/dynamic-module.test.ts

@@ -0,0 +1,53 @@
+import { describe, test, expect } from 'bun:test';
+import {
+  Module,
+  Injectable,
+  Inject,
+  calyxContainer,
+  DynamicModule,
+} from '../src/index.ts';
+
+@Injectable()
+class ConfigService {
+  constructor(@Inject('CONFIG_OPTIONS') public options: { dbHost: string }) {}
+}
+
+@Module({})
+class ConfigModule {
+  static register(options: { dbHost: string }): DynamicModule {
+    return {
+      module: ConfigModule,
+      providers: [
+        {
+          provide: 'CONFIG_OPTIONS',
+          useValue: options,
+        },
+        ConfigService,
+      ],
+      exports: [ConfigService],
+    };
+  }
+}
+
+@Injectable()
+class AppService {
+  constructor(public config: ConfigService) {}
+}
+
+@Module({
+  imports: [ConfigModule.register({ dbHost: 'localhost:5432' })],
+  providers: [AppService],
+})
+class AppModule {}
+
+describe('Dynamic Modules', () => {
+  test('should resolve providers defined dynamically in a DynamicModule', () => {
+    const container = new calyxContainer();
+    container.bootstrap(AppModule);
+
+    const appService = container.getGlobalOrAnyInstance(AppService);
+    expect(appService).toBeInstanceOf(AppService);
+    expect(appService.config).toBeInstanceOf(ConfigService);
+    expect(appService.config.options).toEqual({ dbHost: 'localhost:5432' });
+  });
+});