@webpieces/http-routing 0.2.16 → 0.2.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/http-routing",
-  "version": "0.2.16",
+  "version": "0.2.21",
   "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.2.16",
-    "@webpieces/http-filters": "0.2.16",
+    "@webpieces/http-api": "0.2.21",
+    "@webpieces/http-filters": "0.2.21",
     "inversify": "^7.10.4",
     "minimatch": "^10.0.1"
   }

package/src/MethodMeta.d.ts

@@ -3,11 +3,11 @@ 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).
+ * MethodMeta is DTO-only - it does NOT contain Express req/res directly.
  *
  * Fields:
  * - routeMeta: Static route information (httpMethod, path, methodName)
+ * - requestHeaders: HTTP headers from the request (NEW)
  * - requestDto: The deserialized request body
  * - metadata: Request-scoped data for filters to communicate
  */
@@ -16,6 +16,28 @@ export declare class MethodMeta {
      * Route metadata (httpMethod, path, methodName, parameterTypes)
      */
     routeMeta: RouteMetadata;
+    /**
+     * 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?: Map<string, string[]>;
     /**
      * The deserialized request DTO.
      */
@@ -25,7 +47,7 @@ export declare class MethodMeta {
      * Used by filters to pass data to other filters/controllers.
      */
     metadata: Map<string, unknown>;
-    constructor(routeMeta: RouteMetadata, requestDto?: unknown, metadata?: Map<string, unknown>);
+    constructor(routeMeta: RouteMetadata, requestHeaders?: Map<string, string[]>, requestDto?: unknown, metadata?: Map<string, unknown>);
     /**
      * Get the HTTP method (convenience accessor).
      */

package/src/MethodMeta.js

@@ -5,17 +5,18 @@ 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).
+ * MethodMeta is DTO-only - it does NOT contain Express req/res directly.
  *
  * Fields:
  * - routeMeta: Static route information (httpMethod, path, methodName)
+ * - requestHeaders: HTTP headers from the request (NEW)
  * - requestDto: The deserialized request body
  * - metadata: Request-scoped data for filters to communicate
  */
 class MethodMeta {
-    constructor(routeMeta, requestDto, metadata) {
+    constructor(routeMeta, requestHeaders, requestDto, metadata) {
         this.routeMeta = routeMeta;
+        this.requestHeaders = requestHeaders;
         this.requestDto = requestDto;
         this.metadata = metadata ?? new Map();
     }

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;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"]}
+{"version":3,"file":"MethodMeta.js","sourceRoot":"","sources":["../../../../../packages/http/http-routing/src/MethodMeta.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;GAWG;AACH,MAAa,UAAU;IAwCnB,YACI,SAAwB,EACxB,cAAsC,EACtC,UAAoB,EACpB,QAA+B;QAE/B,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;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;AAxED,gCAwEC","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 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     * 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    ) {\n        this.routeMeta = routeMeta;\n        this.requestHeaders = requestHeaders;\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/RequestContextReader.d.ts

@@ -0,0 +1,22 @@
+import { PlatformHeader, ContextReader } from '@webpieces/http-api';
+/**
+ * RequestContextReader - Reads headers from Node.js RequestContext.
+ *
+ * Only works in Node.js with active AsyncLocalStorage context.
+ * This is a server-side only implementation.
+ *
+ * NOTE: This class is in @webpieces/http-routing (Node.js only) instead of
+ * @webpieces/http-client (cross-platform) because it has a hard dependency
+ * on @webpieces/core-context which uses Node.js AsyncLocalStorage.
+ *
+ * For browser environments, use StaticContextReader from @webpieces/http-client.
+ */
+export declare class RequestContextReader implements ContextReader {
+    /**
+     * Read a header value from the active RequestContext.
+     *
+     * @param header - The platform header to read
+     * @returns The header value, or undefined if not in context
+     */
+    read(header: PlatformHeader): string | undefined;
+}

package/src/RequestContextReader.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestContextReader = void 0;
+const core_context_1 = require("@webpieces/core-context");
+/**
+ * RequestContextReader - Reads headers from Node.js RequestContext.
+ *
+ * Only works in Node.js with active AsyncLocalStorage context.
+ * This is a server-side only implementation.
+ *
+ * NOTE: This class is in @webpieces/http-routing (Node.js only) instead of
+ * @webpieces/http-client (cross-platform) because it has a hard dependency
+ * on @webpieces/core-context which uses Node.js AsyncLocalStorage.
+ *
+ * For browser environments, use StaticContextReader from @webpieces/http-client.
+ */
+class RequestContextReader {
+    /**
+     * Read a header value from the active RequestContext.
+     *
+     * @param header - The platform header to read
+     * @returns The header value, or undefined if not in context
+     */
+    read(header) {
+        // Use RequestContext.getHeader() which calls header.getHeaderName()
+        return core_context_1.RequestContext.getHeader(header);
+    }
+}
+exports.RequestContextReader = RequestContextReader;
+//# sourceMappingURL=RequestContextReader.js.map

package/src/RequestContextReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequestContextReader.js","sourceRoot":"","sources":["../../../../../packages/http/http-routing/src/RequestContextReader.ts"],"names":[],"mappings":";;;AACA,0DAAyD;AAEzD;;;;;;;;;;;GAWG;AACH,MAAa,oBAAoB;IAC7B;;;;;OAKG;IACH,IAAI,CAAC,MAAsB;QACvB,oEAAoE;QACpE,OAAO,6BAAc,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC5C,CAAC;CACJ;AAXD,oDAWC","sourcesContent":["import { PlatformHeader, ContextReader } from '@webpieces/http-api';\nimport { RequestContext } from '@webpieces/core-context';\n\n/**\n * RequestContextReader - Reads headers from Node.js RequestContext.\n *\n * Only works in Node.js with active AsyncLocalStorage context.\n * This is a server-side only implementation.\n *\n * NOTE: This class is in @webpieces/http-routing (Node.js only) instead of\n * @webpieces/http-client (cross-platform) because it has a hard dependency\n * on @webpieces/core-context which uses Node.js AsyncLocalStorage.\n *\n * For browser environments, use StaticContextReader from @webpieces/http-client.\n */\nexport class RequestContextReader implements ContextReader {\n    /**\n     * Read a header value from the active RequestContext.\n     *\n     * @param header - The platform header to read\n     * @returns The header value, or undefined if not in context\n     */\n    read(header: PlatformHeader): string | undefined {\n        // Use RequestContext.getHeader() which calls header.getHeaderName()\n        return RequestContext.getHeader(header);\n    }\n}\n"]}

package/src/RouteBuilderImpl.js

@@ -209,12 +209,17 @@ let RouteBuilderImpl = class RouteBuilderImpl {
                 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]);
+        if (matchingFilters.length === 0) {
+            throw new Error("No filters found for route. Check filter definitions as you must have at least ContextFilter");
         }
-        return filterChain.chainService(controllerService);
+        // Chain filters: highest priority (first in array) should run first (be outermost)
+        // Build from innermost (lowest priority) to outermost (highest priority)
+        // Start with controller, then wrap with filters in reverse priority order
+        let service = controllerService;
+        for (let i = matchingFilters.length - 1; i >= 0; i--) {
+            service = matchingFilters[i].chainService(service);
+        }
+        return service;
     }
     /**
      * Create an invoker function for a route (for testing via createApiClient).

package/src/RouteBuilderImpl.js.map

@@ -1 +1 @@
-{"version":3,"file":"RouteBuilderImpl.js","sourceRoot":"","sources":["../../../../../packages/http/http-routing/src/RouteBuilderImpl.ts"],"names":[],"mappings":";;;;AAAA,yCAAkD;AAGlD,6CAAgD;AAGhD,0DAA8D;AAC9D,mDAA4D;AAY5D;;;GAGG;AACH,MAAa,cAAc;IACvB,YACW,MAAkB,EAClB,UAA4B;QAD5B,WAAM,GAAN,MAAM,CAAY;QAClB,eAAU,GAAV,UAAU,CAAkB;IACpC,CAAC;CACP;AALD,wCAKC;AAED;;;GAGG;AACH,MAAa,gBAAgB;IACzB,YACY,UAAmC,EACnC,MAAiE;QADjE,eAAU,GAAV,UAAU,CAAyB;QACnC,WAAM,GAAN,MAAM,CAA2D;IAC1E,CAAC;IAEJ,KAAK,CAAC,OAAO,CAAC,IAAgB;QAC1B,8CAA8C;QAC9C,sEAAsE;QACtE,MAAM,MAAM,GAAY,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QACjF,OAAO,MAAM,CAAC;IAClB,CAAC;CACJ;AAZD,4CAYC;AACD;;;;;;GAMG;AACH,MAAa,oBAAoB;IAC7B,YACW,uBAA8C,EAC9C,UAA2B;QAD3B,4BAAuB,GAAvB,uBAAuB,CAAuB;QAC9C,eAAU,GAAV,UAAU,CAAiB;IACnC,CAAC;CACP;AALD,oDAKC;AAED;;;;;;;;;;;;;;;GAeG;AAGI,IAAM,gBAAgB,GAAtB,MAAM,gBAAgB;IAAtB;QACK,WAAM,GAA2B,EAAE,CAAC;QACpC,mBAAc,GAA0B,EAAE,CAAC;QAGnD;;;WAGG;QACK,aAAQ,GAAsC,IAAI,GAAG,EAAE,CAAC;IAyNpE,CAAC;IAvNG;;;OAGG;IACK,cAAc,CAAC,MAAc,EAAE,IAAY;QAC/C,OAAO,GAAG,MAAM,CAAC,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC;IAC7C,CAAC;IAED;;;;;OAKG;IACH,YAAY,CAAC,SAAoB;QAC7B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC/B,CAAC;IAED;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAsB;QAC3B,MAAM,aAAa,GAAG,IAAI,CAAC,0BAA0B,CAAC,KAAK,CAAC,CAAC;QAC7D,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAEhC,iDAAiD;QACjD,MAAM,GAAG,GAAG,IAAI,CAAC,cAAc,CAC3B,KAAK,CAAC,SAAS,CAAC,UAAU,EAC1B,KAAK,CAAC,SAAS,CAAC,IAAI,CACvB,CAAC;QACF,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;;;;;;;;OAYG;IACK,0BAA0B,CAC9B,KAAsB;QAEtB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;QACzF,CAAC;QAED,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;QAElC,6EAA6E;QAC7E,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,eAAe,CAA4B,CAAC;QAExF,4BAA4B;QAC5B,MAAM,MAAM,GAAG,UAAU,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;QAChD,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;YAC/B,MAAM,cAAc,GAAI,KAAK,CAAC,eAAqC,CAAC,IAAI,IAAI,SAAS,CAAC;YACtF,MAAM,IAAI,KAAK,CACX,UAAU,SAAS,CAAC,UAAU,4BAA4B,cAAc,EAAE,CAC7E,CAAC;QACN,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAChC,UAAU,EACV,MAAmE,CACtE,CAAC;QAEF,uCAAuC;QACvC,OAAO,IAAI,oBAAoB,CAC3B,OAAgC,EAChC,KAAK,CACR,CAAC;IACN,CAAC;IAED;;;;;;;OAOG;IACH,SAAS,CAAC,SAA2B;QACjC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;QAC1F,CAAC;QAED,4CAA4C;QAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAa,SAAS,CAAC,WAAW,CAAC,CAAC;QAErE,mCAAmC;QACnC,MAAM,cAAc,GAAG,IAAI,cAAc,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QAC7D,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAC7C,CAAC;IAED;;;;OAIG;IACH,SAAS;QACL,OAAO,IAAI,CAAC,MAAM,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,gBAAgB;QACZ,OAAO,CAAC,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC,IAAI,CAChC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,QAAQ,GAAG,CAAC,CAAC,UAAU,CAAC,QAAQ,CAC1D,CAAC;IACN,CAAC;IAOD;;OAEG;IACK,oBAAoB;QACxB,IAAI,CAAC,IAAI,CAAC,uBAAuB,EAAE,CAAC;YAChC,MAAM,aAAa,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC9C,IAAI,CAAC,uBAAuB,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;gBACrD,MAAM,GAAG,GAAG,GAAG,CAAC,UAAU,CAAC;gBAC3B,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;gBACxB,OAAO,GAAG,CAAC;YACf,CAAC,CAAC,CAAC;QACP,CAAC;QACD,OAAO,IAAI,CAAC,uBAAuB,CAAC;IACxC,CAAC;IAED;;;;;;;;;;OAUG;IACI,kBAAkB,CACrB,aAAmC;QAEnC,MAAM,KAAK,GAAG,aAAa,CAAC,UAAU,CAAC;QACvC,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;QAElC,OAAO,CAAC,GAAG,CAAC,oCAAoC,SAAS,CAAC,UAAU,IAAI,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;QAE1F,gCAAgC;QAChC,MAAM,iBAAiB,GAAG,IAAI,CAAC,oBAAoB,EAAE,CAAC;QAEtD,uCAAuC;QACvC,MAAM,eAAe,GAAG,6BAAa,CAAC,mBAAmB,CACrD,KAAK,CAAC,kBAAkB,EACxB,iBAAiB,CACpB,CAAC;QAEF,qDAAqD;QACrD,MAAM,iBAAiB,GAA6C;YAChE,MAAM,EAAE,KAAK,EAAE,IAAgB,EAAgC,EAAE;gBAC7D,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,uBAAuB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBACzE,OAAO,IAAI,yBAAU,CAAC,MAAM,CAAC,CAAC;YAClC,CAAC;SACJ,CAAC;QAEF,kFAAkF;QAClF,IAAI,WAAW,GAAG,eAAe,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAC9D,KAAK,IAAI,CAAC,GAAG,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACnD,WAAW,GAAG,WAAW,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;QACxD,CAAC;QAED,OAAO,WAAW,CAAC,YAAY,CAAC,iBAAiB,CAAC,CAAC;IACvD,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,MAAc,EAAE,IAAY;QAC3C,oDAAoD;QACpD,MAAM,GAAG,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC9C,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAE7C,IAAI,CAAC,aAAa,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,oBAAoB,MAAM,IAAI,IAAI,EAAE,CAAC,CAAC;QAC1D,CAAC;QAED,qDAAqD;QACrD,OAAO,IAAI,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAC;IAClD,CAAC;CACJ,CAAA;AAlOY,4CAAgB;2BAAhB,gBAAgB;IAF5B,IAAA,6BAAgB,GAAE;IAClB,IAAA,sBAAU,GAAE;GACA,gBAAgB,CAkO5B","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"]}
+{"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/index.d.ts

@@ -6,3 +6,4 @@ export { MethodMeta } from './MethodMeta';
 export { RouteHandler } from './RouteHandler';
 export { RouteBuilderImpl, RouteHandlerWithMeta, FilterWithMeta, ExpressRouteHandler, } from './RouteBuilderImpl';
 export { FilterMatcher, HttpFilter } from './FilterMatcher';
+export { RequestContextReader } from './RequestContextReader';

package/src/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-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;
+exports.RequestContextReader = 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; } });
@@ -40,4 +40,7 @@ Object.defineProperty(exports, "FilterWithMeta", { enumerable: true, get: functi
 // Filter matching
 var FilterMatcher_1 = require("./FilterMatcher");
 Object.defineProperty(exports, "FilterMatcher", { enumerable: true, get: function () { return FilterMatcher_1.FilterMatcher; } });
+// Context readers (Node.js only)
+var RequestContextReader_1 = require("./RequestContextReader");
+Object.defineProperty(exports, "RequestContextReader", { enumerable: true, get: function () { return RequestContextReader_1.RequestContextReader; } });
 //# 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;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"]}
+{"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;AAEtB,iCAAiC;AACjC,+DAA8D;AAArD,4HAAA,oBAAoB,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\n// Context readers (Node.js only)\nexport { RequestContextReader } from './RequestContextReader';\n"]}