@martel/calyx 0.1.0 → 1.0.0

package/src/http/application.ts

@@ -1,12 +1,12 @@
-import { calyxContainer } from '../core/container.ts';
-import { METADATA_KEYS } from '../core/metadata.ts';
+import { CalyxContainer } from '../core/container.ts';
+import { METADATA_KEYS, Scope, REQUEST } from '../core/metadata.ts';
 import { RadixRouter } from './router.ts';
 import { ParameterConfig } from './decorators.ts';
 import { HttpException, NotFoundException } from './exceptions.ts';
 import { ArgumentsHost, ExecutionContext } from '../lifecycle/interfaces.ts';
-import { calyxArgumentsHost, calyxExecutionContext } from '../lifecycle/context.ts';
+import { CalyxArgumentsHost, CalyxExecutionContext } from '../lifecycle/context.ts';
 
-export class calyxResponse {
+export class CalyxResponse {
   statusCode = 200;
   headers = new Headers();
   body: any = null;
@@ -36,21 +36,39 @@ export class calyxResponse {
   }
 }
 
+interface CompiledLifecycleItem {
+  isReqScoped: boolean;
+  token: any;
+  instance: any;
+}
+
+interface CompiledParameterConfig extends ParameterConfig {
+  pipesList: CompiledLifecycleItem[];
+  paramType: any;
+}
+
 interface HandlerConfig {
+  controllerClass: any;
+  moduleClass: any;
   instance: any;
   methodName: string;
-  paramsConfig: ParameterConfig[];
+  paramsConfig: CompiledParameterConfig[];
   httpCode?: number;
   headers: { name: string; value: string }[];
   redirect?: { url: string; statusCode?: number };
   hasBodyParam: boolean;
   hasQueryParam: boolean;
   hasResParam: boolean;
+  isPassthrough: boolean;
+  isRequestScoped: boolean;
   hasLifecycleMetadata: boolean;
+  guardsList: CompiledLifecycleItem[];
+  interceptorsList: CompiledLifecycleItem[];
+  filtersList: CompiledLifecycleItem[];
 }
 
-export class calyxApplication {
-  private container = new calyxContainer();
+export class CalyxApplication {
+  private container = new CalyxContainer();
   private router = new RadixRouter<HandlerConfig>();
   private server: any;
 
@@ -83,6 +101,12 @@ export class calyxApplication {
 
     // Build the routing table from registered controllers
     this.buildRoutes();
+
+    // Call OnModuleInit hooks
+    await this.runOnModuleInit();
+
+    // Call OnApplicationBootstrap hooks
+    await this.runOnApplicationBootstrap();
   }
 
   private buildRoutes() {
@@ -90,10 +114,11 @@ export class calyxApplication {
     for (const [moduleClass, record] of modules.entries()) {
       for (const controllerClass of record.controllers) {
         const prefix = Reflect.getMetadata(METADATA_KEYS.CONTROLLER, controllerClass) ?? '';
-        const instance = record.instances.get(controllerClass);
-        if (!instance) continue;
-
         const methods = this.getMethods(controllerClass.prototype);
+        const controllerScope = this.container.getControllerScope(controllerClass);
+        const isRequestScoped = controllerScope === Scope.REQUEST;
+        const instance = isRequestScoped ? null : record.instances.get(controllerClass);
+
         for (const method of methods) {
           const routeMeta = Reflect.getMetadata(METADATA_KEYS.HTTP_METHOD, controllerClass.prototype, method);
           if (!routeMeta) continue;
@@ -114,29 +139,59 @@ export class calyxApplication {
           const hasBodyParam = paramsConfig.some((p) => p.type === 'body');
           const hasQueryParam = paramsConfig.some((p) => p.type === 'query');
           const hasResParam = paramsConfig.some((p) => p.type === 'res');
+          const resParamConfig = paramsConfig.find((p) => p.type === 'res');
+          const isPassthrough = resParamConfig?.name === 'passthrough';
+
+          // Compile lifecycle lists
+          const classGuards = Reflect.getMetadata(METADATA_KEYS.GUARDS, controllerClass) || [];
+          const methodGuards = Reflect.getMetadata(METADATA_KEYS.GUARDS, controllerClass.prototype, method) || [];
+          const guardsList = this.compileLifecycleItems(moduleClass, [...this.globalGuards, ...classGuards, ...methodGuards]);
+
+          const classInterceptors = Reflect.getMetadata(METADATA_KEYS.INTERCEPTORS, controllerClass) || [];
+          const methodInterceptors = Reflect.getMetadata(METADATA_KEYS.INTERCEPTORS, controllerClass.prototype, method) || [];
+          const interceptorsList = this.compileLifecycleItems(moduleClass, [...this.globalInterceptors, ...classInterceptors, ...methodInterceptors]);
+
+          const classFilters = Reflect.getMetadata(METADATA_KEYS.FILTERS, controllerClass) || [];
+          const methodFilters = Reflect.getMetadata(METADATA_KEYS.FILTERS, controllerClass.prototype, method) || [];
+          const filtersList = this.compileLifecycleItems(moduleClass, [...this.globalFilters, ...classFilters, ...methodFilters]);
+
+          const paramTypes = Reflect.getMetadata('design:paramtypes', controllerClass.prototype, method) || [];
+          const compiledParamsConfig: CompiledParameterConfig[] = paramsConfig.map((p) => {
+            const classPipes = Reflect.getMetadata(METADATA_KEYS.PIPES, controllerClass) || [];
+            const methodPipes = Reflect.getMetadata(METADATA_KEYS.PIPES, controllerClass.prototype, method) || [];
+            const paramPipes = p.pipes || [];
+            const allPipes = [...this.globalPipes, ...classPipes, ...methodPipes, ...paramPipes];
+            return {
+              ...p,
+              pipesList: this.compileLifecycleItems(moduleClass, allPipes),
+              paramType: paramTypes[p.index],
+            };
+          });
 
           const hasLifecycleMetadata =
-            Reflect.hasMetadata(METADATA_KEYS.GUARDS, controllerClass) ||
-            Reflect.hasMetadata(METADATA_KEYS.GUARDS, controllerClass.prototype, method) ||
-            Reflect.hasMetadata(METADATA_KEYS.INTERCEPTORS, controllerClass) ||
-            Reflect.hasMetadata(METADATA_KEYS.INTERCEPTORS, controllerClass.prototype, method) ||
-            Reflect.hasMetadata(METADATA_KEYS.PIPES, controllerClass) ||
-            Reflect.hasMetadata(METADATA_KEYS.PIPES, controllerClass.prototype, method) ||
-            Reflect.hasMetadata(METADATA_KEYS.FILTERS, controllerClass) ||
-            Reflect.hasMetadata(METADATA_KEYS.FILTERS, controllerClass.prototype, method) ||
-            paramsConfig.some((p) => p.pipes && p.pipes.length > 0);
+            guardsList.length > 0 ||
+            interceptorsList.length > 0 ||
+            filtersList.length > 0 ||
+            compiledParamsConfig.some((p) => p.pipesList.length > 0);
 
           this.router.insert(routeMeta.method, fullPath, {
+            controllerClass,
+            moduleClass,
             instance,
             methodName: method,
-            paramsConfig,
+            paramsConfig: compiledParamsConfig,
             httpCode,
             headers,
             redirect,
             hasBodyParam,
             hasQueryParam,
             hasResParam,
+            isPassthrough,
+            isRequestScoped,
             hasLifecycleMetadata,
+            guardsList,
+            interceptorsList,
+            filtersList,
           });
         }
       }
@@ -188,21 +243,30 @@ export class calyxApplication {
 
       const { handler, params } = matched;
 
+      let instance = handler.instance;
+      let requestContext: Map<any, any> | undefined = undefined;
+
+      if (handler.isRequestScoped) {
+        requestContext = new Map<any, any>();
+        requestContext.set(REQUEST, req);
+        instance = this.container.resolveControllerInRequestContext(handler.moduleClass, handler.controllerClass, requestContext);
+      }
+
       // Check if we need to run lifecycle hooks
       const hasLifecycle = handler.hasLifecycleMetadata || this.hasGlobalLifecycle();
       if (hasLifecycle) {
         if (handler.hasBodyParam && req.body && req.method !== 'GET' && req.method !== 'HEAD') {
-          return this.handleRequestPipelineAsync(req, handler, params, search);
+          return this.handleRequestPipelineAsync(req, handler, params, search, instance, requestContext);
         }
-        return this.handleRequestPipeline(req, handler, params, search, null);
+        return this.handleRequestPipeline(req, handler, params, search, null, instance, requestContext);
       }
 
       // Check if we need to parse body (which makes it async)
       if (handler.hasBodyParam && req.body && req.method !== 'GET' && req.method !== 'HEAD') {
-        return this.handleRequestAsync(req, handler, params, search);
+        return this.handleRequestAsync(req, handler, params, search, instance, requestContext);
       }
 
-      return this.executeHandlerSync(req, handler, params, search, null);
+      return this.executeHandlerSync(req, handler, params, search, null, instance, requestContext);
     } catch (err: any) {
       return this.handleError(err);
     }
@@ -212,7 +276,9 @@ export class calyxApplication {
     req: Request,
     handler: HandlerConfig,
     params: Record<string, string>,
-    search: string
+    search: string,
+    instance: any,
+    requestContext?: Map<any, any>
   ): Promise<Response> {
     try {
       let body: any = null;
@@ -238,11 +304,11 @@ export class calyxApplication {
         }
       }
 
-      return this.handleRequestPipeline(req, handler, params, search, body);
+      return this.handleRequestPipeline(req, handler, params, search, body, instance, requestContext);
     } catch (err: any) {
-      const resWrapper = new calyxResponse();
-      const host = new calyxArgumentsHost(req, resWrapper);
-      return this.handleLifecycleError(err, host, handler.instance.constructor, handler.methodName);
+      const resWrapper = new CalyxResponse();
+      const host = new CalyxArgumentsHost(req, resWrapper);
+      return this.handleLifecycleError(err, host, handler.controllerClass, handler.methodName, requestContext);
     }
   }
 
@@ -251,34 +317,32 @@ export class calyxApplication {
     handler: HandlerConfig,
     params: Record<string, string>,
     search: string,
-    body: any
+    body: any,
+    instance: any,
+    requestContext?: Map<any, any>
   ): Promise<Response> {
-    const { instance, methodName, paramsConfig, httpCode, headers, redirect, hasQueryParam, hasResParam } = handler;
-    const controllerClass = instance.constructor;
-    const moduleClass = this.getControllerModule(controllerClass);
-    const resWrapper = new calyxResponse();
-    const host = new calyxArgumentsHost(req, resWrapper);
-    const context = new calyxExecutionContext(req, resWrapper, controllerClass, instance[methodName]);
+    const { methodName, paramsConfig, httpCode, headers, redirect, hasQueryParam } = handler;
+    const controllerClass = handler.controllerClass;
+    const moduleClass = handler.moduleClass;
+    const resWrapper = new CalyxResponse();
+    const host = new CalyxArgumentsHost(req, resWrapper);
+    const context = new CalyxExecutionContext(req, resWrapper, controllerClass, instance[methodName]);
 
     try {
       // 1. Run Guards
-      const classGuards = Reflect.getMetadata(METADATA_KEYS.GUARDS, controllerClass) || [];
-      const methodGuards = Reflect.getMetadata(METADATA_KEYS.GUARDS, controllerClass.prototype, methodName) || [];
-      const guards = [...this.globalGuards, ...classGuards, ...methodGuards];
-
-      for (const guard of guards) {
-        const guardInstance = this.resolveLifecycleInstance(moduleClass, guard);
-        const canActivate = await guardInstance.canActivate(context);
-        if (!canActivate) {
+      for (const guard of handler.guardsList) {
+        const guardInstance = guard.isReqScoped
+          ? this.container.resolveTokenInModuleContext(moduleClass, guard.token, requestContext)
+          : guard.instance;
+        const canActivate = guardInstance.canActivate(context);
+        if (canActivate instanceof Promise) {
+          const resolved = await canActivate;
+          if (!resolved) throw new HttpException('Forbidden resource', 403);
+        } else if (!canActivate) {
           throw new HttpException('Forbidden resource', 403);
         }
       }
 
-      // 2. Run Interceptors & Pipes & Handler
-      const classInterceptors = Reflect.getMetadata(METADATA_KEYS.INTERCEPTORS, controllerClass) || [];
-      const methodInterceptors = Reflect.getMetadata(METADATA_KEYS.INTERCEPTORS, controllerClass.prototype, methodName) || [];
-      const interceptors = [...this.globalInterceptors, ...classInterceptors, ...methodInterceptors];
-
       let query: any = null;
       if (hasQueryParam && search) {
         query = Object.fromEntries(new URLSearchParams(search).entries());
@@ -286,83 +350,83 @@ export class calyxApplication {
         query = {};
       }
 
-      const paramTypes = Reflect.getMetadata('design:paramtypes', controllerClass.prototype, methodName) || [];
-
       // Execute pipes for each argument
       const args: any[] = [];
       for (const config of paramsConfig) {
         let val: any;
         switch (config.type) {
-          case 'req':
-            val = req;
-            break;
-          case 'res':
-            val = resWrapper;
-            break;
-          case 'param':
-            val = config.name ? params[config.name] : params;
-            break;
-          case 'query':
-            val = config.name ? query?.[config.name] : query;
-            break;
-          case 'body':
-            val = config.name ? body?.[config.name] : body;
-            break;
-          case 'headers':
-            val = config.name ? req.headers.get(config.name) : Object.fromEntries(req.headers.entries());
-            break;
+          case 'req': val = req; break;
+          case 'res': val = resWrapper; break;
+          case 'param': val = config.name ? params[config.name] : params; break;
+          case 'query': val = config.name ? query?.[config.name] : query; break;
+          case 'body': val = config.name ? body?.[config.name] : body; break;
+          case 'headers': val = config.name ? req.headers.get(config.name) : Object.fromEntries(req.headers.entries()); break;
+          case 'custom': val = config.factory ? config.factory(config.name, context) : undefined; break;
         }
 
         // Apply pipes
-        const classPipes = Reflect.getMetadata(METADATA_KEYS.PIPES, controllerClass) || [];
-        const methodPipes = Reflect.getMetadata(METADATA_KEYS.PIPES, controllerClass.prototype, methodName) || [];
-        const paramPipes = config.pipes || [];
-        const pipes = [...this.globalPipes, ...classPipes, ...methodPipes, ...paramPipes];
-
-        for (const pipe of pipes) {
-          const pipeInstance = this.resolveLifecycleInstance(moduleClass, pipe);
-          val = await pipeInstance.transform(val, {
+        for (const pipe of config.pipesList) {
+          const pipeInstance = pipe.isReqScoped
+            ? this.container.resolveTokenInModuleContext(moduleClass, pipe.token, requestContext)
+            : pipe.instance;
+          const transformed = pipeInstance.transform(val, {
             type: config.type,
-            metatype: paramTypes[config.index],
+            metatype: config.paramType,
             data: config.name,
           });
+          if (transformed instanceof Promise) {
+            val = await transformed;
+          } else {
+            val = transformed;
+          }
         }
 
         args[config.index] = val;
       }
 
-      let interceptorIndex = 0;
-      const executeHandler = async (): Promise<any> => {
-        if (interceptorIndex < interceptors.length) {
-          const interceptor = interceptors[interceptorIndex++];
-          const interceptorInstance = this.resolveLifecycleInstance(moduleClass, interceptor);
-          return interceptorInstance.intercept(context, { handle: () => executeHandler() });
+      let result: any;
+      if (handler.interceptorsList.length > 0) {
+        let interceptorIndex = 0;
+        const executeHandler = async (): Promise<any> => {
+          if (interceptorIndex < handler.interceptorsList.length) {
+            const interceptor = handler.interceptorsList[interceptorIndex++];
+            const interceptorInstance = interceptor.isReqScoped
+              ? this.container.resolveTokenInModuleContext(moduleClass, interceptor.token, requestContext)
+              : interceptor.instance;
+            return interceptorInstance.intercept(context, { handle: () => executeHandler() });
+          }
+          return instance[methodName](...args);
+        };
+        result = await executeHandler();
+      } else {
+        result = instance[methodName](...args);
+        if (result instanceof Promise) {
+          result = await result;
         }
-        return instance[methodName](...args);
-      };
+      }
 
-      const result = await executeHandler();
+      if (this.isObservable(result)) {
+        result = await this.resolveObservable(result);
+      }
 
-      return this.processResult(req, result, resWrapper, httpCode, headers, redirect);
+      return this.processResult(req, result, resWrapper, httpCode, headers, redirect, handler.isPassthrough, handler.hasResParam);
     } catch (err: any) {
-      return this.handleLifecycleError(err, host, controllerClass, methodName);
+      return this.handleLifecycleError(err, host, handler, requestContext);
     }
   }
 
   private async handleLifecycleError(
     err: any,
     host: ArgumentsHost,
-    controllerClass: any,
-    methodName: string
+    handler: HandlerConfig,
+    requestContext?: Map<any, any>
   ): Promise<Response> {
-    const classFilters = Reflect.getMetadata(METADATA_KEYS.FILTERS, controllerClass) || [];
-    const methodFilters = Reflect.getMetadata(METADATA_KEYS.FILTERS, controllerClass.prototype, methodName) || [];
-    const filters = [...this.globalFilters, ...classFilters, ...methodFilters];
-
-    const moduleClass = this.getControllerModule(controllerClass);
+    const moduleClass = handler.moduleClass;
 
-    for (const filter of filters) {
-      const filterInstance = this.resolveLifecycleInstance(moduleClass, filter);
+    for (const filter of handler.filtersList) {
+      const filterInstance = filter.isReqScoped
+        ? this.container.resolveTokenInModuleContext(moduleClass, filter.token, requestContext)
+        : filter.instance;
       const catchExceptions = Reflect.getMetadata(METADATA_KEYS.CATCH, filterInstance.constructor) || [];
 
       const catchesException =
@@ -370,8 +434,11 @@ export class calyxApplication {
         catchExceptions.some((excClass: any) => err instanceof excClass);
 
       if (catchesException) {
-        await filterInstance.catch(err, host);
-        const resWrapper = host.switchToHttp().getResponse<calyxResponse>();
+        const catchResult = filterInstance.catch(err, host);
+        if (catchResult instanceof Promise) {
+          await catchResult;
+        }
+        const resWrapper = host.switchToHttp().getResponse<CalyxResponse>();
         if (resWrapper.sent) {
           return new Response(resWrapper.body, {
             status: resWrapper.statusCode,
@@ -384,32 +451,33 @@ export class calyxApplication {
     return this.handleError(err);
   }
 
-  private getControllerModule(controllerClass: any): any {
-    const modules = this.container.getModules();
-    for (const [moduleClass, record] of modules.entries()) {
-      if (record.controllers.has(controllerClass)) {
-        return moduleClass;
-      }
-    }
-    return null;
-  }
-
-  private resolveLifecycleInstance(moduleClass: any, item: any): any {
-    if (typeof item === 'function') {
-      try {
-        return this.container.resolveTokenInModuleContext(moduleClass, item);
-      } catch {
-        return new item();
+  private compileLifecycleItems(moduleClass: any, items: any[]): CompiledLifecycleItem[] {
+    return items.map((item) => {
+      if (typeof item === 'function') {
+        const scope = this.container.getProviderScope(item);
+        if (scope === Scope.REQUEST) {
+          return { isReqScoped: true, token: item, instance: null };
+        } else {
+          let instance: any;
+          try {
+            instance = this.container.resolveTokenInModuleContext(moduleClass, item);
+          } catch {
+            instance = new item();
+          }
+          return { isReqScoped: false, token: item, instance };
+        }
       }
-    }
-    return item;
+      return { isReqScoped: false, token: item.constructor, instance: item };
+    });
   }
 
   private async handleRequestAsync(
     req: Request,
     handler: HandlerConfig,
     params: Record<string, string>,
-    search: string
+    search: string,
+    instance: any,
+    requestContext?: Map<any, any>
   ): Promise<Response> {
     try {
       let body: any = null;
@@ -435,7 +503,7 @@ export class calyxApplication {
         }
       }
 
-      return this.executeHandlerSync(req, handler, params, search, body);
+      return this.executeHandlerSync(req, handler, params, search, body, instance, requestContext);
     } catch (err: any) {
       return this.handleError(err);
     }
@@ -446,9 +514,11 @@ export class calyxApplication {
     handler: HandlerConfig,
     params: Record<string, string>,
     search: string,
-    body: any
+    body: any,
+    instance: any,
+    requestContext?: Map<any, any>
   ): Response | Promise<Response> {
-    const { instance, methodName, paramsConfig, httpCode, headers, redirect, hasQueryParam, hasResParam } = handler;
+    const { methodName, paramsConfig, httpCode, headers, redirect, hasQueryParam, hasResParam } = handler;
 
     // Parse query on-demand
     let query: any = null;
@@ -458,9 +528,12 @@ export class calyxApplication {
       query = {};
     }
 
-    const resWrapper = hasResParam ? new calyxResponse() : null;
+    const resWrapper = hasResParam ? new CalyxResponse() : null;
     const args: any[] = [];
 
+    const hasCustomParam = paramsConfig.some((p) => p.type === 'custom');
+    const context = hasCustomParam ? new CalyxExecutionContext(req, resWrapper, instance.constructor, instance[methodName]) : null;
+
     for (const config of paramsConfig) {
       let val: any;
       switch (config.type) {
@@ -482,47 +555,63 @@ export class calyxApplication {
         case 'headers':
           val = config.name ? req.headers.get(config.name) : Object.fromEntries(req.headers.entries());
           break;
+        case 'custom':
+          val = config.factory ? config.factory(config.name, context!) : undefined;
+          break;
       }
       args[config.index] = val;
     }
 
-    const result = instance[methodName](...args);
+    let result = instance[methodName](...args);
+
+    if (this.isObservable(result)) {
+      result = this.resolveObservable(result);
+    }
 
     if (result instanceof Promise) {
-      return result.then((resolvedResult) => this.processResult(req, resolvedResult, resWrapper, httpCode, headers, redirect));
+      return result.then((resolvedResult) => this.processResult(req, resolvedResult, resWrapper, httpCode, headers, redirect, handler.isPassthrough, handler.hasResParam));
     }
 
-    return this.processResult(req, result, resWrapper, httpCode, headers, redirect);
+    return this.processResult(req, result, resWrapper, httpCode, headers, redirect, handler.isPassthrough, handler.hasResParam);
   }
 
   private processResult(
     req: Request,
     result: any,
-    resWrapper: calyxResponse | null,
+    resWrapper: CalyxResponse | null,
     httpCode: number | undefined,
     headers: { name: string; value: string }[],
-    redirect: { url: string; statusCode?: number } | undefined
+    redirect: { url: string; statusCode?: number } | undefined,
+    isPassthrough = false,
+    hasResParam = false
   ): Response {
     if (redirect) {
       return Response.redirect(redirect.url, redirect.statusCode || 302);
     }
 
-    if (resWrapper?.sent) {
-      return new Response(resWrapper.body, {
-        status: resWrapper.statusCode,
-        headers: resWrapper.headers,
-      });
+    if (resWrapper) {
+      if (resWrapper.sent && !isPassthrough) {
+        return new Response(resWrapper.body, {
+          status: resWrapper.statusCode,
+          headers: resWrapper.headers,
+        });
+      }
+      if (hasResParam && !isPassthrough) {
+        return new Response(resWrapper.body, {
+          status: resWrapper.statusCode,
+          headers: resWrapper.headers,
+        });
+      }
     }
 
-    const status = httpCode ?? (req.method === 'POST' ? 201 : 200);
+    const status = resWrapper && isPassthrough 
+      ? resWrapper.statusCode 
+      : (httpCode ?? (req.method === 'POST' ? 201 : 200));
 
     // Build headers only if we have custom headers or content-type requirements
-    let responseHeaders: Headers | undefined = undefined;
-    if (headers.length > 0) {
-      responseHeaders = new Headers();
-      for (const header of headers) {
-        responseHeaders.set(header.name, header.value);
-      }
+    let responseHeaders = resWrapper && isPassthrough ? resWrapper.headers : new Headers();
+    for (const header of headers) {
+      responseHeaders.set(header.name, header.value);
     }
 
     if (result === undefined || result === null) {
@@ -534,17 +623,26 @@ export class calyxApplication {
     }
 
     if (typeof result === 'object') {
-      if (responseHeaders) {
-        responseHeaders.set('content-type', 'application/json');
-        return new Response(JSON.stringify(result), { status, headers: responseHeaders });
-      }
-      return Response.json(result, { status });
+      responseHeaders.set('content-type', 'application/json');
+      return new Response(JSON.stringify(result), { status, headers: responseHeaders });
     }
 
-    if (responseHeaders) {
-      return new Response(String(result), { status, headers: responseHeaders });
-    }
-    return new Response(String(result), { status });
+    return new Response(String(result), { status, headers: responseHeaders });
+  }
+
+  private isObservable(obj: any): boolean {
+    return obj && typeof obj === 'object' && typeof obj.subscribe === 'function';
+  }
+
+  private resolveObservable(obs: any): Promise<any> {
+    return new Promise((resolve, reject) => {
+      let lastVal: any = undefined;
+      obs.subscribe({
+        next: (val: any) => { lastVal = val; },
+        error: (err: any) => reject(err),
+        complete: () => resolve(lastVal),
+      });
+    });
   }
 
   private handleError(err: any): Response {
@@ -580,9 +678,77 @@ export class calyxApplication {
     return this.server;
   }
 
-  async close() {
+  private cleanupListeners: (() => void)[] = [];
+
+  enableShutdownHooks(signals: string[] = ['SIGTERM', 'SIGINT']) {
+    const handler = async (signal: string) => {
+      await this.close(signal);
+      process.exit(0);
+    };
+
+    for (const signal of signals) {
+      const listener = () => handler(signal);
+      process.on(signal as any, listener);
+      this.cleanupListeners.push(() => {
+        process.off(signal as any, listener);
+      });
+    }
+  }
+
+  async close(signal?: string) {
+    // Run shutdown hooks
+    await this.runShutdownHooks(signal);
+
+    for (const cleanup of this.cleanupListeners) {
+      cleanup();
+    }
+    this.cleanupListeners = [];
+
     if (this.server) {
       this.server.stop();
     }
   }
+
+  private async runOnModuleInit() {
+    const instances = this.container.getProviderAndControllerInstances();
+    for (const instance of instances) {
+      if (instance && typeof instance.onModuleInit === 'function') {
+        await instance.onModuleInit();
+      }
+    }
+  }
+
+  private async runOnApplicationBootstrap() {
+    const instances = this.container.getProviderAndControllerInstances();
+    for (const instance of instances) {
+      if (instance && typeof instance.onApplicationBootstrap === 'function') {
+        await instance.onApplicationBootstrap();
+      }
+    }
+  }
+
+  private async runShutdownHooks(signal?: string) {
+    const instances = this.container.getProviderAndControllerInstances();
+    
+    // 1. Run OnModuleDestroy
+    for (const instance of instances) {
+      if (instance && typeof instance.onModuleDestroy === 'function') {
+        await instance.onModuleDestroy();
+      }
+    }
+
+    // 2. Run BeforeApplicationShutdown
+    for (const instance of instances) {
+      if (instance && typeof instance.beforeApplicationShutdown === 'function') {
+        await instance.beforeApplicationShutdown(signal);
+      }
+    }
+
+    // 3. Run OnApplicationShutdown
+    for (const instance of instances) {
+      if (instance && typeof instance.onApplicationShutdown === 'function') {
+        await instance.onApplicationShutdown(signal);
+      }
+    }
+  }
 }