@martel/calyx 0.1.0 → 1.1.0

package/src/core/container.ts

@@ -6,6 +6,8 @@ import {
   ModuleMetadata,
   Type,
   resolveForwardRef,
+  Scope,
+  REQUEST,
 } from './metadata.ts';
 import { ModuleRef } from './module-ref.ts';
 
@@ -28,7 +30,7 @@ interface ModuleRecord {
 }
 
 class ContainerModuleRef extends ModuleRef {
-  constructor(private container: calyxContainer, private moduleClass: any) {
+  constructor(private container: CalyxContainer, private moduleClass: any) {
     super();
   }
 
@@ -40,12 +42,28 @@ class ContainerModuleRef extends ModuleRef {
       return this.container.getGlobalOrAnyInstance(token);
     }
   }
+
+  async resolve<T>(token: InjectionToken, contextId?: any, options?: { strict: boolean }): Promise<T> {
+    const requestContext = contextId instanceof Map ? contextId : new Map<any, any>();
+    const strict = options?.strict ?? true;
+    if (strict) {
+      return this.container.resolveTokenInModuleContext(this.moduleClass, token, requestContext);
+    } else {
+      return this.container.resolveTokenGlobally(token, requestContext);
+    }
+  }
+
+  async create<T>(type: Type<T>): Promise<T> {
+    return this.container.instantiateClass(type, this.moduleClass);
+  }
 }
 
-export class calyxContainer {
+export class CalyxContainer {
   private modules = new Map<any, ModuleRecord>();
   private globalModules = new Set<any>();
   private resolvingStack: { moduleClass: any; token: InjectionToken }[] = [];
+  private providerScopes = new Map<InjectionToken, Scope>();
+  private controllerScopes = new Map<any, Scope>();
 
   getModuleRecord(moduleClass: any): ModuleRecord | undefined {
     return this.modules.get(resolveForwardRef(moduleClass));
@@ -55,6 +73,19 @@ export class calyxContainer {
     return this.modules;
   }
 
+  getProviderAndControllerInstances(): any[] {
+    const instances = new Set<any>();
+    for (const record of this.modules.values()) {
+      for (const [token, instance] of record.instances.entries()) {
+        if (token === ModuleRef) continue;
+        if (instance && typeof instance === 'object') {
+          instances.add(instance);
+        }
+      }
+    }
+    return Array.from(instances);
+  }
+
   addModule(moduleClass: any) {
     const resolvedClass = resolveForwardRef(moduleClass);
     if (this.modules.has(resolvedClass)) return;
@@ -146,7 +177,7 @@ export class calyxContainer {
     return provider.provide;
   }
 
-  resolveTokenInModuleContext<T>(moduleClass: any, token: InjectionToken): T {
+  resolveTokenInModuleContext<T>(moduleClass: any, token: InjectionToken, requestContext?: Map<any, any>): T {
     // 1. Check circular dependency
     const isResolving = this.resolvingStack.some(
       (item) => item.moduleClass === moduleClass && item.token === token
@@ -167,6 +198,13 @@ export class calyxContainer {
       }
 
       // Special resolution cases
+      if (token === REQUEST) {
+        if (!requestContext || !requestContext.has(REQUEST)) {
+          throw new Error(`calyx DI: REQUEST token resolved outside of a request context`);
+        }
+        return requestContext.get(REQUEST);
+      }
+
       if (token === ModuleRef) {
         const instance = record.instances.get(ModuleRef);
         if (instance) return instance;
@@ -178,7 +216,7 @@ export class calyxContainer {
       if (token === moduleClass) {
         const instance = record.instances.get(moduleClass);
         if (instance) return instance;
-        const instantiatedModule = this.instantiateClass(moduleClass, moduleClass);
+        const instantiatedModule = this.instantiateClass(moduleClass, moduleClass, requestContext);
         record.instances.set(moduleClass, instantiatedModule);
         return instantiatedModule;
       }
@@ -215,26 +253,30 @@ export class calyxContainer {
       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);
+      const scope = this.providerScopes.get(token) ?? Scope.DEFAULT;
+
+      if (scope === Scope.REQUEST) {
+        if (!requestContext) {
+          throw new Error(`calyx DI: Cannot resolve request-scoped provider "${String(token.name ?? token)}" without request context.`);
+        }
+        if (requestContext.has(token)) {
+          return requestContext.get(token);
+        }
+        const instance = this.createInstanceFromProvider(provider, targetModuleClass, requestContext);
+        requestContext.set(token, instance);
+        return instance;
+      }
+
+      if (scope === Scope.TRANSIENT) {
+        return this.createInstanceFromProvider(provider, targetModuleClass, requestContext);
       }
 
-      // 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);
+      // Check if instance already exists in target module (Singleton)
+      if (targetRecord.instances.has(token)) {
+        return targetRecord.instances.get(token);
       }
 
+      const instance = this.createInstanceFromProvider(provider, targetModuleClass, requestContext);
       targetRecord.instances.set(token, instance);
       return instance;
     } finally {
@@ -242,6 +284,20 @@ export class calyxContainer {
     }
   }
 
+  private createInstanceFromProvider(provider: Provider, targetModuleClass: any, requestContext?: Map<any, any>): any {
+    if (typeof provider !== 'function' && 'useValue' in provider) {
+      return provider.useValue;
+    } else if (typeof provider !== 'function' && 'useClass' in provider) {
+      return this.instantiateClass(provider.useClass, targetModuleClass, requestContext);
+    } else if (typeof provider !== 'function' && 'useFactory' in provider) {
+      const injectTokens = provider.inject || [];
+      const args = injectTokens.map((t) => this.resolveTokenInModuleContext(targetModuleClass, resolveForwardRef(t), requestContext));
+      return provider.useFactory(...args);
+    } else {
+      return this.instantiateClass(provider as Type<any>, targetModuleClass, requestContext);
+    }
+  }
+
   private isTokenExportedByModule(moduleClass: any, token: InjectionToken, visited = new Set<any>()): boolean {
     if (visited.has(moduleClass)) return false;
     visited.add(moduleClass);
@@ -310,7 +366,7 @@ export class calyxContainer {
     return null;
   }
 
-  private instantiateClass(Class: Type<any>, moduleClass: any): any {
+  public instantiateClass(Class: Type<any>, moduleClass: any, requestContext?: Map<any, any>): any {
     if (
       !Reflect.hasMetadata(METADATA_KEYS.INJECTABLE, Class) &&
       !Reflect.hasMetadata(METADATA_KEYS.CONTROLLER, Class) &&
@@ -328,7 +384,7 @@ export class calyxContainer {
       const resolvedToken = resolveForwardRef(token);
       
       try {
-        return this.resolveTokenInModuleContext(moduleClass, resolvedToken);
+        return this.resolveTokenInModuleContext(moduleClass, resolvedToken, requestContext);
       } catch (err) {
         if (optionalParams.has(i)) {
           return undefined;
@@ -337,7 +393,16 @@ export class calyxContainer {
       }
     });
 
-    return new Class(...args);
+    const instance = new Class(...args);
+
+    // Resolve property-level injections
+    const propertyInjects: Map<string | symbol, InjectionToken> =
+      Reflect.getOwnMetadata(METADATA_KEYS.PROPERTY_INJECTS, Class) || new Map();
+    for (const [propertyKey, token] of propertyInjects.entries()) {
+      instance[propertyKey] = this.resolveTokenInModuleContext(moduleClass, token, requestContext);
+    }
+
+    return instance;
   }
 
   getGlobalOrAnyInstance(token: InjectionToken): any {
@@ -352,17 +417,26 @@ export class calyxContainer {
   bootstrap(rootModule: any) {
     this.addModule(rootModule);
 
-    // Instantiate all providers
+    // Compute scopes of all providers and controllers (including bubble-up)
+    this.resolveProviderAndControllerScopes();
+
+    // Instantiate all singleton providers
     for (const [moduleClass, record] of this.modules.entries()) {
       for (const token of record.providers.keys()) {
-        this.resolveTokenInModuleContext(moduleClass, token);
+        const scope = this.providerScopes.get(token) ?? Scope.DEFAULT;
+        if (scope === Scope.DEFAULT) {
+          this.resolveTokenInModuleContext(moduleClass, token);
+        }
       }
     }
 
-    // Instantiate all controllers
+    // Instantiate all singleton controllers
     for (const [moduleClass, record] of this.modules.entries()) {
       for (const controllerClass of record.controllers) {
-        this.resolveController(moduleClass, controllerClass);
+        const scope = this.controllerScopes.get(controllerClass) ?? Scope.DEFAULT;
+        if (scope === Scope.DEFAULT) {
+          this.resolveController(moduleClass, controllerClass);
+        }
       }
     }
 
@@ -384,4 +458,155 @@ export class calyxContainer {
     record.instances.set(controllerClass, instance);
     return instance;
   }
+
+  resolveTokenGlobally<T>(token: InjectionToken, requestContext?: Map<any, any>): T {
+    const scope = this.providerScopes.get(token) ?? Scope.DEFAULT;
+    if (scope === Scope.REQUEST && requestContext?.has(token)) {
+      return requestContext.get(token);
+    }
+    for (const [moduleClass, record] of this.modules.entries()) {
+      if (record.providers.has(token)) {
+        return this.resolveTokenInModuleContext(moduleClass, token, requestContext);
+      }
+    }
+    return this.getGlobalOrAnyInstance(token);
+  }
+
+  resolveControllerInRequestContext(moduleClass: any, controllerClass: any, requestContext: Map<any, any>): any {
+    const scope = this.controllerScopes.get(controllerClass) ?? Scope.DEFAULT;
+    if (scope === Scope.REQUEST) {
+      if (requestContext.has(controllerClass)) {
+        return requestContext.get(controllerClass);
+      }
+      const instance = this.instantiateClass(controllerClass, moduleClass, requestContext);
+      requestContext.set(controllerClass, instance);
+      return instance;
+    }
+    const record = this.modules.get(moduleClass)!;
+    return record.instances.get(controllerClass);
+  }
+
+  getProviderScope(token: InjectionToken): Scope {
+    return this.providerScopes.get(token) ?? Scope.DEFAULT;
+  }
+
+  getControllerScope(controllerClass: any): Scope {
+    return this.controllerScopes.get(controllerClass) ?? Scope.DEFAULT;
+  }
+
+  private resolveProviderAndControllerScopes() {
+    // 1. Resolve direct scopes for providers
+    for (const record of this.modules.values()) {
+      for (const [token, provider] of record.providers.entries()) {
+        let scope = Scope.DEFAULT;
+        if (typeof provider === 'function') {
+          scope = Reflect.getMetadata(METADATA_KEYS.SCOPE, provider) ?? Scope.DEFAULT;
+        } else if (provider && typeof provider === 'object') {
+          scope = provider.scope ?? Scope.DEFAULT;
+          if (scope === Scope.DEFAULT && 'useClass' in provider) {
+            scope = Reflect.getMetadata(METADATA_KEYS.SCOPE, provider.useClass) ?? Scope.DEFAULT;
+          }
+        }
+        this.providerScopes.set(token, scope);
+      }
+    }
+
+    // 2. Bubble up Request Scope through provider dependencies
+    let changed = true;
+    while (changed) {
+      changed = false;
+      for (const record of this.modules.values()) {
+        for (const [token, provider] of record.providers.entries()) {
+          const currentScope = this.providerScopes.get(token) ?? Scope.DEFAULT;
+          if (currentScope === Scope.REQUEST) continue;
+
+          let dependsOnRequestScope = false;
+          const Class = typeof provider === 'function'
+            ? provider
+            : ('useClass' in provider ? provider.useClass : null);
+
+          if (Class) {
+            const paramTypes: any[] = Reflect.getMetadata('design:paramtypes', Class) || [];
+            const injectTokens: Map<number, InjectionToken> = Reflect.getMetadata(METADATA_KEYS.INJECT_TOKENS, Class) || new Map();
+            for (let i = 0; i < paramTypes.length; i++) {
+              const depToken = injectTokens.get(i) ?? paramTypes[i];
+              const resolvedDepToken = resolveForwardRef(depToken);
+              const depScope = this.providerScopes.get(resolvedDepToken) ?? Scope.DEFAULT;
+              if (depScope === Scope.REQUEST) {
+                dependsOnRequestScope = true;
+                break;
+              }
+            }
+
+            if (!dependsOnRequestScope) {
+              const propertyInjects: Map<string | symbol, InjectionToken> =
+                Reflect.getOwnMetadata(METADATA_KEYS.PROPERTY_INJECTS, Class) || new Map();
+              for (const depToken of propertyInjects.values()) {
+                const resolvedDepToken = resolveForwardRef(depToken);
+                const depScope = this.providerScopes.get(resolvedDepToken) ?? Scope.DEFAULT;
+                if (depScope === Scope.REQUEST) {
+                  dependsOnRequestScope = true;
+                  break;
+                }
+              }
+            }
+          } else if (provider && typeof provider === 'object' && 'useFactory' in provider) {
+            const injectTokens = provider.inject || [];
+            for (const depToken of injectTokens) {
+              const resolvedDepToken = resolveForwardRef(depToken);
+              const depScope = this.providerScopes.get(resolvedDepToken) ?? Scope.DEFAULT;
+              if (depScope === Scope.REQUEST) {
+                dependsOnRequestScope = true;
+                break;
+              }
+            }
+          }
+
+          if (dependsOnRequestScope) {
+            this.providerScopes.set(token, Scope.REQUEST);
+            changed = true;
+          }
+        }
+      }
+    }
+
+    // 3. Resolve scopes for controllers
+    for (const record of this.modules.values()) {
+      for (const controllerClass of record.controllers) {
+        let scope = Reflect.getMetadata(METADATA_KEYS.SCOPE, controllerClass) ?? Scope.DEFAULT;
+        if (scope !== Scope.REQUEST) {
+          const paramTypes: any[] = Reflect.getMetadata('design:paramtypes', controllerClass) || [];
+          const injectTokens: Map<number, InjectionToken> = Reflect.getMetadata(METADATA_KEYS.INJECT_TOKENS, controllerClass) || new Map();
+          let dependsOnRequestScope = false;
+          for (let i = 0; i < paramTypes.length; i++) {
+            const depToken = injectTokens.get(i) ?? paramTypes[i];
+            const resolvedDepToken = resolveForwardRef(depToken);
+            const depScope = this.providerScopes.get(resolvedDepToken) ?? Scope.DEFAULT;
+            if (depScope === Scope.REQUEST) {
+              dependsOnRequestScope = true;
+              break;
+            }
+          }
+
+          if (!dependsOnRequestScope) {
+            const propertyInjects: Map<string | symbol, InjectionToken> =
+              Reflect.getOwnMetadata(METADATA_KEYS.PROPERTY_INJECTS, controllerClass) || new Map();
+            for (const depToken of propertyInjects.values()) {
+              const resolvedDepToken = resolveForwardRef(depToken);
+              const depScope = this.providerScopes.get(resolvedDepToken) ?? Scope.DEFAULT;
+              if (depScope === Scope.REQUEST) {
+                dependsOnRequestScope = true;
+                break;
+              }
+            }
+          }
+
+          if (dependsOnRequestScope) {
+            scope = Scope.REQUEST;
+          }
+        }
+        this.controllerScopes.set(controllerClass, scope);
+      }
+    }
+  }
 }

package/src/core/decorators.ts

@@ -1,5 +1,5 @@
 import 'reflect-metadata';
-import { METADATA_KEYS, ModuleMetadata, InjectionToken, ForwardReference } from './metadata.ts';
+import { METADATA_KEYS, ModuleMetadata, InjectionToken, ForwardReference, Scope } from './metadata.ts';
 
 export function Module(metadata: ModuleMetadata): ClassDecorator {
   return (target) => {
@@ -7,20 +7,44 @@ export function Module(metadata: ModuleMetadata): ClassDecorator {
   };
 }
 
-export function Injectable(): ClassDecorator {
+export interface InjectableOptions {
+  scope?: Scope;
+}
+
+export function Injectable(options?: InjectableOptions): ClassDecorator {
   return (target) => {
     Reflect.defineMetadata(METADATA_KEYS.INJECTABLE, true, target);
+    if (options?.scope !== undefined) {
+      Reflect.defineMetadata(METADATA_KEYS.SCOPE, options.scope, 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 Inject(token?: InjectionToken): ParameterDecorator & PropertyDecorator {
+  return (target: any, propertyKey?: string | symbol, parameterIndex?: number) => {
+    if (propertyKey !== undefined && parameterIndex === undefined) {
+      // Property decorator
+      const classTarget = target.constructor;
+      const resolvedToken = token ?? Reflect.getMetadata('design:type', target, propertyKey);
+      if (!resolvedToken) {
+        throw new Error(`Cannot resolve injection token for property "${String(propertyKey)}" of class ${classTarget.name}. Make sure reflect-metadata is imported and emitDecoratorMetadata is enabled, or pass the token explicitly to @Inject().`);
+      }
+      const existingPropertyInjects: Map<string | symbol, InjectionToken> =
+        Reflect.getOwnMetadata(METADATA_KEYS.PROPERTY_INJECTS, classTarget) || new Map();
+      existingPropertyInjects.set(propertyKey, resolvedToken);
+      Reflect.defineMetadata(METADATA_KEYS.PROPERTY_INJECTS, existingPropertyInjects, classTarget);
+    } else {
+      // Parameter decorator
+      const classTarget = propertyKey === undefined ? target : target.constructor;
+      const resolvedToken = token ?? (Reflect.getMetadata('design:paramtypes', classTarget) || [])[parameterIndex!];
+      if (!resolvedToken) {
+        throw new Error(`Cannot resolve injection token for constructor parameter at index ${parameterIndex} of class ${classTarget.name}. Make sure reflect-metadata is imported and emitDecoratorMetadata is enabled, or pass the token explicitly to @Inject().`);
+      }
+      const existingInjectTokens: Map<number, InjectionToken> =
+        Reflect.getOwnMetadata(METADATA_KEYS.INJECT_TOKENS, classTarget) || new Map();
+      existingInjectTokens.set(parameterIndex!, resolvedToken);
+      Reflect.defineMetadata(METADATA_KEYS.INJECT_TOKENS, existingInjectTokens, classTarget);
+    }
   };
 }
 
@@ -43,3 +67,33 @@ export function Global(): ClassDecorator {
 export function forwardRef(fn: () => any): ForwardReference {
   return { forwardRef: fn };
 }
+
+export interface CustomDecorator<TKey = any> {
+  (target: object, key?: string | symbol, descriptor?: any): any;
+  KEY: TKey;
+}
+
+export function SetMetadata<K = any, V = any>(metadataKey: K, metadataValue: V): CustomDecorator<K> {
+  const decoratorFn = (target: any, key?: string | symbol, descriptor?: any) => {
+    if (descriptor) {
+      Reflect.defineMetadata(metadataKey, metadataValue, descriptor.value);
+      return descriptor;
+    }
+    Reflect.defineMetadata(metadataKey, metadataValue, target);
+    return target;
+  };
+  decoratorFn.KEY = metadataKey;
+  return decoratorFn;
+}
+
+export function applyDecorators(...decorators: any[]) {
+  return (target: any, propertyKey?: string | symbol, descriptor?: any) => {
+    for (const decorator of decorators) {
+      if (target instanceof Function && !propertyKey) {
+        decorator(target);
+      } else {
+        decorator(target, propertyKey, descriptor);
+      }
+    }
+  };
+}

package/src/core/index.ts

@@ -2,3 +2,4 @@ export * from './metadata.ts';
 export * from './decorators.ts';
 export * from './module-ref.ts';
 export * from './container.ts';
+export * from './reflector.ts';

package/src/core/metadata.ts

@@ -15,6 +15,8 @@ export const METADATA_KEYS = {
   INTERCEPTORS: 'calyx:interceptors',
   PIPES: 'calyx:pipes',
   FILTERS: 'calyx:filters',
+  PROPERTY_INJECTS: 'calyx:property_injects',
+  SCOPE: 'calyx:scope',
 };
 
 export interface Type<T = any> extends Function {
@@ -26,17 +28,20 @@ export type InjectionToken = string | symbol | Type<any>;
 export interface ValueProvider {
   provide: InjectionToken;
   useValue: any;
+  scope?: Scope;
 }
 
 export interface ClassProvider {
   provide: InjectionToken;
   useClass: Type<any>;
+  scope?: Scope;
 }
 
 export interface FactoryProvider {
   provide: InjectionToken;
   useFactory: (...args: any[]) => any;
   inject?: InjectionToken[];
+  scope?: Scope;
 }
 
 export type Provider = Type<any> | ValueProvider | ClassProvider | FactoryProvider;
@@ -59,3 +64,11 @@ export function isForwardReference(obj: any): obj is ForwardReference {
 export function resolveForwardRef(typeOrFunc: any): any {
   return isForwardReference(typeOrFunc) ? typeOrFunc.forwardRef() : typeOrFunc;
 }
+
+export enum Scope {
+  DEFAULT = 0,
+  TRANSIENT = 1,
+  REQUEST = 2,
+}
+
+export const REQUEST = Symbol('REQUEST');

package/src/core/module-ref.ts

@@ -1,5 +1,7 @@
-import { InjectionToken } from './metadata.ts';
+import { InjectionToken, Type } from './metadata.ts';
 
 export abstract class ModuleRef {
   abstract get<T>(token: InjectionToken, options?: { strict: boolean }): T;
+  abstract resolve<T>(token: InjectionToken, contextId?: any, options?: { strict: boolean }): Promise<T>;
+  abstract create<T>(type: Type<T>): Promise<T>;
 }

package/src/core/reflector.ts

@@ -0,0 +1,32 @@
+import { Injectable } from './decorators.ts';
+import { Type } from './metadata.ts';
+
+@Injectable()
+export class Reflector {
+  get<T = any>(metadataKey: any, target: Function | Type<any>): T {
+    return Reflect.getMetadata(metadataKey, target);
+  }
+
+  getAllAndOverride<T = any>(metadataKey: any, targets: (Function | Type<any>)[]): T {
+    for (const target of targets) {
+      if (!target) continue;
+      const val = Reflect.getMetadata(metadataKey, target);
+      if (val !== undefined) return val;
+    }
+    return undefined as any;
+  }
+
+  getAllAndMerge<T = any>(metadataKey: any, targets: (Function | Type<any>)[]): T {
+    const result: any[] = [];
+    for (const target of targets) {
+      if (!target) continue;
+      const val = Reflect.getMetadata(metadataKey, target);
+      if (Array.isArray(val)) {
+        result.push(...val);
+      } else if (val !== undefined) {
+        result.push(val);
+      }
+    }
+    return result as any as T;
+  }
+}