@webpieces/http-routing 0.2.15 → 0.2.16

package/package.json

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

package/src/FilterMatcher.d.ts

@@ -0,0 +1,39 @@
+import { Filter, WpResponse } from '@webpieces/http-filters';
+import { MethodMeta } from './MethodMeta';
+import { FilterDefinition } from './WebAppMeta';
+/**
+ * Type alias for HTTP filters that work with MethodMeta and ResponseWrapper.
+ */
+export type HttpFilter = Filter<MethodMeta, WpResponse<unknown>>;
+/**
+ * FilterMatcher - Matches filters to routes based on filepath patterns.
+ * Similar to Java SharedMatchUtil.findMatchingFilters().
+ *
+ * Responsibilities:
+ * 1. Filter based on filepath glob pattern matching
+ * 2. Sort matching filters by priority (higher first)
+ *
+ * Differences from Java:
+ * - Uses glob patterns instead of regex
+ * - Only matches filepaths (no URL path or HTTPS filtering yet)
+ * - Simpler API focused on one responsibility
+ */
+export declare class FilterMatcher {
+    /**
+     * Find filters that match the given controller filepath.
+     *
+     * @param controllerFilepath - The filepath of the controller source file
+     * @param allFilters - All registered filters with their definitions
+     * @returns Array of matching filters, sorted by priority (highest first)
+     */
+    static findMatchingFilters(controllerFilepath: string | undefined, allFilters: Array<FilterDefinition>): HttpFilter[];
+    /**
+     * Normalize a controller filepath for consistent matching.
+     * - Converts backslashes to forward slashes (Windows compatibility)
+     * - Removes leading './'
+     *
+     * @param filepath - Raw filepath
+     * @returns Normalized filepath
+     */
+    static normalizeFilepath(filepath: string): string;
+}

package/src/FilterMatcher.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilterMatcher = void 0;
+const minimatch_1 = require("minimatch");
+/**
+ * FilterMatcher - Matches filters to routes based on filepath patterns.
+ * Similar to Java SharedMatchUtil.findMatchingFilters().
+ *
+ * Responsibilities:
+ * 1. Filter based on filepath glob pattern matching
+ * 2. Sort matching filters by priority (higher first)
+ *
+ * Differences from Java:
+ * - Uses glob patterns instead of regex
+ * - Only matches filepaths (no URL path or HTTPS filtering yet)
+ * - Simpler API focused on one responsibility
+ */
+class FilterMatcher {
+    /**
+     * Find filters that match the given controller filepath.
+     *
+     * @param controllerFilepath - The filepath of the controller source file
+     * @param allFilters - All registered filters with their definitions
+     * @returns Array of matching filters, sorted by priority (highest first)
+     */
+    static findMatchingFilters(controllerFilepath, allFilters) {
+        const matchingFilters = [];
+        for (const definition of allFilters) {
+            const pattern = definition.filepathPattern;
+            const filter = definition.filter;
+            // Special case: '*' matches all controllers (global filter)
+            if (pattern === '*') {
+                matchingFilters.push({ filter, priority: definition.priority });
+                continue;
+            }
+            // If no filepath available, only match wildcard patterns
+            if (!controllerFilepath) {
+                if (pattern === '**/*') {
+                    matchingFilters.push({ filter, priority: definition.priority });
+                }
+                continue;
+            }
+            // Normalize filepath for consistent matching
+            const normalizedPath = FilterMatcher.normalizeFilepath(controllerFilepath);
+            // Match using minimatch
+            if ((0, minimatch_1.minimatch)(normalizedPath, pattern)) {
+                matchingFilters.push({ filter, priority: definition.priority });
+            }
+        }
+        // Sort by priority (highest first)
+        matchingFilters.sort((a, b) => b.priority - a.priority);
+        return matchingFilters.map((item) => item.filter);
+    }
+    /**
+     * Normalize a controller filepath for consistent matching.
+     * - Converts backslashes to forward slashes (Windows compatibility)
+     * - Removes leading './'
+     *
+     * @param filepath - Raw filepath
+     * @returns Normalized filepath
+     */
+    static normalizeFilepath(filepath) {
+        return filepath
+            .replace(/\\/g, '/') // Windows backslashes to forward slashes
+            .replace(/^\.\//, ''); // Remove leading './'
+    }
+}
+exports.FilterMatcher = FilterMatcher;
+//# sourceMappingURL=FilterMatcher.js.map

package/src/FilterMatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FilterMatcher.js","sourceRoot":"","sources":["../../../../../packages/http/http-routing/src/FilterMatcher.ts"],"names":[],"mappings":";;;AAGA,yCAAsC;AAOtC;;;;;;;;;;;;GAYG;AACH,MAAa,aAAa;IACtB;;;;;;OAMG;IACH,MAAM,CAAC,mBAAmB,CACtB,kBAAsC,EACtC,UAAmC;QAEnC,MAAM,eAAe,GAAoD,EAAE,CAAC;QAE5E,KAAK,MAAM,UAAU,IAAI,UAAU,EAAE,CAAC;YAClC,MAAM,OAAO,GAAG,UAAU,CAAC,eAAe,CAAC;YAC3C,MAAM,MAAM,GAAG,UAAU,CAAC,MAAoB,CAAC;YAE/C,4DAA4D;YAC5D,IAAI,OAAO,KAAK,GAAG,EAAE,CAAC;gBAClB,eAAe,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC;gBAChE,SAAS;YACb,CAAC;YAED,yDAAyD;YACzD,IAAI,CAAC,kBAAkB,EAAE,CAAC;gBACtB,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;oBACrB,eAAe,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC;gBACpE,CAAC;gBACD,SAAS;YACb,CAAC;YAED,6CAA6C;YAC7C,MAAM,cAAc,GAAG,aAAa,CAAC,iBAAiB,CAAC,kBAAkB,CAAC,CAAC;YAE3E,wBAAwB;YACxB,IAAI,IAAA,qBAAS,EAAC,cAAc,EAAE,OAAO,CAAC,EAAE,CAAC;gBACrC,eAAe,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC;YACpE,CAAC;QACL,CAAC;QAED,mCAAmC;QACnC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;QAExD,OAAO,eAAe,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACtD,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,iBAAiB,CAAC,QAAgB;QACrC,OAAO,QAAQ;aACV,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,yCAAyC;aAC7D,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,sBAAsB;IACrD,CAAC;CACJ;AA5DD,sCA4DC","sourcesContent":["import { Filter, WpResponse } from '@webpieces/http-filters';\nimport { MethodMeta } from './MethodMeta';\nimport { FilterDefinition } from './WebAppMeta';\nimport { minimatch } from 'minimatch';\n\n/**\n * Type alias for HTTP filters that work with MethodMeta and ResponseWrapper.\n */\nexport type HttpFilter = Filter<MethodMeta, WpResponse<unknown>>;\n\n/**\n * FilterMatcher - Matches filters to routes based on filepath patterns.\n * Similar to Java SharedMatchUtil.findMatchingFilters().\n *\n * Responsibilities:\n * 1. Filter based on filepath glob pattern matching\n * 2. Sort matching filters by priority (higher first)\n *\n * Differences from Java:\n * - Uses glob patterns instead of regex\n * - Only matches filepaths (no URL path or HTTPS filtering yet)\n * - Simpler API focused on one responsibility\n */\nexport class FilterMatcher {\n    /**\n     * Find filters that match the given controller filepath.\n     *\n     * @param controllerFilepath - The filepath of the controller source file\n     * @param allFilters - All registered filters with their definitions\n     * @returns Array of matching filters, sorted by priority (highest first)\n     */\n    static findMatchingFilters(\n        controllerFilepath: string | undefined,\n        allFilters: Array<FilterDefinition>,\n    ): HttpFilter[] {\n        const matchingFilters: Array<{ filter: HttpFilter; priority: number }> = [];\n\n        for (const definition of allFilters) {\n            const pattern = definition.filepathPattern;\n            const filter = definition.filter as HttpFilter;\n\n            // Special case: '*' matches all controllers (global filter)\n            if (pattern === '*') {\n                matchingFilters.push({ filter, priority: definition.priority });\n                continue;\n            }\n\n            // If no filepath available, only match wildcard patterns\n            if (!controllerFilepath) {\n                if (pattern === '**/*') {\n                    matchingFilters.push({ filter, priority: definition.priority });\n                }\n                continue;\n            }\n\n            // Normalize filepath for consistent matching\n            const normalizedPath = FilterMatcher.normalizeFilepath(controllerFilepath);\n\n            // Match using minimatch\n            if (minimatch(normalizedPath, pattern)) {\n                matchingFilters.push({ filter, priority: definition.priority });\n            }\n        }\n\n        // Sort by priority (highest first)\n        matchingFilters.sort((a, b) => b.priority - a.priority);\n\n        return matchingFilters.map((item) => item.filter);\n    }\n\n    /**\n     * Normalize a controller filepath for consistent matching.\n     * - Converts backslashes to forward slashes (Windows compatibility)\n     * - Removes leading './'\n     *\n     * @param filepath - Raw filepath\n     * @returns Normalized filepath\n     */\n    static normalizeFilepath(filepath: string): string {\n        return filepath\n            .replace(/\\\\/g, '/') // Windows backslashes to forward slashes\n            .replace(/^\\.\\//, ''); // Remove leading './'\n    }\n}\n"]}

package/src/MethodMeta.d.ts

@@ -0,0 +1,41 @@
+import { RouteMetadata } from '@webpieces/http-api';
+/**
+ * Metadata about the method being invoked.
+ * Passed to filters and contains request information.
+ *
+ * MethodMeta is DTO-only - it does NOT contain Express req/res.
+ * Express objects are handled by the Express layer (wrapExpress, jsonTranslator).
+ *
+ * Fields:
+ * - routeMeta: Static route information (httpMethod, path, methodName)
+ * - requestDto: The deserialized request body
+ * - metadata: Request-scoped data for filters to communicate
+ */
+export declare class MethodMeta {
+    /**
+     * Route metadata (httpMethod, path, methodName, parameterTypes)
+     */
+    routeMeta: RouteMetadata;
+    /**
+     * The deserialized request DTO.
+     */
+    requestDto?: unknown;
+    /**
+     * Additional metadata for storing request-scoped data.
+     * Used by filters to pass data to other filters/controllers.
+     */
+    metadata: Map<string, unknown>;
+    constructor(routeMeta: RouteMetadata, requestDto?: unknown, metadata?: Map<string, unknown>);
+    /**
+     * Get the HTTP method (convenience accessor).
+     */
+    get httpMethod(): string;
+    /**
+     * Get the request path (convenience accessor).
+     */
+    get path(): string;
+    /**
+     * Get the method name (convenience accessor).
+     */
+    get methodName(): string;
+}

package/src/MethodMeta.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MethodMeta = void 0;
+/**
+ * Metadata about the method being invoked.
+ * Passed to filters and contains request information.
+ *
+ * MethodMeta is DTO-only - it does NOT contain Express req/res.
+ * Express objects are handled by the Express layer (wrapExpress, jsonTranslator).
+ *
+ * Fields:
+ * - routeMeta: Static route information (httpMethod, path, methodName)
+ * - requestDto: The deserialized request body
+ * - metadata: Request-scoped data for filters to communicate
+ */
+class MethodMeta {
+    constructor(routeMeta, requestDto, metadata) {
+        this.routeMeta = routeMeta;
+        this.requestDto = requestDto;
+        this.metadata = metadata ?? new Map();
+    }
+    /**
+     * Get the HTTP method (convenience accessor).
+     */
+    get httpMethod() {
+        return this.routeMeta.httpMethod;
+    }
+    /**
+     * Get the request path (convenience accessor).
+     */
+    get path() {
+        return this.routeMeta.path;
+    }
+    /**
+     * Get the method name (convenience accessor).
+     */
+    get methodName() {
+        return this.routeMeta.methodName;
+    }
+}
+exports.MethodMeta = MethodMeta;
+//# sourceMappingURL=MethodMeta.js.map

package/src/MethodMeta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MethodMeta.js","sourceRoot":"","sources":["../../../../../packages/http/http-routing/src/MethodMeta.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;GAWG;AACH,MAAa,UAAU;IAiBnB,YACI,SAAwB,EACxB,UAAoB,EACpB,QAA+B;QAE/B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,QAAQ,IAAI,IAAI,GAAG,EAAE,CAAC;IAC1C,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;AA/CD,gCA+CC","sourcesContent":["import { RouteMetadata } 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.\n * Express objects are handled by the Express layer (wrapExpress, jsonTranslator).\n *\n * Fields:\n * - routeMeta: Static route information (httpMethod, path, methodName)\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     * The deserialized request DTO.\n     */\n    requestDto?: unknown;\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        requestDto?: unknown,\n        metadata?: Map<string, unknown>,\n    ) {\n        this.routeMeta = routeMeta;\n        this.requestDto = requestDto;\n        this.metadata = metadata ?? new Map();\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/RESTApiRoutes.d.ts

@@ -1,4 +1,4 @@
-import { Routes, RouteBuilder } from '@webpieces/core-meta';
+import { Routes, RouteBuilder } from './WebAppMeta';
 /**
  * Type representing a class constructor (abstract or concrete).
  */

package/src/RESTApiRoutes.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RESTApiRoutes = void 0;
-const core_meta_1 = require("@webpieces/core-meta");
+const WebAppMeta_1 = require("./WebAppMeta");
 const http_api_1 = require("@webpieces/http-api");
 const decorators_1 = require("./decorators");
 /**
@@ -82,11 +82,13 @@ class RESTApiRoutes {
             const apiName = this.apiMetaClass.name || 'Unknown';
             throw new Error(`Method ${route.methodName} in ${apiName} must have both @HttpMethod and @Path decorators`);
         }
+        // Set controller class name for logging
+        route.controllerClassName = this.controllerClass.name;
         // Extract controller filepath for filter matching
         const controllerFilepath = this.getControllerFilepath();
         // Pass controller class and method name to RouteBuilder
         // RouteBuilder will resolve the controller from DI and create the handler
-        routeBuilder.addRoute(new core_meta_1.RouteDefinition(route, this.controllerClass, controllerFilepath));
+        routeBuilder.addRoute(new WebAppMeta_1.RouteDefinition(route, this.controllerClass, controllerFilepath));
     }
     /**
      * Get the filepath of the controller source file.

package/src/RESTApiRoutes.js.map

@@ -1 +1 @@
-{"version":3,"file":"RESTApiRoutes.js","sourceRoot":"","sources":["../../../../../packages/http/http-routing/src/RESTApiRoutes.ts"],"names":[],"mappings":"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","sourcesContent":["import { Routes, RouteBuilder, RouteDefinition } from '@webpieces/core-meta';\nimport { getRoutes, isApiInterface, RouteMetadata } from '@webpieces/http-api';\nimport { ROUTING_METADATA_KEYS } from './decorators';\n\n/**\n * Type representing a class constructor (abstract or concrete).\n */\nexport type ClassType<T = any> = Function & { prototype: T };\n\n/**\n * RESTApiRoutes - Automatically wire API interfaces to controllers.\n * Similar to Java WebPieces RESTApiRoutes.\n *\n * This class uses reflection (reflect-metadata) to read decorators from\n * an API interface class and automatically register routes that dispatch\n * to the corresponding controller methods.\n *\n * Usage:\n * ```typescript\n * // In your ServerMeta:\n * getRoutes(): Routes[] {\n *   return [\n *     new RESTApiRoutes(SaveApiPrototype, SaveController),\n *     // ... more routes\n *   ];\n * }\n * ```\n *\n * The API interface and controller must follow this pattern:\n * - API interface class has @ApiInterface() decorator\n * - Methods have @Post()/@Get()/etc and @Path() decorators\n * - Controller class implements the same interface\n * - Controller class has @Controller() decorator\n *\n * Type Parameters:\n * - TApi: The API prototype class type (abstract class with decorators)\n * - TController: The controller class type (must extend TApi)\n */\nexport class RESTApiRoutes<TApi = any, TController extends TApi = any> implements Routes {\n    private apiMetaClass: ClassType<TApi>;\n    private controllerClass: ClassType<TController>;\n\n    /**\n     * Create a new RESTApiRoutes.\n     *\n     * @param apiMetaClass - The API interface class with decorators (e.g., SaveApiPrototype)\n     * @param controllerClass - The controller class that implements the API (e.g., SaveController)\n     */\n    constructor(apiMetaClass: ClassType<TApi>, controllerClass: ClassType<TController>) {\n        this.apiMetaClass = apiMetaClass;\n        this.controllerClass = controllerClass;\n\n        // Validate that apiMetaClass is marked as @ApiInterface\n        if (!isApiInterface(apiMetaClass)) {\n            const className = (apiMetaClass as any).name || 'Unknown';\n            throw new Error(`Class ${className} must be decorated with @ApiInterface()`);\n        }\n\n        // Validate that controllerClass implements the methods from apiMetaClass\n        this.validateControllerImplementsApi();\n    }\n\n    /**\n     * Validate that the controller implements all methods from the API interface.\n     */\n    private validateControllerImplementsApi(): void {\n        const routes = getRoutes(this.apiMetaClass);\n\n        for (const route of routes) {\n            const controllerPrototype = this.controllerClass.prototype;\n\n            if (typeof controllerPrototype[route.methodName] !== 'function') {\n                const controllerName = (this.controllerClass as any).name || 'Unknown';\n                const apiName = (this.apiMetaClass as any).name || 'Unknown';\n                throw new Error(\n                    `Controller ${controllerName} must implement method ${route.methodName} from API ${apiName}`,\n                );\n            }\n        }\n    }\n\n    /**\n     * Configure routes by reading metadata from the API interface.\n     */\n    configure(routeBuilder: RouteBuilder): void {\n        const routes = getRoutes(this.apiMetaClass);\n\n        for (const route of routes) {\n            this.registerRoute(routeBuilder, route);\n        }\n    }\n\n    /**\n     * Register a single route with the route builder.\n     */\n    private registerRoute(routeBuilder: RouteBuilder, route: RouteMetadata): void {\n        if (!route.httpMethod || !route.path) {\n            const apiName = (this.apiMetaClass as any).name || 'Unknown';\n            throw new Error(\n                `Method ${route.methodName} in ${apiName} must have both @HttpMethod and @Path decorators`,\n            );\n        }\n\n        // Extract controller filepath for filter matching\n        const controllerFilepath = this.getControllerFilepath();\n\n        // Pass controller class and method name to RouteBuilder\n        // RouteBuilder will resolve the controller from DI and create the handler\n        routeBuilder.addRoute(new RouteDefinition(route, this.controllerClass, controllerFilepath));\n    }\n\n    /**\n     * Get the filepath of the controller source file.\n     * Uses a heuristic based on the controller class name.\n     *\n     * Since TypeScript doesn't provide source file paths at runtime,\n     * we use the class name to create a pattern that filters can match against.\n     *\n     * @returns Filepath pattern or undefined\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 as any).name;\n        return className ? `**/${className}.ts` : undefined;\n    }\n\n    /**\n     * Get the API interface class.\n     */\n    getApiClass(): any {\n        return this.apiMetaClass;\n    }\n\n    /**\n     * Get the controller class.\n     */\n    getControllerClass(): any {\n        return this.controllerClass;\n    }\n}\n"]}
+{"version":3,"file":"RESTApiRoutes.js","sourceRoot":"","sources":["../../../../../packages/http/http-routing/src/RESTApiRoutes.ts"],"names":[],"mappings":";;;AAAA,6CAAqE;AACrE,kDAA+E;AAC/E,6CAAqD;AAOrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAa,aAAa;IAItB;;;;;OAKG;IACH,YAAY,YAA6B,EAAE,eAAuC;QAC9E,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QAEvC,wDAAwD;QACxD,IAAI,CAAC,IAAA,yBAAc,EAAC,YAAY,CAAC,EAAE,CAAC;YAChC,MAAM,SAAS,GAAI,YAAoB,CAAC,IAAI,IAAI,SAAS,CAAC;YAC1D,MAAM,IAAI,KAAK,CAAC,SAAS,SAAS,yCAAyC,CAAC,CAAC;QACjF,CAAC;QAED,yEAAyE;QACzE,IAAI,CAAC,+BAA+B,EAAE,CAAC;IAC3C,CAAC;IAED;;OAEG;IACK,+BAA+B;QACnC,MAAM,MAAM,GAAG,IAAA,oBAAS,EAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAE5C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YACzB,MAAM,mBAAmB,GAAG,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC;YAE3D,IAAI,OAAO,mBAAmB,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,UAAU,EAAE,CAAC;gBAC9D,MAAM,cAAc,GAAI,IAAI,CAAC,eAAuB,CAAC,IAAI,IAAI,SAAS,CAAC;gBACvE,MAAM,OAAO,GAAI,IAAI,CAAC,YAAoB,CAAC,IAAI,IAAI,SAAS,CAAC;gBAC7D,MAAM,IAAI,KAAK,CACX,cAAc,cAAc,0BAA0B,KAAK,CAAC,UAAU,aAAa,OAAO,EAAE,CAC/F,CAAC;YACN,CAAC;QACL,CAAC;IACL,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,YAA0B;QAChC,MAAM,MAAM,GAAG,IAAA,oBAAS,EAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAE5C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YACzB,IAAI,CAAC,aAAa,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;QAC5C,CAAC;IACL,CAAC;IAED;;OAEG;IACK,aAAa,CAAC,YAA0B,EAAE,KAAoB;QAClE,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YACnC,MAAM,OAAO,GAAI,IAAI,CAAC,YAAoB,CAAC,IAAI,IAAI,SAAS,CAAC;YAC7D,MAAM,IAAI,KAAK,CACX,UAAU,KAAK,CAAC,UAAU,OAAO,OAAO,kDAAkD,CAC7F,CAAC;QACN,CAAC;QAED,wCAAwC;QACxC,KAAK,CAAC,mBAAmB,GAAI,IAAI,CAAC,eAAuB,CAAC,IAAI,CAAC;QAE/D,kDAAkD;QAClD,MAAM,kBAAkB,GAAG,IAAI,CAAC,qBAAqB,EAAE,CAAC;QAExD,wDAAwD;QACxD,0EAA0E;QAC1E,YAAY,CAAC,QAAQ,CAAC,IAAI,4BAAe,CAAC,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAChG,CAAC;IAED;;;;;;;;OAQG;IACK,qBAAqB;QACzB,oDAAoD;QACpD,MAAM,QAAQ,GAAG,OAAO,CAAC,WAAW,CAChC,kCAAqB,CAAC,eAAe,EACrC,IAAI,CAAC,eAAe,CACvB,CAAC;QACF,IAAI,QAAQ,EAAE,CAAC;YACX,OAAO,QAAQ,CAAC;QACpB,CAAC;QAED,iCAAiC;QACjC,MAAM,SAAS,GAAI,IAAI,CAAC,eAAuB,CAAC,IAAI,CAAC;QACrD,OAAO,SAAS,CAAC,CAAC,CAAC,MAAM,SAAS,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IACxD,CAAC;IAED;;OAEG;IACH,WAAW;QACP,OAAO,IAAI,CAAC,YAAY,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,kBAAkB;QACd,OAAO,IAAI,CAAC,eAAe,CAAC;IAChC,CAAC;CACJ;AAjHD,sCAiHC","sourcesContent":["import { Routes, RouteBuilder, RouteDefinition } from './WebAppMeta';\nimport { getRoutes, isApiInterface, RouteMetadata } from '@webpieces/http-api';\nimport { ROUTING_METADATA_KEYS } from './decorators';\n\n/**\n * Type representing a class constructor (abstract or concrete).\n */\nexport type ClassType<T = any> = Function & { prototype: T };\n\n/**\n * RESTApiRoutes - Automatically wire API interfaces to controllers.\n * Similar to Java WebPieces RESTApiRoutes.\n *\n * This class uses reflection (reflect-metadata) to read decorators from\n * an API interface class and automatically register routes that dispatch\n * to the corresponding controller methods.\n *\n * Usage:\n * ```typescript\n * // In your ServerMeta:\n * getRoutes(): Routes[] {\n *   return [\n *     new RESTApiRoutes(SaveApiPrototype, SaveController),\n *     // ... more routes\n *   ];\n * }\n * ```\n *\n * The API interface and controller must follow this pattern:\n * - API interface class has @ApiInterface() decorator\n * - Methods have @Post()/@Get()/etc and @Path() decorators\n * - Controller class implements the same interface\n * - Controller class has @Controller() decorator\n *\n * Type Parameters:\n * - TApi: The API prototype class type (abstract class with decorators)\n * - TController: The controller class type (must extend TApi)\n */\nexport class RESTApiRoutes<TApi = any, TController extends TApi = any> implements Routes {\n    private apiMetaClass: ClassType<TApi>;\n    private controllerClass: ClassType<TController>;\n\n    /**\n     * Create a new RESTApiRoutes.\n     *\n     * @param apiMetaClass - The API interface class with decorators (e.g., SaveApiPrototype)\n     * @param controllerClass - The controller class that implements the API (e.g., SaveController)\n     */\n    constructor(apiMetaClass: ClassType<TApi>, controllerClass: ClassType<TController>) {\n        this.apiMetaClass = apiMetaClass;\n        this.controllerClass = controllerClass;\n\n        // Validate that apiMetaClass is marked as @ApiInterface\n        if (!isApiInterface(apiMetaClass)) {\n            const className = (apiMetaClass as any).name || 'Unknown';\n            throw new Error(`Class ${className} must be decorated with @ApiInterface()`);\n        }\n\n        // Validate that controllerClass implements the methods from apiMetaClass\n        this.validateControllerImplementsApi();\n    }\n\n    /**\n     * Validate that the controller implements all methods from the API interface.\n     */\n    private validateControllerImplementsApi(): void {\n        const routes = getRoutes(this.apiMetaClass);\n\n        for (const route of routes) {\n            const controllerPrototype = this.controllerClass.prototype;\n\n            if (typeof controllerPrototype[route.methodName] !== 'function') {\n                const controllerName = (this.controllerClass as any).name || 'Unknown';\n                const apiName = (this.apiMetaClass as any).name || 'Unknown';\n                throw new Error(\n                    `Controller ${controllerName} must implement method ${route.methodName} from API ${apiName}`,\n                );\n            }\n        }\n    }\n\n    /**\n     * Configure routes by reading metadata from the API interface.\n     */\n    configure(routeBuilder: RouteBuilder): void {\n        const routes = getRoutes(this.apiMetaClass);\n\n        for (const route of routes) {\n            this.registerRoute(routeBuilder, route);\n        }\n    }\n\n    /**\n     * Register a single route with the route builder.\n     */\n    private registerRoute(routeBuilder: RouteBuilder, route: RouteMetadata): void {\n        if (!route.httpMethod || !route.path) {\n            const apiName = (this.apiMetaClass as any).name || 'Unknown';\n            throw new Error(\n                `Method ${route.methodName} in ${apiName} must have both @HttpMethod and @Path decorators`,\n            );\n        }\n\n        // Set controller class name for logging\n        route.controllerClassName = (this.controllerClass as any).name;\n\n        // Extract controller filepath for filter matching\n        const controllerFilepath = this.getControllerFilepath();\n\n        // Pass controller class and method name to RouteBuilder\n        // RouteBuilder will resolve the controller from DI and create the handler\n        routeBuilder.addRoute(new RouteDefinition(route, this.controllerClass, controllerFilepath));\n    }\n\n    /**\n     * Get the filepath of the controller source file.\n     * Uses a heuristic based on the controller class name.\n     *\n     * Since TypeScript doesn't provide source file paths at runtime,\n     * we use the class name to create a pattern that filters can match against.\n     *\n     * @returns Filepath pattern or undefined\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 as any).name;\n        return className ? `**/${className}.ts` : undefined;\n    }\n\n    /**\n     * Get the API interface class.\n     */\n    getApiClass(): any {\n        return this.apiMetaClass;\n    }\n\n    /**\n     * Get the controller class.\n     */\n    getControllerClass(): any {\n        return this.controllerClass;\n    }\n}\n"]}

package/src/RouteBuilderImpl.d.ts

@@ -0,0 +1,159 @@
+import { Container } from 'inversify';
+import { Request, Response, NextFunction } from 'express';
+import { RouteBuilder, RouteDefinition, FilterDefinition } from './WebAppMeta';
+import { RouteHandler } from './RouteHandler';
+import { MethodMeta } from './MethodMeta';
+import { WpResponse, Service } from '@webpieces/http-filters';
+import { HttpFilter } from './FilterMatcher';
+/**
+ * Express route handler function type.
+ * Used by wrapExpress to create handlers that Express can call.
+ */
+export type ExpressRouteHandler = (req: Request, res: Response, next: NextFunction) => Promise<void>;
+/**
+ * FilterWithMeta - Pairs a resolved filter instance with its definition.
+ * Stores both the DI-resolved filter and the metadata needed for matching.
+ */
+export declare class FilterWithMeta {
+    filter: HttpFilter;
+    definition: FilterDefinition;
+    constructor(filter: HttpFilter, definition: FilterDefinition);
+}
+/**
+ * RouteHandlerImpl - Concrete implementation of RouteHandler.
+ * Wraps a resolved controller and method to invoke on each request.
+ */
+export declare class RouteHandlerImpl<TResult> implements RouteHandler<TResult> {
+    private controller;
+    private method;
+    constructor(controller: Record<string, unknown>, method: (this: unknown, requestDto?: unknown) => Promise<TResult>);
+    execute(meta: MethodMeta): Promise<TResult>;
+}
+/**
+ * RouteHandlerWithMeta - Pairs a route handler with its definition.
+ * Stores both the handler (which wraps the DI-resolved controller) and the route metadata.
+ *
+ * We use unknown for the generic type since we store different TResult types in the same Map.
+ * Type safety is maintained through the generic on RouteDefinition at registration time.
+ */
+export declare class RouteHandlerWithMeta {
+    invokeControllerHandler: RouteHandler<unknown>;
+    definition: RouteDefinition;
+    constructor(invokeControllerHandler: RouteHandler<unknown>, definition: RouteDefinition);
+}
+/**
+ * RouteBuilderImpl - Concrete implementation of RouteBuilder interface.
+ *
+ * Similar to Java WebPieces RouteBuilder, this class is responsible for:
+ * 1. Registering routes with their handlers
+ * 2. Registering filters with priority
+ *
+ * This class is explicit (not anonymous) to:
+ * - Improve traceability and debugging
+ * - Make the code easier to understand
+ * - Enable better IDE navigation (Cmd+Click on addRoute works!)
+ *
+ * DI Pattern: This class is registered in webpiecesContainer via @provideSingleton()
+ * but needs appContainer to resolve filters/controllers. The container is set via
+ * setContainer() after appContainer is created (late binding pattern).
+ */
+export declare class RouteBuilderImpl implements RouteBuilder {
+    private routes;
+    private filterRegistry;
+    private container?;
+    /**
+     * Map for O(1) route lookup by method:path.
+     * Used by both addRoute() and createRouteInvoker() for fast route access.
+     */
+    private routeMap;
+    /**
+     * Create route key for consistent lookup.
+     * Key format: "${METHOD}:${path}" (e.g., "POST:/search/item")
+     */
+    private createRouteKey;
+    /**
+     * Set the DI container used for resolving filters and controllers.
+     * Called by WebpiecesCoreServer after appContainer is created.
+     *
+     * @param container - The application DI container (appContainer)
+     */
+    setContainer(container: Container): void;
+    /**
+     * Register a route with the router.
+     *
+     * Uses createRouteHandlerWithMeta() to create the handler, then stores it
+     * in both the routes array and the routeMap for O(1) lookup.
+     *
+     * @param route - Route definition with controller class and method name
+     */
+    addRoute(route: RouteDefinition): void;
+    /**
+     * Create RouteHandlerWithMeta from a RouteDefinition.
+     *
+     * Resolves controller from DI container ONCE and creates a handler that
+     * invokes the controller method with the request DTO.
+     *
+     * This method is used by:
+     * - addRoute() for production route registration
+     * - createRouteInvoker() for test clients (via createApiClient)
+     *
+     * @param route - Route definition with controller class and method name
+     * @returns RouteHandlerWithMeta containing the handler and route definition
+     */
+    private createRouteHandlerWithMeta;
+    /**
+     * Register a filter with the filter chain.
+     *
+     * Resolves the filter from DI container and pairs it with the filter definition.
+     * The definition includes pattern information used for route-specific filtering.
+     *
+     * @param filterDef - Filter definition with priority, filter class, and optional filepath pattern
+     */
+    addFilter(filterDef: FilterDefinition): void;
+    /**
+     * Get all registered routes.
+     *
+     * @returns Map of routes with handlers and definitions, keyed by "METHOD:path"
+     */
+    getRoutes(): RouteHandlerWithMeta[];
+    /**
+     * Get all filters sorted by priority (highest priority first).
+     *
+     * @returns Array of FilterWithMeta sorted by priority
+     */
+    getSortedFilters(): Array<FilterWithMeta>;
+    /**
+     * Cached filter definitions for lazy route setup.
+     */
+    private cachedFilterDefinitions?;
+    /**
+     * Get filter definitions, computing once and caching.
+     */
+    private getFilterDefinitions;
+    /**
+     * Setup a single route by creating its filter chain.
+     * This is called lazily by createHandler() and getRouteService().
+     *
+     * Creates a Service that wraps the filter chain and controller invocation.
+     * The service is DTO-only and has no Express dependency.
+     *
+     * @param key - Route key in format "METHOD:path"
+     * @param routeWithMeta - Route handler with metadata
+     * @returns The service for this route
+     */
+    createRouteHandler(routeWithMeta: RouteHandlerWithMeta): Service<MethodMeta, WpResponse<unknown>>;
+    /**
+     * Create an invoker function for a route (for testing via createApiClient).
+     * Uses routeMap for O(1) lookup, sets up the filter chain ONCE,
+     * and returns a Service that can be called multiple times without
+     * recreating the filter chain.
+     *
+     * This method is called by WebpiecesServer.createApiClient() during proxy setup.
+     * The returned Service is stored as the proxy method and invoked on each call.
+     *
+     * @param method - HTTP method (GET, POST, etc.)
+     * @param path - URL path
+     * @returns A Service that invokes the route
+     */
+    createRouteInvoker(method: string, path: string): Service<MethodMeta, WpResponse<unknown>>;
+}

package/src/RouteBuilderImpl.js

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

package/src/RouteBuilderImpl.js.map

@@ -0,0 +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        // Chain filters with the controller service (reverse order for correct execution)\n        let filterChain = matchingFilters[matchingFilters.length - 1];\n        for (let i = matchingFilters.length - 2; i >= 0; i--) {\n            filterChain = filterChain.chain(matchingFilters[i]);\n        }\n\n        return filterChain.chainService(controllerService);\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/RouteHandler.d.ts

@@ -0,0 +1,22 @@
+import { MethodMeta } from './MethodMeta';
+/**
+ * Handler class for routes.
+ * Takes a MethodMeta and returns the controller method result.
+ *
+ * Generic type parameter TResult represents the return type of the controller method.
+ * Example: RouteHandler<SaveResponse> for a method that returns Promise<SaveResponse>
+ *
+ * Using unknown as default instead of any forces type safety - consumers must
+ * handle the result appropriately rather than assuming any type.
+ *
+ * This is a class instead of a function type to make it easier to trace
+ * who is calling what in the debugger/IDE.
+ */
+export declare abstract class RouteHandler<TResult = unknown> {
+    /**
+     * Execute the route handler.
+     * @param meta - The method metadata containing request info and params
+     * @returns Promise of the controller method result
+     */
+    abstract execute(meta: MethodMeta): Promise<TResult>;
+}

package/src/RouteHandler.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RouteHandler = void 0;
+/**
+ * Handler class for routes.
+ * Takes a MethodMeta and returns the controller method result.
+ *
+ * Generic type parameter TResult represents the return type of the controller method.
+ * Example: RouteHandler<SaveResponse> for a method that returns Promise<SaveResponse>
+ *
+ * Using unknown as default instead of any forces type safety - consumers must
+ * handle the result appropriately rather than assuming any type.
+ *
+ * This is a class instead of a function type to make it easier to trace
+ * who is calling what in the debugger/IDE.
+ */
+class RouteHandler {
+}
+exports.RouteHandler = RouteHandler;
+//# sourceMappingURL=RouteHandler.js.map

package/src/RouteHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouteHandler.js","sourceRoot":"","sources":["../../../../../packages/http/http-routing/src/RouteHandler.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;GAYG;AACH,MAAsB,YAAY;CAOjC;AAPD,oCAOC","sourcesContent":["import { MethodMeta } from './MethodMeta';\n\n/**\n * Handler class for routes.\n * Takes a MethodMeta and returns the controller method result.\n *\n * Generic type parameter TResult represents the return type of the controller method.\n * Example: RouteHandler<SaveResponse> for a method that returns Promise<SaveResponse>\n *\n * Using unknown as default instead of any forces type safety - consumers must\n * handle the result appropriately rather than assuming any type.\n *\n * This is a class instead of a function type to make it easier to trace\n * who is calling what in the debugger/IDE.\n */\nexport abstract class RouteHandler<TResult = unknown> {\n    /**\n     * Execute the route handler.\n     * @param meta - The method metadata containing request info and params\n     * @returns Promise of the controller method result\n     */\n    abstract execute(meta: MethodMeta): Promise<TResult>;\n}\n"]}

package/src/WebAppMeta.d.ts

@@ -0,0 +1,71 @@
+import { ContainerModule } from 'inversify';
+import { RouteMetadata } from "@webpieces/http-api";
+/**
+ * Represents a route configuration that can be registered with the router.
+ * Similar to Java WebPieces Routes interface.
+ */
+export interface Routes {
+    /**
+     * Configure routes using the provided RouteBuilder.
+     */
+    configure(routeBuilder: RouteBuilder): void;
+}
+/**
+ * Builder for registering routes.
+ * Will be implemented in http-server package.
+ */
+export interface RouteBuilder {
+    addRoute(route: RouteDefinition): void;
+    addFilter(filter: FilterDefinition): void;
+}
+/**
+ * Definition of a single route.
+ *
+ * Generic type parameter TResult represents the return type of the route handler.
+ * This provides type safety for the entire request/response cycle.
+ */
+export declare class RouteDefinition {
+    routeMeta: RouteMetadata;
+    controllerClass: any;
+    controllerFilepath?: string | undefined;
+    constructor(routeMeta: RouteMetadata, controllerClass: any, controllerFilepath?: string | undefined);
+}
+/**
+ * Definition of a filter with priority.
+ *
+ * Use filepathPattern to scope filters to specific controllers:
+ *   - 'src/controllers/admin/**' + '/*.ts' - All admin controllers
+ *   - '**' + '/admin/**' - Any file in admin directories
+ *   - '**' + '/UserController.ts' - Specific controller file
+ *
+ * If filepathPattern is not specified, the filter matches all controllers.
+ */
+export declare class FilterDefinition {
+    priority: number;
+    filterClass: any;
+    filter?: any;
+    /**
+     * Glob pattern to match controller file paths.
+     * If not specified, defaults to matching all controllers.
+     */
+    filepathPattern: string;
+    constructor(priority: number, filterClass: any, filepathPattern: string);
+}
+/**
+ * Main application metadata interface.
+ * Similar to Java WebPieces WebAppMeta.
+ *
+ * This is the entry point that WebpiecesServer calls to configure your application.
+ */
+export interface WebAppMeta {
+    /**
+     * Returns the list of Inversify container modules for dependency injection.
+     * Similar to getGuiceModules() in Java.
+     */
+    getDIModules(): ContainerModule[];
+    /**
+     * Returns the list of route configurations.
+     * Similar to getRouteModules() in Java.
+     */
+    getRoutes(): Routes[];
+}

package/src/WebAppMeta.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilterDefinition = exports.RouteDefinition = void 0;
+/**
+ * Definition of a single route.
+ *
+ * Generic type parameter TResult represents the return type of the route handler.
+ * This provides type safety for the entire request/response cycle.
+ */
+class RouteDefinition {
+    constructor(routeMeta, controllerClass, controllerFilepath) {
+        this.routeMeta = routeMeta;
+        this.controllerClass = controllerClass;
+        this.controllerFilepath = controllerFilepath;
+    }
+}
+exports.RouteDefinition = RouteDefinition;
+/**
+ * Definition of a filter with priority.
+ *
+ * Use filepathPattern to scope filters to specific controllers:
+ *   - 'src/controllers/admin/**' + '/*.ts' - All admin controllers
+ *   - '**' + '/admin/**' - Any file in admin directories
+ *   - '**' + '/UserController.ts' - Specific controller file
+ *
+ * If filepathPattern is not specified, the filter matches all controllers.
+ */
+class FilterDefinition {
+    constructor(priority, filterClass, filepathPattern) {
+        this.priority = priority;
+        this.filterClass = filterClass;
+        this.filepathPattern = filepathPattern;
+        this.filter = undefined; // Set later by RouteBuilder
+    }
+}
+exports.FilterDefinition = FilterDefinition;
+//# sourceMappingURL=WebAppMeta.js.map

package/src/WebAppMeta.js.map

@@ -0,0 +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","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"]}

package/src/index.d.ts

@@ -1,3 +1,8 @@
 export { ApiInterface, Get, Post, Put, Delete, Patch, Path, getRoutes, isApiInterface, RouteMetadata, METADATA_KEYS, ValidateImplementation, } from '@webpieces/http-api';
 export { Controller, isController, provideSingleton, provideTransient, ROUTING_METADATA_KEYS, } from './decorators';
 export { RESTApiRoutes, ClassType } from './RESTApiRoutes';
+export { WebAppMeta, Routes, RouteBuilder, RouteDefinition, FilterDefinition, } from './WebAppMeta';
+export { MethodMeta } from './MethodMeta';
+export { RouteHandler } from './RouteHandler';
+export { RouteBuilderImpl, RouteHandlerWithMeta, FilterWithMeta, ExpressRouteHandler, } from './RouteBuilderImpl';
+export { FilterMatcher, HttpFilter } from './FilterMatcher';

package/src/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RESTApiRoutes = exports.ROUTING_METADATA_KEYS = exports.provideTransient = exports.provideSingleton = exports.isController = exports.Controller = exports.METADATA_KEYS = exports.RouteMetadata = exports.isApiInterface = exports.getRoutes = exports.Path = exports.Patch = exports.Delete = exports.Put = exports.Post = exports.Get = exports.ApiInterface = void 0;
+exports.FilterMatcher = exports.FilterWithMeta = exports.RouteHandlerWithMeta = exports.RouteBuilderImpl = exports.RouteHandler = exports.MethodMeta = exports.FilterDefinition = exports.RouteDefinition = exports.RESTApiRoutes = exports.ROUTING_METADATA_KEYS = exports.provideTransient = exports.provideSingleton = exports.isController = exports.Controller = exports.METADATA_KEYS = exports.RouteMetadata = exports.isApiInterface = exports.getRoutes = exports.Path = exports.Patch = exports.Delete = exports.Put = exports.Post = exports.Get = exports.ApiInterface = void 0;
 // Re-export API decorators from http-api for convenience
 var http_api_1 = require("@webpieces/http-api");
 Object.defineProperty(exports, "ApiInterface", { enumerable: true, get: function () { return http_api_1.ApiInterface; } });
@@ -23,4 +23,21 @@ Object.defineProperty(exports, "provideTransient", { enumerable: true, get: func
 Object.defineProperty(exports, "ROUTING_METADATA_KEYS", { enumerable: true, get: function () { return decorators_1.ROUTING_METADATA_KEYS; } });
 var RESTApiRoutes_1 = require("./RESTApiRoutes");
 Object.defineProperty(exports, "RESTApiRoutes", { enumerable: true, get: function () { return RESTApiRoutes_1.RESTApiRoutes; } });
+// Core routing types (moved from core-meta)
+var WebAppMeta_1 = require("./WebAppMeta");
+Object.defineProperty(exports, "RouteDefinition", { enumerable: true, get: function () { return WebAppMeta_1.RouteDefinition; } });
+Object.defineProperty(exports, "FilterDefinition", { enumerable: true, get: function () { return WebAppMeta_1.FilterDefinition; } });
+// Method metadata and route handler
+var MethodMeta_1 = require("./MethodMeta");
+Object.defineProperty(exports, "MethodMeta", { enumerable: true, get: function () { return MethodMeta_1.MethodMeta; } });
+var RouteHandler_1 = require("./RouteHandler");
+Object.defineProperty(exports, "RouteHandler", { enumerable: true, get: function () { return RouteHandler_1.RouteHandler; } });
+// Route builder implementation
+var RouteBuilderImpl_1 = require("./RouteBuilderImpl");
+Object.defineProperty(exports, "RouteBuilderImpl", { enumerable: true, get: function () { return RouteBuilderImpl_1.RouteBuilderImpl; } });
+Object.defineProperty(exports, "RouteHandlerWithMeta", { enumerable: true, get: function () { return RouteBuilderImpl_1.RouteHandlerWithMeta; } });
+Object.defineProperty(exports, "FilterWithMeta", { enumerable: true, get: function () { return RouteBuilderImpl_1.FilterWithMeta; } });
+// Filter matching
+var FilterMatcher_1 = require("./FilterMatcher");
+Object.defineProperty(exports, "FilterMatcher", { enumerable: true, get: function () { return FilterMatcher_1.FilterMatcher; } });
 //# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/http/http-routing/src/index.ts"],"names":[],"mappings":";;;AAAA,yDAAyD;AACzD,gDAa6B;AAZzB,wGAAA,YAAY,OAAA;AACZ,+FAAA,GAAG,OAAA;AACH,gGAAA,IAAI,OAAA;AACJ,+FAAA,GAAG,OAAA;AACH,kGAAA,MAAM,OAAA;AACN,iGAAA,KAAK,OAAA;AACL,gGAAA,IAAI,OAAA;AACJ,qGAAA,SAAS,OAAA;AACT,0GAAA,cAAc,OAAA;AACd,yGAAA,aAAa,OAAA;AACb,yGAAA,aAAa,OAAA;AAIjB,+CAA+C;AAC/C,2CAMsB;AALlB,wGAAA,UAAU,OAAA;AACV,0GAAA,YAAY,OAAA;AACZ,8GAAA,gBAAgB,OAAA;AAChB,8GAAA,gBAAgB,OAAA;AAChB,mHAAA,qBAAqB,OAAA;AAGzB,iDAA2D;AAAlD,8GAAA,aAAa,OAAA","sourcesContent":["// Re-export API decorators from http-api for convenience\nexport {\n    ApiInterface,\n    Get,\n    Post,\n    Put,\n    Delete,\n    Patch,\n    Path,\n    getRoutes,\n    isApiInterface,\n    RouteMetadata,\n    METADATA_KEYS,\n    ValidateImplementation,\n} from '@webpieces/http-api';\n\n// Server-side routing decorators and utilities\nexport {\n    Controller,\n    isController,\n    provideSingleton,\n    provideTransient,\n    ROUTING_METADATA_KEYS,\n} from './decorators';\n\nexport { RESTApiRoutes, ClassType } from './RESTApiRoutes';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/http/http-routing/src/index.ts"],"names":[],"mappings":";;;AAAA,yDAAyD;AACzD,gDAa6B;AAZzB,wGAAA,YAAY,OAAA;AACZ,+FAAA,GAAG,OAAA;AACH,gGAAA,IAAI,OAAA;AACJ,+FAAA,GAAG,OAAA;AACH,kGAAA,MAAM,OAAA;AACN,iGAAA,KAAK,OAAA;AACL,gGAAA,IAAI,OAAA;AACJ,qGAAA,SAAS,OAAA;AACT,0GAAA,cAAc,OAAA;AACd,yGAAA,aAAa,OAAA;AACb,yGAAA,aAAa,OAAA;AAIjB,+CAA+C;AAC/C,2CAMsB;AALlB,wGAAA,UAAU,OAAA;AACV,0GAAA,YAAY,OAAA;AACZ,8GAAA,gBAAgB,OAAA;AAChB,8GAAA,gBAAgB,OAAA;AAChB,mHAAA,qBAAqB,OAAA;AAGzB,iDAA2D;AAAlD,8GAAA,aAAa,OAAA;AAEtB,4CAA4C;AAC5C,2CAMsB;AAFlB,6GAAA,eAAe,OAAA;AACf,8GAAA,gBAAgB,OAAA;AAGpB,oCAAoC;AACpC,2CAA0C;AAAjC,wGAAA,UAAU,OAAA;AACnB,+CAA8C;AAArC,4GAAA,YAAY,OAAA;AAErB,+BAA+B;AAC/B,uDAK4B;AAJxB,oHAAA,gBAAgB,OAAA;AAChB,wHAAA,oBAAoB,OAAA;AACpB,kHAAA,cAAc,OAAA;AAIlB,kBAAkB;AAClB,iDAA4D;AAAnD,8GAAA,aAAa,OAAA","sourcesContent":["// Re-export API decorators from http-api for convenience\nexport {\n    ApiInterface,\n    Get,\n    Post,\n    Put,\n    Delete,\n    Patch,\n    Path,\n    getRoutes,\n    isApiInterface,\n    RouteMetadata,\n    METADATA_KEYS,\n    ValidateImplementation,\n} from '@webpieces/http-api';\n\n// Server-side routing decorators and utilities\nexport {\n    Controller,\n    isController,\n    provideSingleton,\n    provideTransient,\n    ROUTING_METADATA_KEYS,\n} from './decorators';\n\nexport { RESTApiRoutes, ClassType } from './RESTApiRoutes';\n\n// Core routing types (moved from core-meta)\nexport {\n    WebAppMeta,\n    Routes,\n    RouteBuilder,\n    RouteDefinition,\n    FilterDefinition,\n} from './WebAppMeta';\n\n// Method metadata and route handler\nexport { MethodMeta } from './MethodMeta';\nexport { RouteHandler } from './RouteHandler';\n\n// Route builder implementation\nexport {\n    RouteBuilderImpl,\n    RouteHandlerWithMeta,\n    FilterWithMeta,\n    ExpressRouteHandler,\n} from './RouteBuilderImpl';\n\n// Filter matching\nexport { FilterMatcher, HttpFilter } from './FilterMatcher';\n"]}