@martel/calyx 1.11.0 → 1.13.0

package/src/core/container.ts

@@ -47,14 +47,14 @@ class ContainerModuleRef extends ModuleRef {
     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);
+      return await this.container.resolveTokenInModuleContextAsync(this.moduleClass, token, requestContext);
     } else {
-      return this.container.resolveTokenGlobally(token, requestContext);
+      return await this.container.resolveTokenGloballyAsync(token, requestContext);
     }
   }
 
   async create<T>(type: Type<T>): Promise<T> {
-    return this.container.instantiateClass(type, this.moduleClass);
+    return await this.container.instantiateClassAsync(type, this.moduleClass);
   }
 }
 
@@ -65,6 +65,7 @@ export class CalyxContainer {
   private providerScopes = new Map<InjectionToken, Scope>();
   private controllerScopes = new Map<any, Scope>();
   private compiledControllerFactories = new Map<any, (requestContext: Map<any, any>) => any>();
+  private deferredProxies: { moduleClass: any; token: any; proxyTarget: { instance: any } }[] = [];
 
   getModuleRecord(moduleClass: any): ModuleRecord | undefined {
     return this.modules.get(resolveForwardRef(moduleClass));
@@ -124,29 +125,9 @@ export class CalyxContainer {
       this.addModule(actualModule);
       record.imports.add(actualModule);
 
-      // If it is dynamic module, merge its extra providers/exports/controllers
+      // If it is dynamic module, merge its extra metadata recursively
       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);
-        }
+        this.mergeDynamicModuleMetadata(resolvedImp);
       }
     }
 
@@ -171,6 +152,45 @@ export class CalyxContainer {
     }
   }
 
+  private mergeDynamicModuleMetadata(dynModule: DynamicModule) {
+    const actualModule = dynModule.module;
+    const record = this.modules.get(actualModule)!;
+
+    if (dynModule.imports) {
+      for (const imp of dynModule.imports) {
+        const resolvedImp = resolveForwardRef(imp);
+        const actualImp = isDynamicModule(resolvedImp) ? resolvedImp.module : resolvedImp;
+
+        this.addModule(actualImp);
+        record.imports.add(actualImp);
+
+        if (isDynamicModule(resolvedImp)) {
+          this.mergeDynamicModuleMetadata(resolvedImp);
+        }
+      }
+    }
+    if (dynModule.providers) {
+      for (const prov of dynModule.providers) {
+        const token = this.getProviderToken(prov);
+        record.providers.set(token, prov);
+      }
+    }
+    if (dynModule.controllers) {
+      for (const ctrl of dynModule.controllers) {
+        record.controllers.add(ctrl);
+      }
+    }
+    if (dynModule.exports) {
+      for (const exp of dynModule.exports) {
+        const resolvedExp = resolveForwardRef(exp);
+        record.exports.add(resolvedExp);
+      }
+    }
+    if (dynModule.global) {
+      this.globalModules.add(actualModule);
+    }
+  }
+
   private getProviderToken(provider: Provider): InjectionToken {
     if (typeof provider === 'function') {
       return provider;
@@ -178,19 +198,82 @@ export class CalyxContainer {
     return provider.provide;
   }
 
+  private resolveDeferredProxies() {
+    for (const dp of this.deferredProxies) {
+      if (!dp.proxyTarget.instance) {
+        const record = this.modules.get(dp.moduleClass);
+        if (record && record.instances.has(dp.token)) {
+          dp.proxyTarget.instance = record.instances.get(dp.token);
+        } else {
+          try {
+            dp.proxyTarget.instance = this.getGlobalOrAnyInstance(dp.token);
+          } catch {
+            // ignore
+          }
+        }
+      }
+    }
+  }
+
   resolveTokenInModuleContext<T>(moduleClass: any, token: InjectionToken, requestContext?: Map<any, any>): T {
+    const resolvedToken = resolveForwardRef(token);
     // 1. Check circular dependency
     const isResolving = this.resolvingStack.some(
-      (item) => item.moduleClass === moduleClass && item.token === token
+      (item) => item.moduleClass === moduleClass && item.token === resolvedToken
     );
     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)}`);
+      const container = this;
+      const proxyTarget = { instance: null as any };
+      this.deferredProxies.push({
+        moduleClass,
+        token: resolvedToken,
+        proxyTarget,
+      });
+      return new Proxy(proxyTarget, {
+        get(target, prop) {
+          if (prop === '__isCalyxProxy') return true;
+          if (prop === '__proxyTarget') return target;
+          if (!target.instance) {
+            const record = container.modules.get(moduleClass);
+            if (record && record.instances.has(resolvedToken)) {
+              target.instance = record.instances.get(resolvedToken);
+            }
+          }
+          if (!target.instance) {
+            try {
+              target.instance = container.getGlobalOrAnyInstance(resolvedToken);
+            } catch {
+              // ignore
+            }
+          }
+          if (!target.instance) {
+            if (typeof prop === 'symbol' || prop === 'then' || prop === 'toJSON') {
+              return undefined;
+            }
+            throw new Error(`Calyx circular proxy DI error: Accessing property "${String(prop)}" on circular dependency ${resolvedToken.name || resolvedToken} before it is instantiated.`);
+          }
+          const value = Reflect.get(target.instance, prop);
+          if (typeof value === 'function') {
+            return value.bind(target.instance);
+          }
+          return value;
+        },
+        set(target, prop, value) {
+          if (!target.instance) {
+            const record = container.modules.get(moduleClass);
+            if (record && record.instances.has(resolvedToken)) {
+              target.instance = record.instances.get(resolvedToken);
+            }
+          }
+          if (!target.instance) {
+            throw new Error(`Calyx circular proxy DI error: Setting property "${String(prop)}" on circular dependency ${resolvedToken.name || resolvedToken} before it is instantiated.`);
+          }
+          return Reflect.set(target.instance, prop, value);
+        }
+      }) as any;
     }
 
-    this.resolvingStack.push({ moduleClass, token });
+    this.resolvingStack.push({ moduleClass, token: resolvedToken });
 
     try {
       const record = this.modules.get(moduleClass);
@@ -199,14 +282,14 @@ export class CalyxContainer {
       }
 
       // Special resolution cases
-      if (token === REQUEST) {
+      if (resolvedToken === 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) {
+      if (resolvedToken === ModuleRef) {
         const instance = record.instances.get(ModuleRef);
         if (instance) return instance;
         const moduleRefInstance = new ContainerModuleRef(this, moduleClass);
@@ -214,16 +297,17 @@ export class CalyxContainer {
         return moduleRefInstance as any;
       }
 
-      if (token === moduleClass) {
+      if (resolvedToken === moduleClass) {
         const instance = record.instances.get(moduleClass);
         if (instance) return instance;
         const instantiatedModule = this.instantiateClass(moduleClass, moduleClass, requestContext);
         record.instances.set(moduleClass, instantiatedModule);
+        this.resolveDeferredProxies();
         return instantiatedModule;
       }
 
       // Find where the token is defined
-      const resolution = this.findProviderDefinition(moduleClass, token);
+      const resolution = this.findProviderDefinition(moduleClass, resolvedToken);
       if (!resolution) {
         // Not found. Check if the token is optional
         const currentResolving = this.resolvingStack[this.resolvingStack.length - 2];
@@ -238,7 +322,7 @@ export class CalyxContainer {
             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)) {
+              if (resolvedPToken === resolvedToken && optionalParams.has(i)) {
                 isOptional = true;
                 break;
               }
@@ -248,23 +332,24 @@ export class CalyxContainer {
             }
           }
         }
-        throw new Error(`calyx DI: Cannot resolve dependency "${String(token.name ?? token)}" in module ${moduleClass.name || moduleClass}`);
+        throw new Error(`calyx DI: Cannot resolve dependency "${String(resolvedToken.name ?? resolvedToken)}" in module ${moduleClass.name || moduleClass}`);
       }
 
       const { targetModuleClass, provider } = resolution;
       const targetRecord = this.modules.get(targetModuleClass)!;
 
-      const scope = this.providerScopes.get(token) ?? Scope.DEFAULT;
+      const scope = this.providerScopes.get(resolvedToken) ?? 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.`);
+          throw new Error(`calyx DI: Cannot resolve request-scoped provider "${String(resolvedToken.name ?? resolvedToken)}" without request context.`);
         }
-        if (requestContext.has(token)) {
-          return requestContext.get(token);
+        if (requestContext.has(resolvedToken)) {
+          return requestContext.get(resolvedToken);
         }
         const instance = this.createInstanceFromProvider(provider, targetModuleClass, requestContext);
-        requestContext.set(token, instance);
+        requestContext.set(resolvedToken, instance);
+        this.resolveDeferredProxies();
         return instance;
       }
 
@@ -273,12 +358,13 @@ export class CalyxContainer {
       }
 
       // Check if instance already exists in target module (Singleton)
-      if (targetRecord.instances.has(token)) {
-        return targetRecord.instances.get(token);
+      if (targetRecord.instances.has(resolvedToken)) {
+        return targetRecord.instances.get(resolvedToken);
       }
 
       const instance = this.createInstanceFromProvider(provider, targetModuleClass, requestContext);
-      targetRecord.instances.set(token, instance);
+      targetRecord.instances.set(resolvedToken, instance);
+      this.resolveDeferredProxies();
       return instance;
     } finally {
       this.resolvingStack.pop();
@@ -288,6 +374,8 @@ 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' && 'useExisting' in provider) {
+      return this.resolveTokenInModuleContext(targetModuleClass, resolveForwardRef(provider.useExisting), requestContext);
     } else if (typeof provider !== 'function' && 'useClass' in provider) {
       return this.instantiateClass(provider.useClass, targetModuleClass, requestContext);
     } else if (typeof provider !== 'function' && 'useFactory' in provider) {
@@ -400,7 +488,7 @@ export class CalyxContainer {
     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);
+      instance[propertyKey] = this.resolveTokenInModuleContext(moduleClass, resolveForwardRef(token), requestContext);
     }
 
     return instance;
@@ -415,13 +503,31 @@ export class CalyxContainer {
     throw new Error(`calyx DI: Instance of "${String(token.name ?? token)}" not found in any module context`);
   }
 
-  bootstrap(rootModule: any) {
+  bootstrap(rootModule: any): void | Promise<void> {
     this.addModule(rootModule);
-
-    // Compute scopes of all providers and controllers (including bubble-up)
     this.resolveProviderAndControllerScopes();
 
-    // Instantiate all singleton providers
+    let hasAsync = false;
+    for (const record of this.modules.values()) {
+      for (const provider of record.providers.values()) {
+        if (typeof provider !== 'function' && 'useFactory' in provider) {
+          if (provider.useFactory.constructor.name === 'AsyncFunction') {
+            hasAsync = true;
+            break;
+          }
+        }
+      }
+      if (hasAsync) break;
+    }
+
+    if (hasAsync) {
+      return this.bootstrapAsync(rootModule);
+    }
+
+    this.bootstrapSync(rootModule);
+  }
+
+  private bootstrapSync(rootModule: any) {
     for (const [moduleClass, record] of this.modules.entries()) {
       for (const token of record.providers.keys()) {
         const scope = this.providerScopes.get(token) ?? Scope.DEFAULT;
@@ -431,7 +537,6 @@ export class CalyxContainer {
       }
     }
 
-    // Instantiate all singleton controllers
     for (const [moduleClass, record] of this.modules.entries()) {
       for (const controllerClass of record.controllers) {
         const scope = this.controllerScopes.get(controllerClass) ?? Scope.DEFAULT;
@@ -441,14 +546,46 @@ export class CalyxContainer {
       }
     }
 
-    // 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);
+        this.resolveDeferredProxies();
       }
     }
 
+    this.resolveDeferredProxies();
+    this.compileControllerFactories();
+  }
+
+  private async bootstrapAsync(rootModule: any) {
+    for (const [moduleClass, record] of this.modules.entries()) {
+      for (const token of record.providers.keys()) {
+        const scope = this.providerScopes.get(token) ?? Scope.DEFAULT;
+        if (scope === Scope.DEFAULT) {
+          await this.resolveTokenInModuleContextAsync(moduleClass, token);
+        }
+      }
+    }
+
+    for (const [moduleClass, record] of this.modules.entries()) {
+      for (const controllerClass of record.controllers) {
+        const scope = this.controllerScopes.get(controllerClass) ?? Scope.DEFAULT;
+        if (scope === Scope.DEFAULT) {
+          await this.resolveControllerAsync(moduleClass, controllerClass);
+        }
+      }
+    }
+
+    for (const [moduleClass, record] of this.modules.entries()) {
+      if (record.instances.get(moduleClass) === null) {
+        const instance = await this.instantiateClassAsync(moduleClass, moduleClass);
+        record.instances.set(moduleClass, instance);
+        this.resolveDeferredProxies();
+      }
+    }
+
+    this.resolveDeferredProxies();
     this.compileControllerFactories();
   }
 
@@ -459,6 +596,18 @@ export class CalyxContainer {
     }
     const instance = this.instantiateClass(controllerClass, moduleClass);
     record.instances.set(controllerClass, instance);
+    this.resolveDeferredProxies();
+    return instance;
+  }
+
+  private async resolveControllerAsync(moduleClass: any, controllerClass: any): Promise<any> {
+    const record = this.modules.get(moduleClass)!;
+    if (record.instances.has(controllerClass)) {
+      return record.instances.get(controllerClass);
+    }
+    const instance = await this.instantiateClassAsync(controllerClass, moduleClass);
+    record.instances.set(controllerClass, instance);
+    this.resolveDeferredProxies();
     return instance;
   }
 
@@ -475,6 +624,229 @@ export class CalyxContainer {
     return this.getGlobalOrAnyInstance(token);
   }
 
+  async resolveTokenGloballyAsync<T>(token: InjectionToken, requestContext?: Map<any, any>): Promise<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 await this.resolveTokenInModuleContextAsync(moduleClass, token, requestContext);
+      }
+    }
+    return this.getGlobalOrAnyInstance(token);
+  }
+
+  async resolveTokenInModuleContextAsync<T>(moduleClass: any, token: InjectionToken, requestContext?: Map<any, any>): Promise<T> {
+    const resolvedToken = resolveForwardRef(token);
+    const isResolving = this.resolvingStack.some(
+      (item) => item.moduleClass === moduleClass && item.token === resolvedToken
+    );
+    if (isResolving) {
+      const container = this;
+      const proxyTarget = { instance: null as any };
+      this.deferredProxies.push({
+        moduleClass,
+        token: resolvedToken,
+        proxyTarget,
+      });
+      return new Proxy(proxyTarget, {
+        get(target, prop) {
+          if (prop === '__isCalyxProxy') return true;
+          if (prop === '__proxyTarget') return target;
+          if (!target.instance) {
+            const record = container.modules.get(moduleClass);
+            if (record && record.instances.has(resolvedToken)) {
+              target.instance = record.instances.get(resolvedToken);
+            }
+          }
+          if (!target.instance) {
+            try {
+              target.instance = container.getGlobalOrAnyInstance(resolvedToken);
+            } catch {
+              // ignore
+            }
+          }
+          if (!target.instance) {
+            if (typeof prop === 'symbol' || prop === 'then' || prop === 'toJSON') {
+              return undefined;
+            }
+            throw new Error(`Calyx circular proxy DI error: Accessing property "${String(prop)}" on circular dependency ${resolvedToken.name || resolvedToken} before it is instantiated.`);
+          }
+          const value = Reflect.get(target.instance, prop);
+          if (typeof value === 'function') {
+            return value.bind(target.instance);
+          }
+          return value;
+        },
+        set(target, prop, value) {
+          if (!target.instance) {
+            const record = container.modules.get(moduleClass);
+            if (record && record.instances.has(resolvedToken)) {
+              target.instance = record.instances.get(resolvedToken);
+            }
+          }
+          if (!target.instance) {
+            throw new Error(`Calyx circular proxy DI error: Setting property "${String(prop)}" on circular dependency ${resolvedToken.name || resolvedToken} before it is instantiated.`);
+          }
+          return Reflect.set(target.instance, prop, value);
+        }
+      }) as any;
+    }
+
+    this.resolvingStack.push({ moduleClass, token: resolvedToken });
+
+    try {
+      const record = this.modules.get(moduleClass);
+      if (!record) {
+        throw new Error(`Module ${moduleClass.name || moduleClass} is not registered in the container`);
+      }
+
+      if (resolvedToken === REQUEST) {
+        if (!requestContext || !requestContext.has(REQUEST)) {
+          throw new Error(`calyx DI: REQUEST token resolved outside of a request context`);
+        }
+        return requestContext.get(REQUEST);
+      }
+
+      if (resolvedToken === 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 (resolvedToken === moduleClass) {
+        const instance = record.instances.get(moduleClass);
+        if (instance) return instance;
+        const instantiatedModule = await this.instantiateClassAsync(moduleClass, moduleClass, requestContext);
+        record.instances.set(moduleClass, instantiatedModule);
+        this.resolveDeferredProxies();
+        return instantiatedModule;
+      }
+
+      const resolution = this.findProviderDefinition(moduleClass, resolvedToken);
+      if (!resolution) {
+        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 === resolvedToken && optionalParams.has(i)) {
+                isOptional = true;
+                break;
+              }
+            }
+            if (isOptional) {
+              return undefined as any;
+            }
+          }
+        }
+        throw new Error(`calyx DI: Cannot resolve dependency "${String(resolvedToken.name ?? resolvedToken)}" in module ${moduleClass.name || moduleClass}`);
+      }
+
+      const { targetModuleClass, provider } = resolution;
+      const targetRecord = this.modules.get(targetModuleClass)!;
+
+      const scope = this.providerScopes.get(resolvedToken) ?? Scope.DEFAULT;
+
+      if (scope === Scope.REQUEST) {
+        if (!requestContext) {
+          throw new Error(`calyx DI: Cannot resolve request-scoped provider "${String(resolvedToken.name ?? resolvedToken)}" without request context.`);
+        }
+        if (requestContext.has(resolvedToken)) {
+          return requestContext.get(resolvedToken);
+        }
+        const instance = await this.createInstanceFromProviderAsync(provider, targetModuleClass, requestContext);
+        requestContext.set(resolvedToken, instance);
+        this.resolveDeferredProxies();
+        return instance;
+      }
+
+      if (scope === Scope.TRANSIENT) {
+        return await this.createInstanceFromProviderAsync(provider, targetModuleClass, requestContext);
+      }
+
+      if (targetRecord.instances.has(resolvedToken)) {
+        return targetRecord.instances.get(resolvedToken);
+      }
+
+      const instance = await this.createInstanceFromProviderAsync(provider, targetModuleClass, requestContext);
+      targetRecord.instances.set(resolvedToken, instance);
+      this.resolveDeferredProxies();
+      return instance;
+    } finally {
+      this.resolvingStack.pop();
+    }
+  }
+
+  private async createInstanceFromProviderAsync(provider: Provider, targetModuleClass: any, requestContext?: Map<any, any>): Promise<any> {
+    if (typeof provider !== 'function' && 'useValue' in provider) {
+      return provider.useValue;
+    } else if (typeof provider !== 'function' && 'useExisting' in provider) {
+      return await this.resolveTokenInModuleContextAsync(targetModuleClass, resolveForwardRef(provider.useExisting), requestContext);
+    } else if (typeof provider !== 'function' && 'useClass' in provider) {
+      return await this.instantiateClassAsync(provider.useClass, targetModuleClass, requestContext);
+    } else if (typeof provider !== 'function' && 'useFactory' in provider) {
+      const injectTokens = provider.inject || [];
+      const args = await Promise.all(
+        injectTokens.map((t) => this.resolveTokenInModuleContextAsync(targetModuleClass, resolveForwardRef(t), requestContext))
+      );
+      const res = provider.useFactory(...args);
+      return res instanceof Promise ? await res : res;
+    } else {
+      return await this.instantiateClassAsync(provider as Type<any>, targetModuleClass, requestContext);
+    }
+  }
+
+  public async instantiateClassAsync(Class: Type<any>, moduleClass: any, requestContext?: Map<any, any>): Promise<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 = await Promise.all(
+      paramTypes.map(async (paramType, i) => {
+        const token = injectTokens.get(i) ?? paramType;
+        const resolvedToken = resolveForwardRef(token);
+        
+        try {
+          return await this.resolveTokenInModuleContextAsync(moduleClass, resolvedToken, requestContext);
+        } catch (err) {
+          if (optionalParams.has(i)) {
+            return undefined;
+          }
+          throw err;
+        }
+      })
+    );
+
+    const instance = new Class(...args);
+
+    const propertyInjects: Map<string | symbol, InjectionToken> =
+      Reflect.getOwnMetadata(METADATA_KEYS.PROPERTY_INJECTS, Class) || new Map();
+    for (const [propertyKey, token] of propertyInjects.entries()) {
+      instance[propertyKey] = await this.resolveTokenInModuleContextAsync(moduleClass, resolveForwardRef(token), requestContext);
+    }
+
+    return instance;
+  }
+
   resolveControllerInRequestContext(moduleClass: any, controllerClass: any, requestContext: Map<any, any>): any {
     const scope = this.controllerScopes.get(controllerClass) ?? Scope.DEFAULT;
     if (scope === Scope.REQUEST) {
@@ -634,123 +1006,170 @@ export class CalyxContainer {
             return idx;
           };
 
+          const getLazyRequestProxy = (token: any, requestContext: Map<any, any>) => {
+            const proxyTarget = { instance: null as any };
+            return new Proxy(proxyTarget, {
+              get(target, prop) {
+                if (prop === '__isCalyxProxy') return true;
+                if (prop === '__proxyTarget') return target;
+                if (!target.instance) {
+                  target.instance = requestContext.get(token);
+                }
+                if (!target.instance) {
+                  if (typeof prop === 'symbol' || prop === 'then' || prop === 'toJSON') {
+                    return undefined;
+                  }
+                  throw new Error(`Calyx circular request proxy error: Accessing property "${String(prop)}" before it is instantiated.`);
+                }
+                const val = Reflect.get(target.instance, prop);
+                if (typeof val === 'function') {
+                  return val.bind(target.instance);
+                }
+                return val;
+              },
+              set(target, prop, value) {
+                if (!target.instance) {
+                  target.instance = requestContext.get(token);
+                }
+                if (!target.instance) {
+                  throw new Error(`Calyx circular request proxy error: Setting property "${String(prop)}" before it is instantiated.`);
+                }
+                return Reflect.set(target.instance, prop, value);
+              }
+            });
+          };
+
+          const lazyProxyHelperIdx = getClosureIdx(getLazyRequestProxy);
+
           const instantiations: string[] = [];
           const compiledTokens = new Set<string>();
+          const compilingTokens = new Set<string>();
 
           const compileToken = (token: any, currentModuleClass: any): string => {
-            if (token === REQUEST) {
+            const resolvedToken = resolveForwardRef(token);
+            if (resolvedToken === REQUEST) {
               return `requestContext.get(c[${getClosureIdx(REQUEST)}])`;
             }
-            if (token === ModuleRef) {
+            if (resolvedToken === ModuleRef) {
               const record = this.modules.get(currentModuleClass)!;
               return `c[${getClosureIdx(record.instances.get(ModuleRef))}]`;
             }
 
-            const scope = this.providerScopes.get(token) ?? Scope.DEFAULT;
+            const scope = this.providerScopes.get(resolvedToken) ?? Scope.DEFAULT;
             if (scope === Scope.DEFAULT) {
-              const instance = this.resolveTokenInModuleContext(currentModuleClass, token);
+              const instance = this.resolveTokenInModuleContext(currentModuleClass, resolvedToken);
               return `c[${getClosureIdx(instance)}]`;
             }
 
-            const tokenKey = `${currentModuleClass.name || currentModuleClass}::${String(token.name || token)}`;
+            const tokenKey = `${currentModuleClass.name || currentModuleClass}::${String(resolvedToken.name || resolvedToken)}`;
             if (compiledTokens.has(tokenKey)) {
-              return `requestContext.get(c[${getClosureIdx(token)}])`;
+              return `requestContext.get(c[${getClosureIdx(resolvedToken)}])`;
             }
-
-            const resolution = this.findProviderDefinition(currentModuleClass, token);
-            if (!resolution) {
-              const optional = this.isTokenOptional(token, currentModuleClass);
-              return optional ? `undefined` : `(() => { throw new Error('calyx JIT DI: Cannot resolve dependency ' + String(c[${getClosureIdx(token)}])); })()`;
+            if (compilingTokens.has(tokenKey)) {
+              return `c[${lazyProxyHelperIdx}](c[${getClosureIdx(resolvedToken)}], requestContext)`;
             }
 
-            const { targetModuleClass, provider } = resolution;
-            
-            let valExpr = '';
-            if (typeof provider !== 'function' && 'useValue' in provider) {
-              valExpr = `c[${getClosureIdx(provider.useValue)}]`;
-            } else {
-              const ClassToInstantiate = typeof provider === 'function'
-                ? provider
-                : ('useClass' in provider ? provider.useClass : null);
-
-              if (ClassToInstantiate) {
-                const paramTypes: any[] = Reflect.getMetadata('design:paramtypes', ClassToInstantiate) || [];
-                const injectTokens: Map<number, any> = Reflect.getMetadata(METADATA_KEYS.INJECT_TOKENS, ClassToInstantiate) || new Map();
-                const optionalParams: Set<number> = Reflect.getMetadata(METADATA_KEYS.OPTIONAL_PARAMS, ClassToInstantiate) || new Set();
-
-                const argsExprs = paramTypes.map((paramType, i) => {
-                  const depToken = injectTokens.get(i) ?? paramType;
-                  const resolvedDepToken = resolveForwardRef(depToken);
-                  try {
-                    return compileToken(resolvedDepToken, targetModuleClass);
-                  } catch (err) {
-                    if (optionalParams.has(i)) {
-                      return `undefined`;
+            compilingTokens.add(tokenKey);
+            try {
+              const resolution = this.findProviderDefinition(currentModuleClass, resolvedToken);
+              if (!resolution) {
+                const optional = this.isTokenOptional(resolvedToken, currentModuleClass);
+                return optional ? `undefined` : `(() => { throw new Error('calyx JIT DI: Cannot resolve dependency ' + String(c[${getClosureIdx(resolvedToken)}])); })()`;
+              }
+
+              const { targetModuleClass, provider } = resolution;
+              
+              let valExpr = '';
+              if (typeof provider !== 'function' && 'useValue' in provider) {
+                valExpr = `c[${getClosureIdx(provider.useValue)}]`;
+              } else if (typeof provider !== 'function' && 'useExisting' in provider) {
+                return compileToken(resolveForwardRef(provider.useExisting), targetModuleClass);
+              } else {
+                const ClassToInstantiate = typeof provider === 'function'
+                  ? provider
+                  : ('useClass' in provider ? provider.useClass : null);
+
+                if (ClassToInstantiate) {
+                  const paramTypes: any[] = Reflect.getMetadata('design:paramtypes', ClassToInstantiate) || [];
+                  const injectTokens: Map<number, any> = Reflect.getMetadata(METADATA_KEYS.INJECT_TOKENS, ClassToInstantiate) || new Map();
+                  const optionalParams: Set<number> = Reflect.getMetadata(METADATA_KEYS.OPTIONAL_PARAMS, ClassToInstantiate) || new Set();
+
+                  const argsExprs = paramTypes.map((paramType, i) => {
+                    const depToken = injectTokens.get(i) ?? paramType;
+                    const resolvedDepToken = resolveForwardRef(depToken);
+                    try {
+                      return compileToken(resolvedDepToken, targetModuleClass);
+                    } catch (err) {
+                      if (optionalParams.has(i)) {
+                        return `undefined`;
+                      }
+                      throw err;
                     }
-                    throw err;
+                  });
+
+                  const propertyInjects: Map<string | symbol, any> =
+                    Reflect.getOwnMetadata(METADATA_KEYS.PROPERTY_INJECTS, ClassToInstantiate) || new Map();
+                  
+                  const propAssignments: string[] = [];
+                  for (const [propKey, propToken] of propertyInjects.entries()) {
+                    const resolvedPropToken = resolveForwardRef(propToken);
+                    const propValExpr = compileToken(resolvedPropToken, targetModuleClass);
+                    propAssignments.push(`inst.${String(propKey)} = ${propValExpr};`);
                   }
-                });
-
-                const propertyInjects: Map<string | symbol, any> =
-                  Reflect.getOwnMetadata(METADATA_KEYS.PROPERTY_INJECTS, ClassToInstantiate) || new Map();
-                
-                const propAssignments: string[] = [];
-                for (const [propKey, propToken] of propertyInjects.entries()) {
-                  const resolvedPropToken = resolveForwardRef(propToken);
-                  const propValExpr = compileToken(resolvedPropToken, targetModuleClass);
-                  propAssignments.push(`inst.${String(propKey)} = ${propValExpr};`);
-                }
 
-                const classIdx = getClosureIdx(ClassToInstantiate);
-                const instantiateExpr = `new c[${classIdx}](${argsExprs.join(', ')})`;
-
-                if (scope === Scope.REQUEST) {
-                  compiledTokens.add(tokenKey);
-                  const tokenIdx = getClosureIdx(token);
-                  instantiations.push(`
-                    if (!requestContext.has(c[${tokenIdx}])) {
-                      const inst = ${instantiateExpr};
-                      ${propAssignments.join('\n')}
-                      requestContext.set(c[${tokenIdx}], inst);
+                  const classIdx = getClosureIdx(ClassToInstantiate);
+                  const instantiateExpr = `new c[${classIdx}](${argsExprs.join(', ')})`;
+
+                  if (scope === Scope.REQUEST) {
+                    compiledTokens.add(tokenKey);
+                    const tokenIdx = getClosureIdx(resolvedToken);
+                    instantiations.push(`
+                      if (!requestContext.has(c[${tokenIdx}])) {
+                        const inst = ${instantiateExpr};
+                        ${propAssignments.join('\n')}
+                        requestContext.set(c[${tokenIdx}], inst);
+                      }
+                    `);
+                    valExpr = `requestContext.get(c[${tokenIdx}])`;
+                  } else {
+                    if (propAssignments.length > 0) {
+                      const tempVar = `transient_${compiledTokens.size}`;
+                      compiledTokens.add(tempVar);
+                      instantiations.push(`
+                        const ${tempVar} = ${instantiateExpr};
+                        ${propAssignments.map(line => line.replace('inst.', `${tempVar}.`)).join('\n')}
+                      `);
+                      valExpr = tempVar;
+                    } else {
+                      valExpr = instantiateExpr;
                     }
-                  `);
-                  valExpr = `requestContext.get(c[${tokenIdx}])`;
-                } else {
-                  if (propAssignments.length > 0) {
-                    const tempVar = `transient_${compiledTokens.size}`;
-                    compiledTokens.add(tempVar);
+                  }
+                } else if (provider && typeof provider === 'object' && 'useFactory' in provider) {
+                  const injectTokens = provider.inject || [];
+                  const argsExprs = injectTokens.map((t) => compileToken(resolveForwardRef(t), targetModuleClass));
+                  
+                  const factoryIdx = getClosureIdx(provider.useFactory);
+                  const factoryCallExpr = `c[${factoryIdx}](${argsExprs.join(', ')})`;
+
+                  if (scope === Scope.REQUEST) {
+                    compiledTokens.add(tokenKey);
+                    const tokenIdx = getClosureIdx(resolvedToken);
                     instantiations.push(`
-                      const ${tempVar} = ${instantiateExpr};
-                      ${propAssignments.map(line => line.replace('inst.', `${tempVar}.`)).join('\n')}
+                      if (!requestContext.has(c[${tokenIdx}])) {
+                        requestContext.set(c[${tokenIdx}], ${factoryCallExpr});
+                      }
                     `);
-                    valExpr = tempVar;
+                    valExpr = `requestContext.get(c[${tokenIdx}])`;
                   } else {
-                    valExpr = instantiateExpr;
+                    valExpr = factoryCallExpr;
                   }
                 }
-              } else if (provider && typeof provider === 'object' && 'useFactory' in provider) {
-                const injectTokens = provider.inject || [];
-                const argsExprs = injectTokens.map((t) => compileToken(resolveForwardRef(t), targetModuleClass));
-                
-                const factoryIdx = getClosureIdx(provider.useFactory);
-                const factoryCallExpr = `c[${factoryIdx}](${argsExprs.join(', ')})`;
-
-                if (scope === Scope.REQUEST) {
-                  compiledTokens.add(tokenKey);
-                  const tokenIdx = getClosureIdx(token);
-                  instantiations.push(`
-                    if (!requestContext.has(c[${tokenIdx}])) {
-                      requestContext.set(c[${tokenIdx}], ${factoryCallExpr});
-                    }
-                  `);
-                  valExpr = `requestContext.get(c[${tokenIdx}])`;
-                } else {
-                  valExpr = factoryCallExpr;
-                }
               }
-            }
 
-            return valExpr;
+              return valExpr;
+            } finally {
+              compilingTokens.delete(tokenKey);
+            }
           };
 
           const paramTypes: any[] = Reflect.getMetadata('design:paramtypes', controllerClass) || [];