@martel/calyx 1.2.3 → 1.3.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [1.3.0](https://github.com/bmartel/calyx/compare/v1.2.4...v1.3.0) (2026-07-01)
+
+
+### Features
+
+* **http:** implement middleware support, JIT radix router compilation, and context pooling ([f0cf712](https://github.com/bmartel/calyx/commit/f0cf7125181749728eda29261e8423cd467b4977))
+
+## [1.2.4](https://github.com/bmartel/calyx/compare/v1.2.3...v1.2.4) (2026-07-01)
+
+
+### Bug Fixes
+
+* make scaffolded project port dynamically read process.env.PORT ([3fbf8a6](https://github.com/bmartel/calyx/commit/3fbf8a6cb4a6be7a0bf8056bbe5fc391d9f77e97))
+
 ## [1.2.3](https://github.com/bmartel/calyx/compare/v1.2.2...v1.2.3) (2026-07-01)
 
 

package/package.json

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

package/src/cli/index.ts

@@ -247,8 +247,9 @@ import { AppModule } from './app.module';
 
 async function bootstrap() {
   const app = await CalyxFactory.create(AppModule);
-  await app.listen(3000);
-  console.log('Application is running on http://localhost:3000');
+  const port = process.env.PORT || 3000;
+  await app.listen(port);
+  console.log(\`Application is running on http://localhost:\${port}\`);
 }
 bootstrap();
 `;

package/src/http/application.ts

@@ -5,6 +5,20 @@ 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 { CalyxMiddlewareConsumer, MiddlewareConfiguration, RequestMethodMap, CompiledLifecycleItem as CompiledMiddlewareItem } from './middleware.ts';
+
+class ObjectPool<T> {
+  private pool: T[] = [];
+  constructor(private readonly factory: () => T) {}
+
+  acquire(): T {
+    return this.pool.pop() ?? this.factory();
+  }
+
+  release(item: T) {
+    this.pool.push(item);
+  }
+}
 
 export class CalyxResponse {
   statusCode = 200;
@@ -65,6 +79,7 @@ interface HandlerConfig {
   guardsList: CompiledLifecycleItem[];
   interceptorsList: CompiledLifecycleItem[];
   filtersList: CompiledLifecycleItem[];
+  middlewaresList: CompiledLifecycleItem[];
 }
 
 export class CalyxApplication {
@@ -76,6 +91,15 @@ export class CalyxApplication {
   private globalInterceptors: any[] = [];
   private globalPipes: any[] = [];
   private globalFilters: any[] = [];
+  private globalMiddlewares: any[] = [];
+  private middlewareConfigurations: MiddlewareConfiguration[] = [];
+  private hostPool = new ObjectPool<CalyxArgumentsHost>(() => new CalyxArgumentsHost());
+  private contextPool = new ObjectPool<CalyxExecutionContext>(() => new CalyxExecutionContext());
+
+  use(...middlewares: any[]) {
+    this.globalMiddlewares.push(...middlewares);
+    return this;
+  }
 
   useGlobalGuards(...guards: any[]) {
     this.globalGuards.push(...guards);
@@ -99,6 +123,9 @@ export class CalyxApplication {
     // Bootstrap the dependency injection container
     this.container.bootstrap(this.rootModule);
 
+    // Resolve registered modules middlewares
+    this.resolveMiddleware();
+
     // Build the routing table from registered controllers
     this.buildRoutes();
 
@@ -116,8 +143,8 @@ export class CalyxApplication {
         const prefix = Reflect.getMetadata(METADATA_KEYS.CONTROLLER, controllerClass) ?? '';
         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);
+        const isControllerRequestScoped = controllerScope === Scope.REQUEST;
+        const singletonInstance = isControllerRequestScoped ? null : record.instances.get(controllerClass);
 
         for (const method of methods) {
           const routeMeta = Reflect.getMetadata(METADATA_KEYS.HTTP_METHOD, controllerClass.prototype, method);
@@ -155,6 +182,8 @@ export class CalyxApplication {
           const methodFilters = Reflect.getMetadata(METADATA_KEYS.FILTERS, controllerClass.prototype, method) || [];
           const filtersList = this.compileLifecycleItems(moduleClass, [...this.globalFilters, ...classFilters, ...methodFilters]);
 
+          const middlewaresList = this.getMiddlewaresForRoute(routeMeta.method, fullPath, controllerClass, moduleClass);
+
           const paramTypes = Reflect.getMetadata('design:paramtypes', controllerClass.prototype, method) || [];
           const compiledParamsConfig: CompiledParameterConfig[] = paramsConfig.map((p) => {
             const classPipes = Reflect.getMetadata(METADATA_KEYS.PIPES, controllerClass) || [];
@@ -172,12 +201,27 @@ export class CalyxApplication {
             guardsList.length > 0 ||
             interceptorsList.length > 0 ||
             filtersList.length > 0 ||
+            middlewaresList.length > 0 ||
             compiledParamsConfig.some((p) => p.pipesList.length > 0);
 
+          const hasReqScopedGuard = guardsList.some((g) => g.isReqScoped);
+          const hasReqScopedInterceptor = interceptorsList.some((i) => i.isReqScoped);
+          const hasReqScopedFilter = filtersList.some((f) => f.isReqScoped);
+          const hasReqScopedPipe = compiledParamsConfig.some((p) => p.pipesList.some((pi) => pi.isReqScoped));
+          const hasReqScopedMiddleware = middlewaresList.some((m) => m.isReqScoped);
+
+          const isRouteRequestScoped =
+            isControllerRequestScoped ||
+            hasReqScopedGuard ||
+            hasReqScopedInterceptor ||
+            hasReqScopedFilter ||
+            hasReqScopedPipe ||
+            hasReqScopedMiddleware;
+
           this.router.insert(routeMeta.method, fullPath, {
             controllerClass,
             moduleClass,
-            instance,
+            instance: singletonInstance,
             methodName: method,
             paramsConfig: compiledParamsConfig,
             httpCode,
@@ -187,17 +231,108 @@ export class CalyxApplication {
             hasQueryParam,
             hasResParam,
             isPassthrough,
-            isRequestScoped,
+            isRequestScoped: isRouteRequestScoped,
             hasLifecycleMetadata,
             guardsList,
             interceptorsList,
             filtersList,
+            middlewaresList,
           });
         }
       }
     }
   }
 
+  private resolveMiddleware() {
+    const consumer = new CalyxMiddlewareConsumer();
+    const modules = this.container.getModules();
+    for (const [moduleClass, record] of modules.entries()) {
+      const instance = record.instances.get(moduleClass);
+      if (instance && typeof instance.configure === 'function') {
+        instance.configure(consumer);
+      }
+    }
+    this.middlewareConfigurations = consumer.getConfigurations();
+  }
+
+  private getMiddlewaresForRoute(
+    method: string,
+    routePath: string,
+    controllerClass: any,
+    moduleClass: any
+  ): CompiledLifecycleItem[] {
+    const matchedMiddlewares: any[] = [...this.globalMiddlewares];
+
+    for (const config of this.middlewareConfigurations) {
+      // 1. Check if excluded
+      let isExcluded = false;
+      for (const ex of config.exclude) {
+        if (typeof ex === 'string') {
+          if (this.routePathMatches(routePath, ex)) {
+            isExcluded = true;
+            break;
+          }
+        } else {
+          // RouteInfo
+          const exMethod = RequestMethodMap[ex.method];
+          if ((exMethod === 'ALL' || exMethod === method.toUpperCase()) && this.routePathMatches(routePath, ex.path)) {
+            isExcluded = true;
+            break;
+          }
+        }
+      }
+
+      if (isExcluded) continue;
+
+      // 2. Check if matched in forRoutes
+      let isMatched = false;
+      for (const rule of config.forRoutes) {
+        if (typeof rule === 'string') {
+          if (rule === '*' || this.routePathMatches(routePath, rule)) {
+            isMatched = true;
+            break;
+          }
+        } else if (typeof rule === 'function') {
+          // It's a controller class
+          if (rule === controllerClass) {
+            isMatched = true;
+            break;
+          }
+        } else {
+          // RouteInfo
+          const ruleMethod = RequestMethodMap[rule.method];
+          if ((ruleMethod === 'ALL' || ruleMethod === method.toUpperCase()) && this.routePathMatches(routePath, rule.path)) {
+            isMatched = true;
+            break;
+          }
+        }
+      }
+
+      if (isMatched) {
+        matchedMiddlewares.push(...config.middleware);
+      }
+    }
+
+    return this.compileLifecycleItems(moduleClass, matchedMiddlewares);
+  }
+
+  private routePathMatches(routePath: string, pattern: string): boolean {
+    const rPath = routePath.startsWith('/') ? routePath : '/' + routePath;
+    const pPath = pattern.startsWith('/') ? pattern : '/' + pattern;
+
+    if (pPath === '/*' || pPath === '*' || pPath === '/**') {
+      return true;
+    }
+
+    const regexStr = pPath
+      .replace(/\?/g, '\\?')
+      .replace(/\/\*/g, '(/.*)?')
+      .replace(/:[a-zA-Z0-9_]+/g, '[^/]+');
+
+    const regex = new RegExp(`^${regexStr}$`);
+    return regex.test(rPath);
+  }
+
   private getMethods(obj: any): string[] {
     const properties = new Set<string>();
     let currentObj = obj;
@@ -238,6 +373,9 @@ export class CalyxApplication {
 
       const matched = this.router.match(req.method, pathname);
       if (!matched) {
+        if (this.globalMiddlewares.length > 0) {
+          return this.handleGlobalMiddlewaresAnd404(req, pathname);
+        }
         throw new NotFoundException(`Cannot ${req.method} ${pathname}`);
       }
 
@@ -249,13 +387,18 @@ export class CalyxApplication {
       if (handler.isRequestScoped) {
         requestContext = new Map<any, any>();
         requestContext.set(REQUEST, req);
-        instance = this.container.resolveControllerInRequestContext(handler.moduleClass, handler.controllerClass, requestContext);
+        const controllerScope = this.container.getControllerScope(handler.controllerClass);
+        if (controllerScope === Scope.REQUEST) {
+          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') {
+        const needsBodyParsing = (handler.hasBodyParam || handler.middlewaresList.length > 0) &&
+                                  req.body && req.method !== 'GET' && req.method !== 'HEAD';
+        if (needsBodyParsing) {
           return this.handleRequestPipelineAsync(req, handler, params, search, instance, requestContext);
         }
         return this.handleRequestPipeline(req, handler, params, search, null, instance, requestContext);
@@ -304,14 +447,19 @@ export class CalyxApplication {
         }
       }
 
-      return this.handleRequestPipeline(req, handler, params, search, body, instance, requestContext);
+      return await 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.controllerClass, handler.methodName, requestContext);
+      const host = this.hostPool.acquire();
+      host.reset(req, resWrapper);
+      try {
+        return await this.handleLifecycleError(err, host, handler, requestContext);
+      } finally {
+        host.clear();
+        this.hostPool.release(host);
+      }
     }
   }
-
   private async handleRequestPipeline(
     req: Request,
     handler: HandlerConfig,
@@ -325,10 +473,43 @@ export class CalyxApplication {
     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]);
+    const host = this.hostPool.acquire();
+    host.reset(req, resWrapper);
+    const context = this.contextPool.acquire();
+    context.resetContext(req, resWrapper, controllerClass, instance[methodName]);
 
     try {
+      // 0. Run Middleware
+      if (handler.middlewaresList.length > 0) {
+        let index = 0;
+        const next = async (err?: any): Promise<void> => {
+          if (err) throw err;
+          if (index < handler.middlewaresList.length) {
+            const item = handler.middlewaresList[index++];
+            const mwInstance = item.isReqScoped
+              ? this.container.resolveTokenInModuleContext(moduleClass, item.token, requestContext)
+              : item.instance;
+
+            if (typeof mwInstance.use === 'function') {
+              await mwInstance.use(req, resWrapper, next);
+            } else if (typeof mwInstance === 'function') {
+              await mwInstance(req, resWrapper, next);
+            } else {
+              await next();
+            }
+          }
+        };
+        await next();
+
+        // If middleware sent a response, return it directly
+        if (resWrapper.sent) {
+          return new Response(resWrapper.body, {
+            status: resWrapper.statusCode,
+            headers: resWrapper.headers,
+          });
+        }
+      }
+
       // 1. Run Guards
       for (const guard of handler.guardsList) {
         const guardInstance = guard.isReqScoped
@@ -411,7 +592,45 @@ export class CalyxApplication {
 
       return this.processResult(req, result, resWrapper, httpCode, headers, redirect, handler.isPassthrough, handler.hasResParam);
     } catch (err: any) {
-      return this.handleLifecycleError(err, host, handler, requestContext);
+      return await this.handleLifecycleError(err, host, handler, requestContext);
+    } finally {
+      host.clear();
+      context.clearContext();
+      this.hostPool.release(host);
+      this.contextPool.release(context);
+    }
+  }
+
+  private async handleGlobalMiddlewaresAnd404(req: Request, pathname: string): Promise<Response> {
+    const resWrapper = new CalyxResponse();
+    try {
+      const compiled = this.compileLifecycleItems(this.rootModule, this.globalMiddlewares);
+      let index = 0;
+      const next = async (err?: any): Promise<void> => {
+        if (err) throw err;
+        if (index < compiled.length) {
+          const item = compiled[index++];
+          const mwInstance = item.instance;
+          if (typeof mwInstance.use === 'function') {
+            await mwInstance.use(req, resWrapper, next);
+          } else if (typeof mwInstance === 'function') {
+            await mwInstance(req, resWrapper, next);
+          } else {
+            await next();
+          }
+        }
+      };
+      await next();
+
+      if (resWrapper.sent) {
+        return new Response(resWrapper.body, {
+          status: resWrapper.statusCode,
+          headers: resWrapper.headers,
+        });
+      }
+      throw new NotFoundException(`Cannot ${req.method} ${pathname}`);
+    } catch (err: any) {
+      return this.handleError(err);
     }
   }
 
@@ -454,6 +673,22 @@ export class CalyxApplication {
   private compileLifecycleItems(moduleClass: any, items: any[]): CompiledLifecycleItem[] {
     return items.map((item) => {
       if (typeof item === 'function') {
+        const isClass = 
+          item.prototype && (
+            typeof item.prototype.canActivate === 'function' ||
+            typeof item.prototype.intercept === 'function' ||
+            typeof item.prototype.transform === 'function' ||
+            typeof item.prototype.catch === 'function' ||
+            typeof item.prototype.use === 'function' ||
+            Reflect.hasMetadata(METADATA_KEYS.INJECTABLE, item) ||
+            Reflect.hasMetadata(METADATA_KEYS.CONTROLLER, item) ||
+            Reflect.hasMetadata(METADATA_KEYS.MODULE, item)
+          );
+
+        if (!isClass) {
+          return { isReqScoped: false, token: item, instance: item };
+        }
+
         const scope = this.container.getProviderScope(item);
         if (scope === Scope.REQUEST) {
           return { isReqScoped: true, token: item, instance: null };
@@ -609,7 +844,7 @@ export class CalyxApplication {
       : (httpCode ?? (req.method === 'POST' ? 201 : 200));
 
     // Build headers as a plain object Record<string, string>
-    const responseHeaders: Record<string, string> = resWrapper && isPassthrough 
+    const responseHeaders: Record<string, string> = resWrapper 
       ? { ...resWrapper.headers } 
       : {};
 

package/src/http/index.ts

@@ -3,3 +3,4 @@ export * from './router.ts';
 export * from './exceptions.ts';
 export * from './application.ts';
 export * from './factory.ts';
+export * from './middleware.ts';

package/src/http/middleware.ts

@@ -0,0 +1,82 @@
+import { Type } from '../core/metadata.ts';
+import { CalyxResponse } from './application.ts';
+
+export enum RequestMethod {
+  GET = 0,
+  POST = 1,
+  PUT = 2,
+  DELETE = 3,
+  PATCH = 4,
+  ALL = 5,
+  OPTIONS = 6,
+  HEAD = 7,
+}
+
+export const RequestMethodMap: Record<RequestMethod, string> = {
+  [RequestMethod.GET]: 'GET',
+  [RequestMethod.POST]: 'POST',
+  [RequestMethod.PUT]: 'PUT',
+  [RequestMethod.DELETE]: 'DELETE',
+  [RequestMethod.PATCH]: 'PATCH',
+  [RequestMethod.ALL]: 'ALL',
+  [RequestMethod.OPTIONS]: 'OPTIONS',
+  [RequestMethod.HEAD]: 'HEAD',
+};
+
+export interface RouteInfo {
+  path: string;
+  method: RequestMethod;
+}
+
+export interface NestMiddleware {
+  use(req: Request, res: CalyxResponse, next: (error?: any) => void | Promise<void>): any;
+}
+
+export interface MiddlewareConfigProxy {
+  exclude(...routes: (string | RouteInfo)[]): MiddlewareConfigProxy;
+  forRoutes(...routes: (string | Type<any> | RouteInfo)[]): MiddlewareConsumer;
+}
+
+export interface MiddlewareConsumer {
+  apply(...middleware: any[]): MiddlewareConfigProxy;
+}
+
+export interface NestModule {
+  configure(consumer: MiddlewareConsumer): void;
+}
+
+export interface MiddlewareConfiguration {
+  middleware: any[];
+  forRoutes: (string | Type<any> | RouteInfo)[];
+  exclude: (string | RouteInfo)[];
+}
+
+export class CalyxMiddlewareConsumer implements MiddlewareConsumer {
+  private configurations: MiddlewareConfiguration[] = [];
+
+  apply(...middleware: any[]): MiddlewareConfigProxy {
+    const config: MiddlewareConfiguration = {
+      middleware,
+      forRoutes: [],
+      exclude: [],
+    };
+    this.configurations.push(config);
+
+    const proxy: MiddlewareConfigProxy = {
+      exclude: (...routes: (string | RouteInfo)[]) => {
+        config.exclude.push(...routes);
+        return proxy;
+      },
+      forRoutes: (...routes: (string | Type<any> | RouteInfo)[]) => {
+        config.forRoutes.push(...routes);
+        return this;
+      },
+    };
+
+    return proxy;
+  }
+
+  getConfigurations(): MiddlewareConfiguration[] {
+    return this.configurations;
+  }
+}

package/src/http/router.ts

@@ -14,6 +14,8 @@ class RouterNode<T> {
 export class RadixRouter<T> {
   private root = new RouterNode<T>();
   private staticRoutes = new Map<string, T>();
+  private handlersArray: T[] = [];
+  private compiledMatch: ((method: string, path: string) => RouteMatch<T> | null) | null = null;
 
   insert(method: string, path: string, handler: T) {
     const hasParams = path.includes(':') || path.includes('*');
@@ -49,61 +51,144 @@ export class RadixRouter<T> {
     }
 
     node.handlers.set(method.toUpperCase(), handler);
+    this.compiledMatch = null;
   }
 
   match(method: string, path: string): RouteMatch<T> | null {
-    const key = method.toUpperCase() + ' ' + path;
-    const staticHandler = this.staticRoutes.get(key);
-    if (staticHandler) {
-      return { handler: staticHandler, params: {} };
+    if (this.compiledMatch) {
+      return this.compiledMatch(method, path);
     }
+    this.compile();
+    return this.compiledMatch!(method, path);
+  }
 
-    const segments = path.split('/').filter(Boolean);
-    const params: Record<string, string> = {};
-    const matchNode = this.matchSegment(this.root, segments, 0, params);
+  compile() {
+    this.handlersArray = [];
+    const registerHandler = (handler: T): number => {
+      let idx = this.handlersArray.indexOf(handler);
+      if (idx === -1) {
+        idx = this.handlersArray.length;
+        this.handlersArray.push(handler);
+      }
+      return idx;
+    };
+
+    // 1. Compile static routes check
+    const staticRoutesByMethod: Record<string, Record<string, number>> = {};
+    for (const [key, handler] of this.staticRoutes.entries()) {
+      const spaceIdx = key.indexOf(' ');
+      const method = key.substring(0, spaceIdx);
+      const path = key.substring(spaceIdx + 1);
+      const handlerIdx = registerHandler(handler);
+
+      if (!staticRoutesByMethod[method]) {
+        staticRoutesByMethod[method] = {};
+      }
+      staticRoutesByMethod[method][path] = handlerIdx;
+    }
 
-    if (!matchNode) return null;
+    let staticCheckCode = '';
+    if (Object.keys(staticRoutesByMethod).length > 0) {
+      staticCheckCode = `
+      switch (method) {
+      `;
+      for (const [method, routes] of Object.entries(staticRoutesByMethod)) {
+        staticCheckCode += `  case '${method}':\n    switch (path) {\n`;
+        for (const [path, handlerIdx] of Object.entries(routes)) {
+          staticCheckCode += `      case '${path}': return { handler: handlers[${handlerIdx}], params: {} };\n`;
+        }
+        staticCheckCode += `    }\n    break;\n`;
+      }
+      staticCheckCode += `}\n`;
+    }
 
-    const handler = matchNode.handlers.get(method.toUpperCase()) ?? matchNode.handlers.get('ALL');
-    if (!handler) return null;
+    // 2. Compile dynamic routes recursively
+    const compileNode = (node: RouterNode<T>, segmentIdx: number, startVar: string, collectedParams: string[]): string => {
+      const parts: string[] = [];
+      const nextStartVar = `s${segmentIdx + 1}`;
+      const nextEndVar = `e${segmentIdx + 1}`;
+
+      parts.push(`const ${nextEndVar} = path.indexOf('/', ${startVar});`);
+      parts.push(`const ${nextStartVar} = ${nextEndVar} === -1 ? len : ${nextEndVar};`);
+      parts.push(`const len${segmentIdx} = ${nextStartVar} - (${startVar});`);
+
+      // Static children check
+      if (node.children.size > 0) {
+        for (const [segment, childNode] of node.children.entries()) {
+          parts.push(`if (len${segmentIdx} === ${segment.length} && path.startsWith('${segment}', ${startVar})) {`);
+          parts.push(compileNode(childNode, segmentIdx + 1, `${nextStartVar} + 1`, collectedParams));
+          parts.push(`}`);
+        }
+      }
 
-    return { handler, params };
-  }
+      // Parameter child check
+      if (node.paramChild && node.paramName) {
+        parts.push(`if (len${segmentIdx} > 0) {`);
+        parts.push(`  const p_${node.paramName} = path.substring(${startVar}, ${nextStartVar});`);
+        parts.push(compileNode(node.paramChild, segmentIdx + 1, `${nextStartVar} + 1`, [...collectedParams, node.paramName]));
+        parts.push(`}`);
+      }
 
-  private matchSegment(
-    node: RouterNode<T>,
-    segments: string[],
-    index: number,
-    params: Record<string, string>
-  ): RouterNode<T> | null {
-    if (index === segments.length) {
-      // If we've reached the end of segments, the current node must have handlers
-      return node.handlers.size > 0 ? node : null;
-    }
+      // Wildcard child check
+      if (node.wildcardChild) {
+        parts.push(`const p_wildcard = path.substring(${startVar});`);
+        const paramsEntries = [...collectedParams.map(p => `${p}: p_${p}`), `'*': p_wildcard`].join(', ');
+        parts.push(`const params = { ${paramsEntries} };`);
+        parts.push(`switch (method) {`);
+        for (const [method, handler] of node.wildcardChild.handlers.entries()) {
+          const handlerIdx = registerHandler(handler);
+          parts.push(`  case '${method}': return { handler: handlers[${handlerIdx}], params };`);
+        }
+        const fallbackWildcardHandler = node.wildcardChild.handlers.get('ALL') ?? node.wildcardChild.handlers.values().next().value;
+        if (fallbackWildcardHandler) {
+          const handlerIdx = registerHandler(fallbackWildcardHandler);
+          parts.push(`  default: return { handler: handlers[${handlerIdx}], params };`);
+        }
+        parts.push(`}`);
+      }
+
+      // Terminal handler check
+      if (node.handlers.size > 0) {
+        parts.push(`if (${nextStartVar} === len) {`);
+        const paramsEntries = collectedParams.map(p => `${p}: p_${p}`).join(', ');
+        parts.push(`  const params = { ${paramsEntries} };`);
+        parts.push(`  switch (method) {`);
+        for (const [method, handler] of node.handlers.entries()) {
+          const handlerIdx = registerHandler(handler);
+          parts.push(`    case '${method}': return { handler: handlers[${handlerIdx}], params };`);
+        }
+        const fallbackHandler = node.handlers.get('ALL') ?? node.handlers.values().next().value;
+        if (fallbackHandler) {
+          const handlerIdx = registerHandler(fallbackHandler);
+          parts.push(`    default: return { handler: handlers[${handlerIdx}], params };`);
+        }
+        parts.push(`  }`);
+        parts.push(`}`);
+      }
 
-    const segment = segments[index];
+      return parts.join('\n');
+    };
 
-    // 1. Try static match
-    const staticChild = node.children.get(segment);
-    if (staticChild) {
-      const match = this.matchSegment(staticChild, segments, index + 1, params);
-      if (match) return match;
-    }
+    const dynamicMatchCode = compileNode(this.root, 0, '1', []);
 
-    // 2. Try parameter match
-    if (node.paramChild && node.paramName) {
-      params[node.paramName] = segment;
-      const match = this.matchSegment(node.paramChild, segments, index + 1, params);
-      if (match) return match;
-      delete params[node.paramName]; // backtrack
-    }
+    const fnBody = `
+      const len = path.length;
+      ${staticCheckCode}
+      ${dynamicMatchCode}
+      return null;
+    `;
 
-    // 3. Try wildcard match
-    if (node.wildcardChild) {
-      params['*'] = segments.slice(index).join('/');
-      return node.wildcardChild;
-    }
 
-    return null;
+    try {
+      this.compiledMatch = new Function('handlers', `
+        return function match(method, path) {
+          ${fnBody}
+        }
+      `)(this.handlersArray);
+    } catch (err) {
+      console.error('Failed to compile radix router matcher:', err);
+      console.error('Generated function body was:', fnBody);
+      throw err;
+    }
   }
 }

package/src/lifecycle/context.ts

@@ -2,7 +2,24 @@ import { ArgumentsHost, HttpArgumentsHost, ExecutionContext } from './interfaces
 import { Type } from '../core/metadata.ts';
 
 export class CalyxArgumentsHost implements ArgumentsHost {
-  constructor(private readonly req: Request, private readonly res: any) {}
+  protected req!: Request;
+  protected res!: any;
+
+  constructor(req?: Request, res?: any) {
+    if (req && res) {
+      this.reset(req, res);
+    }
+  }
+
+  reset(req: Request, res: any) {
+    this.req = req;
+    this.res = res;
+  }
+
+  clear() {
+    this.req = null as any;
+    this.res = null;
+  }
 
   getArgs<T extends any[] = any[]>(): T {
     return [this.req, this.res] as unknown as T;
@@ -22,13 +39,36 @@ export class CalyxArgumentsHost implements ArgumentsHost {
 }
 
 export class CalyxExecutionContext extends CalyxArgumentsHost implements ExecutionContext {
+  protected targetClass!: Type<any>;
+  protected handlerMethod!: Function;
+
   constructor(
+    req?: Request,
+    res?: any,
+    targetClass?: Type<any>,
+    handlerMethod?: Function
+  ) {
+    super(req, res);
+    if (targetClass && handlerMethod) {
+      this.resetContext(req!, res, targetClass, handlerMethod);
+    }
+  }
+
+  resetContext(
     req: Request,
     res: any,
-    private readonly targetClass: Type<any>,
-    private readonly handlerMethod: Function
+    targetClass: Type<any>,
+    handlerMethod: Function
   ) {
-    super(req, res);
+    this.reset(req, res);
+    this.targetClass = targetClass;
+    this.handlerMethod = handlerMethod;
+  }
+
+  clearContext() {
+    this.clear();
+    this.targetClass = null as any;
+    this.handlerMethod = null as any;
   }
 
   getClass<T = any>(): Type<T> {

package/tests/middleware.test.ts

@@ -0,0 +1,160 @@
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import {
+  Module,
+  Controller,
+  Get,
+  Post,
+  Injectable,
+  CalyxFactory,
+  CalyxResponse,
+  NestMiddleware,
+  MiddlewareConsumer,
+  NestModule,
+  RequestMethod,
+  Scope,
+} from '../src/index.ts';
+
+// 1. Functional Global Middleware
+function globalMiddleware(req: Request, res: CalyxResponse, next: () => void) {
+  res.headers['x-global-middleware'] = 'run';
+  next();
+}
+
+// 2. Class Middleware (Injectable)
+@Injectable()
+class LoggerMiddleware implements NestMiddleware {
+  use(req: Request, res: CalyxResponse, next: () => void) {
+    res.headers['x-logger-middleware'] = 'run';
+    next();
+  }
+}
+
+// 3. Request Scoped Middleware
+let requestScopedCount = 0;
+
+@Injectable({ scope: Scope.REQUEST })
+class RequestScopedMiddleware implements NestMiddleware {
+  constructor() {
+    requestScopedCount++;
+  }
+  use(req: Request, res: CalyxResponse, next: () => void) {
+    res.headers['x-request-scoped-count'] = String(requestScopedCount);
+    next();
+  }
+}
+
+// 4. Short-circuiting Middleware
+@Injectable()
+class AuthMiddleware implements NestMiddleware {
+  use(req: Request, res: CalyxResponse, next: () => void) {
+    const token = req.headers.get('x-auth-token');
+    if (token !== 'secret') {
+      res.status(401).json({ message: 'Unauthorized Middleware' });
+      return; // Do not call next()
+    }
+    next();
+  }
+}
+
+@Controller('users')
+class UsersController {
+  @Get()
+  findAll() {
+    return { data: 'users' };
+  }
+
+  @Get(':id')
+  findOne() {
+    return { data: 'user' };
+  }
+
+  @Post()
+  create() {
+    return { created: true };
+  }
+}
+
+@Controller('admin')
+class AdminController {
+  @Get('dashboard')
+  dashboard() {
+    return { admin: true };
+  }
+}
+
+@Module({
+  controllers: [UsersController, AdminController],
+  providers: [LoggerMiddleware, RequestScopedMiddleware, AuthMiddleware],
+})
+class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    // Apply LoggerMiddleware to all routes under UsersController
+    consumer.apply(LoggerMiddleware).forRoutes(UsersController);
+
+    // Apply RequestScopedMiddleware to users POST route
+    consumer.apply(RequestScopedMiddleware).forRoutes({ path: 'users', method: RequestMethod.POST });
+
+    // Apply AuthMiddleware to dashboard, but exclude specific checks if needed
+    consumer.apply(AuthMiddleware)
+      .exclude('admin/dashboard/free')
+      .forRoutes('admin/*');
+  }
+}
+
+describe('NestJS Middleware Compatibility', () => {
+  let app: any;
+  let baseUrl: string;
+  const PORT = 3855;
+
+  beforeAll(async () => {
+    app = await CalyxFactory.create(AppModule);
+    app.use(globalMiddleware);
+    await app.listen(PORT);
+    baseUrl = `http://localhost:${PORT}`;
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('should run global functional middleware on any request', async () => {
+    const res = await fetch(`${baseUrl}/users`);
+    expect(res.status).toBe(200);
+    expect(res.headers.get('x-global-middleware')).toBe('run');
+  });
+
+  test('should apply class middleware to controller routes configured via forRoutes(Controller)', async () => {
+    const res = await fetch(`${baseUrl}/users`);
+    expect(res.headers.get('x-logger-middleware')).toBe('run');
+  });
+
+  test('should apply request-scoped middleware to specific route configured with RequestMethod', async () => {
+    const prevCount = requestScopedCount;
+    const res = await fetch(`${baseUrl}/users`, {
+      method: 'POST',
+      body: JSON.stringify({}),
+      headers: { 'Content-Type': 'application/json' },
+    });
+    expect(res.status).toBe(201);
+    expect(res.headers.get('x-request-scoped-count')).toBeDefined();
+    expect(requestScopedCount).toBe(prevCount + 1);
+  });
+
+  test('should short-circuit pipeline and return custom response if middleware does not call next()', async () => {
+    const res = await fetch(`${baseUrl}/admin/dashboard`, {
+      headers: { 'x-auth-token': 'bad' },
+    });
+    expect(res.status).toBe(401);
+    const body = await res.json();
+    expect(body).toEqual({ message: 'Unauthorized Middleware' });
+  });
+
+  test('should continue to handler if short-circuiting middleware passes', async () => {
+    const res = await fetch(`${baseUrl}/admin/dashboard`, {
+      headers: { 'x-auth-token': 'secret' },
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toEqual({ admin: true });
+  });
+});