@martel/calyx 0.1.0

package/src/core/container.ts

@@ -0,0 +1,387 @@
+import 'reflect-metadata';
+import {
+  METADATA_KEYS,
+  Provider,
+  InjectionToken,
+  ModuleMetadata,
+  Type,
+  resolveForwardRef,
+} from './metadata.ts';
+import { ModuleRef } from './module-ref.ts';
+
+export interface DynamicModule extends ModuleMetadata {
+  module: any;
+  global?: boolean;
+}
+
+export function isDynamicModule(obj: any): obj is DynamicModule {
+  return obj && typeof obj === 'object' && 'module' in obj;
+}
+
+interface ModuleRecord {
+  moduleClass: any;
+  imports: Set<any>;
+  providers: Map<InjectionToken, Provider>;
+  controllers: Set<any>;
+  exports: Set<any>;
+  instances: Map<InjectionToken, any>;
+}
+
+class ContainerModuleRef extends ModuleRef {
+  constructor(private container: calyxContainer, private moduleClass: any) {
+    super();
+  }
+
+  get<T>(token: InjectionToken, options?: { strict: boolean }): T {
+    const strict = options?.strict ?? true;
+    if (strict) {
+      return this.container.resolveTokenInModuleContext(this.moduleClass, token);
+    } else {
+      return this.container.getGlobalOrAnyInstance(token);
+    }
+  }
+}
+
+export class calyxContainer {
+  private modules = new Map<any, ModuleRecord>();
+  private globalModules = new Set<any>();
+  private resolvingStack: { moduleClass: any; token: InjectionToken }[] = [];
+
+  getModuleRecord(moduleClass: any): ModuleRecord | undefined {
+    return this.modules.get(resolveForwardRef(moduleClass));
+  }
+
+  getModules(): Map<any, ModuleRecord> {
+    return this.modules;
+  }
+
+  addModule(moduleClass: any) {
+    const resolvedClass = resolveForwardRef(moduleClass);
+    if (this.modules.has(resolvedClass)) return;
+
+    const metadata: ModuleMetadata = Reflect.getMetadata(METADATA_KEYS.MODULE, resolvedClass);
+    if (!metadata) {
+      throw new Error(`Class ${resolvedClass.name || resolvedClass} is not a valid Module (missing @Module decorator)`);
+    }
+
+    const isGlobal = Reflect.hasMetadata(METADATA_KEYS.GLOBAL, resolvedClass);
+    if (isGlobal) {
+      this.globalModules.add(resolvedClass);
+    }
+
+    const record: ModuleRecord = {
+      moduleClass: resolvedClass,
+      imports: new Set(),
+      providers: new Map(),
+      controllers: new Set(),
+      exports: new Set(),
+      instances: new Map(),
+    };
+    this.modules.set(resolvedClass, record);
+
+    // Register self and ModuleRef
+    record.instances.set(resolvedClass, null); // Placeholder, will instantiate module class later
+    record.instances.set(ModuleRef, new ContainerModuleRef(this, resolvedClass));
+
+    // Process imports
+    const imports = metadata.imports || [];
+    for (const imp of imports) {
+      const resolvedImp = resolveForwardRef(imp);
+      const actualModule = isDynamicModule(resolvedImp) ? resolvedImp.module : resolvedImp;
+
+      this.addModule(actualModule);
+      record.imports.add(actualModule);
+
+      // If it is dynamic module, merge its extra providers/exports/controllers
+      if (isDynamicModule(resolvedImp)) {
+        const dynamicRecord = this.modules.get(actualModule)!;
+        if (resolvedImp.providers) {
+          for (const prov of resolvedImp.providers) {
+            const token = this.getProviderToken(prov);
+            dynamicRecord.providers.set(token, prov);
+          }
+        }
+        if (resolvedImp.controllers) {
+          for (const ctrl of resolvedImp.controllers) {
+            dynamicRecord.controllers.add(ctrl);
+          }
+        }
+        if (resolvedImp.exports) {
+          for (const exp of resolvedImp.exports) {
+            const resolvedExp = resolveForwardRef(exp);
+            dynamicRecord.exports.add(resolvedExp);
+          }
+        }
+        if (resolvedImp.global) {
+          this.globalModules.add(actualModule);
+        }
+      }
+    }
+
+    // Process providers
+    const providers = metadata.providers || [];
+    for (const prov of providers) {
+      const token = this.getProviderToken(prov);
+      record.providers.set(token, prov);
+    }
+
+    // Process controllers
+    const controllers = metadata.controllers || [];
+    for (const ctrl of controllers) {
+      record.controllers.add(ctrl);
+    }
+
+    // Process exports
+    const exportsList = metadata.exports || [];
+    for (const exp of exportsList) {
+      const resolvedExp = resolveForwardRef(exp);
+      record.exports.add(resolvedExp);
+    }
+  }
+
+  private getProviderToken(provider: Provider): InjectionToken {
+    if (typeof provider === 'function') {
+      return provider;
+    }
+    return provider.provide;
+  }
+
+  resolveTokenInModuleContext<T>(moduleClass: any, token: InjectionToken): T {
+    // 1. Check circular dependency
+    const isResolving = this.resolvingStack.some(
+      (item) => item.moduleClass === moduleClass && item.token === token
+    );
+    if (isResolving) {
+      const path = this.resolvingStack
+        .map((item) => `${item.moduleClass.name ?? item.moduleClass}::${String(item.token.name ?? item.token)}`)
+        .join(' -> ');
+      throw new Error(`Circular dependency detected: ${path} -> ${moduleClass.name ?? moduleClass}::${String(token.name ?? token)}`);
+    }
+
+    this.resolvingStack.push({ moduleClass, token });
+
+    try {
+      const record = this.modules.get(moduleClass);
+      if (!record) {
+        throw new Error(`Module ${moduleClass.name || moduleClass} is not registered in the container`);
+      }
+
+      // Special resolution cases
+      if (token === ModuleRef) {
+        const instance = record.instances.get(ModuleRef);
+        if (instance) return instance;
+        const moduleRefInstance = new ContainerModuleRef(this, moduleClass);
+        record.instances.set(ModuleRef, moduleRefInstance);
+        return moduleRefInstance as any;
+      }
+
+      if (token === moduleClass) {
+        const instance = record.instances.get(moduleClass);
+        if (instance) return instance;
+        const instantiatedModule = this.instantiateClass(moduleClass, moduleClass);
+        record.instances.set(moduleClass, instantiatedModule);
+        return instantiatedModule;
+      }
+
+      // Find where the token is defined
+      const resolution = this.findProviderDefinition(moduleClass, token);
+      if (!resolution) {
+        // Not found. Check if the token is optional
+        const currentResolving = this.resolvingStack[this.resolvingStack.length - 2];
+        if (currentResolving) {
+          const parentClass = currentResolving.token;
+          if (typeof parentClass === 'function') {
+            const optionalParams: Set<number> = Reflect.getMetadata(METADATA_KEYS.OPTIONAL_PARAMS, parentClass) || new Set();
+            const injectTokens: Map<number, InjectionToken> = Reflect.getMetadata(METADATA_KEYS.INJECT_TOKENS, parentClass) || new Map();
+            const paramTypes = Reflect.getMetadata('design:paramtypes', parentClass) || [];
+            
+            let isOptional = false;
+            for (let i = 0; i < paramTypes.length; i++) {
+              const pToken = injectTokens.get(i) ?? paramTypes[i];
+              const resolvedPToken = resolveForwardRef(pToken);
+              if (resolvedPToken === token && optionalParams.has(i)) {
+                isOptional = true;
+                break;
+              }
+            }
+            if (isOptional) {
+              return undefined as any;
+            }
+          }
+        }
+        throw new Error(`calyx DI: Cannot resolve dependency "${String(token.name ?? token)}" in module ${moduleClass.name || moduleClass}`);
+      }
+
+      const { targetModuleClass, provider } = resolution;
+      const targetRecord = this.modules.get(targetModuleClass)!;
+
+      // Check if instance already exists in target module
+      if (targetRecord.instances.has(token)) {
+        return targetRecord.instances.get(token);
+      }
+
+      // Instantiate based on provider definition
+      let instance: any;
+      if (typeof provider !== 'function' && 'useValue' in provider) {
+        instance = provider.useValue;
+      } else if (typeof provider !== 'function' && 'useClass' in provider) {
+        instance = this.instantiateClass(provider.useClass, targetModuleClass);
+      } else if (typeof provider !== 'function' && 'useFactory' in provider) {
+        const injectTokens = provider.inject || [];
+        const args = injectTokens.map((t) => this.resolveTokenInModuleContext(targetModuleClass, resolveForwardRef(t)));
+        instance = provider.useFactory(...args);
+      } else {
+        // Raw class provider
+        instance = this.instantiateClass(provider as Type<any>, targetModuleClass);
+      }
+
+      targetRecord.instances.set(token, instance);
+      return instance;
+    } finally {
+      this.resolvingStack.pop();
+    }
+  }
+
+  private isTokenExportedByModule(moduleClass: any, token: InjectionToken, visited = new Set<any>()): boolean {
+    if (visited.has(moduleClass)) return false;
+    visited.add(moduleClass);
+
+    const record = this.modules.get(moduleClass);
+    if (!record) return false;
+
+    if (record.exports.has(token)) {
+      return true;
+    }
+
+    for (const exportedItem of record.exports) {
+      if (this.modules.has(exportedItem)) {
+        if (this.isTokenExportedByModule(exportedItem, token, visited)) {
+          return true;
+        }
+      }
+    }
+
+    return false;
+  }
+
+  private findProviderInModuleOrExports(moduleClass: any, token: InjectionToken, visited = new Set<any>()): { targetModuleClass: any; provider: Provider } | null {
+    if (visited.has(moduleClass)) return null;
+    visited.add(moduleClass);
+
+    const record = this.modules.get(moduleClass);
+    if (!record) return null;
+
+    if (record.providers.has(token)) {
+      return { targetModuleClass: moduleClass, provider: record.providers.get(token)! };
+    }
+
+    for (const importedModule of record.imports) {
+      if (this.isTokenExportedByModule(importedModule, token)) {
+        const found = this.findProviderInModuleOrExports(importedModule, token, visited);
+        if (found) return found;
+      }
+    }
+
+    return null;
+  }
+
+  private findProviderDefinition(moduleClass: any, token: InjectionToken): { targetModuleClass: any; provider: Provider } | null {
+    const record = this.modules.get(moduleClass);
+    if (record && record.providers.has(token)) {
+      return { targetModuleClass: moduleClass, provider: record.providers.get(token)! };
+    }
+
+    if (record) {
+      for (const importedModule of record.imports) {
+        if (this.isTokenExportedByModule(importedModule, token)) {
+          const found = this.findProviderInModuleOrExports(importedModule, token);
+          if (found) return found;
+        }
+      }
+    }
+
+    for (const globalModule of this.globalModules) {
+      if (globalModule !== moduleClass && this.isTokenExportedByModule(globalModule, token)) {
+        const found = this.findProviderInModuleOrExports(globalModule, token);
+        if (found) return found;
+      }
+    }
+
+    return null;
+  }
+
+  private instantiateClass(Class: Type<any>, moduleClass: any): any {
+    if (
+      !Reflect.hasMetadata(METADATA_KEYS.INJECTABLE, Class) &&
+      !Reflect.hasMetadata(METADATA_KEYS.CONTROLLER, Class) &&
+      !Reflect.hasMetadata(METADATA_KEYS.MODULE, Class)
+    ) {
+      throw new Error(`Class ${Class.name} is missing @Injectable(), @Controller() or @Module() decorator`);
+    }
+
+    const paramTypes: any[] = Reflect.getMetadata('design:paramtypes', Class) || [];
+    const injectTokens: Map<number, InjectionToken> = Reflect.getMetadata(METADATA_KEYS.INJECT_TOKENS, Class) || new Map();
+    const optionalParams: Set<number> = Reflect.getMetadata(METADATA_KEYS.OPTIONAL_PARAMS, Class) || new Set();
+
+    const args = paramTypes.map((paramType, i) => {
+      const token = injectTokens.get(i) ?? paramType;
+      const resolvedToken = resolveForwardRef(token);
+      
+      try {
+        return this.resolveTokenInModuleContext(moduleClass, resolvedToken);
+      } catch (err) {
+        if (optionalParams.has(i)) {
+          return undefined;
+        }
+        throw err;
+      }
+    });
+
+    return new Class(...args);
+  }
+
+  getGlobalOrAnyInstance(token: InjectionToken): any {
+    for (const record of this.modules.values()) {
+      if (record.instances.has(token)) {
+        return record.instances.get(token);
+      }
+    }
+    throw new Error(`calyx DI: Instance of "${String(token.name ?? token)}" not found in any module context`);
+  }
+
+  bootstrap(rootModule: any) {
+    this.addModule(rootModule);
+
+    // Instantiate all providers
+    for (const [moduleClass, record] of this.modules.entries()) {
+      for (const token of record.providers.keys()) {
+        this.resolveTokenInModuleContext(moduleClass, token);
+      }
+    }
+
+    // Instantiate all controllers
+    for (const [moduleClass, record] of this.modules.entries()) {
+      for (const controllerClass of record.controllers) {
+        this.resolveController(moduleClass, controllerClass);
+      }
+    }
+
+    // Instantiate module classes themselves
+    for (const [moduleClass, record] of this.modules.entries()) {
+      if (record.instances.get(moduleClass) === null) {
+        const instance = this.instantiateClass(moduleClass, moduleClass);
+        record.instances.set(moduleClass, instance);
+      }
+    }
+  }
+
+  private resolveController(moduleClass: any, controllerClass: any): any {
+    const record = this.modules.get(moduleClass)!;
+    if (record.instances.has(controllerClass)) {
+      return record.instances.get(controllerClass);
+    }
+    const instance = this.instantiateClass(controllerClass, moduleClass);
+    record.instances.set(controllerClass, instance);
+    return instance;
+  }
+}

package/src/core/decorators.ts

@@ -0,0 +1,45 @@
+import 'reflect-metadata';
+import { METADATA_KEYS, ModuleMetadata, InjectionToken, ForwardReference } from './metadata.ts';
+
+export function Module(metadata: ModuleMetadata): ClassDecorator {
+  return (target) => {
+    Reflect.defineMetadata(METADATA_KEYS.MODULE, metadata, target);
+  };
+}
+
+export function Injectable(): ClassDecorator {
+  return (target) => {
+    Reflect.defineMetadata(METADATA_KEYS.INJECTABLE, true, target);
+  };
+}
+
+export function Inject(token: InjectionToken): ParameterDecorator {
+  return (target, propertyKey, parameterIndex) => {
+    // For constructor parameters, propertyKey is undefined
+    const classTarget = propertyKey === undefined ? target : target.constructor;
+    const existingInjectTokens: Map<number, InjectionToken> =
+      Reflect.getOwnMetadata(METADATA_KEYS.INJECT_TOKENS, classTarget) || new Map();
+    existingInjectTokens.set(parameterIndex, token);
+    Reflect.defineMetadata(METADATA_KEYS.INJECT_TOKENS, existingInjectTokens, classTarget);
+  };
+}
+
+export function Optional(): ParameterDecorator {
+  return (target, propertyKey, parameterIndex) => {
+    const classTarget = propertyKey === undefined ? target : target.constructor;
+    const existingOptionalParams: Set<number> =
+      Reflect.getOwnMetadata(METADATA_KEYS.OPTIONAL_PARAMS, classTarget) || new Set();
+    existingOptionalParams.add(parameterIndex);
+    Reflect.defineMetadata(METADATA_KEYS.OPTIONAL_PARAMS, existingOptionalParams, classTarget);
+  };
+}
+
+export function Global(): ClassDecorator {
+  return (target) => {
+    Reflect.defineMetadata(METADATA_KEYS.GLOBAL, true, target);
+  };
+}
+
+export function forwardRef(fn: () => any): ForwardReference {
+  return { forwardRef: fn };
+}

package/src/core/index.ts

@@ -0,0 +1,4 @@
+export * from './metadata.ts';
+export * from './decorators.ts';
+export * from './module-ref.ts';
+export * from './container.ts';

package/src/core/metadata.ts

@@ -0,0 +1,61 @@
+export const METADATA_KEYS = {
+  MODULE: 'calyx:module',
+  INJECTABLE: 'calyx:injectable',
+  INJECT_TOKENS: 'calyx:inject_tokens',
+  OPTIONAL_PARAMS: 'calyx:optional_params',
+  GLOBAL: 'calyx:global',
+  CONTROLLER: 'calyx:controller',
+  CATCH: 'calyx:catch',
+  HTTP_METHOD: 'calyx:http_method',
+  HTTP_PARAMS: 'calyx:http_params',
+  HTTP_CODE: 'calyx:http_code',
+  HTTP_HEADERS: 'calyx:http_headers',
+  REDIRECT: 'calyx:redirect',
+  GUARDS: 'calyx:guards',
+  INTERCEPTORS: 'calyx:interceptors',
+  PIPES: 'calyx:pipes',
+  FILTERS: 'calyx:filters',
+};
+
+export interface Type<T = any> extends Function {
+  new (...args: any[]): T;
+}
+
+export type InjectionToken = string | symbol | Type<any>;
+
+export interface ValueProvider {
+  provide: InjectionToken;
+  useValue: any;
+}
+
+export interface ClassProvider {
+  provide: InjectionToken;
+  useClass: Type<any>;
+}
+
+export interface FactoryProvider {
+  provide: InjectionToken;
+  useFactory: (...args: any[]) => any;
+  inject?: InjectionToken[];
+}
+
+export type Provider = Type<any> | ValueProvider | ClassProvider | FactoryProvider;
+
+export interface ModuleMetadata {
+  imports?: any[];
+  controllers?: any[];
+  providers?: Provider[];
+  exports?: any[];
+}
+
+export interface ForwardReference {
+  forwardRef: () => any;
+}
+
+export function isForwardReference(obj: any): obj is ForwardReference {
+  return obj && typeof obj === 'object' && typeof obj.forwardRef === 'function';
+}
+
+export function resolveForwardRef(typeOrFunc: any): any {
+  return isForwardReference(typeOrFunc) ? typeOrFunc.forwardRef() : typeOrFunc;
+}

package/src/core/module-ref.ts

@@ -0,0 +1,5 @@
+import { InjectionToken } from './metadata.ts';
+
+export abstract class ModuleRef {
+  abstract get<T>(token: InjectionToken, options?: { strict: boolean }): T;
+}