@mxweb/core 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,71 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-01-03
+
+### Added
+
+- **Feature**: Added feature-level guards, filters, interceptors, and pipes support
+  - `FeatureInitialize` now extends `DecoratorOptions` for full decorator support
+  - Features can now define their own guards, filters, interceptors, and pipes
+  - Execution order: Application → Feature → Route for guards and pipes
+  - Execution order: Route → Feature → Application for filters and interceptors
+  - Example:
+    ```ts
+    Feature.create({
+      controller: ProductController,
+      router: productRouter,
+      guards: [FeatureAuthGuard],
+      filters: [FeatureExceptionFilter],
+      interceptors: [FeatureLoggingInterceptor],
+      pipes: [FeatureValidationPipe],
+    });
+    ```
+
+- **Common**: Added `DecoratorOptions` interface for shared decorator configuration
+  - Provides a common base for guards, filters, interceptors, and pipes configuration
+  - Used by both `ApplicationOptions` and `FeatureInitialize`
+  - Properties: `guards?: Guard[]`, `filters?: Filter[]`, `interceptors?: Interceptor[]`, `pipes?: Pipe[]`
+
+- **Common**: Added `FeatureContext` interface to avoid circular dependencies
+  - Abstract interface for feature context accessible from `ExecuteContext`
+  - Methods: `hasInject()`, `getInject()`, `getInjectSync()`
+  - `RequestContext.feature` now uses `FeatureContext` type
+
+- **Common**: Moved `Guard`, `Filter`, `Interceptor` type definitions to `common.ts`
+  - Centralized type definitions for better code organization
+  - Types are no longer re-exported from `execute.ts`
+
+- **Response**: Added `CoreResponseInterceptorHandler` interface
+  - Specialized interface for interceptors working with `CoreResponse`
+  - Separated from generic `ResponseInterceptorHandler` in `common.ts`
+
+### Changed
+
+- **Application**: Updated to include feature-level decorators in execution chains
+  - `executeGuards()` now includes feature guards: App → Feature → Route
+  - `executeFilters()` now includes feature filters: Route → Feature → App
+  - `executeInterceptors()` now includes feature interceptors: Route → Feature → App
+  - `executePipes()` now includes feature pipes: App → Feature → Route
+
+- **ExecuteContext**: Simplified `getFeature()` method signature
+  - Now uses generic `<Feature extends FeatureContext>` for type flexibility
+  - Returns `FeatureContext` by default, can be cast to specific Feature type
+
+### Fixed
+
+- **Circular Dependencies**: Resolved all circular import issues
+  - Removed `Feature` import from `execute.ts` (was causing circular: execute → feature → controller/router → execute)
+  - Introduced `FeatureContext` interface in `common.ts` as abstraction
+  - All 6 circular dependencies have been eliminated
+
+### Internal
+
+- **Type Simplification**: Simplified generic types in decorator interfaces
+  - `ResponseInterceptorHandler` now uses single generic `<Response>`
+  - `Interceptor` type simplified to single generic
+  - `DecoratorOptions` no longer requires generic parameters
+
 ## [1.1.0] - 2026-01-02
 
 ### ⚠️ Breaking Changes

package/dist/application.d.ts

@@ -1,8 +1,8 @@
 import { Feature } from "./feature";
 import { CoreResponse, ResponseClass } from "./response";
-import { CoreRequest, Filter, Guard, Interceptor } from "./execute";
+import { CoreRequest } from "./execute";
 import { ApplicationHooksOptions } from "./hooks";
-import { ApplicationInject, InjectEntry, InjectFactory, InjectRegistry, Pipe, RoutePayload } from "./common";
+import { ApplicationInject, DecoratorOptions, InjectEntry, InjectFactory, InjectRegistry, RoutePayload } from "./common";
 /**
  * Type for application-level dependency injection configuration.
  * An array of inject factory functions that register injects via InjectRegistry.
@@ -75,7 +75,7 @@ export type ApplicationCors = string[] | ((registry: InjectRegistry) => string[]
  * };
  * ```
  */
-export interface ApplicationOptions<Key extends string = "path"> extends ApplicationHooksOptions {
+export interface ApplicationOptions<Key extends string = "path"> extends ApplicationHooksOptions, DecoratorOptions {
     /** The key used to extract path segments from catch-all route params. Defaults to "path". */
     key?: Key;
     /**
@@ -107,14 +107,6 @@ export interface ApplicationOptions<Key extends string = "path"> extends Applica
     poweredBy?: string | false;
     /** Array of inject factories for dependency injection */
     injects?: ApplicationInjects;
-    /** Global guards applied to all routes */
-    guards?: Guard[];
-    /** Global exception filters applied to all routes */
-    filters?: Filter[];
-    /** Global interceptors applied to all routes */
-    interceptors?: Interceptor[];
-    /** Global pipes applied to all routes */
-    pipes?: Pipe[];
     /** CORS configuration - allowed origins or resolver function */
     cors?: ApplicationCors;
 }

package/dist/application.js

@@ -1 +1 @@
-"use strict";var e=require("./error.js"),t=require("./context.js"),s=require("./response.js"),r=require("./hooks.js"),o=require("./logger.js"),n=require("./common.js");const i={key:"path"};class a{static toResponse(e){return!1!==this.poweredBy&&e.headers.set("X-Powered-By",this.poweredBy),this.ResponseClass.json(e.body,{status:e.status,statusText:e.statusText,headers:e.headers})}constructor(e,t,o){this.request=e,this.method=t,this.payload=o,this.feature=null,this.route=null,this.response=new s.ServerResponse,this.requestHooks=new r.RequestHooks(a.hooks)}static getInject(e){return t.executeContext.getInject(e)}static getInjectSync(e){return t.executeContext.getInjectSync(e)}static getInjects(){return new Map(t.executeContext.injections)}static createInjectRegistry(){return this.registryCreated||(this.registry={get:async e=>t.executeContext.getInject(e),set(e,s){t.executeContext.setInject(e,s)}},t.executeContext.setRegistry(this.registry),this.registryCreated=!0),this.registry}static async registerInjectFactories(){if(this.factoriesRegistered)return;const e=this.options.injects;if(!e||!e.length)return void(this.factoriesRegistered=!0);const t=this.createInjectRegistry();for(const s of e)await s(t);this.factoriesRegistered=!0,await this.initializeInjects(),this.registerShutdown(),await this.loadCors()}static async initializeInjects(){for(const[e,s]of t.executeContext.injections)if(!s.instance)try{const e=this.createInjectRegistry();s.instance=await s.factory(e),s.instance&&"function"==typeof s.instance.onInit&&await s.instance.onInit()}catch(t){throw a.logger.error(`Error initializing inject ${e}:`,t),t}}static registerShutdown(){if(this.shutdownRegistered)return;this.shutdownRegistered=!0;const e=async()=>{a.logger.info("Shutting down...");for(const e of this.features)await e.destroyInjects();for(const[e,s]of t.executeContext.injections)if(s.instance&&"function"==typeof s.instance.onDestroy)try{await s.instance.onDestroy(),a.logger.info(`Destroyed inject: ${e}`)}catch(t){a.logger.error(`Error destroying inject ${e}:`,t)}a.logger.info("Shutdown complete"),process.exit(0)};process.on("SIGTERM",e),process.on("SIGINT",e)}static async loadCors(){const e=this.options.cors;e&&(Array.isArray(e)?this.corsOrigins=e:this.corsOrigins=await e(this.registry))}static async loadImports(){if(!this.initialized)return this.initPromise||(this.initPromise=(async()=>{this.initialized=!0})()),this.initPromise}isMatchFeature(e,t){for(const s of a.features)if(this.route=s.matchRoute(e,t),this.route)return this.feature=s,!0;return null}async executeGuards(){const e=this.route?.route.getReflect().getGuards()??new Set,s=[...a.guards,...e];if(!s.length)return!0;for(const e of s)try{const s=new e;if(!await s.canActivate(t.executeContext))return!1}catch{return!1}return!0}async executeMiddlewares(){const e=this.route.route.getMiddlewares();if(!e.length)return!0;for(const s of e){let e=!1;const r=()=>{e=!0};try{if(await s(t.executeContext,r),!e)return!1}catch{return!1}}return!0}async executeFilters(e){const r=[...this.route?.route.getReflect().getFilters()??new Set,...a.filters];for(const o of r)try{const r=new o,n=await r.catch(e,t.executeContext);if(n instanceof s.CoreResponse||n instanceof Response)return n}catch{continue}return null}async executeInterceptors(e){const t=[...this.route?.route.getReflect().getInterceptors()??new Set,...a.interceptors];if(!t.length)return e;let s=e;for(const e of t){const t=new e;s=await t.transform(s)}return s}async executePipes(e){const t=this.route?.route.getReflect().getPipes()??new Set,s=[...a.pipes,...t];if(!s.length)return e;let r=e;for(const e of s){const t=new e;r=await t.transform(r)}return r}checkCors(){const e=a.corsOrigins;if(!e.length)return!0;const t=this.request.headers.get("origin");return!t||(e.includes("*")||e.includes(t))}applyCorsHeaders(e){const t=a.corsOrigins;if(!t.length)return e;const s=this.request.headers.get("origin");return s?(t.includes("*")?e.headers.set("Access-Control-Allow-Origin","*"):t.includes(s)&&(e.headers.set("Access-Control-Allow-Origin",s),e.headers.set("Vary","Origin")),e.headers.set("Access-Control-Allow-Methods","GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS"),e.headers.set("Access-Control-Allow-Headers","Content-Type, Authorization"),e.headers.set("Access-Control-Max-Age","86400"),e):e}async dispatch(){const r=this.route,o=this.feature,n=t.executeContext.getContextOrThrow();try{if(!await this.executeGuards())return this.response.forbidden();if(!await this.executeMiddlewares())return this.response.forbidden();const e=r.route.getAction();let t=null;if("string"==typeof e){const s=o.getController();"function"==typeof s._initDependencies&&await s._initDependencies(),"function"==typeof s[e]&&(t=s[e].bind(s))}else"function"==typeof e&&(t=e);if(!t)return this.response.internalServer(new Error("Route action handler not found"));await this.executePipes(n);const s=await t(n);let i=this.response.success(s);return i=await this.executeInterceptors(i),i}catch(t){const r=await this.executeFilters(t);if(r)return r instanceof Response?s.CoreResponse.json({success:r.ok,message:r.statusText,code:"FILTER_RESPONSE",status:r.status,data:null,error:null},{status:r.status,statusText:r.statusText}):r;if(t instanceof e.HttpError)switch(t.statusCode){case 400:return this.response.badRequest(t.message,t.error);case 401:return this.response.unauthorized(t.message,t.error);case 403:return this.response.forbidden(t.message,t.error);case 404:return this.response.notFound(t.message,t.error);case 409:return this.response.conflict(t.message,t.error);case 422:return this.response.unprocessableEntity(t.message,t.error);case 429:return this.response.tooManyRequests(t.message,t.error);case 501:return this.response.notImplemented(t.message,t.error);case 502:return this.response.badGateway(t.message,t.error);case 503:return this.response.serviceUnavailable(t.message,t.error);case 504:return this.response.gatewayTimeout(t.message,t.error)}return a.logger.error("[dispatch] Error:",t instanceof Error?t.message:t),t instanceof Error&&t.stack&&a.logger.debug("Stack trace:",t.stack),this.response.internalServer(t)}}async match(){let e=null;try{if(!this.checkCors())return this.applyCorsHeaders(this.response.forbidden("CORS not allowed"));const s=await this.payload.params,r=a.options.key||i.key,o=s?.[r]?.join("/")||"";if(!this.isMatchFeature(this.method,o))return this.applyCorsHeaders(this.response.notFound("Route not found",{method:this.method,path:o,params:s}));await this.feature.loadInjects(),e={req:this.request,res:this.response,method:this.method,path:o,params:this.route.params,wildcards:this.route.wildcards,reflect:this.route.route.getReflect(),feature:this.feature},this.requestHooks.setFeatureHooks(this.feature.getHooks()),await this.requestHooks.featureRequest(e);const n=await t.executeContext.run(e,()=>this.dispatch());return await this.requestHooks.featureResponse(e),await this.requestHooks.appResponse(e),this.applyCorsHeaders(n)}catch(t){return e&&(await this.requestHooks.featureResponse(e),await this.requestHooks.appResponse(e)),this.applyCorsHeaders(this.response.internalServer(t))}}static createHandler(e){return async(t,s)=>{await a.registerInjectFactories(),await a.loadImports();const r=new a(t,e,s);await r.requestHooks.appRequest(t,e);const o=await r.match.bind(r)();return a.toResponse(o)}}static create(e=i){return this.options=e,this.hooks=new r.ApplicationHooks(this.options),this.ResponseClass=e.response??Response,this.poweredBy=e.poweredBy??"MxWeb",e.guards&&e.guards.forEach(e=>this.guards.add(e)),e.filters&&e.filters.forEach(e=>this.filters.add(e)),e.interceptors&&e.interceptors.forEach(e=>this.interceptors.add(e)),e.pipes&&e.pipes.forEach(e=>this.pipes.add(e)),{[n.RouteMethod.GET]:a.createHandler(n.RouteMethod.GET),[n.RouteMethod.POST]:a.createHandler(n.RouteMethod.POST),[n.RouteMethod.PUT]:a.createHandler(n.RouteMethod.PUT),[n.RouteMethod.PATCH]:a.createHandler(n.RouteMethod.PATCH),[n.RouteMethod.DELETE]:a.createHandler(n.RouteMethod.DELETE),[n.RouteMethod.HEAD]:a.createHeadHandler(),[n.RouteMethod.OPTIONS]:a.createOptionsHandler()}}static createHeadHandler(){return async(e,t)=>{await a.registerInjectFactories(),await a.loadImports();const s=new a(e,n.RouteMethod.HEAD,t);await s.requestHooks.appRequest(e,n.RouteMethod.HEAD);const r=await s.match.bind(s)();return new Response(null,{status:r.status,statusText:r.statusText,headers:r.headers})}}static createOptionsHandler(){return async e=>{await a.registerInjectFactories();const t=this.corsOrigins,r=e.headers.get("origin"),o=s.ServerResponse.options();if(!t.length||!r)return o;const n=new Headers(o.headers);return t.includes("*")?n.set("Access-Control-Allow-Origin","*"):t.includes(r)&&(n.set("Access-Control-Allow-Origin",r),n.set("Vary","Origin")),n.set("Access-Control-Allow-Methods","GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS"),n.set("Access-Control-Allow-Headers","Content-Type, Authorization"),n.set("Access-Control-Max-Age","86400"),new Response(null,{status:204,headers:n})}}static register(...e){return e.forEach(e=>this.features.add(e)),this}}a.logger=o.Logger.create("Application"),a.features=new Set,a.guards=new Set,a.filters=new Set,a.interceptors=new Set,a.pipes=new Set,a.corsOrigins=[],a.options=i,a.ResponseClass=Response,a.poweredBy="MxWeb",a.initialized=!1,a.initPromise=null,a.shutdownRegistered=!1,a.registryCreated=!1,a.factoriesRegistered=!1,exports.Application=a;
+"use strict";var e=require("./error.js"),t=require("./context.js"),s=require("./response.js"),r=require("./hooks.js"),o=require("./logger.js"),n=require("./common.js");const i={key:"path"};class a{static toResponse(e){return!1!==this.poweredBy&&e.headers.set("X-Powered-By",this.poweredBy),this.ResponseClass.json(e.body,{status:e.status,statusText:e.statusText,headers:e.headers})}constructor(e,t,o){this.request=e,this.method=t,this.payload=o,this.feature=null,this.route=null,this.response=new s.ServerResponse,this.requestHooks=new r.RequestHooks(a.hooks)}static getInject(e){return t.executeContext.getInject(e)}static getInjectSync(e){return t.executeContext.getInjectSync(e)}static getInjects(){return new Map(t.executeContext.injections)}static createInjectRegistry(){return this.registryCreated||(this.registry={get:async e=>t.executeContext.getInject(e),set(e,s){t.executeContext.setInject(e,s)}},t.executeContext.setRegistry(this.registry),this.registryCreated=!0),this.registry}static async registerInjectFactories(){if(this.factoriesRegistered)return;const e=this.options.injects;if(!e||!e.length)return void(this.factoriesRegistered=!0);const t=this.createInjectRegistry();for(const s of e)await s(t);this.factoriesRegistered=!0,await this.initializeInjects(),this.registerShutdown(),await this.loadCors()}static async initializeInjects(){for(const[e,s]of t.executeContext.injections)if(!s.instance)try{const e=this.createInjectRegistry();s.instance=await s.factory(e),s.instance&&"function"==typeof s.instance.onInit&&await s.instance.onInit()}catch(t){throw a.logger.error(`Error initializing inject ${e}:`,t),t}}static registerShutdown(){if(this.shutdownRegistered)return;this.shutdownRegistered=!0;const e=async()=>{a.logger.info("Shutting down...");for(const e of this.features)await e.destroyInjects();for(const[e,s]of t.executeContext.injections)if(s.instance&&"function"==typeof s.instance.onDestroy)try{await s.instance.onDestroy(),a.logger.info(`Destroyed inject: ${e}`)}catch(t){a.logger.error(`Error destroying inject ${e}:`,t)}a.logger.info("Shutdown complete"),process.exit(0)};process.on("SIGTERM",e),process.on("SIGINT",e)}static async loadCors(){const e=this.options.cors;e&&(Array.isArray(e)?this.corsOrigins=e:this.corsOrigins=await e(this.registry))}static async loadImports(){if(!this.initialized)return this.initPromise||(this.initPromise=(async()=>{this.initialized=!0})()),this.initPromise}isMatchFeature(e,t){for(const s of a.features)if(this.route=s.matchRoute(e,t),this.route)return this.feature=s,!0;return null}async executeGuards(){const e=this.feature?.getGuards()??new Set,s=this.route?.route.getReflect().getGuards()??new Set,r=[...a.guards,...e,...s];if(!r.length)return!0;for(const e of r)try{const s=new e;if(!await s.canActivate(t.executeContext))return!1}catch{return!1}return!0}async executeMiddlewares(){const e=this.route.route.getMiddlewares();if(!e.length)return!0;for(const s of e){let e=!1;const r=()=>{e=!0};try{if(await s(t.executeContext,r),!e)return!1}catch{return!1}}return!0}async executeFilters(e){const r=[...this.route?.route.getReflect().getFilters()??new Set,...this.feature?.getFilters()??new Set,...a.filters];for(const o of r)try{const r=new o,n=await r.catch(e,t.executeContext);if(n instanceof s.CoreResponse||n instanceof Response)return n}catch{continue}return null}async executeInterceptors(e){const t=[...this.route?.route.getReflect().getInterceptors()??new Set,...this.feature?.getInterceptors()??new Set,...a.interceptors];if(!t.length)return e;let s=e;for(const e of t){const t=new e;s=await t.transform(s)}return s}async executePipes(e){const t=this.feature?.getPipes()??new Set,s=this.route?.route.getReflect().getPipes()??new Set,r=[...a.pipes,...t,...s];if(!r.length)return e;let o=e;for(const e of r){const t=new e;o=await t.transform(o)}return o}checkCors(){const e=a.corsOrigins;if(!e.length)return!0;const t=this.request.headers.get("origin");return!t||(e.includes("*")||e.includes(t))}applyCorsHeaders(e){const t=a.corsOrigins;if(!t.length)return e;const s=this.request.headers.get("origin");return s?(t.includes("*")?e.headers.set("Access-Control-Allow-Origin","*"):t.includes(s)&&(e.headers.set("Access-Control-Allow-Origin",s),e.headers.set("Vary","Origin")),e.headers.set("Access-Control-Allow-Methods","GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS"),e.headers.set("Access-Control-Allow-Headers","Content-Type, Authorization"),e.headers.set("Access-Control-Max-Age","86400"),e):e}async dispatch(){const r=this.route,o=this.feature,n=t.executeContext.getContextOrThrow();try{if(!await this.executeGuards())return this.response.forbidden();if(!await this.executeMiddlewares())return this.response.forbidden();const e=r.route.getAction();let t=null;if("string"==typeof e){const s=o.getController();"function"==typeof s._initDependencies&&await s._initDependencies(),"function"==typeof s[e]&&(t=s[e].bind(s))}else"function"==typeof e&&(t=e);if(!t)return this.response.internalServer(new Error("Route action handler not found"));await this.executePipes(n);const s=await t(n);let i=this.response.success(s);return i=await this.executeInterceptors(i),i}catch(t){const r=await this.executeFilters(t);if(r)return r instanceof Response?s.CoreResponse.json({success:r.ok,message:r.statusText,code:"FILTER_RESPONSE",status:r.status,data:null,error:null},{status:r.status,statusText:r.statusText}):r;if(t instanceof e.HttpError)switch(t.statusCode){case 400:return this.response.badRequest(t.message,t.error);case 401:return this.response.unauthorized(t.message,t.error);case 403:return this.response.forbidden(t.message,t.error);case 404:return this.response.notFound(t.message,t.error);case 409:return this.response.conflict(t.message,t.error);case 422:return this.response.unprocessableEntity(t.message,t.error);case 429:return this.response.tooManyRequests(t.message,t.error);case 501:return this.response.notImplemented(t.message,t.error);case 502:return this.response.badGateway(t.message,t.error);case 503:return this.response.serviceUnavailable(t.message,t.error);case 504:return this.response.gatewayTimeout(t.message,t.error)}return a.logger.error("[dispatch] Error:",t instanceof Error?t.message:t),t instanceof Error&&t.stack&&a.logger.debug("Stack trace:",t.stack),this.response.internalServer(t)}}async match(){let e=null;try{if(!this.checkCors())return this.applyCorsHeaders(this.response.forbidden("CORS not allowed"));const s=await this.payload.params,r=a.options.key||i.key,o=s?.[r]?.join("/")||"";if(!this.isMatchFeature(this.method,o))return this.applyCorsHeaders(this.response.notFound("Route not found",{method:this.method,path:o,params:s}));await this.feature.loadInjects(),e={req:this.request,res:this.response,method:this.method,path:o,params:this.route.params,wildcards:this.route.wildcards,reflect:this.route.route.getReflect(),feature:this.feature},this.requestHooks.setFeatureHooks(this.feature.getHooks()),await this.requestHooks.featureRequest(e);const n=await t.executeContext.run(e,()=>this.dispatch());return await this.requestHooks.featureResponse(e),await this.requestHooks.appResponse(e),this.applyCorsHeaders(n)}catch(t){return e&&(await this.requestHooks.featureResponse(e),await this.requestHooks.appResponse(e)),this.applyCorsHeaders(this.response.internalServer(t))}}static createHandler(e){return async(t,s)=>{await a.registerInjectFactories(),await a.loadImports();const r=new a(t,e,s);await r.requestHooks.appRequest(t,e);const o=await r.match.bind(r)();return a.toResponse(o)}}static create(e=i){return this.options=e,this.hooks=new r.ApplicationHooks(this.options),this.ResponseClass=e.response??Response,this.poweredBy=e.poweredBy??"MxWeb",e.guards&&e.guards.forEach(e=>this.guards.add(e)),e.filters&&e.filters.forEach(e=>this.filters.add(e)),e.interceptors&&e.interceptors.forEach(e=>this.interceptors.add(e)),e.pipes&&e.pipes.forEach(e=>this.pipes.add(e)),{[n.RouteMethod.GET]:a.createHandler(n.RouteMethod.GET),[n.RouteMethod.POST]:a.createHandler(n.RouteMethod.POST),[n.RouteMethod.PUT]:a.createHandler(n.RouteMethod.PUT),[n.RouteMethod.PATCH]:a.createHandler(n.RouteMethod.PATCH),[n.RouteMethod.DELETE]:a.createHandler(n.RouteMethod.DELETE),[n.RouteMethod.HEAD]:a.createHeadHandler(),[n.RouteMethod.OPTIONS]:a.createOptionsHandler()}}static createHeadHandler(){return async(e,t)=>{await a.registerInjectFactories(),await a.loadImports();const s=new a(e,n.RouteMethod.HEAD,t);await s.requestHooks.appRequest(e,n.RouteMethod.HEAD);const r=await s.match.bind(s)();return new Response(null,{status:r.status,statusText:r.statusText,headers:r.headers})}}static createOptionsHandler(){return async e=>{await a.registerInjectFactories();const t=this.corsOrigins,r=e.headers.get("origin"),o=s.ServerResponse.options();if(!t.length||!r)return o;const n=new Headers(o.headers);return t.includes("*")?n.set("Access-Control-Allow-Origin","*"):t.includes(r)&&(n.set("Access-Control-Allow-Origin",r),n.set("Vary","Origin")),n.set("Access-Control-Allow-Methods","GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS"),n.set("Access-Control-Allow-Headers","Content-Type, Authorization"),n.set("Access-Control-Max-Age","86400"),new Response(null,{status:204,headers:n})}}static register(...e){return e.forEach(e=>this.features.add(e)),this}}a.logger=o.Logger.create("Application"),a.features=new Set,a.guards=new Set,a.filters=new Set,a.interceptors=new Set,a.pipes=new Set,a.corsOrigins=[],a.options=i,a.ResponseClass=Response,a.poweredBy="MxWeb",a.initialized=!1,a.initPromise=null,a.shutdownRegistered=!1,a.registryCreated=!1,a.factoriesRegistered=!1,exports.Application=a;

package/dist/application.mjs

@@ -1 +1 @@
-import{HttpError as e}from"./error.mjs";import{executeContext as t}from"./context.mjs";import{ServerResponse as s,CoreResponse as r}from"./response.mjs";import{RequestHooks as n,ApplicationHooks as i}from"./hooks.mjs";import{Logger as o}from"./logger.mjs";import{RouteMethod as a}from"./common.mjs";const c={key:"path"};class u{static toResponse(e){return!1!==this.poweredBy&&e.headers.set("X-Powered-By",this.poweredBy),this.ResponseClass.json(e.body,{status:e.status,statusText:e.statusText,headers:e.headers})}constructor(e,t,r){this.request=e,this.method=t,this.payload=r,this.feature=null,this.route=null,this.response=new s,this.requestHooks=new n(u.hooks)}static getInject(e){return t.getInject(e)}static getInjectSync(e){return t.getInjectSync(e)}static getInjects(){return new Map(t.injections)}static createInjectRegistry(){return this.registryCreated||(this.registry={get:async e=>t.getInject(e),set(e,s){t.setInject(e,s)}},t.setRegistry(this.registry),this.registryCreated=!0),this.registry}static async registerInjectFactories(){if(this.factoriesRegistered)return;const e=this.options.injects;if(!e||!e.length)return void(this.factoriesRegistered=!0);const t=this.createInjectRegistry();for(const s of e)await s(t);this.factoriesRegistered=!0,await this.initializeInjects(),this.registerShutdown(),await this.loadCors()}static async initializeInjects(){for(const[e,s]of t.injections)if(!s.instance)try{const e=this.createInjectRegistry();s.instance=await s.factory(e),s.instance&&"function"==typeof s.instance.onInit&&await s.instance.onInit()}catch(t){throw u.logger.error(`Error initializing inject ${e}:`,t),t}}static registerShutdown(){if(this.shutdownRegistered)return;this.shutdownRegistered=!0;const e=async()=>{u.logger.info("Shutting down...");for(const e of this.features)await e.destroyInjects();for(const[e,s]of t.injections)if(s.instance&&"function"==typeof s.instance.onDestroy)try{await s.instance.onDestroy(),u.logger.info(`Destroyed inject: ${e}`)}catch(t){u.logger.error(`Error destroying inject ${e}:`,t)}u.logger.info("Shutdown complete"),process.exit(0)};process.on("SIGTERM",e),process.on("SIGINT",e)}static async loadCors(){const e=this.options.cors;e&&(Array.isArray(e)?this.corsOrigins=e:this.corsOrigins=await e(this.registry))}static async loadImports(){if(!this.initialized)return this.initPromise||(this.initPromise=(async()=>{this.initialized=!0})()),this.initPromise}isMatchFeature(e,t){for(const s of u.features)if(this.route=s.matchRoute(e,t),this.route)return this.feature=s,!0;return null}async executeGuards(){const e=this.route?.route.getReflect().getGuards()??new Set,s=[...u.guards,...e];if(!s.length)return!0;for(const e of s)try{const s=new e;if(!await s.canActivate(t))return!1}catch{return!1}return!0}async executeMiddlewares(){const e=this.route.route.getMiddlewares();if(!e.length)return!0;for(const s of e){let e=!1;const r=()=>{e=!0};try{if(await s(t,r),!e)return!1}catch{return!1}}return!0}async executeFilters(e){const s=[...this.route?.route.getReflect().getFilters()??new Set,...u.filters];for(const n of s)try{const s=new n,i=await s.catch(e,t);if(i instanceof r||i instanceof Response)return i}catch{continue}return null}async executeInterceptors(e){const t=[...this.route?.route.getReflect().getInterceptors()??new Set,...u.interceptors];if(!t.length)return e;let s=e;for(const e of t){const t=new e;s=await t.transform(s)}return s}async executePipes(e){const t=this.route?.route.getReflect().getPipes()??new Set,s=[...u.pipes,...t];if(!s.length)return e;let r=e;for(const e of s){const t=new e;r=await t.transform(r)}return r}checkCors(){const e=u.corsOrigins;if(!e.length)return!0;const t=this.request.headers.get("origin");return!t||(e.includes("*")||e.includes(t))}applyCorsHeaders(e){const t=u.corsOrigins;if(!t.length)return e;const s=this.request.headers.get("origin");return s?(t.includes("*")?e.headers.set("Access-Control-Allow-Origin","*"):t.includes(s)&&(e.headers.set("Access-Control-Allow-Origin",s),e.headers.set("Vary","Origin")),e.headers.set("Access-Control-Allow-Methods","GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS"),e.headers.set("Access-Control-Allow-Headers","Content-Type, Authorization"),e.headers.set("Access-Control-Max-Age","86400"),e):e}async dispatch(){const s=this.route,n=this.feature,i=t.getContextOrThrow();try{if(!await this.executeGuards())return this.response.forbidden();if(!await this.executeMiddlewares())return this.response.forbidden();const e=s.route.getAction();let t=null;if("string"==typeof e){const s=n.getController();"function"==typeof s._initDependencies&&await s._initDependencies(),"function"==typeof s[e]&&(t=s[e].bind(s))}else"function"==typeof e&&(t=e);if(!t)return this.response.internalServer(new Error("Route action handler not found"));await this.executePipes(i);const r=await t(i);let o=this.response.success(r);return o=await this.executeInterceptors(o),o}catch(t){const s=await this.executeFilters(t);if(s)return s instanceof Response?r.json({success:s.ok,message:s.statusText,code:"FILTER_RESPONSE",status:s.status,data:null,error:null},{status:s.status,statusText:s.statusText}):s;if(t instanceof e)switch(t.statusCode){case 400:return this.response.badRequest(t.message,t.error);case 401:return this.response.unauthorized(t.message,t.error);case 403:return this.response.forbidden(t.message,t.error);case 404:return this.response.notFound(t.message,t.error);case 409:return this.response.conflict(t.message,t.error);case 422:return this.response.unprocessableEntity(t.message,t.error);case 429:return this.response.tooManyRequests(t.message,t.error);case 501:return this.response.notImplemented(t.message,t.error);case 502:return this.response.badGateway(t.message,t.error);case 503:return this.response.serviceUnavailable(t.message,t.error);case 504:return this.response.gatewayTimeout(t.message,t.error)}return u.logger.error("[dispatch] Error:",t instanceof Error?t.message:t),t instanceof Error&&t.stack&&u.logger.debug("Stack trace:",t.stack),this.response.internalServer(t)}}async match(){let e=null;try{if(!this.checkCors())return this.applyCorsHeaders(this.response.forbidden("CORS not allowed"));const s=await this.payload.params,r=u.options.key||c.key,n=s?.[r]?.join("/")||"";if(!this.isMatchFeature(this.method,n))return this.applyCorsHeaders(this.response.notFound("Route not found",{method:this.method,path:n,params:s}));await this.feature.loadInjects(),e={req:this.request,res:this.response,method:this.method,path:n,params:this.route.params,wildcards:this.route.wildcards,reflect:this.route.route.getReflect(),feature:this.feature},this.requestHooks.setFeatureHooks(this.feature.getHooks()),await this.requestHooks.featureRequest(e);const i=await t.run(e,()=>this.dispatch());return await this.requestHooks.featureResponse(e),await this.requestHooks.appResponse(e),this.applyCorsHeaders(i)}catch(t){return e&&(await this.requestHooks.featureResponse(e),await this.requestHooks.appResponse(e)),this.applyCorsHeaders(this.response.internalServer(t))}}static createHandler(e){return async(t,s)=>{await u.registerInjectFactories(),await u.loadImports();const r=new u(t,e,s);await r.requestHooks.appRequest(t,e);const n=await r.match.bind(r)();return u.toResponse(n)}}static create(e=c){return this.options=e,this.hooks=new i(this.options),this.ResponseClass=e.response??Response,this.poweredBy=e.poweredBy??"MxWeb",e.guards&&e.guards.forEach(e=>this.guards.add(e)),e.filters&&e.filters.forEach(e=>this.filters.add(e)),e.interceptors&&e.interceptors.forEach(e=>this.interceptors.add(e)),e.pipes&&e.pipes.forEach(e=>this.pipes.add(e)),{[a.GET]:u.createHandler(a.GET),[a.POST]:u.createHandler(a.POST),[a.PUT]:u.createHandler(a.PUT),[a.PATCH]:u.createHandler(a.PATCH),[a.DELETE]:u.createHandler(a.DELETE),[a.HEAD]:u.createHeadHandler(),[a.OPTIONS]:u.createOptionsHandler()}}static createHeadHandler(){return async(e,t)=>{await u.registerInjectFactories(),await u.loadImports();const s=new u(e,a.HEAD,t);await s.requestHooks.appRequest(e,a.HEAD);const r=await s.match.bind(s)();return new Response(null,{status:r.status,statusText:r.statusText,headers:r.headers})}}static createOptionsHandler(){return async e=>{await u.registerInjectFactories();const t=this.corsOrigins,r=e.headers.get("origin"),n=s.options();if(!t.length||!r)return n;const i=new Headers(n.headers);return t.includes("*")?i.set("Access-Control-Allow-Origin","*"):t.includes(r)&&(i.set("Access-Control-Allow-Origin",r),i.set("Vary","Origin")),i.set("Access-Control-Allow-Methods","GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS"),i.set("Access-Control-Allow-Headers","Content-Type, Authorization"),i.set("Access-Control-Max-Age","86400"),new Response(null,{status:204,headers:i})}}static register(...e){return e.forEach(e=>this.features.add(e)),this}}u.logger=o.create("Application"),u.features=new Set,u.guards=new Set,u.filters=new Set,u.interceptors=new Set,u.pipes=new Set,u.corsOrigins=[],u.options=c,u.ResponseClass=Response,u.poweredBy="MxWeb",u.initialized=!1,u.initPromise=null,u.shutdownRegistered=!1,u.registryCreated=!1,u.factoriesRegistered=!1;export{u as Application};
+import{HttpError as e}from"./error.mjs";import{executeContext as t}from"./context.mjs";import{ServerResponse as s,CoreResponse as r}from"./response.mjs";import{RequestHooks as n,ApplicationHooks as i}from"./hooks.mjs";import{Logger as o}from"./logger.mjs";import{RouteMethod as a}from"./common.mjs";const c={key:"path"};class u{static toResponse(e){return!1!==this.poweredBy&&e.headers.set("X-Powered-By",this.poweredBy),this.ResponseClass.json(e.body,{status:e.status,statusText:e.statusText,headers:e.headers})}constructor(e,t,r){this.request=e,this.method=t,this.payload=r,this.feature=null,this.route=null,this.response=new s,this.requestHooks=new n(u.hooks)}static getInject(e){return t.getInject(e)}static getInjectSync(e){return t.getInjectSync(e)}static getInjects(){return new Map(t.injections)}static createInjectRegistry(){return this.registryCreated||(this.registry={get:async e=>t.getInject(e),set(e,s){t.setInject(e,s)}},t.setRegistry(this.registry),this.registryCreated=!0),this.registry}static async registerInjectFactories(){if(this.factoriesRegistered)return;const e=this.options.injects;if(!e||!e.length)return void(this.factoriesRegistered=!0);const t=this.createInjectRegistry();for(const s of e)await s(t);this.factoriesRegistered=!0,await this.initializeInjects(),this.registerShutdown(),await this.loadCors()}static async initializeInjects(){for(const[e,s]of t.injections)if(!s.instance)try{const e=this.createInjectRegistry();s.instance=await s.factory(e),s.instance&&"function"==typeof s.instance.onInit&&await s.instance.onInit()}catch(t){throw u.logger.error(`Error initializing inject ${e}:`,t),t}}static registerShutdown(){if(this.shutdownRegistered)return;this.shutdownRegistered=!0;const e=async()=>{u.logger.info("Shutting down...");for(const e of this.features)await e.destroyInjects();for(const[e,s]of t.injections)if(s.instance&&"function"==typeof s.instance.onDestroy)try{await s.instance.onDestroy(),u.logger.info(`Destroyed inject: ${e}`)}catch(t){u.logger.error(`Error destroying inject ${e}:`,t)}u.logger.info("Shutdown complete"),process.exit(0)};process.on("SIGTERM",e),process.on("SIGINT",e)}static async loadCors(){const e=this.options.cors;e&&(Array.isArray(e)?this.corsOrigins=e:this.corsOrigins=await e(this.registry))}static async loadImports(){if(!this.initialized)return this.initPromise||(this.initPromise=(async()=>{this.initialized=!0})()),this.initPromise}isMatchFeature(e,t){for(const s of u.features)if(this.route=s.matchRoute(e,t),this.route)return this.feature=s,!0;return null}async executeGuards(){const e=this.feature?.getGuards()??new Set,s=this.route?.route.getReflect().getGuards()??new Set,r=[...u.guards,...e,...s];if(!r.length)return!0;for(const e of r)try{const s=new e;if(!await s.canActivate(t))return!1}catch{return!1}return!0}async executeMiddlewares(){const e=this.route.route.getMiddlewares();if(!e.length)return!0;for(const s of e){let e=!1;const r=()=>{e=!0};try{if(await s(t,r),!e)return!1}catch{return!1}}return!0}async executeFilters(e){const s=[...this.route?.route.getReflect().getFilters()??new Set,...this.feature?.getFilters()??new Set,...u.filters];for(const n of s)try{const s=new n,i=await s.catch(e,t);if(i instanceof r||i instanceof Response)return i}catch{continue}return null}async executeInterceptors(e){const t=[...this.route?.route.getReflect().getInterceptors()??new Set,...this.feature?.getInterceptors()??new Set,...u.interceptors];if(!t.length)return e;let s=e;for(const e of t){const t=new e;s=await t.transform(s)}return s}async executePipes(e){const t=this.feature?.getPipes()??new Set,s=this.route?.route.getReflect().getPipes()??new Set,r=[...u.pipes,...t,...s];if(!r.length)return e;let n=e;for(const e of r){const t=new e;n=await t.transform(n)}return n}checkCors(){const e=u.corsOrigins;if(!e.length)return!0;const t=this.request.headers.get("origin");return!t||(e.includes("*")||e.includes(t))}applyCorsHeaders(e){const t=u.corsOrigins;if(!t.length)return e;const s=this.request.headers.get("origin");return s?(t.includes("*")?e.headers.set("Access-Control-Allow-Origin","*"):t.includes(s)&&(e.headers.set("Access-Control-Allow-Origin",s),e.headers.set("Vary","Origin")),e.headers.set("Access-Control-Allow-Methods","GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS"),e.headers.set("Access-Control-Allow-Headers","Content-Type, Authorization"),e.headers.set("Access-Control-Max-Age","86400"),e):e}async dispatch(){const s=this.route,n=this.feature,i=t.getContextOrThrow();try{if(!await this.executeGuards())return this.response.forbidden();if(!await this.executeMiddlewares())return this.response.forbidden();const e=s.route.getAction();let t=null;if("string"==typeof e){const s=n.getController();"function"==typeof s._initDependencies&&await s._initDependencies(),"function"==typeof s[e]&&(t=s[e].bind(s))}else"function"==typeof e&&(t=e);if(!t)return this.response.internalServer(new Error("Route action handler not found"));await this.executePipes(i);const r=await t(i);let o=this.response.success(r);return o=await this.executeInterceptors(o),o}catch(t){const s=await this.executeFilters(t);if(s)return s instanceof Response?r.json({success:s.ok,message:s.statusText,code:"FILTER_RESPONSE",status:s.status,data:null,error:null},{status:s.status,statusText:s.statusText}):s;if(t instanceof e)switch(t.statusCode){case 400:return this.response.badRequest(t.message,t.error);case 401:return this.response.unauthorized(t.message,t.error);case 403:return this.response.forbidden(t.message,t.error);case 404:return this.response.notFound(t.message,t.error);case 409:return this.response.conflict(t.message,t.error);case 422:return this.response.unprocessableEntity(t.message,t.error);case 429:return this.response.tooManyRequests(t.message,t.error);case 501:return this.response.notImplemented(t.message,t.error);case 502:return this.response.badGateway(t.message,t.error);case 503:return this.response.serviceUnavailable(t.message,t.error);case 504:return this.response.gatewayTimeout(t.message,t.error)}return u.logger.error("[dispatch] Error:",t instanceof Error?t.message:t),t instanceof Error&&t.stack&&u.logger.debug("Stack trace:",t.stack),this.response.internalServer(t)}}async match(){let e=null;try{if(!this.checkCors())return this.applyCorsHeaders(this.response.forbidden("CORS not allowed"));const s=await this.payload.params,r=u.options.key||c.key,n=s?.[r]?.join("/")||"";if(!this.isMatchFeature(this.method,n))return this.applyCorsHeaders(this.response.notFound("Route not found",{method:this.method,path:n,params:s}));await this.feature.loadInjects(),e={req:this.request,res:this.response,method:this.method,path:n,params:this.route.params,wildcards:this.route.wildcards,reflect:this.route.route.getReflect(),feature:this.feature},this.requestHooks.setFeatureHooks(this.feature.getHooks()),await this.requestHooks.featureRequest(e);const i=await t.run(e,()=>this.dispatch());return await this.requestHooks.featureResponse(e),await this.requestHooks.appResponse(e),this.applyCorsHeaders(i)}catch(t){return e&&(await this.requestHooks.featureResponse(e),await this.requestHooks.appResponse(e)),this.applyCorsHeaders(this.response.internalServer(t))}}static createHandler(e){return async(t,s)=>{await u.registerInjectFactories(),await u.loadImports();const r=new u(t,e,s);await r.requestHooks.appRequest(t,e);const n=await r.match.bind(r)();return u.toResponse(n)}}static create(e=c){return this.options=e,this.hooks=new i(this.options),this.ResponseClass=e.response??Response,this.poweredBy=e.poweredBy??"MxWeb",e.guards&&e.guards.forEach(e=>this.guards.add(e)),e.filters&&e.filters.forEach(e=>this.filters.add(e)),e.interceptors&&e.interceptors.forEach(e=>this.interceptors.add(e)),e.pipes&&e.pipes.forEach(e=>this.pipes.add(e)),{[a.GET]:u.createHandler(a.GET),[a.POST]:u.createHandler(a.POST),[a.PUT]:u.createHandler(a.PUT),[a.PATCH]:u.createHandler(a.PATCH),[a.DELETE]:u.createHandler(a.DELETE),[a.HEAD]:u.createHeadHandler(),[a.OPTIONS]:u.createOptionsHandler()}}static createHeadHandler(){return async(e,t)=>{await u.registerInjectFactories(),await u.loadImports();const s=new u(e,a.HEAD,t);await s.requestHooks.appRequest(e,a.HEAD);const r=await s.match.bind(s)();return new Response(null,{status:r.status,statusText:r.statusText,headers:r.headers})}}static createOptionsHandler(){return async e=>{await u.registerInjectFactories();const t=this.corsOrigins,r=e.headers.get("origin"),n=s.options();if(!t.length||!r)return n;const i=new Headers(n.headers);return t.includes("*")?i.set("Access-Control-Allow-Origin","*"):t.includes(r)&&(i.set("Access-Control-Allow-Origin",r),i.set("Vary","Origin")),i.set("Access-Control-Allow-Methods","GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS"),i.set("Access-Control-Allow-Headers","Content-Type, Authorization"),i.set("Access-Control-Max-Age","86400"),new Response(null,{status:204,headers:i})}}static register(...e){return e.forEach(e=>this.features.add(e)),this}}u.logger=o.create("Application"),u.features=new Set,u.guards=new Set,u.filters=new Set,u.interceptors=new Set,u.pipes=new Set,u.corsOrigins=[],u.options=c,u.ResponseClass=Response,u.poweredBy="MxWeb",u.initialized=!1,u.initPromise=null,u.shutdownRegistered=!1,u.registryCreated=!1,u.factoriesRegistered=!1;export{u as Application};

package/dist/common.d.ts

@@ -9,6 +9,161 @@ export type Callback<R = void, A extends any[] = []> = (...args: A) => R;
  * This module provides foundational types for dependency injection, routing, and lifecycle management.
  * @module common
  */
+/**
+ * Interface representing the feature context accessible from ExecuteContext.
+ * This abstraction allows execute.ts to work with features without importing Feature class directly,
+ * avoiding circular dependencies.
+ *
+ * @remarks
+ * Feature class implements this interface.
+ * Used in RequestContext and ExecuteContext methods.
+ */
+export interface FeatureContext {
+    /**
+     * Checks if an inject exists in this feature.
+     * @param name - The inject name to check
+     * @returns true if the inject exists
+     */
+    hasInject(name: string): boolean;
+    /**
+     * Retrieves an inject by name with lazy initialization.
+     * @template T - Expected return type
+     * @param name - The name of the inject to retrieve
+     * @returns Promise resolving to the inject or undefined
+     */
+    getInject<T = unknown>(name: string): Promise<T | undefined>;
+    /**
+     * Retrieves an inject synchronously (only if already initialized).
+     * @template T - Expected return type
+     * @param name - The name of the inject to retrieve
+     * @returns The inject or undefined
+     */
+    getInjectSync<T = unknown>(name: string): T | undefined;
+}
+/**
+ * Interface for guard classes that determine if a request should proceed.
+ * Guards are used for authorization, authentication, and access control.
+ *
+ * @template Context - The execution context type (defaults to unknown for flexibility)
+ *
+ * @example
+ * ```ts
+ * class AuthGuard implements CanActivate {
+ *   canActivate(context: ExecuteContext): boolean {
+ *     const token = context.switchHttp().headers()["authorization"];
+ *     return !!token && isValidToken(token);
+ *   }
+ * }
+ * ```
+ */
+export interface CanActivate<Context = unknown> {
+    /**
+     * Determines if the request should be allowed to proceed.
+     *
+     * @param context - The execution context for the current request
+     * @returns true to allow, false to deny (results in 403 Forbidden)
+     */
+    canActivate(context: Context): boolean | Promise<boolean>;
+}
+/**
+ * Constructor type for guard classes.
+ *
+ * @template Context - The execution context type
+ */
+export type Guard<Context = unknown> = new (...args: unknown[]) => CanActivate<Context>;
+/**
+ * Interface for exception filter classes that handle errors.
+ * Filters can transform exceptions into custom responses.
+ *
+ * @template Response - The type of response the filter returns
+ * @template Context - The execution context type (defaults to unknown for flexibility)
+ *
+ * @example
+ * ```ts
+ * class HttpExceptionFilter implements ExceptionFilter<Response> {
+ *   catch(exception: unknown, context: ExecuteContext): Response {
+ *     if (exception instanceof HttpError) {
+ *       return new Response(JSON.stringify({ error: exception.message }), {
+ *         status: exception.statusCode,
+ *       });
+ *     }
+ *     throw exception; // Re-throw if not handled
+ *   }
+ * }
+ * ```
+ */
+export interface ExceptionFilter<Response = unknown, Context = unknown> {
+    /**
+     * Handles an exception and optionally returns a response.
+     *
+     * @param exception - The thrown exception
+     * @param context - The execution context for the current request
+     * @returns A response to send, or re-throw to pass to next filter
+     */
+    catch(exception: unknown, context: Context): Response | Promise<Response>;
+}
+/**
+ * Constructor type for exception filter classes.
+ *
+ * @template Response - The type of response the filter returns
+ * @template Context - The execution context type
+ */
+export type Filter<Response = unknown, Context = unknown> = new (...args: unknown[]) => ExceptionFilter<Response, Context>;
+/**
+ * Interface for class-based response interceptors.
+ * Provides more flexibility than function interceptors with access to instance state.
+ *
+ * @template T - The type of the response data
+ * @template Response - The response type (defaults to unknown for flexibility)
+ *
+ * @example
+ * ```ts
+ * class LoggingInterceptor implements ResponseInterceptorHandler {
+ *   transform(response: CoreResponse): CoreResponse {
+ *     console.log(`[${response.status}] ${response.body.message}`);
+ *     return response;
+ *   }
+ * }
+ *
+ * class CacheHeaderInterceptor implements ResponseInterceptorHandler {
+ *   transform(response: CoreResponse): CoreResponse {
+ *     if (response.status >= 200 && response.status < 300) {
+ *       response.headers.set("Cache-Control", "max-age=3600");
+ *     }
+ *     return response;
+ *   }
+ * }
+ * ```
+ */
+export interface ResponseInterceptorHandler<Response = unknown> {
+    /**
+     * Transforms the response.
+     * Called after the handler returns, allowing post-processing of the response.
+     *
+     * @param response - The response to transform
+     * @returns The transformed response (can be the same instance or a new one)
+     */
+    transform(response: Response): Response | Promise<Response>;
+}
+/**
+ * Constructor type for response interceptor classes.
+ * Interceptors transform the response after the handler returns.
+ *
+ * @template Response - The response type
+ *
+ * @example
+ * ```ts
+ * import { ResponseInterceptorHandler, CoreResponse } from "@mxweb/core";
+ *
+ * class LoggingInterceptor implements ResponseInterceptorHandler {
+ *   transform(response: CoreResponse): CoreResponse {
+ *     console.log(`Response: ${response.status} ${response.body.message}`);
+ *     return response;
+ *   }
+ * }
+ * ```
+ */
+export type Interceptor<Response = unknown> = new (...args: unknown[]) => ResponseInterceptorHandler<Response>;
 /**
  * Interface for Application-level dependency injects.
  * All global injects must implement this interface to ensure consistent lifecycle management.
@@ -275,6 +430,56 @@ export interface PipeTransform<Input = unknown, Output = unknown> {
  * @template Output - The type of output value the pipe produces
  */
 export type Pipe<Input = unknown, Output = unknown> = new (...args: unknown[]) => PipeTransform<Input, Output>;
+/**
+ * Generic constructor type for class instantiation.
+ */
+export type ClassConstructor<T = unknown> = new (...args: any[]) => T;
+/**
+ * Shared options for guards, filters, interceptors, and pipes.
+ * Used by both Application and Feature configurations.
+ *
+ * @remarks
+ * This interface provides a common base for decorator options across
+ * different levels of the application hierarchy (Application, Feature, Route).
+ *
+ * Execution order:
+ * - Guards: Application → Feature → Route
+ * - Filters: Route → Feature → Application (reverse for catch)
+ * - Interceptors: Route → Feature → Application (for transform)
+ * - Pipes: Application → Feature → Route
+ *
+ * @example
+ * ```ts
+ * const options: DecoratorOptions = {
+ *   guards: [AuthGuard, RolesGuard],
+ *   filters: [HttpExceptionFilter],
+ *   interceptors: [LoggingInterceptor],
+ *   pipes: [ValidationPipe],
+ * };
+ * ```
+ */
+export interface DecoratorOptions {
+    /**
+     * Guards to apply at this level.
+     * Guards determine if a request should be processed.
+     */
+    guards?: Guard[];
+    /**
+     * Exception filters to apply at this level.
+     * Filters handle exceptions thrown during request processing.
+     */
+    filters?: Filter[];
+    /**
+     * Interceptors to apply at this level.
+     * Interceptors can transform the response.
+     */
+    interceptors?: Interceptor[];
+    /**
+     * Pipes to apply at this level.
+     * Pipes transform input data before it reaches the handler.
+     */
+    pipes?: Pipe[];
+}
 /**
  * Constructor type for inject classes.
  * Used when registering injects that need to be instantiated.

package/dist/decorator.d.ts

@@ -8,8 +8,8 @@
  *
  * @module decorator
  */
-import { CoreRequest, ExecuteContext, Filter, Guard, Interceptor } from "./execute";
-import { FeatureInject, Pipe } from "./common";
+import { CoreRequest, ExecuteContext } from "./execute";
+import { FeatureInject, Filter, Guard, Interceptor, Pipe } from "./common";
 /**
  * Result object from decorator functions.
  * Contains sets of guards, filters, interceptors, pipes, and metadata

package/dist/execute.d.ts

@@ -9,8 +9,7 @@
  * @module execute
  */
 import { ServerResponse } from "./response";
-import { Feature } from "./feature";
-import { ApplicationInject, InjectEntry, InjectInstanceFactory, InjectRegistry, Pipe, RouteMethod, RouteNextHandler } from "./common";
+import { ApplicationInject, FeatureContext, Filter, Guard, InjectEntry, InjectInstanceFactory, InjectRegistry, Interceptor, Pipe, RouteMethod, RouteNextHandler } from "./common";
 /**
  * Core request interface defining the minimal contract for HTTP requests.
  * This abstraction allows @mxweb/core to work with any request implementation
@@ -264,12 +263,12 @@ export declare class Reflect {
      * Returns the set of exception filter classes attached to this route.
      * @returns Set of filter class constructors
      */
-    getFilters(): Set<Filter<unknown>>;
+    getFilters(): Set<Filter>;
     /**
      * Returns the set of interceptor classes attached to this route.
      * @returns Set of interceptor class constructors
      */
-    getInterceptors(): Set<Interceptor<unknown>>;
+    getInterceptors(): Set<Interceptor>;
     /**
      * Returns the set of pipe classes attached to this route.
      * @returns Set of pipe class constructors
@@ -314,7 +313,7 @@ export interface RequestContext {
     /** Route metadata and decorators */
     reflect: Reflect;
     /** The feature that matched this request */
-    feature: Feature;
+    feature: FeatureContext;
 }
 /**
  * Request-scoped execution context using AsyncLocalStorage.
@@ -561,7 +560,7 @@ export declare class ExecuteContext {
      *
      * @returns The Feature instance or undefined if no context
      */
-    getFeature(): Feature | undefined;
+    getFeature<Feature extends FeatureContext>(): Feature | undefined;
     /**
      * Retrieves a feature-local inject by name with lazy initialization.
      * Falls back to global injects if not found in the feature.
@@ -639,33 +638,6 @@ export declare class ExecuteContext {
      */
     switchSync<T = unknown>(name: string): T | undefined;
 }
-/**
- * Interface for guard classes that determine if a request should proceed.
- * Guards are used for authorization, authentication, and access control.
- *
- * @example
- * ```ts
- * class AuthGuard implements CanActivate {
- *   canActivate(context: ExecuteContext): boolean {
- *     const token = context.switchHttp().headers()["authorization"];
- *     return !!token && isValidToken(token);
- *   }
- * }
- * ```
- */
-export interface CanActivate {
-    /**
-     * Determines if the request should be allowed to proceed.
-     *
-     * @param context - The execution context for the current request
-     * @returns true to allow, false to deny (results in 403 Forbidden)
-     */
-    canActivate(context: ExecuteContext): boolean | Promise<boolean>;
-}
-/**
- * Constructor type for guard classes.
- */
-export type Guard = new (...args: unknown[]) => CanActivate;
 /**
  * Function type for route action handlers (inline handlers).
  *
@@ -705,71 +677,3 @@ export type RouteHandler<Data = unknown> = (context: ExecuteContext) => Data;
  * ```
  */
 export type RouteMiddleware = (context: ExecuteContext, next: RouteNextHandler) => void | Promise<void>;
-/**
- * Interface for exception filter classes that handle errors.
- * Filters can transform exceptions into custom responses.
- *
- * @template Response - The type of response the filter returns
- *
- * @example
- * ```ts
- * class HttpExceptionFilter implements ExceptionFilter<Response> {
- *   catch(exception: unknown, context: ExecuteContext): Response {
- *     if (exception instanceof HttpError) {
- *       return new Response(JSON.stringify({ error: exception.message }), {
- *         status: exception.statusCode,
- *       });
- *     }
- *     throw exception; // Re-throw if not handled
- *   }
- * }
- * ```
- */
-export interface ExceptionFilter<Response = unknown> {
-    /**
-     * Handles an exception and optionally returns a response.
-     *
-     * @param exception - The thrown exception
-     * @param context - The execution context for the current request
-     * @returns A response to send, or re-throw to pass to next filter
-     */
-    catch(exception: unknown, context: ExecuteContext): Response | Promise<Response>;
-}
-/**
- * Constructor type for exception filter classes.
- *
- * @template Response - The type of response the filter returns
- */
-export type Filter<Response = unknown> = new (...args: unknown[]) => ExceptionFilter<Response>;
-/**
- * Constructor type for response interceptor classes.
- * Interceptors transform the CoreResponse after the handler returns.
- *
- * @template T - The type of the response data
- *
- * @remarks
- * The old `InterceptorHandler` interface with `intercept(context, next)` is deprecated.
- * Use `ResponseInterceptorHandler` from `response.ts` instead for the new pattern.
- *
- * @example
- * ```ts
- * import { ResponseInterceptorHandler, CoreResponse } from "@mxweb/core";
- *
- * class LoggingInterceptor implements ResponseInterceptorHandler {
- *   transform(response: CoreResponse): CoreResponse {
- *     console.log(`Response: ${response.status} ${response.body.message}`);
- *     return response;
- *   }
- * }
- *
- * class CacheHeaderInterceptor implements ResponseInterceptorHandler {
- *   transform(response: CoreResponse): CoreResponse {
- *     if (response.status >= 200 && response.status < 300) {
- *       response.headers.set("Cache-Control", "max-age=3600");
- *     }
- *     return response;
- *   }
- * }
- * ```
- */
-export type Interceptor<T = unknown> = new (...args: unknown[]) => import("./response").ResponseInterceptorHandler<T>;

package/dist/feature.d.ts

@@ -10,7 +10,7 @@
 import { ControllerConstructor } from "./controller";
 import { RouteMatched, Router } from "./router";
 import { FeatureHooks, FeatureHooksOptions } from "./hooks";
-import { FeatureInjectFactory, RouteMethod } from "./common";
+import { DecoratorOptions, FeatureInjectFactory, Filter, Guard, Interceptor, Pipe, RouteMethod } from "./common";
 /**
  * Type for feature-specific dependency injection configuration.
  * Array of factory functions that register injects.
@@ -41,7 +41,7 @@ export type FeatureInjects = FeatureInjectFactory[];
 export type FeatureImports = unknown[] | (() => unknown[]) | (() => Promise<unknown[]>);
 /**
  * Configuration options for creating a Feature.
- * Extends FeatureHooksOptions for lifecycle hooks.
+ * Extends FeatureHooksOptions for lifecycle hooks and DecoratorOptions for guards/filters/interceptors/pipes.
  *
  * @example
  * ```ts
@@ -52,13 +52,17 @@ export type FeatureImports = unknown[] | (() => unknown[]) | (() => Promise<unkn
  *     Route.post("/products", "create"),
  *   ),
  *   imports: [Connection.forFeature([ProductEntity])],
- *   injects: { productRepo: new ProductRepository() },
+ *   injects: [(registry) => registry.set("productRepo", () => new ProductRepository())],
+ *   guards: [AuthGuard],
+ *   filters: [HttpExceptionFilter],
+ *   interceptors: [LoggingInterceptor],
+ *   pipes: [ValidationPipe],
  *   onStart: () => console.log("Product feature started"),
  *   onRequest: (ctx) => console.log("Product feature request"),
  * };
  * ```
  */
-export interface FeatureInitialize extends FeatureHooksOptions {
+export interface FeatureInitialize extends FeatureHooksOptions, DecoratorOptions {
     /** The controller class that handles requests for this feature */
     controller: ControllerConstructor<any>;
     /** Router with registered routes for this feature */
@@ -148,6 +152,14 @@ export declare class Feature {
     private factoriesRegistered;
     /** Flag indicating if imports have been loaded */
     private importsLoaded;
+    /** Feature-level guards */
+    private guards;
+    /** Feature-level exception filters */
+    private filters;
+    /** Feature-level interceptors */
+    private interceptors;
+    /** Feature-level pipes */
+    private pipes;
     /**
      * Private constructor - use Feature.create() to instantiate.
      *
@@ -256,6 +268,30 @@ export declare class Feature {
      * @returns The FeatureHooks instance
      */
     getHooks(): FeatureHooks;
+    /**
+     * Returns the feature-level guards.
+     *
+     * @returns Set of guard classes for this feature
+     */
+    getGuards(): Set<Guard>;
+    /**
+     * Returns the feature-level exception filters.
+     *
+     * @returns Set of filter classes for this feature
+     */
+    getFilters(): Set<Filter>;
+    /**
+     * Returns the feature-level interceptors.
+     *
+     * @returns Set of interceptor classes for this feature
+     */
+    getInterceptors(): Set<Interceptor>;
+    /**
+     * Returns the feature-level pipes.
+     *
+     * @returns Set of pipe classes for this feature
+     */
+    getPipes(): Set<Pipe>;
     /**
      * Attempts to match a request against this feature's routes.
      *

package/dist/feature.js

@@ -1 +1 @@
-"use strict";var t=require("./hooks.js");class e{constructor(e,s,i){this.options=e,this.ControllerContructor=s,this.router=i,this.routeMatched=null,this.controller=null,this.injects=new Map,this.factoriesRegistered=!1,this.importsLoaded=!1,this.hooks=new t.FeatureHooks(this.options),this.registry=this.createInjectRegistry()}createInjectRegistry(){return{get:t=>this.getInject(t),set:(t,e)=>{this.injects.set(t,{factory:e})}}}static create(t){return new e(t,t.controller,t.router)}async loadImports(){if(this.importsLoaded)return;this.importsLoaded=!0;const{imports:t}=this.options;if(!t)return;"function"==typeof t&&await t()}async loadInjects(){if(await this.loadImports(),this.factoriesRegistered)return;this.factoriesRegistered=!0;const{injects:t}=this.options;if(t&&t.length)for(const e of t)await e(this.registry)}async destroyInjects(){for(const[t,e]of this.injects)if(e.instance&&e.instance.onFeatureDestroy)try{await e.instance.onFeatureDestroy()}catch(t){}this.injects.clear(),this.factoriesRegistered=!1}async getInject(t){const e=this.injects.get(t);if(e)return e.instance||(e.instance=await e.factory(this.registry),"function"==typeof e.instance.onFeature&&await e.instance.onFeature()),"function"==typeof e.instance.switch?e.instance.switch():e.instance}getInjectSync(t){const e=this.injects.get(t);if(e?.instance)return"function"==typeof e.instance.switch?e.instance.switch():e.instance}hasInject(t){return this.injects.has(t)}isInjectInitialized(t){const e=this.injects.get(t);return!!e?.instance}getController(){if(!this.controller){const t=this.ControllerContructor;this.controller=new t}return this.controller}getHooks(){return this.hooks}matchRoute(t,e){return this.routeMatched=this.router.match(t,e),this.routeMatched}}exports.Feature=e;
+"use strict";var t=require("./hooks.js");class e{constructor(e,s,i){this.options=e,this.ControllerContructor=s,this.router=i,this.routeMatched=null,this.controller=null,this.injects=new Map,this.factoriesRegistered=!1,this.importsLoaded=!1,this.guards=new Set,this.filters=new Set,this.interceptors=new Set,this.pipes=new Set,this.hooks=new t.FeatureHooks(this.options),this.registry=this.createInjectRegistry(),e.guards&&e.guards.forEach(t=>this.guards.add(t)),e.filters&&e.filters.forEach(t=>this.filters.add(t)),e.interceptors&&e.interceptors.forEach(t=>this.interceptors.add(t)),e.pipes&&e.pipes.forEach(t=>this.pipes.add(t))}createInjectRegistry(){return{get:t=>this.getInject(t),set:(t,e)=>{this.injects.set(t,{factory:e})}}}static create(t){return new e(t,t.controller,t.router)}async loadImports(){if(this.importsLoaded)return;this.importsLoaded=!0;const{imports:t}=this.options;if(!t)return;"function"==typeof t&&await t()}async loadInjects(){if(await this.loadImports(),this.factoriesRegistered)return;this.factoriesRegistered=!0;const{injects:t}=this.options;if(t&&t.length)for(const e of t)await e(this.registry)}async destroyInjects(){for(const[t,e]of this.injects)if(e.instance&&e.instance.onFeatureDestroy)try{await e.instance.onFeatureDestroy()}catch(t){}this.injects.clear(),this.factoriesRegistered=!1}async getInject(t){const e=this.injects.get(t);if(e)return e.instance||(e.instance=await e.factory(this.registry),"function"==typeof e.instance.onFeature&&await e.instance.onFeature()),"function"==typeof e.instance.switch?e.instance.switch():e.instance}getInjectSync(t){const e=this.injects.get(t);if(e?.instance)return"function"==typeof e.instance.switch?e.instance.switch():e.instance}hasInject(t){return this.injects.has(t)}isInjectInitialized(t){const e=this.injects.get(t);return!!e?.instance}getController(){if(!this.controller){const t=this.ControllerContructor;this.controller=new t}return this.controller}getHooks(){return this.hooks}getGuards(){return this.guards}getFilters(){return this.filters}getInterceptors(){return this.interceptors}getPipes(){return this.pipes}matchRoute(t,e){return this.routeMatched=this.router.match(t,e),this.routeMatched}}exports.Feature=e;

package/dist/feature.mjs

@@ -1 +1 @@
-import{FeatureHooks as t}from"./hooks.mjs";class e{constructor(e,s,i){this.options=e,this.ControllerContructor=s,this.router=i,this.routeMatched=null,this.controller=null,this.injects=new Map,this.factoriesRegistered=!1,this.importsLoaded=!1,this.hooks=new t(this.options),this.registry=this.createInjectRegistry()}createInjectRegistry(){return{get:t=>this.getInject(t),set:(t,e)=>{this.injects.set(t,{factory:e})}}}static create(t){return new e(t,t.controller,t.router)}async loadImports(){if(this.importsLoaded)return;this.importsLoaded=!0;const{imports:t}=this.options;if(!t)return;"function"==typeof t&&await t()}async loadInjects(){if(await this.loadImports(),this.factoriesRegistered)return;this.factoriesRegistered=!0;const{injects:t}=this.options;if(t&&t.length)for(const e of t)await e(this.registry)}async destroyInjects(){for(const[t,e]of this.injects)if(e.instance&&e.instance.onFeatureDestroy)try{await e.instance.onFeatureDestroy()}catch(t){}this.injects.clear(),this.factoriesRegistered=!1}async getInject(t){const e=this.injects.get(t);if(e)return e.instance||(e.instance=await e.factory(this.registry),"function"==typeof e.instance.onFeature&&await e.instance.onFeature()),"function"==typeof e.instance.switch?e.instance.switch():e.instance}getInjectSync(t){const e=this.injects.get(t);if(e?.instance)return"function"==typeof e.instance.switch?e.instance.switch():e.instance}hasInject(t){return this.injects.has(t)}isInjectInitialized(t){const e=this.injects.get(t);return!!e?.instance}getController(){if(!this.controller){const t=this.ControllerContructor;this.controller=new t}return this.controller}getHooks(){return this.hooks}matchRoute(t,e){return this.routeMatched=this.router.match(t,e),this.routeMatched}}export{e as Feature};
+import{FeatureHooks as t}from"./hooks.mjs";class e{constructor(e,s,i){this.options=e,this.ControllerContructor=s,this.router=i,this.routeMatched=null,this.controller=null,this.injects=new Map,this.factoriesRegistered=!1,this.importsLoaded=!1,this.guards=new Set,this.filters=new Set,this.interceptors=new Set,this.pipes=new Set,this.hooks=new t(this.options),this.registry=this.createInjectRegistry(),e.guards&&e.guards.forEach(t=>this.guards.add(t)),e.filters&&e.filters.forEach(t=>this.filters.add(t)),e.interceptors&&e.interceptors.forEach(t=>this.interceptors.add(t)),e.pipes&&e.pipes.forEach(t=>this.pipes.add(t))}createInjectRegistry(){return{get:t=>this.getInject(t),set:(t,e)=>{this.injects.set(t,{factory:e})}}}static create(t){return new e(t,t.controller,t.router)}async loadImports(){if(this.importsLoaded)return;this.importsLoaded=!0;const{imports:t}=this.options;if(!t)return;"function"==typeof t&&await t()}async loadInjects(){if(await this.loadImports(),this.factoriesRegistered)return;this.factoriesRegistered=!0;const{injects:t}=this.options;if(t&&t.length)for(const e of t)await e(this.registry)}async destroyInjects(){for(const[t,e]of this.injects)if(e.instance&&e.instance.onFeatureDestroy)try{await e.instance.onFeatureDestroy()}catch(t){}this.injects.clear(),this.factoriesRegistered=!1}async getInject(t){const e=this.injects.get(t);if(e)return e.instance||(e.instance=await e.factory(this.registry),"function"==typeof e.instance.onFeature&&await e.instance.onFeature()),"function"==typeof e.instance.switch?e.instance.switch():e.instance}getInjectSync(t){const e=this.injects.get(t);if(e?.instance)return"function"==typeof e.instance.switch?e.instance.switch():e.instance}hasInject(t){return this.injects.has(t)}isInjectInitialized(t){const e=this.injects.get(t);return!!e?.instance}getController(){if(!this.controller){const t=this.ControllerContructor;this.controller=new t}return this.controller}getHooks(){return this.hooks}getGuards(){return this.guards}getFilters(){return this.filters}getInterceptors(){return this.interceptors}getPipes(){return this.pipes}matchRoute(t,e){return this.routeMatched=this.router.match(t,e),this.routeMatched}}export{e as Feature};

package/dist/response.d.ts

@@ -245,21 +245,21 @@ export declare function applyTransformer<R = Response>(transformer: ResponseTran
  */
 export type ResponseInterceptor<T = unknown> = (response: CoreResponse<T>) => CoreResponse<T> | Promise<CoreResponse<T>>;
 /**
- * Interface for class-based response interceptors.
+ * Interface for class-based response interceptors with CoreResponse.
  * Provides more flexibility than function interceptors with access to instance state.
  *
  * @template T - The type of the response data
  *
  * @example
  * ```ts
- * class LoggingInterceptor implements ResponseInterceptorHandler {
+ * class LoggingInterceptor implements CoreResponseInterceptorHandler {
  *   transform(response: CoreResponse): CoreResponse {
  *     console.log(`[${response.status}] ${response.body.message}`);
  *     return response;
  *   }
  * }
  *
- * class CacheHeaderInterceptor implements ResponseInterceptorHandler {
+ * class CacheHeaderInterceptor implements CoreResponseInterceptorHandler {
  *   transform(response: CoreResponse): CoreResponse {
  *     if (response.status >= 200 && response.status < 300) {
  *       response.headers.set("Cache-Control", "max-age=3600");
@@ -269,7 +269,7 @@ export type ResponseInterceptor<T = unknown> = (response: CoreResponse<T>) => Co
  * }
  * ```
  */
-export interface ResponseInterceptorHandler<T = unknown> {
+export interface CoreResponseInterceptorHandler<T = unknown> {
     /**
      * Transforms the response.
      * Called after the handler returns, allowing post-processing of the response.

package/dist/route.d.ts

@@ -33,9 +33,9 @@
  * })
  * ```
  */
-import { Pipe, RouteMethod } from "./common";
+import { Filter, Guard, Interceptor, Pipe, RouteMethod } from "./common";
 import { DecoratorResult } from "./decorator";
-import { Filter, Guard, Interceptor, Reflect, RouteHandler, RouteMiddleware } from "./execute";
+import { Reflect, RouteHandler, RouteMiddleware } from "./execute";
 /**
  * Represents a single route definition in the application.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mxweb/core",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A NestJS-inspired backend framework for Next.js App Router with dependency injection, guards, interceptors, and modular architecture",
   "keywords": [
     "nextjs",