@martel/calyx 1.10.1 → 1.12.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [1.12.0](https://github.com/bmartel/calyx/compare/v1.11.0...v1.12.0) (2026-07-01)
+
+
+### Features
+
+* **core:** implement core NestJS feature parity extensions ([ba69f26](https://github.com/bmartel/calyx/commit/ba69f266d1b6ead3ab2ce4f6c5b112258131ed75))
+
+# [1.11.0](https://github.com/bmartel/calyx/compare/v1.10.1...v1.11.0) (2026-07-01)
+
+
+### Features
+
+* **graphql,openapi:** support schema-first compiling, custom context and validation schema auto-enrichment ([e8dcce7](https://github.com/bmartel/calyx/commit/e8dcce78d75097ac88a8a3a984b5834d4d7f1818))
+
 ## [1.10.1](https://github.com/bmartel/calyx/compare/v1.10.0...v1.10.1) (2026-07-01)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martel/calyx",
-  "version": "1.10.1",
+  "version": "1.12.0",
   "description": "High-performance Bun-native NestJS-compatible framework",
   "main": "src/index.ts",
   "bin": {

package/src/cache/cache.interceptor.ts

@@ -18,7 +18,9 @@ export class CacheInterceptor implements NestInterceptor {
     }
 
     const url = new URL(req.url);
-    const key = `http_cache::${url.pathname}${url.search}`;
+    const handler = context.getHandler();
+    const key = Reflect.getMetadata('cache_metadata_key', handler) ?? `http_cache::${url.pathname}${url.search}`;
+    const ttl = Reflect.getMetadata('cache_metadata_ttl', handler);
 
     const cached = await this.cacheService.get(key);
     if (cached !== undefined) {
@@ -26,7 +28,7 @@ export class CacheInterceptor implements NestInterceptor {
     }
 
     const result = await next.handle();
-    await this.cacheService.set(key, result);
+    await this.cacheService.set(key, result, ttl);
     return result;
   }
 }

package/src/cache/decorators.ts

@@ -0,0 +1,4 @@
+import { SetMetadata } from '../core/decorators.ts';
+
+export const CacheKey = (key: string) => SetMetadata('cache_metadata_key', key);
+export const CacheTTL = (ttl: number) => SetMetadata('cache_metadata_ttl', ttl);

package/src/cache/index.ts

@@ -1,3 +1,4 @@
 export * from './cache.service.ts';
 export * from './cache.interceptor.ts';
 export * from './cache.module.ts';
+export * from './decorators.ts';

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);
   }
 }
 
@@ -288,6 +288,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) {
@@ -415,13 +417,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 +451,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,7 +460,6 @@ 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);
@@ -452,6 +470,35 @@ export class CalyxContainer {
     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.compileControllerFactories();
+  }
+
   private resolveController(moduleClass: any, controllerClass: any): any {
     const record = this.modules.get(moduleClass)!;
     if (record.instances.has(controllerClass)) {
@@ -462,6 +509,16 @@ export class CalyxContainer {
     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);
+    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)) {
@@ -475,6 +532,180 @@ 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 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`);
+      }
+
+      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;
+        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 = await this.instantiateClassAsync(moduleClass, moduleClass, requestContext);
+        record.instances.set(moduleClass, instantiatedModule);
+        return instantiatedModule;
+      }
+
+      const resolution = this.findProviderDefinition(moduleClass, token);
+      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 === 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)!;
+
+      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 = await this.createInstanceFromProviderAsync(provider, targetModuleClass, requestContext);
+        requestContext.set(token, instance);
+        return instance;
+      }
+
+      if (scope === Scope.TRANSIENT) {
+        return await this.createInstanceFromProviderAsync(provider, targetModuleClass, requestContext);
+      }
+
+      if (targetRecord.instances.has(token)) {
+        return targetRecord.instances.get(token);
+      }
+
+      const instance = await this.createInstanceFromProviderAsync(provider, targetModuleClass, requestContext);
+      targetRecord.instances.set(token, instance);
+      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, 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) {
@@ -668,6 +899,8 @@ export class CalyxContainer {
             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

package/src/core/index.ts

@@ -3,3 +3,5 @@ export * from './decorators.ts';
 export * from './module-ref.ts';
 export * from './container.ts';
 export * from './reflector.ts';
+export * from './lazy-module-loader.ts';
+export * from './testing-module.ts';

package/src/core/lazy-module-loader.ts

@@ -0,0 +1,29 @@
+import { Injectable } from './decorators.ts';
+import { CalyxContainer } from './container.ts';
+import { ModuleRef } from './module-ref.ts';
+
+@Injectable()
+export class LazyModuleLoader {
+  constructor(private readonly moduleRef: ModuleRef) {}
+
+  async load(loader: () => Promise<any> | any): Promise<ModuleRef> {
+    let moduleClass = await loader();
+    if (moduleClass && typeof moduleClass === 'object' && 'default' in moduleClass) {
+      moduleClass = moduleClass.default;
+    }
+    
+    const container: CalyxContainer = (this.moduleRef as any).container;
+    if (!container) {
+      throw new Error('LazyModuleLoader: Container reference not found on moduleRef');
+    }
+    
+    await container.bootstrap(moduleClass);
+    
+    const record = container.getModuleRecord(moduleClass);
+    if (!record) {
+      throw new Error(`LazyModuleLoader: Module record not found for ${moduleClass.name}`);
+    }
+    
+    return record.instances.get(ModuleRef);
+  }
+}

package/src/core/metadata.ts

@@ -44,7 +44,12 @@ export interface FactoryProvider {
   scope?: Scope;
 }
 
-export type Provider = Type<any> | ValueProvider | ClassProvider | FactoryProvider;
+export interface ExistingProvider {
+  provide: InjectionToken;
+  useExisting: InjectionToken;
+}
+
+export type Provider = Type<any> | ValueProvider | ClassProvider | FactoryProvider | ExistingProvider;
 
 export interface ModuleMetadata {
   imports?: any[];

package/src/core/testing-module.ts

@@ -0,0 +1,119 @@
+import { CalyxContainer } from './container.ts';
+import { ModuleMetadata, Type, InjectionToken } from './metadata.ts';
+import { Module } from './decorators.ts';
+import { ModuleRef } from './module-ref.ts';
+import { CalyxApplication } from '../http/application.ts';
+
+export class TestingModule extends ModuleRef {
+  constructor(public readonly container: CalyxContainer, private readonly rootModuleClass: any) {
+    super();
+  }
+
+  createCalyxApplication(): CalyxApplication {
+    const app = new CalyxApplication(this.rootModuleClass);
+    (app as any).container = this.container;
+    return app;
+  }
+
+  get<T>(token: InjectionToken, options?: { strict: boolean }): T {
+    const strict = options?.strict ?? false;
+    if (strict) {
+      return this.container.resolveTokenInModuleContext(this.rootModuleClass, token);
+    } else {
+      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 ?? false;
+    if (strict) {
+      return await this.container.resolveTokenInModuleContextAsync(this.rootModuleClass, token, requestContext);
+    } else {
+      return await this.container.resolveTokenGloballyAsync(token, requestContext);
+    }
+  }
+
+  async create<T>(type: Type<T>): Promise<T> {
+    return await this.container.instantiateClassAsync(type, this.rootModuleClass);
+  }
+
+  async close() {
+    const instances = this.container.getProviderAndControllerInstances();
+    for (const inst of instances) {
+      if (inst && typeof inst.onModuleDestroy === 'function') {
+        await inst.onModuleDestroy();
+      }
+      if (inst && typeof inst.onApplicationShutdown === 'function') {
+        await inst.onApplicationShutdown();
+      }
+    }
+  }
+}
+
+export class TestingModuleBuilder {
+  private overrides = new Map<InjectionToken, { useValue?: any; useClass?: any; useFactory?: any; inject?: any[] }>();
+
+  constructor(private readonly metadata: ModuleMetadata) {}
+
+  overrideProvider(token: InjectionToken) {
+    const builder = {
+      useValue: (value: any) => {
+        this.overrides.set(token, { useValue: value });
+        return this;
+      },
+      useClass: (clazz: any) => {
+        this.overrides.set(token, { useClass: clazz });
+        return this;
+      },
+      useFactory: (options: { factory: (...args: any[]) => any; inject?: any[] }) => {
+        this.overrides.set(token, { useFactory: options.factory, inject: options.inject });
+        return this;
+      },
+    };
+    return builder;
+  }
+
+  overrideGuard(token: any) { return this.overrideProvider(token); }
+  overrideInterceptor(token: any) { return this.overrideProvider(token); }
+  overridePipe(token: any) { return this.overrideProvider(token); }
+  overrideFilter(token: any) { return this.overrideProvider(token); }
+
+  async compile(): Promise<TestingModule> {
+    @Module({
+      imports: this.metadata.imports || [],
+      controllers: this.metadata.controllers || [],
+      providers: this.metadata.providers || [],
+      exports: this.metadata.exports || [],
+    })
+    class RootTestModule {}
+
+    const container = new CalyxContainer();
+    container.addModule(RootTestModule);
+
+    // Apply overrides to module records
+    for (const [token, override] of this.overrides.entries()) {
+      for (const record of (container as any).modules.values()) {
+        if (record.providers.has(token)) {
+          if ('useValue' in override) {
+            record.providers.set(token, { provide: token, useValue: override.useValue });
+          } else if ('useClass' in override) {
+            record.providers.set(token, { provide: token, useClass: override.useClass });
+          } else if ('useFactory' in override) {
+            record.providers.set(token, { provide: token, useFactory: override.useFactory, inject: override.inject });
+          }
+        }
+      }
+    }
+
+    await container.bootstrap(RootTestModule);
+
+    return new TestingModule(container, RootTestModule);
+  }
+}
+
+export class Test {
+  static createTestingModule(metadata: ModuleMetadata): TestingModuleBuilder {
+    return new TestingModuleBuilder(metadata);
+  }
+}