@webpieces/http-routing 0.3.166 → 0.3.167

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/http-routing",
-  "version": "0.3.166",
+  "version": "0.3.167",
   "description": "Decorator-based routing with auto-wiring for WebPieces",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -21,8 +21,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@webpieces/http-api": "0.3.166",
-    "@webpieces/http-filters": "0.3.166",
+    "@webpieces/http-api": "0.3.167",
+    "@webpieces/http-filters": "0.3.167",
     "inversify": "7.10.4",
     "minimatch": "10.0.1"
   }

package/src/ApiRoutingFactory.js

@@ -24,6 +24,8 @@ const decorators_1 = require("./decorators");
  */
 // webpieces-disable no-any-unknown -- generic class requires unconstrained default type params
 class ApiRoutingFactory {
+    apiMetaClass;
+    controllerClass;
     /**
      * @param apiMetaClass - The API prototype class with @ApiPath/@Endpoint decorators
      * @param controllerClass - The controller class that implements the API

package/src/ApiRoutingFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"ApiRoutingFactory.js","sourceRoot":"","sources":["../../../../../packages/http/http-routing/src/ApiRoutingFactory.ts"],"names":[],"mappings":"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","sourcesContent":["import { Routes, RouteBuilder, RouteDefinition } from './WebAppMeta';\nimport { isApiPath, getApiPath, getEndpoints, getAuthMeta, RouteMetadata, AuthMeta } from '@webpieces/http-api';\nimport 'reflect-metadata';\nimport { ROUTING_METADATA_KEYS } from './decorators';\n\n/**\n * Type representing a class constructor (abstract or concrete).\n */\n// webpieces-disable no-any-unknown -- generic type alias requires unconstrained default\nexport type ClassType<T = unknown> = Function & { prototype: T };\n\n/**\n * ApiRoutingFactory - Automatically wire API interfaces to controllers.\n * Reads @ApiPath/@Endpoint decorators from an API prototype class and\n * registers POST routes for each endpoint.\n *\n * Replaces the old RESTApiRoutes class.\n *\n * Usage:\n * ```typescript\n * // In your ServerMeta:\n * getRoutes(): Routes[] {\n *   return [\n *     new ApiRoutingFactory(SaveApi, SaveController),\n *   ];\n * }\n * ```\n */\n// webpieces-disable no-any-unknown -- generic class requires unconstrained default type params\nexport class ApiRoutingFactory<TApi = unknown, TController extends TApi = TApi> implements Routes {\n    private apiMetaClass: ClassType<TApi>;\n    private controllerClass: ClassType<TController>;\n\n    /**\n     * @param apiMetaClass - The API prototype class with @ApiPath/@Endpoint decorators\n     * @param controllerClass - The controller class that implements the API\n     */\n    constructor(apiMetaClass: ClassType<TApi>, controllerClass: ClassType<TController>) {\n        this.apiMetaClass = apiMetaClass;\n        this.controllerClass = controllerClass;\n\n        // Validate that apiMetaClass is marked with @ApiPath\n        if (!isApiPath(apiMetaClass)) {\n            const className = apiMetaClass.name || 'Unknown';\n            throw new Error(`Class ${className} must be decorated with @ApiPath()`);\n        }\n\n        // Validate that controllerClass actually extends apiMetaClass.\n        // TypeScript's structural typing won't catch a missing `extends` here, so we check\n        // the runtime prototype chain. Without this, a controller can silently drift from\n        // the API contract (wrong method names, wrong signatures) and only fail later as a\n        // confusing routing or method-not-found error.\n        const apiName = apiMetaClass.name || 'Unknown';\n        const controllerName = controllerClass.name || 'Unknown';\n        if (!(apiMetaClass.prototype as object).isPrototypeOf(controllerClass.prototype as object)) {\n            throw new Error(\n                `Controller ${controllerName} must extend ${apiName}. ` +\n                `Change the class declaration to: ` +\n                `'export class ${controllerName} extends ${apiName} { ... }'`,\n            );\n        }\n\n    }\n\n    /**\n     * Configure routes by reading @ApiPath + @Endpoint metadata.\n     * Validates controller methods and auth decorators in single loop.\n     */\n    configure(routeBuilder: RouteBuilder): void {\n        const basePath = getApiPath(this.apiMetaClass)!;\n        const endpoints = getEndpoints(this.apiMetaClass) || {};\n        const controllerFilepath = this.getControllerFilepath();\n        const apiName = this.apiMetaClass.name || 'Unknown';\n        const controllerName = this.controllerClass.name || 'Unknown';\n\n        for (const [methodName, endpointPath] of Object.entries(endpoints)) {\n            // Validate controller implements this method\n            if (typeof this.controllerClass.prototype[methodName] !== 'function') {\n                throw new Error(\n                    `Controller ${controllerName} must implement method ${methodName} from API ${apiName}`,\n                );\n            }\n\n            // Validate auth decorator exists (class-level or method-level)\n            const authMeta = getAuthMeta(this.apiMetaClass, methodName);\n            if (!authMeta) {\n                throw new Error(\n                    `Endpoint '${methodName}' in ${apiName} has no @Authentication decorator. ` +\n                    `Add @Authentication(new AuthenticationConfig(...)) to the class or method.`,\n                );\n            }\n\n            const fullPath = basePath + endpointPath;\n            const routeMeta = new RouteMetadata(\n                'POST',\n                fullPath,\n                methodName,\n                controllerName,\n                authMeta,\n            );\n\n            routeBuilder.addRoute(new RouteDefinition(routeMeta, this.controllerClass, controllerFilepath));\n        }\n    }\n\n    /**\n     * Get the filepath of the controller source file.\n     * Uses a heuristic based on the controller class name.\n     */\n    private getControllerFilepath(): string | undefined {\n        // Check for explicit @SourceFile decorator metadata\n        const filepath = Reflect.getMetadata(\n            ROUTING_METADATA_KEYS.SOURCE_FILEPATH,\n            this.controllerClass,\n        );\n        if (filepath) {\n            return filepath;\n        }\n\n        // Fallback to class name pattern\n        const className = this.controllerClass.name;\n        return className ? `**/${className}.ts` : undefined;\n    }\n\n    /**\n     * Get auth metadata for a specific method, falling back to class-level.\n     */\n    getAuthMetaForMethod(methodName: string): AuthMeta | undefined {\n        return getAuthMeta(this.apiMetaClass, methodName);\n    }\n\n    /**\n     * Get the API interface class.\n     */\n    getApiClass(): ClassType<TApi> {\n        return this.apiMetaClass;\n    }\n\n    /**\n     * Get the controller class.\n     */\n    getControllerClass(): ClassType<TController> {\n        return this.controllerClass;\n    }\n}\n"]}
+{"version":3,"file":"ApiRoutingFactory.js","sourceRoot":"","sources":["../../../../../packages/http/http-routing/src/ApiRoutingFactory.ts"],"names":[],"mappings":"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","sourcesContent":["import { Routes, RouteBuilder, RouteDefinition } from './WebAppMeta';\nimport { isApiPath, getApiPath, getEndpoints, getAuthMeta, RouteMetadata, AuthMeta } from '@webpieces/http-api';\nimport 'reflect-metadata';\nimport { ROUTING_METADATA_KEYS } from './decorators';\n\n/**\n * Type representing a class constructor (abstract or concrete).\n */\n// webpieces-disable no-any-unknown -- generic type alias requires unconstrained default\nexport type ClassType<T = unknown> = Function & { prototype: T };\n\n/**\n * ApiRoutingFactory - Automatically wire API interfaces to controllers.\n * Reads @ApiPath/@Endpoint decorators from an API prototype class and\n * registers POST routes for each endpoint.\n *\n * Replaces the old RESTApiRoutes class.\n *\n * Usage:\n * ```typescript\n * // In your ServerMeta:\n * getRoutes(): Routes[] {\n *   return [\n *     new ApiRoutingFactory(SaveApi, SaveController),\n *   ];\n * }\n * ```\n */\n// webpieces-disable no-any-unknown -- generic class requires unconstrained default type params\nexport class ApiRoutingFactory<TApi = unknown, TController extends TApi = TApi> implements Routes {\n    private apiMetaClass: ClassType<TApi>;\n    private controllerClass: ClassType<TController>;\n\n    /**\n     * @param apiMetaClass - The API prototype class with @ApiPath/@Endpoint decorators\n     * @param controllerClass - The controller class that implements the API\n     */\n    constructor(apiMetaClass: ClassType<TApi>, controllerClass: ClassType<TController>) {\n        this.apiMetaClass = apiMetaClass;\n        this.controllerClass = controllerClass;\n\n        // Validate that apiMetaClass is marked with @ApiPath\n        if (!isApiPath(apiMetaClass)) {\n            const className = apiMetaClass.name || 'Unknown';\n            throw new Error(`Class ${className} must be decorated with @ApiPath()`);\n        }\n\n        // Validate that controllerClass actually extends apiMetaClass.\n        // TypeScript's structural typing won't catch a missing `extends` here, so we check\n        // the runtime prototype chain. Without this, a controller can silently drift from\n        // the API contract (wrong method names, wrong signatures) and only fail later as a\n        // confusing routing or method-not-found error.\n        const apiName = apiMetaClass.name || 'Unknown';\n        const controllerName = controllerClass.name || 'Unknown';\n        if (!(apiMetaClass.prototype as object).isPrototypeOf(controllerClass.prototype as object)) {\n            throw new Error(\n                `Controller ${controllerName} must extend ${apiName}. ` +\n                `Change the class declaration to: ` +\n                `'export class ${controllerName} extends ${apiName} { ... }'`,\n            );\n        }\n\n    }\n\n    /**\n     * Configure routes by reading @ApiPath + @Endpoint metadata.\n     * Validates controller methods and auth decorators in single loop.\n     */\n    configure(routeBuilder: RouteBuilder): void {\n        const basePath = getApiPath(this.apiMetaClass)!;\n        const endpoints = getEndpoints(this.apiMetaClass) || {};\n        const controllerFilepath = this.getControllerFilepath();\n        const apiName = this.apiMetaClass.name || 'Unknown';\n        const controllerName = this.controllerClass.name || 'Unknown';\n\n        for (const [methodName, endpointPath] of Object.entries(endpoints)) {\n            // Validate controller implements this method\n            if (typeof this.controllerClass.prototype[methodName] !== 'function') {\n                throw new Error(\n                    `Controller ${controllerName} must implement method ${methodName} from API ${apiName}`,\n                );\n            }\n\n            // Validate auth decorator exists (class-level or method-level)\n            const authMeta = getAuthMeta(this.apiMetaClass, methodName);\n            if (!authMeta) {\n                throw new Error(\n                    `Endpoint '${methodName}' in ${apiName} has no @Authentication decorator. ` +\n                    `Add @Authentication(new AuthenticationConfig(...)) to the class or method.`,\n                );\n            }\n\n            const fullPath = basePath + endpointPath;\n            const routeMeta = new RouteMetadata(\n                'POST',\n                fullPath,\n                methodName,\n                controllerName,\n                authMeta,\n            );\n\n            routeBuilder.addRoute(new RouteDefinition(routeMeta, this.controllerClass, controllerFilepath));\n        }\n    }\n\n    /**\n     * Get the filepath of the controller source file.\n     * Uses a heuristic based on the controller class name.\n     */\n    private getControllerFilepath(): string | undefined {\n        // Check for explicit @SourceFile decorator metadata\n        const filepath = Reflect.getMetadata(\n            ROUTING_METADATA_KEYS.SOURCE_FILEPATH,\n            this.controllerClass,\n        );\n        if (filepath) {\n            return filepath;\n        }\n\n        // Fallback to class name pattern\n        const className = this.controllerClass.name;\n        return className ? `**/${className}.ts` : undefined;\n    }\n\n    /**\n     * Get auth metadata for a specific method, falling back to class-level.\n     */\n    getAuthMetaForMethod(methodName: string): AuthMeta | undefined {\n        return getAuthMeta(this.apiMetaClass, methodName);\n    }\n\n    /**\n     * Get the API interface class.\n     */\n    getApiClass(): ClassType<TApi> {\n        return this.apiMetaClass;\n    }\n\n    /**\n     * Get the controller class.\n     */\n    getControllerClass(): ClassType<TController> {\n        return this.controllerClass;\n    }\n}\n"]}

package/src/MethodMeta.js

@@ -14,6 +14,46 @@ exports.MethodMeta = void 0;
  * - metadata: Request-scoped data for filters to communicate
  */
 class MethodMeta {
+    /**
+     * Route metadata (httpMethod, path, methodName, parameterTypes)
+     */
+    routeMeta;
+    /**
+     * HTTP headers from the request.
+     * Map of header name (lowercase) -> array of values.
+     *
+     * HTTP spec allows multiple values for same header name,
+     * so we store as string[] (even though most headers have single value).
+     *
+     * LIFECYCLE:
+     * 1. Set by ExpressWrapper BEFORE filter chain executes
+     * 2. ContextFilter (priority 2000) transfers headers to RequestContext
+     * 3. ContextFilter CLEARS this field (sets to undefined) after transfer
+     * 4. ALL FILTERS AFTER ContextFilter will see this as UNDEFINED
+     *
+     * IMPORTANT: Downstream filters should NOT read from requestHeaders!
+     * Instead, use RequestContext.getHeader() to read headers after ContextFilter.
+     *
+     * Example (correct usage in downstream filters):
+     * ```typescript
+     * const requestId = RequestContext.getHeader(WebpiecesCoreHeaders.REQUEST_ID);
+     * ```
+     */
+    requestHeaders;
+    /**
+     * The deserialized request DTO.
+     */
+    requestDto;
+    /**
+     * Auth metadata from @Public/@Authenticated/@Roles decorators.
+     * Populated by ApiRoutingFactory so filters can read auth requirements.
+     */
+    authMeta;
+    /**
+     * Additional metadata for storing request-scoped data.
+     * Used by filters to pass data to other filters/controllers.
+     */
+    metadata;
     constructor(routeMeta, requestHeaders, requestDto, metadata, authMeta) {
         this.routeMeta = routeMeta;
         this.requestHeaders = requestHeaders;

package/src/MethodMeta.js.map

@@ -1 +1 @@
-{"version":3,"file":"MethodMeta.js","sourceRoot":"","sources":["../../../../../packages/http/http-routing/src/MethodMeta.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;GAWG;AACH,MAAa,UAAU;IA8CnB,YACI,SAAwB,EACxB,cAAsC,EACtC,UAAoB,EACpB,QAA+B,EAC/B,QAAmB;QAEnB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;QACrC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,QAAQ,IAAI,IAAI,GAAG,EAAE,CAAC;QACtC,IAAI,CAAC,QAAQ,GAAG,QAAQ,IAAI,SAAS,CAAC,QAAQ,CAAC;IACnD,CAAC;IAED;;OAEG;IACH,IAAI,UAAU;QACV,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACJ,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,IAAI,UAAU;QACV,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC;IACrC,CAAC;CACJ;AAhFD,gCAgFC","sourcesContent":["import { RouteMetadata, AuthMeta } from '@webpieces/http-api';\n\n/**\n * Metadata about the method being invoked.\n * Passed to filters and contains request information.\n *\n * MethodMeta is DTO-only - it does NOT contain Express req/res directly.\n *\n * Fields:\n * - routeMeta: Static route information (httpMethod, path, methodName)\n * - requestHeaders: HTTP headers from the request (NEW)\n * - requestDto: The deserialized request body\n * - metadata: Request-scoped data for filters to communicate\n */\nexport class MethodMeta {\n    /**\n     * Route metadata (httpMethod, path, methodName, parameterTypes)\n     */\n    routeMeta: RouteMetadata;\n\n    /**\n     * HTTP headers from the request.\n     * Map of header name (lowercase) -> array of values.\n     *\n     * HTTP spec allows multiple values for same header name,\n     * so we store as string[] (even though most headers have single value).\n     *\n     * LIFECYCLE:\n     * 1. Set by ExpressWrapper BEFORE filter chain executes\n     * 2. ContextFilter (priority 2000) transfers headers to RequestContext\n     * 3. ContextFilter CLEARS this field (sets to undefined) after transfer\n     * 4. ALL FILTERS AFTER ContextFilter will see this as UNDEFINED\n     *\n     * IMPORTANT: Downstream filters should NOT read from requestHeaders!\n     * Instead, use RequestContext.getHeader() to read headers after ContextFilter.\n     *\n     * Example (correct usage in downstream filters):\n     * ```typescript\n     * const requestId = RequestContext.getHeader(WebpiecesCoreHeaders.REQUEST_ID);\n     * ```\n     */\n    public requestHeaders?: Map<string, string[]>;\n\n    /**\n     * The deserialized request DTO.\n     */\n    requestDto?: unknown;\n\n    /**\n     * Auth metadata from @Public/@Authenticated/@Roles decorators.\n     * Populated by ApiRoutingFactory so filters can read auth requirements.\n     */\n    authMeta?: AuthMeta;\n\n    /**\n     * Additional metadata for storing request-scoped data.\n     * Used by filters to pass data to other filters/controllers.\n     */\n    metadata: Map<string, unknown>;\n\n    constructor(\n        routeMeta: RouteMetadata,\n        requestHeaders?: Map<string, string[]>,\n        requestDto?: unknown,\n        metadata?: Map<string, unknown>,\n        authMeta?: AuthMeta,\n    ) {\n        this.routeMeta = routeMeta;\n        this.requestHeaders = requestHeaders;\n        this.requestDto = requestDto;\n        this.metadata = metadata ?? new Map();\n        this.authMeta = authMeta ?? routeMeta.authMeta;\n    }\n\n    /**\n     * Get the HTTP method (convenience accessor).\n     */\n    get httpMethod(): string {\n        return this.routeMeta.httpMethod;\n    }\n\n    /**\n     * Get the request path (convenience accessor).\n     */\n    get path(): string {\n        return this.routeMeta.path;\n    }\n\n    /**\n     * Get the method name (convenience accessor).\n     */\n    get methodName(): string {\n        return this.routeMeta.methodName;\n    }\n}\n"]}
+{"version":3,"file":"MethodMeta.js","sourceRoot":"","sources":["../../../../../packages/http/http-routing/src/MethodMeta.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;GAWG;AACH,MAAa,UAAU;IACnB;;OAEG;IACH,SAAS,CAAgB;IAEzB;;;;;;;;;;;;;;;;;;;;OAoBG;IACI,cAAc,CAAyB;IAE9C;;OAEG;IACH,UAAU,CAAW;IAErB;;;OAGG;IACH,QAAQ,CAAY;IAEpB;;;OAGG;IACH,QAAQ,CAAuB;IAE/B,YACI,SAAwB,EACxB,cAAsC,EACtC,UAAoB,EACpB,QAA+B,EAC/B,QAAmB;QAEnB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;QACrC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,QAAQ,IAAI,IAAI,GAAG,EAAE,CAAC;QACtC,IAAI,CAAC,QAAQ,GAAG,QAAQ,IAAI,SAAS,CAAC,QAAQ,CAAC;IACnD,CAAC;IAED;;OAEG;IACH,IAAI,UAAU;QACV,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACJ,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,IAAI,UAAU;QACV,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC;IACrC,CAAC;CACJ;AAhFD,gCAgFC","sourcesContent":["import { RouteMetadata, AuthMeta } from '@webpieces/http-api';\n\n/**\n * Metadata about the method being invoked.\n * Passed to filters and contains request information.\n *\n * MethodMeta is DTO-only - it does NOT contain Express req/res directly.\n *\n * Fields:\n * - routeMeta: Static route information (httpMethod, path, methodName)\n * - requestHeaders: HTTP headers from the request (NEW)\n * - requestDto: The deserialized request body\n * - metadata: Request-scoped data for filters to communicate\n */\nexport class MethodMeta {\n    /**\n     * Route metadata (httpMethod, path, methodName, parameterTypes)\n     */\n    routeMeta: RouteMetadata;\n\n    /**\n     * HTTP headers from the request.\n     * Map of header name (lowercase) -> array of values.\n     *\n     * HTTP spec allows multiple values for same header name,\n     * so we store as string[] (even though most headers have single value).\n     *\n     * LIFECYCLE:\n     * 1. Set by ExpressWrapper BEFORE filter chain executes\n     * 2. ContextFilter (priority 2000) transfers headers to RequestContext\n     * 3. ContextFilter CLEARS this field (sets to undefined) after transfer\n     * 4. ALL FILTERS AFTER ContextFilter will see this as UNDEFINED\n     *\n     * IMPORTANT: Downstream filters should NOT read from requestHeaders!\n     * Instead, use RequestContext.getHeader() to read headers after ContextFilter.\n     *\n     * Example (correct usage in downstream filters):\n     * ```typescript\n     * const requestId = RequestContext.getHeader(WebpiecesCoreHeaders.REQUEST_ID);\n     * ```\n     */\n    public requestHeaders?: Map<string, string[]>;\n\n    /**\n     * The deserialized request DTO.\n     */\n    requestDto?: unknown;\n\n    /**\n     * Auth metadata from @Public/@Authenticated/@Roles decorators.\n     * Populated by ApiRoutingFactory so filters can read auth requirements.\n     */\n    authMeta?: AuthMeta;\n\n    /**\n     * Additional metadata for storing request-scoped data.\n     * Used by filters to pass data to other filters/controllers.\n     */\n    metadata: Map<string, unknown>;\n\n    constructor(\n        routeMeta: RouteMetadata,\n        requestHeaders?: Map<string, string[]>,\n        requestDto?: unknown,\n        metadata?: Map<string, unknown>,\n        authMeta?: AuthMeta,\n    ) {\n        this.routeMeta = routeMeta;\n        this.requestHeaders = requestHeaders;\n        this.requestDto = requestDto;\n        this.metadata = metadata ?? new Map();\n        this.authMeta = authMeta ?? routeMeta.authMeta;\n    }\n\n    /**\n     * Get the HTTP method (convenience accessor).\n     */\n    get httpMethod(): string {\n        return this.routeMeta.httpMethod;\n    }\n\n    /**\n     * Get the request path (convenience accessor).\n     */\n    get path(): string {\n        return this.routeMeta.path;\n    }\n\n    /**\n     * Get the method name (convenience accessor).\n     */\n    get methodName(): string {\n        return this.routeMeta.methodName;\n    }\n}\n"]}

package/src/RouteBuilderImpl.js

@@ -11,6 +11,8 @@ const FilterMatcher_1 = require("./FilterMatcher");
  * Stores both the DI-resolved filter and the metadata needed for matching.
  */
 class FilterWithMeta {
+    filter;
+    definition;
     constructor(filter, definition) {
         this.filter = filter;
         this.definition = definition;
@@ -22,6 +24,8 @@ exports.FilterWithMeta = FilterWithMeta;
  * Wraps a resolved controller and method to invoke on each request.
  */
 class RouteHandlerImpl {
+    controller;
+    method;
     constructor(controller, method) {
         this.controller = controller;
         this.method = method;
@@ -42,6 +46,8 @@ exports.RouteHandlerImpl = RouteHandlerImpl;
  * Type safety is maintained through the generic on RouteDefinition at registration time.
  */
 class RouteHandlerWithMeta {
+    invokeControllerHandler;
+    definition;
     constructor(invokeControllerHandler, definition) {
         this.invokeControllerHandler = invokeControllerHandler;
         this.definition = definition;
@@ -65,15 +71,14 @@ exports.RouteHandlerWithMeta = RouteHandlerWithMeta;
  * setContainer() after appContainer is created (late binding pattern).
  */
 let RouteBuilderImpl = class RouteBuilderImpl {
-    constructor() {
-        this.routes = [];
-        this.filterRegistry = [];
-        /**
-         * Map for O(1) route lookup by method:path.
-         * Used by both addRoute() and createRouteInvoker() for fast route access.
-         */
-        this.routeMap = new Map();
-    }
+    routes = [];
+    filterRegistry = [];
+    container;
+    /**
+     * Map for O(1) route lookup by method:path.
+     * Used by both addRoute() and createRouteInvoker() for fast route access.
+     */
+    routeMap = new Map();
     /**
      * Create route key for consistent lookup.
      * Key format: "${METHOD}:${path}" (e.g., "POST:/search/item")
@@ -169,6 +174,10 @@ let RouteBuilderImpl = class RouteBuilderImpl {
     getSortedFilters() {
         return [...this.filterRegistry].sort((a, b) => b.definition.priority - a.definition.priority);
     }
+    /**
+     * Cached filter definitions for lazy route setup.
+     */
+    cachedFilterDefinitions;
     /**
      * Get filter definitions, computing once and caching.
      */

package/src/RouteBuilderImpl.js.map

@@ -1 +1 @@
-{"version":3,"file":"RouteBuilderImpl.js","sourceRoot":"","sources":["../../../../../packages/http/http-routing/src/RouteBuilderImpl.ts"],"names":[],"mappings":"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","sourcesContent":["import { Container, injectable } from 'inversify';\nimport { Request, Response, NextFunction } from 'express';\nimport { RouteBuilder, RouteDefinition, FilterDefinition } from './WebAppMeta';\nimport { provideSingleton } from './decorators';\nimport { RouteHandler } from './RouteHandler';\nimport { MethodMeta } from './MethodMeta';\nimport { WpResponse, Service } from '@webpieces/http-filters';\nimport { FilterMatcher, HttpFilter } from './FilterMatcher';\n\n/**\n * Express route handler function type.\n * Used by wrapExpress to create handlers that Express can call.\n */\nexport type ExpressRouteHandler = (\n    req: Request,\n    res: Response,\n    next: NextFunction,\n) => Promise<void>;\n\n/**\n * FilterWithMeta - Pairs a resolved filter instance with its definition.\n * Stores both the DI-resolved filter and the metadata needed for matching.\n */\nexport class FilterWithMeta {\n    constructor(\n        public filter: HttpFilter,\n        public definition: FilterDefinition,\n    ) {}\n}\n\n/**\n * RouteHandlerImpl - Concrete implementation of RouteHandler.\n * Wraps a resolved controller and method to invoke on each request.\n */\nexport class RouteHandlerImpl<TResult> implements RouteHandler<TResult> {\n    constructor(\n        private controller: Record<string, unknown>,\n        private method: (this: unknown, requestDto?: unknown) => Promise<TResult>,\n    ) {}\n\n    async execute(meta: MethodMeta): Promise<TResult> {\n        // Invoke the method with requestDto from meta\n        // The controller is already resolved - no DI lookup on every request!\n        const result: TResult = await this.method.call(this.controller, meta.requestDto);\n        return result;\n    }\n}\n/**\n * RouteHandlerWithMeta - Pairs a route handler with its definition.\n * Stores both the handler (which wraps the DI-resolved controller) and the route metadata.\n *\n * We use unknown for the generic type since we store different TResult types in the same Map.\n * Type safety is maintained through the generic on RouteDefinition at registration time.\n */\nexport class RouteHandlerWithMeta {\n    constructor(\n        public invokeControllerHandler: RouteHandler<unknown>,\n        public definition: RouteDefinition,\n    ) {}\n}\n\n/**\n * RouteBuilderImpl - Concrete implementation of RouteBuilder interface.\n *\n * Similar to Java WebPieces RouteBuilder, this class is responsible for:\n * 1. Registering routes with their handlers\n * 2. Registering filters with priority\n *\n * This class is explicit (not anonymous) to:\n * - Improve traceability and debugging\n * - Make the code easier to understand\n * - Enable better IDE navigation (Cmd+Click on addRoute works!)\n *\n * DI Pattern: This class is registered in webpiecesContainer via @provideSingleton()\n * but needs appContainer to resolve filters/controllers. The container is set via\n * setContainer() after appContainer is created (late binding pattern).\n */\n@provideSingleton()\n@injectable()\nexport class RouteBuilderImpl implements RouteBuilder {\n    private routes: RouteHandlerWithMeta[] = [];\n    private filterRegistry: Array<FilterWithMeta> = [];\n    private container?: Container;\n\n    /**\n     * Map for O(1) route lookup by method:path.\n     * Used by both addRoute() and createRouteInvoker() for fast route access.\n     */\n    private routeMap: Map<string, RouteHandlerWithMeta> = new Map();\n\n    /**\n     * Create route key for consistent lookup.\n     * Key format: \"${METHOD}:${path}\" (e.g., \"POST:/search/item\")\n     */\n    private createRouteKey(method: string, path: string): string {\n        return `${method.toUpperCase()}:${path}`;\n    }\n\n    /**\n     * Set the DI container used for resolving filters and controllers.\n     * Called by WebpiecesCoreServer after appContainer is created.\n     *\n     * @param container - The application DI container (appContainer)\n     */\n    setContainer(container: Container): void {\n        this.container = container;\n    }\n\n    /**\n     * Register a route with the router.\n     *\n     * Uses createRouteHandlerWithMeta() to create the handler, then stores it\n     * in both the routes array and the routeMap for O(1) lookup.\n     *\n     * @param route - Route definition with controller class and method name\n     */\n    addRoute(route: RouteDefinition): void {\n        const routeWithMeta = this.createRouteHandlerWithMeta(route);\n        this.routes.push(routeWithMeta);\n\n        // Also add to map for O(1) lookup by method:path\n        const key = this.createRouteKey(\n            route.routeMeta.httpMethod,\n            route.routeMeta.path\n        );\n        this.routeMap.set(key, routeWithMeta);\n    }\n\n    /**\n     * Create RouteHandlerWithMeta from a RouteDefinition.\n     *\n     * Resolves controller from DI container ONCE and creates a handler that\n     * invokes the controller method with the request DTO.\n     *\n     * This method is used by:\n     * - addRoute() for production route registration\n     * - createRouteInvoker() for test clients (via createApiClient)\n     *\n     * @param route - Route definition with controller class and method name\n     * @returns RouteHandlerWithMeta containing the handler and route definition\n     */\n    private createRouteHandlerWithMeta<TResult = unknown>(\n        route: RouteDefinition,\n    ): RouteHandlerWithMeta {\n        if (!this.container) {\n            throw new Error('Container not set. Call setContainer() before registering routes.');\n        }\n\n        const routeMeta = route.routeMeta;\n\n        // Resolve controller instance from DI container ONCE (not on every request!)\n        const controller = this.container.get(route.controllerClass) as Record<string, unknown>;\n\n        // Get the controller method\n        const method = controller[routeMeta.methodName];\n        if (typeof method !== 'function') {\n            const controllerName = (route.controllerClass as { name?: string }).name || 'Unknown';\n            throw new Error(\n                `Method ${routeMeta.methodName} not found on controller ${controllerName}`,\n            );\n        }\n\n        const handler = new RouteHandlerImpl<TResult>(\n            controller,\n            method as (this: unknown, requestDto?: unknown) => Promise<TResult>\n        );\n\n        // Return handler with route definition\n        return new RouteHandlerWithMeta(\n            handler as RouteHandler<unknown>,\n            route,\n        );\n    }\n\n    /**\n     * Register a filter with the filter chain.\n     *\n     * Resolves the filter from DI container and pairs it with the filter definition.\n     * The definition includes pattern information used for route-specific filtering.\n     *\n     * @param filterDef - Filter definition with priority, filter class, and optional filepath pattern\n     */\n    addFilter(filterDef: FilterDefinition): void {\n        if (!this.container) {\n            throw new Error('Container not set. Call setContainer() before registering filters.');\n        }\n\n        // Resolve filter instance from DI container\n        const filter = this.container.get<HttpFilter>(filterDef.filterClass);\n\n        // Store filter with its definition\n        const filterWithMeta = new FilterWithMeta(filter, filterDef);\n        this.filterRegistry.push(filterWithMeta);\n    }\n\n    /**\n     * Get all registered routes.\n     *\n     * @returns Map of routes with handlers and definitions, keyed by \"METHOD:path\"\n     */\n    getRoutes(): RouteHandlerWithMeta[] {\n        return this.routes;\n    }\n\n    /**\n     * Get all filters sorted by priority (highest priority first).\n     *\n     * @returns Array of FilterWithMeta sorted by priority\n     */\n    getSortedFilters(): Array<FilterWithMeta> {\n        return [...this.filterRegistry].sort(\n            (a, b) => b.definition.priority - a.definition.priority,\n        );\n    }\n\n    /**\n     * Cached filter definitions for lazy route setup.\n     */\n    private cachedFilterDefinitions?: FilterDefinition[];\n\n    /**\n     * Get filter definitions, computing once and caching.\n     */\n    private getFilterDefinitions(): FilterDefinition[] {\n        if (!this.cachedFilterDefinitions) {\n            const sortedFilters = this.getSortedFilters();\n            this.cachedFilterDefinitions = sortedFilters.map((fwm) => {\n                const def = fwm.definition;\n                def.filter = fwm.filter;\n                return def;\n            });\n        }\n        return this.cachedFilterDefinitions;\n    }\n\n    /**\n     * Setup a single route by creating its filter chain.\n     * This is called lazily by createHandler() and getRouteService().\n     *\n     * Creates a Service that wraps the filter chain and controller invocation.\n     * The service is DTO-only and has no Express dependency.\n     *\n     * @param key - Route key in format \"METHOD:path\"\n     * @param routeWithMeta - Route handler with metadata\n     * @returns The service for this route\n     */\n    public createRouteHandler(\n        routeWithMeta: RouteHandlerWithMeta,\n    ): Service<MethodMeta, WpResponse<unknown>> {\n        const route = routeWithMeta.definition;\n        const routeMeta = route.routeMeta;\n\n        console.log(`[RouteBuilder] Setting up route: ${routeMeta.httpMethod} ${routeMeta.path}`);\n\n        // Get cached filter definitions\n        const filterDefinitions = this.getFilterDefinitions();\n\n        // Find matching filters for this route\n        const matchingFilters = FilterMatcher.findMatchingFilters(\n            route.controllerFilepath,\n            filterDefinitions,\n        );\n\n        // Create service that wraps the controller execution\n        const controllerService: Service<MethodMeta, WpResponse<unknown>> = {\n            invoke: async (meta: MethodMeta): Promise<WpResponse<unknown>> => {\n                const result = await routeWithMeta.invokeControllerHandler.execute(meta);\n                return new WpResponse(result);\n            },\n        };\n\n        if (matchingFilters.length === 0) {\n            throw new Error(\"No filters found for route. Check filter definitions as you must have at least ContextFilter\");\n        }\n\n        // Chain filters: highest priority (first in array) should run first (be outermost)\n        // Build from innermost (lowest priority) to outermost (highest priority)\n        // Start with controller, then wrap with filters in reverse priority order\n        let service: Service<MethodMeta, WpResponse<unknown>> = controllerService;\n        for (let i = matchingFilters.length - 1; i >= 0; i--) {\n            service = matchingFilters[i].chainService(service);\n        }\n\n        return service;\n    }\n\n    /**\n     * Create an invoker function for a route (for testing via createApiClient).\n     * Uses routeMap for O(1) lookup, sets up the filter chain ONCE,\n     * and returns a Service that can be called multiple times without\n     * recreating the filter chain.\n     *\n     * This method is called by WebpiecesServer.createApiClient() during proxy setup.\n     * The returned Service is stored as the proxy method and invoked on each call.\n     *\n     * @param method - HTTP method (GET, POST, etc.)\n     * @param path - URL path\n     * @returns A Service that invokes the route\n     */\n    createRouteInvoker(method: string, path: string): Service<MethodMeta, WpResponse<unknown>> {\n        // Use routeMap for O(1) lookup (not linear search!)\n        const key = this.createRouteKey(method, path);\n        const routeWithMeta = this.routeMap.get(key);\n\n        if (!routeWithMeta) {\n            throw new Error(`Route not found: ${method} ${path}`);\n        }\n\n        // Setup filter chain ONCE (not on every invocation!)\n        return this.createRouteHandler(routeWithMeta);\n    }\n}\n"]}
+{"version":3,"file":"RouteBuilderImpl.js","sourceRoot":"","sources":["../../../../../packages/http/http-routing/src/RouteBuilderImpl.ts"],"names":[],"mappings":"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","sourcesContent":["import { Container, injectable } from 'inversify';\nimport { Request, Response, NextFunction } from 'express';\nimport { RouteBuilder, RouteDefinition, FilterDefinition } from './WebAppMeta';\nimport { provideSingleton } from './decorators';\nimport { RouteHandler } from './RouteHandler';\nimport { MethodMeta } from './MethodMeta';\nimport { WpResponse, Service } from '@webpieces/http-filters';\nimport { FilterMatcher, HttpFilter } from './FilterMatcher';\n\n/**\n * Express route handler function type.\n * Used by wrapExpress to create handlers that Express can call.\n */\nexport type ExpressRouteHandler = (\n    req: Request,\n    res: Response,\n    next: NextFunction,\n) => Promise<void>;\n\n/**\n * FilterWithMeta - Pairs a resolved filter instance with its definition.\n * Stores both the DI-resolved filter and the metadata needed for matching.\n */\nexport class FilterWithMeta {\n    constructor(\n        public filter: HttpFilter,\n        public definition: FilterDefinition,\n    ) {}\n}\n\n/**\n * RouteHandlerImpl - Concrete implementation of RouteHandler.\n * Wraps a resolved controller and method to invoke on each request.\n */\nexport class RouteHandlerImpl<TResult> implements RouteHandler<TResult> {\n    constructor(\n        private controller: Record<string, unknown>,\n        private method: (this: unknown, requestDto?: unknown) => Promise<TResult>,\n    ) {}\n\n    async execute(meta: MethodMeta): Promise<TResult> {\n        // Invoke the method with requestDto from meta\n        // The controller is already resolved - no DI lookup on every request!\n        const result: TResult = await this.method.call(this.controller, meta.requestDto);\n        return result;\n    }\n}\n/**\n * RouteHandlerWithMeta - Pairs a route handler with its definition.\n * Stores both the handler (which wraps the DI-resolved controller) and the route metadata.\n *\n * We use unknown for the generic type since we store different TResult types in the same Map.\n * Type safety is maintained through the generic on RouteDefinition at registration time.\n */\nexport class RouteHandlerWithMeta {\n    constructor(\n        public invokeControllerHandler: RouteHandler<unknown>,\n        public definition: RouteDefinition,\n    ) {}\n}\n\n/**\n * RouteBuilderImpl - Concrete implementation of RouteBuilder interface.\n *\n * Similar to Java WebPieces RouteBuilder, this class is responsible for:\n * 1. Registering routes with their handlers\n * 2. Registering filters with priority\n *\n * This class is explicit (not anonymous) to:\n * - Improve traceability and debugging\n * - Make the code easier to understand\n * - Enable better IDE navigation (Cmd+Click on addRoute works!)\n *\n * DI Pattern: This class is registered in webpiecesContainer via @provideSingleton()\n * but needs appContainer to resolve filters/controllers. The container is set via\n * setContainer() after appContainer is created (late binding pattern).\n */\n@provideSingleton()\n@injectable()\nexport class RouteBuilderImpl implements RouteBuilder {\n    private routes: RouteHandlerWithMeta[] = [];\n    private filterRegistry: Array<FilterWithMeta> = [];\n    private container?: Container;\n\n    /**\n     * Map for O(1) route lookup by method:path.\n     * Used by both addRoute() and createRouteInvoker() for fast route access.\n     */\n    private routeMap: Map<string, RouteHandlerWithMeta> = new Map();\n\n    /**\n     * Create route key for consistent lookup.\n     * Key format: \"${METHOD}:${path}\" (e.g., \"POST:/search/item\")\n     */\n    private createRouteKey(method: string, path: string): string {\n        return `${method.toUpperCase()}:${path}`;\n    }\n\n    /**\n     * Set the DI container used for resolving filters and controllers.\n     * Called by WebpiecesCoreServer after appContainer is created.\n     *\n     * @param container - The application DI container (appContainer)\n     */\n    setContainer(container: Container): void {\n        this.container = container;\n    }\n\n    /**\n     * Register a route with the router.\n     *\n     * Uses createRouteHandlerWithMeta() to create the handler, then stores it\n     * in both the routes array and the routeMap for O(1) lookup.\n     *\n     * @param route - Route definition with controller class and method name\n     */\n    addRoute(route: RouteDefinition): void {\n        const routeWithMeta = this.createRouteHandlerWithMeta(route);\n        this.routes.push(routeWithMeta);\n\n        // Also add to map for O(1) lookup by method:path\n        const key = this.createRouteKey(\n            route.routeMeta.httpMethod,\n            route.routeMeta.path\n        );\n        this.routeMap.set(key, routeWithMeta);\n    }\n\n    /**\n     * Create RouteHandlerWithMeta from a RouteDefinition.\n     *\n     * Resolves controller from DI container ONCE and creates a handler that\n     * invokes the controller method with the request DTO.\n     *\n     * This method is used by:\n     * - addRoute() for production route registration\n     * - createRouteInvoker() for test clients (via createApiClient)\n     *\n     * @param route - Route definition with controller class and method name\n     * @returns RouteHandlerWithMeta containing the handler and route definition\n     */\n    private createRouteHandlerWithMeta<TResult = unknown>(\n        route: RouteDefinition,\n    ): RouteHandlerWithMeta {\n        if (!this.container) {\n            throw new Error('Container not set. Call setContainer() before registering routes.');\n        }\n\n        const routeMeta = route.routeMeta;\n\n        // Resolve controller instance from DI container ONCE (not on every request!)\n        const controller = this.container.get(route.controllerClass) as Record<string, unknown>;\n\n        // Get the controller method\n        const method = controller[routeMeta.methodName];\n        if (typeof method !== 'function') {\n            const controllerName = (route.controllerClass as { name?: string }).name || 'Unknown';\n            throw new Error(\n                `Method ${routeMeta.methodName} not found on controller ${controllerName}`,\n            );\n        }\n\n        const handler = new RouteHandlerImpl<TResult>(\n            controller,\n            method as (this: unknown, requestDto?: unknown) => Promise<TResult>\n        );\n\n        // Return handler with route definition\n        return new RouteHandlerWithMeta(\n            handler as RouteHandler<unknown>,\n            route,\n        );\n    }\n\n    /**\n     * Register a filter with the filter chain.\n     *\n     * Resolves the filter from DI container and pairs it with the filter definition.\n     * The definition includes pattern information used for route-specific filtering.\n     *\n     * @param filterDef - Filter definition with priority, filter class, and optional filepath pattern\n     */\n    addFilter(filterDef: FilterDefinition): void {\n        if (!this.container) {\n            throw new Error('Container not set. Call setContainer() before registering filters.');\n        }\n\n        // Resolve filter instance from DI container\n        const filter = this.container.get<HttpFilter>(filterDef.filterClass);\n\n        // Store filter with its definition\n        const filterWithMeta = new FilterWithMeta(filter, filterDef);\n        this.filterRegistry.push(filterWithMeta);\n    }\n\n    /**\n     * Get all registered routes.\n     *\n     * @returns Map of routes with handlers and definitions, keyed by \"METHOD:path\"\n     */\n    getRoutes(): RouteHandlerWithMeta[] {\n        return this.routes;\n    }\n\n    /**\n     * Get all filters sorted by priority (highest priority first).\n     *\n     * @returns Array of FilterWithMeta sorted by priority\n     */\n    getSortedFilters(): Array<FilterWithMeta> {\n        return [...this.filterRegistry].sort(\n            (a, b) => b.definition.priority - a.definition.priority,\n        );\n    }\n\n    /**\n     * Cached filter definitions for lazy route setup.\n     */\n    private cachedFilterDefinitions?: FilterDefinition[];\n\n    /**\n     * Get filter definitions, computing once and caching.\n     */\n    private getFilterDefinitions(): FilterDefinition[] {\n        if (!this.cachedFilterDefinitions) {\n            const sortedFilters = this.getSortedFilters();\n            this.cachedFilterDefinitions = sortedFilters.map((fwm) => {\n                const def = fwm.definition;\n                def.filter = fwm.filter;\n                return def;\n            });\n        }\n        return this.cachedFilterDefinitions;\n    }\n\n    /**\n     * Setup a single route by creating its filter chain.\n     * This is called lazily by createHandler() and getRouteService().\n     *\n     * Creates a Service that wraps the filter chain and controller invocation.\n     * The service is DTO-only and has no Express dependency.\n     *\n     * @param key - Route key in format \"METHOD:path\"\n     * @param routeWithMeta - Route handler with metadata\n     * @returns The service for this route\n     */\n    public createRouteHandler(\n        routeWithMeta: RouteHandlerWithMeta,\n    ): Service<MethodMeta, WpResponse<unknown>> {\n        const route = routeWithMeta.definition;\n        const routeMeta = route.routeMeta;\n\n        console.log(`[RouteBuilder] Setting up route: ${routeMeta.httpMethod} ${routeMeta.path}`);\n\n        // Get cached filter definitions\n        const filterDefinitions = this.getFilterDefinitions();\n\n        // Find matching filters for this route\n        const matchingFilters = FilterMatcher.findMatchingFilters(\n            route.controllerFilepath,\n            filterDefinitions,\n        );\n\n        // Create service that wraps the controller execution\n        const controllerService: Service<MethodMeta, WpResponse<unknown>> = {\n            invoke: async (meta: MethodMeta): Promise<WpResponse<unknown>> => {\n                const result = await routeWithMeta.invokeControllerHandler.execute(meta);\n                return new WpResponse(result);\n            },\n        };\n\n        if (matchingFilters.length === 0) {\n            throw new Error(\"No filters found for route. Check filter definitions as you must have at least ContextFilter\");\n        }\n\n        // Chain filters: highest priority (first in array) should run first (be outermost)\n        // Build from innermost (lowest priority) to outermost (highest priority)\n        // Start with controller, then wrap with filters in reverse priority order\n        let service: Service<MethodMeta, WpResponse<unknown>> = controllerService;\n        for (let i = matchingFilters.length - 1; i >= 0; i--) {\n            service = matchingFilters[i].chainService(service);\n        }\n\n        return service;\n    }\n\n    /**\n     * Create an invoker function for a route (for testing via createApiClient).\n     * Uses routeMap for O(1) lookup, sets up the filter chain ONCE,\n     * and returns a Service that can be called multiple times without\n     * recreating the filter chain.\n     *\n     * This method is called by WebpiecesServer.createApiClient() during proxy setup.\n     * The returned Service is stored as the proxy method and invoked on each call.\n     *\n     * @param method - HTTP method (GET, POST, etc.)\n     * @param path - URL path\n     * @returns A Service that invokes the route\n     */\n    createRouteInvoker(method: string, path: string): Service<MethodMeta, WpResponse<unknown>> {\n        // Use routeMap for O(1) lookup (not linear search!)\n        const key = this.createRouteKey(method, path);\n        const routeWithMeta = this.routeMap.get(key);\n\n        if (!routeWithMeta) {\n            throw new Error(`Route not found: ${method} ${path}`);\n        }\n\n        // Setup filter chain ONCE (not on every invocation!)\n        return this.createRouteHandler(routeWithMeta);\n    }\n}\n"]}

package/src/WebAppMeta.js

@@ -8,6 +8,9 @@ exports.WEBAPP_META_TOKEN = exports.FilterDefinition = exports.RouteDefinition =
  * This provides type safety for the entire request/response cycle.
  */
 class RouteDefinition {
+    routeMeta;
+    controllerClass;
+    controllerFilepath;
     constructor(routeMeta, controllerClass, controllerFilepath) {
         this.routeMeta = routeMeta;
         this.controllerClass = controllerClass;
@@ -26,6 +29,14 @@ exports.RouteDefinition = RouteDefinition;
  * If filepathPattern is not specified, the filter matches all controllers.
  */
 class FilterDefinition {
+    priority;
+    filterClass;
+    filter; // Filter instance (set by RouteBuilder when resolving from DI)
+    /**
+     * Glob pattern to match controller file paths.
+     * If not specified, defaults to matching all controllers.
+     */
+    filepathPattern;
     constructor(priority, filterClass, filepathPattern) {
         this.priority = priority;
         this.filterClass = filterClass;

package/src/WebAppMeta.js.map

@@ -1 +1 @@
-{"version":3,"file":"WebAppMeta.js","sourceRoot":"","sources":["../../../../../packages/http/http-routing/src/WebAppMeta.ts"],"names":[],"mappings":";;;AAuBA;;;;;GAKG;AACH,MAAa,eAAe;IACxB,YACW,SAAwB,EACxB,eAAoB,EACpB,kBAA2B;QAF3B,cAAS,GAAT,SAAS,CAAe;QACxB,oBAAe,GAAf,eAAe,CAAK;QACpB,uBAAkB,GAAlB,kBAAkB,CAAS;IACnC,CAAC;CACP;AAND,0CAMC;AAED;;;;;;;;;GASG;AACH,MAAa,gBAAgB;IAWzB,YAAY,QAAgB,EAAE,WAAgB,EAAE,eAAuB;QACnE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QACvC,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,4BAA4B;IACzD,CAAC;CACJ;AAjBD,4CAiBC;AAuBD;;GAEG;AACU,QAAA,iBAAiB,GAAG,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC","sourcesContent":["import { ContainerModule } from 'inversify';\nimport {RouteMetadata} from \"@webpieces/http-api\";\n\n/**\n * Represents a route configuration that can be registered with the router.\n * Similar to Java WebPieces Routes interface.\n */\nexport interface Routes {\n    /**\n     * Configure routes using the provided RouteBuilder.\n     */\n    configure(routeBuilder: RouteBuilder): void;\n}\n\n/**\n * Builder for registering routes.\n * Will be implemented in http-server package.\n */\nexport interface RouteBuilder {\n    addRoute(route: RouteDefinition): void;\n    addFilter(filter: FilterDefinition): void;\n}\n\n/**\n * Definition of a single route.\n *\n * Generic type parameter TResult represents the return type of the route handler.\n * This provides type safety for the entire request/response cycle.\n */\nexport class RouteDefinition {\n    constructor(\n        public routeMeta: RouteMetadata,\n        public controllerClass: any,\n        public controllerFilepath?: string,\n    ) {}\n}\n\n/**\n * Definition of a filter with priority.\n *\n * Use filepathPattern to scope filters to specific controllers:\n *   - 'src/controllers/admin/**' + '/*.ts' - All admin controllers\n *   - '**' + '/admin/**' - Any file in admin directories\n *   - '**' + '/UserController.ts' - Specific controller file\n *\n * If filepathPattern is not specified, the filter matches all controllers.\n */\nexport class FilterDefinition {\n    priority: number;\n    filterClass: any;\n    filter?: any; // Filter instance (set by RouteBuilder when resolving from DI)\n\n    /**\n     * Glob pattern to match controller file paths.\n     * If not specified, defaults to matching all controllers.\n     */\n    filepathPattern: string;\n\n    constructor(priority: number, filterClass: any, filepathPattern: string) {\n        this.priority = priority;\n        this.filterClass = filterClass;\n        this.filepathPattern = filepathPattern;\n        this.filter = undefined; // Set later by RouteBuilder\n    }\n}\n\n\n/**\n * Main application metadata interface.\n * Similar to Java WebPieces WebAppMeta.\n *\n * This is the entry point that WebpiecesServer calls to configure your application.\n */\nexport interface WebAppMeta {\n    /**\n     * Returns the list of Inversify container modules for dependency injection.\n     * Similar to getGuiceModules() in Java.\n     */\n    getDIModules(): ContainerModule[];\n\n    /**\n     * Returns the list of route configurations.\n     * Similar to getRouteModules() in Java.\n     */\n    getRoutes(): Routes[];\n}\n\n/**\n * DI token for WebAppMeta injection.\n */\nexport const WEBAPP_META_TOKEN = Symbol.for('WebAppMeta');\n"]}
+{"version":3,"file":"WebAppMeta.js","sourceRoot":"","sources":["../../../../../packages/http/http-routing/src/WebAppMeta.ts"],"names":[],"mappings":";;;AAuBA;;;;;GAKG;AACH,MAAa,eAAe;IAEb;IACA;IACA;IAHX,YACW,SAAwB,EACxB,eAAoB,EACpB,kBAA2B;QAF3B,cAAS,GAAT,SAAS,CAAe;QACxB,oBAAe,GAAf,eAAe,CAAK;QACpB,uBAAkB,GAAlB,kBAAkB,CAAS;IACnC,CAAC;CACP;AAND,0CAMC;AAED;;;;;;;;;GASG;AACH,MAAa,gBAAgB;IACzB,QAAQ,CAAS;IACjB,WAAW,CAAM;IACjB,MAAM,CAAO,CAAC,+DAA+D;IAE7E;;;OAGG;IACH,eAAe,CAAS;IAExB,YAAY,QAAgB,EAAE,WAAgB,EAAE,eAAuB;QACnE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QACvC,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,4BAA4B;IACzD,CAAC;CACJ;AAjBD,4CAiBC;AAuBD;;GAEG;AACU,QAAA,iBAAiB,GAAG,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC","sourcesContent":["import { ContainerModule } from 'inversify';\nimport {RouteMetadata} from \"@webpieces/http-api\";\n\n/**\n * Represents a route configuration that can be registered with the router.\n * Similar to Java WebPieces Routes interface.\n */\nexport interface Routes {\n    /**\n     * Configure routes using the provided RouteBuilder.\n     */\n    configure(routeBuilder: RouteBuilder): void;\n}\n\n/**\n * Builder for registering routes.\n * Will be implemented in http-server package.\n */\nexport interface RouteBuilder {\n    addRoute(route: RouteDefinition): void;\n    addFilter(filter: FilterDefinition): void;\n}\n\n/**\n * Definition of a single route.\n *\n * Generic type parameter TResult represents the return type of the route handler.\n * This provides type safety for the entire request/response cycle.\n */\nexport class RouteDefinition {\n    constructor(\n        public routeMeta: RouteMetadata,\n        public controllerClass: any,\n        public controllerFilepath?: string,\n    ) {}\n}\n\n/**\n * Definition of a filter with priority.\n *\n * Use filepathPattern to scope filters to specific controllers:\n *   - 'src/controllers/admin/**' + '/*.ts' - All admin controllers\n *   - '**' + '/admin/**' - Any file in admin directories\n *   - '**' + '/UserController.ts' - Specific controller file\n *\n * If filepathPattern is not specified, the filter matches all controllers.\n */\nexport class FilterDefinition {\n    priority: number;\n    filterClass: any;\n    filter?: any; // Filter instance (set by RouteBuilder when resolving from DI)\n\n    /**\n     * Glob pattern to match controller file paths.\n     * If not specified, defaults to matching all controllers.\n     */\n    filepathPattern: string;\n\n    constructor(priority: number, filterClass: any, filepathPattern: string) {\n        this.priority = priority;\n        this.filterClass = filterClass;\n        this.filepathPattern = filepathPattern;\n        this.filter = undefined; // Set later by RouteBuilder\n    }\n}\n\n\n/**\n * Main application metadata interface.\n * Similar to Java WebPieces WebAppMeta.\n *\n * This is the entry point that WebpiecesServer calls to configure your application.\n */\nexport interface WebAppMeta {\n    /**\n     * Returns the list of Inversify container modules for dependency injection.\n     * Similar to getGuiceModules() in Java.\n     */\n    getDIModules(): ContainerModule[];\n\n    /**\n     * Returns the list of route configurations.\n     * Similar to getRouteModules() in Java.\n     */\n    getRoutes(): Routes[];\n}\n\n/**\n * DI token for WebAppMeta injection.\n */\nexport const WEBAPP_META_TOKEN = Symbol.for('WebAppMeta');\n"]}