@nestjs/core 11.1.23 → 11.1.25

package/Readme.md

@@ -96,6 +96,8 @@ Nest is an MIT-licensed open source project. It can grow thanks to the sponsors
 </tr><tr>
 <td align="center" valign="middle"><a href="https://pandektes.com" target="_blank"><img src="https://nestjs.com/img/logos/pandektes-logo.png" width="65" valign="middle" /></a></td>
 <td align="center" valign="middle"><a href="https://www.fintechcrafts.com/" target="_blank"><img src="https://nestjs.com/img/logos/fintechcrafts-logo.svg" width="65" valign="middle" /></a></td>
+<td align="center" valign="middle"><a href="https://talordata.com/?campaignid=Ya5Xpw2gmhyee6Tg&utm_source=nestjs&utm_term=nestjs" target="_blank"><img src="https://images.opencollective.com/elowen/9ccac7f/avatar/512.png" width="65" valign="middle" /></a></td>
+<td align="center" valign="middle"><a href="https://www.rapidproxy.io/?ref=nestjs" target="_blank"><img src="https://nestjs.com/img/logos/rapid-logo.svg" width="120" valign="middle" /></a></td>
 </tr>
 </table>
 

package/errors/exceptions/route-conflict.exception.d.ts

@@ -0,0 +1,4 @@
+import { RuntimeException } from './runtime.exception.js';
+export declare class RouteConflictException extends RuntimeException {
+    constructor(messages: string[]);
+}

package/errors/exceptions/route-conflict.exception.js

@@ -0,0 +1,7 @@
+import { ROUTE_CONFLICT_MESSAGE } from '../messages.js';
+import { RuntimeException } from './runtime.exception.js';
+export class RouteConflictException extends RuntimeException {
+    constructor(messages) {
+        super(ROUTE_CONFLICT_MESSAGE(messages));
+    }
+}

package/helpers/handler-metadata-storage.d.ts

@@ -10,6 +10,7 @@ export type HandlerResponseBasicFn = <TResult, TResponse>(result: TResult, res:
 export type HandleSseResponseFn = <TResult extends Observable<unknown> = any, TResponse extends HeaderStream = any, TRequest extends IncomingMessage = any>(result: TResult, res: TResponse, req: TRequest) => any;
 export interface HandlerMetadata {
     argsLength: number;
+    isSseHandler: boolean;
     paramtypes: any[];
     httpStatusCode: number;
     responseHeaders: any[];

package/injector/instance-wrapper.d.ts

@@ -91,6 +91,8 @@ export declare class InstanceWrapper<T = any> {
     getStaticTransientInstances(): (InstancePerContext<T> | undefined)[];
     mergeWith(provider: Provider): void;
     private isNewable;
+    private registerDependencyTreeParent;
+    private resetDependencyTreeState;
     private initialize;
     private printIntrospectedAsRequestScoped;
     private printIntrospectedAsDurable;

package/injector/instance-wrapper.js

@@ -12,6 +12,7 @@ const constants_1 = require("./constants");
 const provider_classifier_1 = require("./helpers/provider-classifier");
 exports.INSTANCE_METADATA_SYMBOL = Symbol.for('instance_metadata:cache');
 exports.INSTANCE_ID_SYMBOL = Symbol.for('instance_metadata:id');
+const dependencyTreeParents = new WeakMap();
 class InstanceWrapper {
     constructor(metadata = {}) {
         this.isAlias = false;
@@ -99,6 +100,8 @@ class InstanceWrapper {
             this[exports.INSTANCE_METADATA_SYMBOL].dependencies = [];
         }
         this[exports.INSTANCE_METADATA_SYMBOL].dependencies[index] = wrapper;
+        this.registerDependencyTreeParent(wrapper);
+        this.resetDependencyTreeState();
     }
     getCtorMetadata() {
         return this[exports.INSTANCE_METADATA_SYMBOL].dependencies;
@@ -111,6 +114,8 @@ class InstanceWrapper {
             key,
             wrapper,
         });
+        this.registerDependencyTreeParent(wrapper);
+        this.resetDependencyTreeState();
     }
     getPropertiesMetadata() {
         return this[exports.INSTANCE_METADATA_SYMBOL].properties;
@@ -120,6 +125,8 @@ class InstanceWrapper {
             this[exports.INSTANCE_METADATA_SYMBOL].enhancers = [];
         }
         this[exports.INSTANCE_METADATA_SYMBOL].enhancers.push(wrapper);
+        this.registerDependencyTreeParent(wrapper);
+        this.resetDependencyTreeState();
     }
     getEnhancersMetadata() {
         return this[exports.INSTANCE_METADATA_SYMBOL].enhancers;
@@ -311,6 +318,24 @@ class InstanceWrapper {
     isNewable() {
         return (0, shared_utils_1.isNil)(this.inject) && this.metatype && this.metatype.prototype;
     }
+    registerDependencyTreeParent(wrapper) {
+        if (wrapper instanceof InstanceWrapper) {
+            const parents = dependencyTreeParents.get(wrapper) ?? new Set();
+            parents.add(this);
+            dependencyTreeParents.set(wrapper, parents);
+        }
+    }
+    resetDependencyTreeState(lookupRegistry = new Set()) {
+        if (lookupRegistry.has(this[exports.INSTANCE_ID_SYMBOL])) {
+            return;
+        }
+        lookupRegistry.add(this[exports.INSTANCE_ID_SYMBOL]);
+        this.isTreeStatic = undefined;
+        this.isTreeDurable = undefined;
+        dependencyTreeParents
+            .get(this)
+            ?.forEach(parent => parent.resetDependencyTreeState(lookupRegistry));
+    }
     initialize(metadata) {
         const { instance, isResolved, ...wrapperPartial } = metadata;
         Object.assign(this, wrapperPartial);

package/nest-application.d.ts

@@ -22,6 +22,7 @@ export declare class NestApplication extends NestApplicationContext<NestApplicat
     private readonly microservices;
     private httpServer;
     private isListening;
+    private isWsModuleRegistered;
     constructor(container: NestContainer, httpAdapter: HttpServer, config: ApplicationConfig, graphInspector: GraphInspector, appOptions?: NestApplicationOptions);
     protected dispose(): Promise<void>;
     getHttpAdapter(): AbstractHttpAdapter;

package/nest-application.js

@@ -35,6 +35,7 @@ class NestApplication extends nest_application_context_1.NestApplicationContext
         this.socketModule = SocketModule && new SocketModule();
         this.microservices = [];
         this.isListening = false;
+        this.isWsModuleRegistered = false;
         this.selectContextModule();
         this.registerHttpServer();
         this.injector = new injector_1.Injector({
@@ -89,6 +90,7 @@ class NestApplication extends nest_application_context_1.NestApplicationContext
             return;
         }
         this.socketModule.register(this.container, this.config, this.graphInspector, this.appOptions, this.httpServer);
+        this.isWsModuleRegistered = true;
     }
     async init() {
         if (this.isInitialized) {
@@ -252,6 +254,9 @@ class NestApplication extends nest_application_context_1.NestApplicationContext
         return this;
     }
     useWebSocketAdapter(adapter) {
+        if (this.isWsModuleRegistered) {
+            this.logger.warn('useWebSocketAdapter() was called after WebSocket gateways were already initialized. The provided adapter will be stored but will NOT be applied to existing gateways — they remain bound to the previously installed adapter. To install a custom adapter, call app.useWebSocketAdapter(...) BEFORE app.init() (or app.listen()).');
+        }
         this.config.setIoAdapter(adapter);
         return this;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestjs/core",
-  "version": "11.1.23",
+  "version": "11.1.25",
   "description": "Nest - modern, fast, powerful node.js web framework (@core)",
   "author": "Kamil Mysliwiec",
   "license": "MIT",
@@ -20,18 +20,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "postinstall": "opencollective || exit 0"
-  },
-  "collective": {
-    "type": "opencollective",
-    "url": "https://opencollective.com/nest",
-    "donation": {
-      "text": "Become a partner:"
-    }
-  },
   "dependencies": {
-    "@nuxt/opencollective": "0.4.1",
     "fast-safe-stringify": "2.1.1",
     "iterare": "1.2.1",
     "path-to-regexp": "8.4.2",
@@ -39,7 +28,7 @@
     "uid": "2.0.2"
   },
   "devDependencies": {
-    "@nestjs/common": "11.1.23"
+    "@nestjs/common": "11.1.25"
   },
   "peerDependencies": {
     "@nestjs/common": "^11.0.0",
@@ -60,5 +49,5 @@
       "optional": true
     }
   },
-  "gitHead": "b8be8c12270b2e6dcd275d435e573f08b4c79d79"
+  "gitHead": "02f804159841a2771755c382832a7938b904c420"
 }

package/router/interfaces/resolved-route.interface.d.ts

@@ -0,0 +1,32 @@
+import { RequestMethod } from '@nestjs/common';
+import { type VersionValue } from '@nestjs/common/internal';
+import { InstanceWrapper } from '../../injector/instance-wrapper.js';
+import { RouterProxyCallback } from '../router-proxy.js';
+/**
+ * Loose callable signature shared by the various handler wrappers that
+ * are composed before adapter registration (host filter, version
+ * filter, request-scoped handler, etc.). They all accept the (req, res,
+ * next) trio but may be invoked variadically by adapter shims.
+ */
+export type ResolvedRouteHandler = (...args: unknown[]) => unknown;
+/**
+ * Final route description produced during the "collect" phase of the
+ * router pipeline and consumed during the "register" phase. Holds the
+ * fully composed path, the pre-built handler chain (proxy + host filter
+ * + optional version filter), and the metadata needed to register the
+ * route on the HTTP adapter and to insert an entrypoint into the graph
+ * inspector.
+ */
+export interface ResolvedRoute {
+    method: RequestMethod;
+    path: string;
+    rawPath?: string;
+    host: string | RegExp | Array<string | RegExp> | undefined;
+    version: VersionValue | undefined;
+    methodVersion: VersionValue | undefined;
+    controllerVersion: VersionValue | undefined;
+    handler: ResolvedRouteHandler;
+    targetCallback: RouterProxyCallback;
+    methodName: string;
+    instanceWrapper: InstanceWrapper;
+}

package/router/interfaces/resolved-route.interface.js

@@ -0,0 +1 @@
+export {};

package/router/interfaces/route-conflict.interface.d.ts

@@ -0,0 +1,14 @@
+import { ResolvedRoute } from './resolved-route.interface.js';
+/**
+ * Distinguishes the two flavors of route overlap.
+ * - `duplicate` — identical method + path + version + host registered twice.
+ * - `shadow`    — patterns can match the same request but are not identical.
+ */
+export type ConflictKind = 'duplicate' | 'shadow';
+export interface RouteConflict {
+    /** Route registered first; on order-sensitive adapters this wins. */
+    winner: ResolvedRoute;
+    /** Route registered later; on order-sensitive adapters this never matches. */
+    shadowed: ResolvedRoute;
+    kind: ConflictKind;
+}

package/router/interfaces/route-conflict.interface.js

@@ -0,0 +1 @@
+export {};

package/router/interfaces/route-resolution-options.interface.d.ts

@@ -0,0 +1,24 @@
+import { ResolvedRoute } from './resolved-route.interface.js';
+/**
+ * Options that control how `Resolver.resolve` walks the controller
+ * graph and registers routes on the HTTP adapter. Used internally to
+ * thread route-collection and deferred-registration concerns through
+ * the resolver chain without bloating individual method signatures.
+ */
+export interface RouteResolutionOptions {
+    /**
+     * Invoked once for each route after its final path, host and version
+     * have been composed. Lets the caller observe resolved routes (for
+     * conflict detection, specificity sorting, etc.) without coupling
+     * those concerns to the resolver itself.
+     */
+    onRouteResolved?: (route: ResolvedRoute) => void;
+    /**
+     * When `true`, the resolver still walks every controller and emits
+     * `onRouteResolved` callbacks but skips the actual adapter
+     * registration step. The caller is then responsible for ordering and
+     * installing the collected routes via `registerResolvedRoute`.
+     * Defaults to `false`.
+     */
+    deferRegistration?: boolean;
+}

package/router/interfaces/route-resolution-options.interface.js

@@ -0,0 +1 @@
+export {};

package/router/route-conflict-detector.d.ts

@@ -0,0 +1,71 @@
+import { Logger, type RouteConflictPolicy, type VersioningOptions } from '@nestjs/common';
+import { ResolvedRoute } from './interfaces/resolved-route.interface.js';
+import { RouteConflict } from './interfaces/route-conflict.interface.js';
+type SegmentKind = 'literal' | 'param' | 'wildcard';
+interface PathSegment {
+    kind: SegmentKind;
+    value: string;
+}
+/**
+ * Static utility class that detects overlapping HTTP routes and reports
+ * them according to a per-kind policy. Stateless — every method takes
+ * everything it needs as parameters.
+ */
+export declare class RouteConflictDetector {
+    /**
+     * Strips the leading `:` / `*` marker (if present) and tags each
+     * segment as a literal, named param, or named wildcard. Supports both
+     * bare named wildcards (`*path`) and adapter-normalized path-to-regexp
+     * wildcard groups (`{*path}`).
+     */
+    static tokenizePath(rawPath: string): PathSegment[];
+    /**
+     * Decides whether two paths can match the same incoming request, given
+     * only their declared patterns (no host/method/version considered).
+     */
+    static pathsCanOverlap(leftPath: string, rightPath: string): boolean;
+    /**
+     * Walks every unique pair of resolved routes and produces a conflict
+     * record for each pair whose (method, host, version, path) tuples can
+     * collide at runtime.
+     */
+    static detect(routes: ResolvedRoute[], versioningOptions: VersioningOptions | undefined): RouteConflict[];
+    /**
+     * Applies the per-kind policy to a set of conflicts: silences `'off'`,
+     * logs `'warn'` once per conflict, and aggregates every `'error'`-level
+     * conflict into a single `RouteConflictException`.
+     */
+    static handle(conflicts: RouteConflict[], policy: RouteConflictPolicy | undefined, logger: Logger): void;
+    /**
+     * Removes shadow conflicts that specificity sorting has already resolved.
+     *
+     * When `routeResolutionStrategy: 'specificity'` is active, the sort
+     * promotes more-specific routes ahead of less-specific ones. A shadow
+     * where the sort promoted the winner (it was declared *later* but sorted
+     * *first*) is handled correctly at runtime — the more-specific route is
+     * registered first and handles its requests while the less-specific route
+     * handles the rest. Retaining such a conflict would cause `shadow: 'error'`
+     * to abort an application whose routes actually work as intended.
+     *
+     * Shadows where the winner was already first in declaration order (the
+     * sort did not swap them) are genuine and are kept unchanged. Duplicate
+     * conflicts are always kept.
+     *
+     * @param conflicts     Conflicts detected on the sorted route list.
+     * @param declarationOrder  Routes in their original declaration order
+     *                          (i.e. before specificity sorting was applied).
+     */
+    static filterSortResolvedShadows(conflicts: RouteConflict[], declarationOrder: ResolvedRoute[]): RouteConflict[];
+    private static segmentsCanOverlap;
+    private static methodsCanOverlap;
+    private static versionsCanOverlap;
+    private static hostsCanOverlap;
+    private static hostValuesCanMatchSameRequest;
+    private static routesAreIdentical;
+    private static hostsAreIdentical;
+    private static hostValuesAreIdentical;
+    private static versionsAreIdentical;
+    private static forEachUniquePair;
+    private static describeConflict;
+}
+export {};

package/router/route-conflict-detector.js

@@ -0,0 +1,276 @@
+import { RequestMethod, VERSION_NEUTRAL, VersioningType, } from '@nestjs/common';
+import { RouteConflictException } from '../errors/exceptions/route-conflict.exception.js';
+import { DUPLICATE_ROUTE_MESSAGE, SHADOWED_ROUTE_MESSAGE, } from '../errors/messages.js';
+/**
+ * Static utility class that detects overlapping HTTP routes and reports
+ * them according to a per-kind policy. Stateless — every method takes
+ * everything it needs as parameters.
+ */
+export class RouteConflictDetector {
+    /**
+     * Strips the leading `:` / `*` marker (if present) and tags each
+     * segment as a literal, named param, or named wildcard. Supports both
+     * bare named wildcards (`*path`) and adapter-normalized path-to-regexp
+     * wildcard groups (`{*path}`).
+     */
+    static tokenizePath(rawPath) {
+        const segments = [];
+        rawPath
+            .split('/')
+            .filter(rawSegment => rawSegment.length > 0)
+            .forEach(rawSegment => {
+            if (rawSegment.startsWith('*')) {
+                segments.push({ kind: 'wildcard', value: rawSegment.slice(1) });
+                return;
+            }
+            if (rawSegment.startsWith('{*') && rawSegment.endsWith('}')) {
+                segments.push({
+                    kind: 'wildcard',
+                    value: rawSegment.slice(2, -1),
+                });
+                return;
+            }
+            if (rawSegment.startsWith(':')) {
+                segments.push({ kind: 'param', value: rawSegment.slice(1) });
+                return;
+            }
+            segments.push({ kind: 'literal', value: rawSegment });
+        });
+        return segments;
+    }
+    /**
+     * Decides whether two paths can match the same incoming request, given
+     * only their declared patterns (no host/method/version considered).
+     */
+    static pathsCanOverlap(leftPath, rightPath) {
+        const leftSegments = RouteConflictDetector.tokenizePath(leftPath);
+        const rightSegments = RouteConflictDetector.tokenizePath(rightPath);
+        const leftEndsInWildcard = leftSegments[leftSegments.length - 1]?.kind === 'wildcard';
+        const rightEndsInWildcard = rightSegments[rightSegments.length - 1]?.kind === 'wildcard';
+        // A named wildcard like `*path` requires at least one matched segment,
+        // so only the *shorter* side's trailing wildcard can absorb the
+        // difference. If the longer side has the wildcard, the other side
+        // simply does not have enough segments to ever reach that position.
+        if (leftSegments.length !== rightSegments.length) {
+            const shorterEndsInWildcard = leftSegments.length < rightSegments.length
+                ? leftEndsInWildcard
+                : rightEndsInWildcard;
+            if (!shorterEndsInWildcard) {
+                return false;
+            }
+        }
+        const sharedLength = Math.min(leftSegments.length, rightSegments.length);
+        let canOverlap = true;
+        leftSegments.slice(0, sharedLength).forEach((leftSegment, segmentIndex) => {
+            if (!canOverlap)
+                return;
+            if (!RouteConflictDetector.segmentsCanOverlap(leftSegment, rightSegments[segmentIndex])) {
+                canOverlap = false;
+            }
+        });
+        return canOverlap;
+    }
+    /**
+     * Walks every unique pair of resolved routes and produces a conflict
+     * record for each pair whose (method, host, version, path) tuples can
+     * collide at runtime.
+     */
+    static detect(routes, versioningOptions) {
+        const conflicts = [];
+        RouteConflictDetector.forEachUniquePair(routes, (earlierRoute, laterRoute) => {
+            if (!RouteConflictDetector.methodsCanOverlap(earlierRoute.method, laterRoute.method)) {
+                return;
+            }
+            if (!RouteConflictDetector.versionsCanOverlap(earlierRoute.version, laterRoute.version, versioningOptions)) {
+                return;
+            }
+            if (!RouteConflictDetector.hostsCanOverlap(earlierRoute.host, laterRoute.host)) {
+                return;
+            }
+            if (!RouteConflictDetector.pathsCanOverlap(earlierRoute.path, laterRoute.path)) {
+                return;
+            }
+            const isIdentical = RouteConflictDetector.routesAreIdentical(earlierRoute, laterRoute, versioningOptions);
+            conflicts.push({
+                winner: earlierRoute,
+                shadowed: laterRoute,
+                kind: isIdentical ? 'duplicate' : 'shadow',
+            });
+        });
+        return conflicts;
+    }
+    /**
+     * Applies the per-kind policy to a set of conflicts: silences `'off'`,
+     * logs `'warn'` once per conflict, and aggregates every `'error'`-level
+     * conflict into a single `RouteConflictException`.
+     */
+    static handle(conflicts, policy, logger) {
+        if (conflicts.length === 0 || policy === undefined)
+            return;
+        const errorMessages = [];
+        conflicts.forEach(conflict => {
+            const policyForKind = policy[conflict.kind] ?? 'off';
+            if (policyForKind === 'off')
+                return;
+            const message = RouteConflictDetector.describeConflict(conflict);
+            if (policyForKind === 'warn') {
+                logger.warn(message);
+                return;
+            }
+            errorMessages.push(message);
+        });
+        if (errorMessages.length > 0) {
+            throw new RouteConflictException(errorMessages);
+        }
+    }
+    /**
+     * Removes shadow conflicts that specificity sorting has already resolved.
+     *
+     * When `routeResolutionStrategy: 'specificity'` is active, the sort
+     * promotes more-specific routes ahead of less-specific ones. A shadow
+     * where the sort promoted the winner (it was declared *later* but sorted
+     * *first*) is handled correctly at runtime — the more-specific route is
+     * registered first and handles its requests while the less-specific route
+     * handles the rest. Retaining such a conflict would cause `shadow: 'error'`
+     * to abort an application whose routes actually work as intended.
+     *
+     * Shadows where the winner was already first in declaration order (the
+     * sort did not swap them) are genuine and are kept unchanged. Duplicate
+     * conflicts are always kept.
+     *
+     * @param conflicts     Conflicts detected on the sorted route list.
+     * @param declarationOrder  Routes in their original declaration order
+     *                          (i.e. before specificity sorting was applied).
+     */
+    static filterSortResolvedShadows(conflicts, declarationOrder) {
+        const declarationIndex = new Map(declarationOrder.map((route, idx) => [route, idx]));
+        return conflicts.filter(conflict => {
+            if (conflict.kind !== 'shadow')
+                return true;
+            const winnerDeclIdx = declarationIndex.get(conflict.winner) ?? -1;
+            const shadowedDeclIdx = declarationIndex.get(conflict.shadowed) ?? -1;
+            // The sort promoted the winner (declared later, but sorted to the
+            // front because it is more specific). The shadow is resolved at
+            // runtime — drop it. Keep only genuine shadows where the winner was
+            // already first in declaration order.
+            return winnerDeclIdx < shadowedDeclIdx;
+        });
+    }
+    static segmentsCanOverlap(leftSegment, rightSegment) {
+        if (leftSegment.kind === 'wildcard' || rightSegment.kind === 'wildcard') {
+            return true;
+        }
+        if (leftSegment.kind === 'param' || rightSegment.kind === 'param') {
+            return true;
+        }
+        return leftSegment.value === rightSegment.value;
+    }
+    static methodsCanOverlap(leftMethod, rightMethod) {
+        if (leftMethod === RequestMethod.ALL || rightMethod === RequestMethod.ALL) {
+            return true;
+        }
+        return leftMethod === rightMethod;
+    }
+    static versionsCanOverlap(leftVersion, rightVersion, versioningOptions) {
+        if (!versioningOptions)
+            return true;
+        if (versioningOptions.type === VersioningType.URI)
+            return true;
+        const leftMatchesAnyVersion = leftVersion === undefined || leftVersion === VERSION_NEUTRAL;
+        const rightMatchesAnyVersion = rightVersion === undefined || rightVersion === VERSION_NEUTRAL;
+        if (leftMatchesAnyVersion || rightMatchesAnyVersion)
+            return true;
+        const leftValues = Array.isArray(leftVersion) ? leftVersion : [leftVersion];
+        const rightValues = Array.isArray(rightVersion)
+            ? rightVersion
+            : [rightVersion];
+        return leftValues.some(versionValue => rightValues.includes(versionValue));
+    }
+    static hostsCanOverlap(leftHost, rightHost) {
+        if (leftHost === undefined || rightHost === undefined)
+            return true;
+        const leftHosts = Array.isArray(leftHost) ? leftHost : [leftHost];
+        const rightHosts = Array.isArray(rightHost) ? rightHost : [rightHost];
+        return leftHosts.some(leftValue => rightHosts.some(rightValue => RouteConflictDetector.hostValuesCanMatchSameRequest(leftValue, rightValue)));
+    }
+    static hostValuesCanMatchSameRequest(leftValue, rightValue) {
+        const leftIsRegExp = leftValue instanceof RegExp;
+        const rightIsRegExp = rightValue instanceof RegExp;
+        if (leftIsRegExp && rightIsRegExp)
+            return true;
+        // Reset lastIndex before calling test() to guard against RegExps with the
+        // `g` or `y` flags: those are stateful and would produce inconsistent
+        // results (false negatives) when the same instance is reused across the
+        // multiple pair comparisons that a single detect() run performs.
+        if (leftIsRegExp) {
+            leftValue.lastIndex = 0;
+            return leftValue.test(rightValue);
+        }
+        if (rightIsRegExp) {
+            rightValue.lastIndex = 0;
+            return rightValue.test(leftValue);
+        }
+        return leftValue === rightValue;
+    }
+    static routesAreIdentical(leftRoute, rightRoute, versioningOptions) {
+        return (leftRoute.method === rightRoute.method &&
+            leftRoute.path === rightRoute.path &&
+            RouteConflictDetector.hostsAreIdentical(leftRoute.host, rightRoute.host) &&
+            RouteConflictDetector.versionsAreIdentical(leftRoute.version, rightRoute.version, versioningOptions));
+    }
+    static hostsAreIdentical(leftHost, rightHost) {
+        if (leftHost === undefined && rightHost === undefined)
+            return true;
+        if (leftHost === undefined || rightHost === undefined)
+            return false;
+        const leftHosts = Array.isArray(leftHost) ? leftHost : [leftHost];
+        const rightHosts = Array.isArray(rightHost) ? rightHost : [rightHost];
+        if (leftHosts.length !== rightHosts.length)
+            return false;
+        // Order-insensitive set comparison: ['a', 'b'] and ['b', 'a']
+        // describe the same allowed-host set, so they are identical for
+        // duplicate-classification purposes.
+        return leftHosts.every(leftValue => rightHosts.some(rightValue => RouteConflictDetector.hostValuesAreIdentical(leftValue, rightValue)));
+    }
+    static hostValuesAreIdentical(leftValue, rightValue) {
+        if (leftValue instanceof RegExp && rightValue instanceof RegExp) {
+            return (leftValue.source === rightValue.source &&
+                leftValue.flags === rightValue.flags);
+        }
+        return leftValue === rightValue;
+    }
+    static versionsAreIdentical(leftVersion, rightVersion, versioningOptions) {
+        // When versioning is not configured (or URI-based, where the
+        // version is encoded in the path), version metadata does not
+        // gate request matching at runtime, so two routes that differ
+        // only in their declared `version` are runtime duplicates.
+        if (!versioningOptions || versioningOptions.type === VersioningType.URI) {
+            return true;
+        }
+        if (leftVersion === rightVersion)
+            return true;
+        const leftValues = Array.isArray(leftVersion) ? leftVersion : [leftVersion];
+        const rightValues = Array.isArray(rightVersion)
+            ? rightVersion
+            : [rightVersion];
+        if (leftValues.length !== rightValues.length)
+            return false;
+        return leftValues.every(value => rightValues.includes(value));
+    }
+    static forEachUniquePair(items, visit) {
+        items.forEach((leftItem, leftIndex) => {
+            items.slice(leftIndex + 1).forEach(rightItem => {
+                visit(leftItem, rightItem);
+            });
+        });
+    }
+    static describeConflict(conflict) {
+        const method = RequestMethod[conflict.winner.method];
+        const winnerLabel = `${conflict.winner.instanceWrapper.name}#${conflict.winner.methodName}`;
+        const shadowedLabel = `${conflict.shadowed.instanceWrapper.name}#${conflict.shadowed.methodName}`;
+        if (conflict.kind === 'duplicate') {
+            return DUPLICATE_ROUTE_MESSAGE(method, conflict.winner.path, winnerLabel, shadowedLabel);
+        }
+        return SHADOWED_ROUTE_MESSAGE(method, conflict.shadowed.path, shadowedLabel, conflict.winner.path, winnerLabel);
+    }
+}

package/router/route-specificity-sorter.d.ts

@@ -0,0 +1,23 @@
+import { ResolvedRoute } from './interfaces/resolved-route.interface.js';
+/**
+ * Static utility class that orders resolved routes by specificity so the
+ * underlying HTTP adapter registers more specific patterns first.
+ * Stateless — every method takes everything it needs as parameters.
+ */
+export declare class RouteSpecificitySorter {
+    /**
+     * Lower rank means more specific. A literal segment beats a named
+     * param, which beats a named wildcard. A position that is absent on
+     * one side is the least specific of all (it means the path is shorter
+     * at that point).
+     */
+    private static readonly SEGMENT_KIND_RANK;
+    /**
+     * Returns a new array of routes sorted from most-specific to
+     * least-specific. Routes that tie on specificity keep their original
+     * declaration order.
+     */
+    static sort(routes: ResolvedRoute[]): ResolvedRoute[];
+    private static comparePathSpecificity;
+    private static rankSegmentByKind;
+}

package/router/route-specificity-sorter.js

@@ -0,0 +1,59 @@
+import { RouteConflictDetector } from './route-conflict-detector.js';
+/**
+ * Static utility class that orders resolved routes by specificity so the
+ * underlying HTTP adapter registers more specific patterns first.
+ * Stateless — every method takes everything it needs as parameters.
+ */
+export class RouteSpecificitySorter {
+    /**
+     * Lower rank means more specific. A literal segment beats a named
+     * param, which beats a named wildcard. A position that is absent on
+     * one side is the least specific of all (it means the path is shorter
+     * at that point).
+     */
+    static SEGMENT_KIND_RANK = {
+        literal: 0,
+        param: 1,
+        wildcard: 2,
+        missing: 3,
+    };
+    /**
+     * Returns a new array of routes sorted from most-specific to
+     * least-specific. Routes that tie on specificity keep their original
+     * declaration order.
+     */
+    static sort(routes) {
+        const decoratedRoutes = routes.map((route, declarationIndex) => ({
+            route,
+            declarationIndex,
+        }));
+        decoratedRoutes.sort((leftEntry, rightEntry) => {
+            const specificityDelta = RouteSpecificitySorter.comparePathSpecificity(leftEntry.route.path, rightEntry.route.path);
+            if (specificityDelta !== 0)
+                return specificityDelta;
+            return leftEntry.declarationIndex - rightEntry.declarationIndex;
+        });
+        return decoratedRoutes.map(decoratedEntry => decoratedEntry.route);
+    }
+    static comparePathSpecificity(leftPath, rightPath) {
+        const leftSegments = RouteConflictDetector.tokenizePath(leftPath);
+        const rightSegments = RouteConflictDetector.tokenizePath(rightPath);
+        const longestPathLength = Math.max(leftSegments.length, rightSegments.length);
+        let specificityDelta = 0;
+        Array.from({ length: longestPathLength }).forEach((_, segmentIndex) => {
+            if (specificityDelta !== 0)
+                return;
+            const leftKind = leftSegments[segmentIndex]?.kind ?? 'missing';
+            const rightKind = rightSegments[segmentIndex]?.kind ?? 'missing';
+            const leftRank = RouteSpecificitySorter.rankSegmentByKind(leftKind);
+            const rightRank = RouteSpecificitySorter.rankSegmentByKind(rightKind);
+            if (leftRank !== rightRank) {
+                specificityDelta = leftRank - rightRank;
+            }
+        });
+        return specificityDelta;
+    }
+    static rankSegmentByKind(kind) {
+        return RouteSpecificitySorter.SEGMENT_KIND_RANK[kind];
+    }
+}

package/router/router-execution-context.js

@@ -26,7 +26,7 @@ class RouterExecutionContext {
     }
     create(instance, callback, methodName, moduleKey, requestMethod, contextId = constants_2.STATIC_CONTEXT, inquirerId) {
         const contextType = 'http';
-        const { argsLength, fnHandleResponse, paramtypes, getParamsMetadata, httpStatusCode, responseHeaders, hasCustomHeaders, } = this.getMetadata(instance, callback, methodName, moduleKey, requestMethod, contextType);
+        const { argsLength, fnHandleResponse, isSseHandler, paramtypes, getParamsMetadata, httpStatusCode, responseHeaders, hasCustomHeaders, } = this.getMetadata(instance, callback, methodName, moduleKey, requestMethod, contextType);
         const paramsOptions = this.contextUtils.mergeParamsMetatypes(getParamsMetadata(moduleKey, contextId, inquirerId), paramtypes);
         const pipes = this.pipesContextCreator.create(instance, callback, moduleKey, contextId, inquirerId);
         const guards = this.guardsContextCreator.create(instance, callback, moduleKey, contextId, inquirerId);
@@ -43,7 +43,8 @@ class RouterExecutionContext {
             this.responseController.setStatus(res, httpStatusCode);
             hasCustomHeaders &&
                 this.responseController.setHeaders(res, responseHeaders);
-            const result = await this.interceptorsConsumer.intercept(interceptors, [req, res, next], instance, callback, handler(args, req, res, next), contextType);
+            const resultOrDeferred = this.interceptorsConsumer.intercept(interceptors, [req, res, next], instance, callback, handler(args, req, res, next), contextType);
+            const result = isSseHandler ? resultOrDeferred : await resultOrDeferred;
             await fnHandleResponse(result, res, req);
         };
     }
@@ -62,6 +63,7 @@ class RouterExecutionContext {
         const isResponseHandled = this.isResponseHandled(instance, methodName, paramsMetadata);
         const httpRedirectResponse = this.reflectRedirect(callback);
         const fnHandleResponse = this.createHandleResponseFn(callback, isResponseHandled, httpRedirectResponse);
+        const isSseHandler = !!this.reflectSse(callback);
         const httpCode = this.reflectHttpStatusCode(callback);
         const httpStatusCode = httpCode
             ? httpCode
@@ -71,6 +73,7 @@ class RouterExecutionContext {
         const handlerMetadata = {
             argsLength,
             fnHandleResponse,
+            isSseHandler,
             paramtypes,
             getParamsMetadata,
             httpStatusCode,

package/router/router-response-controller.js

@@ -53,74 +53,102 @@ class RouterResponseController {
         if (response.writableEnded) {
             return;
         }
-        const observableResult = await Promise.resolve(result);
-        this.assertObservable(observableResult);
         const stream = new sse_stream_1.SseStream(request);
         const statusCode = options?.statusCode ??
             response.statusCode ??
             200;
-        stream.pipe(response, {
-            additionalHeaders: options?.additionalHeaders,
-            statusCode,
-        });
         return new Promise((resolve, reject) => {
             let settled = false;
+            let subscription;
+            const cleanup = () => request.removeListener('close', onClose);
             const onClose = () => {
+                if (settled) {
+                    return;
+                }
                 settled = true;
-                subscription.unsubscribe();
+                cleanup();
+                subscription?.unsubscribe();
                 if (!stream.writableEnded) {
                     stream.end();
                 }
                 response.end();
                 resolve();
             };
-            const subscription = observableResult
-                .pipe((0, operators_1.map)((message) => {
-                if ((0, shared_utils_1.isObject)(message)) {
-                    return message;
-                }
-                return { data: message };
-            }), (0, operators_1.concatMap)(message => new Promise(resolve => stream.writeMessage(message, () => resolve()))), (0, operators_1.catchError)(err => {
-                if (!stream.headersCommitted) {
-                    throw err;
+            request.once('close', onClose);
+            Promise.resolve(result)
+                .then(observableResult => {
+                if (settled) {
+                    return;
                 }
-                const data = err instanceof Error ? err.message : err;
-                stream.writeMessage({ type: 'error', data }, writeError => {
-                    if (writeError) {
-                        this.logger.error(writeError);
-                    }
+                this.assertObservable(observableResult);
+                stream.pipe(response, {
+                    additionalHeaders: options?.additionalHeaders,
+                    statusCode,
                 });
-                return rxjs_1.EMPTY;
-            }))
-                .subscribe({
-                error: err => {
-                    settled = true;
-                    request.removeListener('close', onClose);
-                    if (!stream.writableEnded) {
-                        stream.end();
+                subscription = observableResult
+                    .pipe((0, operators_1.map)((message) => {
+                    if ((0, shared_utils_1.isObject)(message)) {
+                        return message;
                     }
-                    reject(err);
-                },
-                complete: () => {
-                    settled = true;
-                    request.removeListener('close', onClose);
-                    if (!stream.writableEnded) {
-                        stream.end();
+                    return { data: message };
+                }), (0, operators_1.concatMap)(message => new Promise(resolve => stream.writeMessage(message, () => resolve()))), (0, operators_1.catchError)(err => {
+                    if (!stream.headersCommitted) {
+                        throw err;
                     }
-                    resolve();
-                },
-            });
-            // Commit SSE headers on the next macrotask. Pipe validation errors
-            // propagate through microtasks (which complete before macrotasks),
-            // so if the lifecycle errored, `settled` is already true and we
-            // skip the write. Otherwise headers are sent immediately rather
-            // than waiting for the first Observable emission.
-            setTimeout(() => {
-                if (!settled) {
-                    stream.commitHeaders();
+                    const data = err instanceof Error ? err.message : err;
+                    stream.writeMessage({ type: 'error', data }, writeError => {
+                        if (writeError) {
+                            this.logger.error(writeError);
+                        }
+                    });
+                    return rxjs_1.EMPTY;
+                }))
+                    .subscribe({
+                    error: err => {
+                        if (settled) {
+                            return;
+                        }
+                        settled = true;
+                        cleanup();
+                        if (!stream.writableEnded) {
+                            stream.end();
+                        }
+                        reject(err);
+                    },
+                    complete: () => {
+                        if (settled) {
+                            return;
+                        }
+                        settled = true;
+                        cleanup();
+                        if (!stream.writableEnded) {
+                            stream.end();
+                        }
+                        resolve();
+                    },
+                });
+                // Commit SSE headers on the next macrotask. Pipe validation errors
+                // propagate through microtasks (which complete before macrotasks),
+                // so if the lifecycle errored, `settled` is already true and we
+                // skip the write. Otherwise headers are sent immediately rather
+                // than waiting for the first Observable emission.
+                setTimeout(() => {
+                    if (!settled) {
+                        stream.commitHeaders();
+                    }
+                }, 0);
+            })
+                .catch(err => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                cleanup();
+                if (!stream.writableEnded) {
+                    stream.end();
                 }
-            }, 0);
-            request.on('close', onClose);
+                reject(err);
+            });
         });
     }
     assertObservable(value) {