@nestjs/core 12.0.0-alpha.3 → 12.0.0-alpha.5

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-explorer.d.ts

@@ -7,7 +7,9 @@ import { Module } from '../injector/module.js';
 import { GraphInspector } from '../inspector/graph-inspector.js';
 import { MetadataScanner } from '../metadata-scanner.js';
 import { ExceptionsFilter } from './interfaces/exceptions-filter.interface.js';
+import { ResolvedRoute } from './interfaces/resolved-route.interface.js';
 import { RoutePathMetadata } from './interfaces/route-path-metadata.interface.js';
+import { RouteResolutionOptions } from './interfaces/route-resolution-options.interface.js';
 import { RoutePathFactory } from './route-path-factory.js';
 import { RouterProxy, RouterProxyCallback } from './router-proxy.js';
 import { type Controller, type VersionValue } from '@nestjs/common/internal';
@@ -32,10 +34,17 @@ export declare class RouterExplorer {
     private readonly logger;
     private readonly exceptionFiltersCache;
     constructor(metadataScanner: MetadataScanner, container: NestContainer, injector: Injector, routerProxy: RouterProxy, exceptionsFilter: ExceptionsFilter, config: ApplicationConfig, routePathFactory: RoutePathFactory, graphInspector: GraphInspector);
-    explore<T extends HttpServer = any>(instanceWrapper: InstanceWrapper, moduleKey: string, httpAdapterRef: T, host: string | RegExp | Array<string | RegExp>, routePathMetadata: RoutePathMetadata): void;
+    explore<T extends HttpServer = any>(instanceWrapper: InstanceWrapper, moduleKey: string, httpAdapterRef: T, host: string | RegExp | Array<string | RegExp>, routePathMetadata: RoutePathMetadata, options?: RouteResolutionOptions): void;
     extractRouterPath(metatype: Type<Controller>): string[];
-    applyPathsToRouterProxy<T extends HttpServer>(router: T, routeDefinitions: RouteDefinition[], instanceWrapper: InstanceWrapper, moduleKey: string, routePathMetadata: RoutePathMetadata, host: string | RegExp | Array<string | RegExp>): void;
+    applyPathsToRouterProxy<T extends HttpServer>(router: T, routeDefinitions: RouteDefinition[], instanceWrapper: InstanceWrapper, moduleKey: string, routePathMetadata: RoutePathMetadata, host: string | RegExp | Array<string | RegExp>, options?: RouteResolutionOptions): void;
     private applyCallbackToRouter;
+    /**
+     * Registers a previously resolved route on the underlying HTTP adapter.
+     * Used when route registration has been deferred (e.g. when sorting
+     * routes by specificity) so the caller can choose the order in which
+     * routes are installed on the adapter.
+     */
+    registerResolvedRoute<T extends HttpServer>(router: T, route: ResolvedRoute): void;
     private applyHostFilter;
     private applyVersionFilter;
     private createCallbackProxy;

package/router/router-explorer.js

@@ -45,10 +45,10 @@ export class RouterExplorer {
         const interceptorsConsumer = new InterceptorsConsumer();
         this.executionContextCreator = new RouterExecutionContext(routeParamsFactory, pipesContextCreator, pipesConsumer, guardsContextCreator, guardsConsumer, interceptorsContextCreator, interceptorsConsumer, container.getHttpAdapterRef());
     }
-    explore(instanceWrapper, moduleKey, httpAdapterRef, host, routePathMetadata) {
+    explore(instanceWrapper, moduleKey, httpAdapterRef, host, routePathMetadata, options = {}) {
         const { instance } = instanceWrapper;
         const routerPaths = this.pathsExplorer.scanForPaths(instance);
-        this.applyPathsToRouterProxy(httpAdapterRef, routerPaths, instanceWrapper, moduleKey, routePathMetadata, host);
+        this.applyPathsToRouterProxy(httpAdapterRef, routerPaths, instanceWrapper, moduleKey, routePathMetadata, host, options);
     }
     extractRouterPath(metatype) {
         const path = Reflect.getMetadata(PATH_METADATA, metatype);
@@ -60,14 +60,15 @@ export class RouterExplorer {
         }
         return [addLeadingSlash(path)];
     }
-    applyPathsToRouterProxy(router, routeDefinitions, instanceWrapper, moduleKey, routePathMetadata, host) {
+    applyPathsToRouterProxy(router, routeDefinitions, instanceWrapper, moduleKey, routePathMetadata, host, options = {}) {
         (routeDefinitions || []).forEach(routeDefinition => {
             const { version: methodVersion } = routeDefinition;
             routePathMetadata.methodVersion = methodVersion;
-            this.applyCallbackToRouter(router, routeDefinition, instanceWrapper, moduleKey, routePathMetadata, host);
+            this.applyCallbackToRouter(router, routeDefinition, instanceWrapper, moduleKey, routePathMetadata, host, options);
         });
     }
-    applyCallbackToRouter(router, routeDefinition, instanceWrapper, moduleKey, routePathMetadata, host) {
+    applyCallbackToRouter(router, routeDefinition, instanceWrapper, moduleKey, routePathMetadata, host, options = {}) {
+        const { onRouteResolved, deferRegistration = false } = options;
         const { path: paths, requestMethod, targetCallback, methodName, } = routeDefinition;
         const { instance } = instanceWrapper;
         const routerMethodRef = this.routerMethodFactory
@@ -90,6 +91,9 @@ export class RouterExplorer {
             routePathMetadata.methodPath = path;
             const pathsToRegister = this.routePathFactory.create(routePathMetadata, requestMethod);
             pathsToRegister.forEach(path => {
+                const normalizedPath = router.normalizePath
+                    ? router.normalizePath(path)
+                    : path;
                 const entrypointDefinition = {
                     type: 'http-endpoint',
                     methodName,
@@ -103,21 +107,34 @@ export class RouterExplorer {
                         controllerVersion: routePathMetadata.controllerVersion,
                     },
                 };
-                this.copyMetadataToCallback(targetCallback, routeHandler);
-                const normalizedPath = router.normalizePath
-                    ? router.normalizePath(path)
-                    : path;
-                const httpAdapter = this.container.getHttpAdapterRef();
-                const onRouteTriggered = httpAdapter.getOnRouteTriggered?.();
-                if (onRouteTriggered) {
-                    routerMethodRef(normalizedPath, (...args) => {
-                        onRouteTriggered(requestMethod, path);
-                        return routeHandler(...args);
-                    });
-                }
-                else {
-                    routerMethodRef(normalizedPath, routeHandler);
+                if (!deferRegistration) {
+                    this.copyMetadataToCallback(targetCallback, routeHandler);
+                    const httpAdapter = this.container.getHttpAdapterRef();
+                    const onRouteTriggered = httpAdapter.getOnRouteTriggered?.();
+                    if (onRouteTriggered) {
+                        routerMethodRef(normalizedPath, (...args) => {
+                            onRouteTriggered(requestMethod, path);
+                            return routeHandler(...args);
+                        });
+                    }
+                    else {
+                        routerMethodRef(normalizedPath, routeHandler);
+                    }
                 }
+                onRouteResolved?.({
+                    method: requestMethod,
+                    path: normalizedPath,
+                    rawPath: path,
+                    host,
+                    version: routePathMetadata.methodVersion ??
+                        routePathMetadata.controllerVersion,
+                    methodVersion: routePathMetadata.methodVersion,
+                    controllerVersion: routePathMetadata.controllerVersion,
+                    handler: routeHandler,
+                    targetCallback,
+                    methodName,
+                    instanceWrapper,
+                });
                 this.graphInspector.insertEntrypointDefinition(entrypointDefinition, instanceWrapper.id);
             });
             const pathsToLog = this.routePathFactory.create({
@@ -135,6 +152,31 @@ export class RouterExplorer {
             });
         });
     }
+    /**
+     * Registers a previously resolved route on the underlying HTTP adapter.
+     * Used when route registration has been deferred (e.g. when sorting
+     * routes by specificity) so the caller can choose the order in which
+     * routes are installed on the adapter.
+     */
+    registerResolvedRoute(router, route) {
+        const routerMethodRef = this.routerMethodFactory
+            .get(router, route.method)
+            .bind(router);
+        this.copyMetadataToCallback(route.targetCallback, route.handler);
+        const normalizedPath = route.path;
+        const rawPath = route.rawPath ?? route.path;
+        const httpAdapter = this.container.getHttpAdapterRef();
+        const onRouteTriggered = httpAdapter.getOnRouteTriggered?.();
+        if (onRouteTriggered) {
+            routerMethodRef(normalizedPath, (...args) => {
+                onRouteTriggered(route.method, rawPath);
+                return route.handler(...args);
+            });
+        }
+        else {
+            routerMethodRef(normalizedPath, route.handler);
+        }
+    }
     applyHostFilter(host, handler) {
         if (!host) {
             return handler;

package/router/routes-resolver.d.ts

@@ -1,11 +1,13 @@
+import { type HttpServer } from '@nestjs/common';
+import { type Controller } from '@nestjs/common/internal';
 import { ApplicationConfig } from '../application-config.js';
 import { NestContainer } from '../injector/container.js';
 import { Injector } from '../injector/injector.js';
 import { InstanceWrapper } from '../injector/instance-wrapper.js';
 import { GraphInspector } from '../inspector/graph-inspector.js';
+import { ResolvedRoute } from './interfaces/resolved-route.interface.js';
 import { Resolver } from './interfaces/resolver.interface.js';
-import { type Controller } from '@nestjs/common/internal';
-import { type HttpServer } from '@nestjs/common';
+import { RouteResolutionOptions } from './interfaces/route-resolution-options.interface.js';
 export declare class RoutesResolver implements Resolver {
     private readonly container;
     private readonly applicationConfig;
@@ -16,8 +18,9 @@ export declare class RoutesResolver implements Resolver {
     private readonly routerExceptionsFilter;
     private readonly routerExplorer;
     constructor(container: NestContainer, applicationConfig: ApplicationConfig, injector: Injector, graphInspector: GraphInspector);
-    resolve<T extends HttpServer>(applicationRef: T, globalPrefix: string): void;
-    registerRouters(routes: Map<string | symbol | Function, InstanceWrapper<Controller>>, moduleName: string, globalPrefix: string, modulePath: string, applicationRef: HttpServer): void;
+    resolve<T extends HttpServer>(applicationRef: T, globalPrefix: string, options?: RouteResolutionOptions): void;
+    registerResolvedRoute<T extends HttpServer>(applicationRef: T, route: ResolvedRoute): void;
+    registerRouters(routes: Map<string | symbol | Function, InstanceWrapper<Controller>>, moduleName: string, globalPrefix: string, modulePath: string, applicationRef: HttpServer, options?: RouteResolutionOptions): void;
     registerNotFoundHandler(): void;
     registerExceptionHandler(): void;
     private getModulePathMetadata;

package/router/routes-resolver.js

@@ -1,12 +1,11 @@
-import { NotFoundException, } from '@nestjs/common';
+import { Logger, NotFoundException, } from '@nestjs/common';
+import { HOST_METADATA, MODULE_PATH, VERSION_METADATA, } from '@nestjs/common/internal';
 import { CONTROLLER_MAPPING_MESSAGE, VERSIONED_CONTROLLER_MAPPING_MESSAGE, } from '../helpers/messages.js';
 import { MetadataScanner } from '../metadata-scanner.js';
 import { RoutePathFactory } from './route-path-factory.js';
 import { RouterExceptionFilters } from './router-exception-filters.js';
 import { RouterExplorer } from './router-explorer.js';
 import { RouterProxy } from './router-proxy.js';
-import { HOST_METADATA, MODULE_PATH, VERSION_METADATA, } from '@nestjs/common/internal';
-import { Logger } from '@nestjs/common';
 export class RoutesResolver {
     container;
     applicationConfig;
@@ -28,14 +27,17 @@ export class RoutesResolver {
         const metadataScanner = new MetadataScanner();
         this.routerExplorer = new RouterExplorer(metadataScanner, this.container, this.injector, this.routerProxy, this.routerExceptionsFilter, this.applicationConfig, this.routePathFactory, graphInspector);
     }
-    resolve(applicationRef, globalPrefix) {
+    resolve(applicationRef, globalPrefix, options = {}) {
         const modules = this.container.getModules();
         modules.forEach(({ controllers, metatype }, moduleName) => {
             const modulePath = this.getModulePathMetadata(metatype);
-            this.registerRouters(controllers, moduleName, globalPrefix, modulePath, applicationRef);
+            this.registerRouters(controllers, moduleName, globalPrefix, modulePath, applicationRef, options);
         });
     }
-    registerRouters(routes, moduleName, globalPrefix, modulePath, applicationRef) {
+    registerResolvedRoute(applicationRef, route) {
+        this.routerExplorer.registerResolvedRoute(applicationRef, route);
+    }
+    registerRouters(routes, moduleName, globalPrefix, modulePath, applicationRef, options = {}) {
         routes.forEach(instanceWrapper => {
             const { metatype } = instanceWrapper;
             const host = this.getHostMetadata(metatype);
@@ -68,7 +70,7 @@ export class RoutesResolver {
                     controllerVersion,
                     versioningOptions,
                 };
-                this.routerExplorer.explore(instanceWrapper, moduleName, applicationRef, host, routePathMetadata);
+                this.routerExplorer.explore(instanceWrapper, moduleName, applicationRef, host, routePathMetadata, options);
             });
         });
     }