@nestjs/core 11.2.1 → 11.2.3

package/helpers/safe-instance-decorator.d.ts

@@ -0,0 +1,10 @@
+type InstanceDecorator = (target: unknown) => unknown;
+/**
+ * Wraps an `instrument.instanceDecorator` so that a decorator throwing on a
+ * given instance (e.g. when inspecting a Proxy whose traps throw outside of
+ * their intended context, such as `nestjs-cls` proxy providers) does not
+ * crash the application bootstrap. The original, undecorated instance is
+ * used instead and a warning is logged.
+ */
+export declare function makeSafeInstanceDecorator(decorator: InstanceDecorator): InstanceDecorator;
+export {};

package/helpers/safe-instance-decorator.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeSafeInstanceDecorator = makeSafeInstanceDecorator;
+const common_1 = require("@nestjs/common");
+const logger = new common_1.Logger('InstrumentLogger');
+/**
+ * Wraps an `instrument.instanceDecorator` so that a decorator throwing on a
+ * given instance (e.g. when inspecting a Proxy whose traps throw outside of
+ * their intended context, such as `nestjs-cls` proxy providers) does not
+ * crash the application bootstrap. The original, undecorated instance is
+ * used instead and a warning is logged.
+ */
+function makeSafeInstanceDecorator(decorator) {
+    return (target) => {
+        try {
+            return decorator(target);
+        }
+        catch (err) {
+            logger.warn(`The "instanceDecorator" function threw an error while decorating an instance (${err?.message ?? err}). The undecorated instance will be used instead.`);
+            return target;
+        }
+    };
+}

package/injector/injector.js

@@ -12,6 +12,7 @@ const runtime_exception_1 = require("../errors/exceptions/runtime.exception");
 const undefined_dependency_exception_1 = require("../errors/exceptions/undefined-dependency.exception");
 const unknown_dependencies_exception_1 = require("../errors/exceptions/unknown-dependencies.exception");
 const barrier_1 = require("../helpers/barrier");
+const safe_instance_decorator_1 = require("../helpers/safe-instance-decorator");
 const constants_2 = require("./constants");
 const inquirer_1 = require("./inquirer");
 const instance_wrapper_1 = require("./instance-wrapper");
@@ -22,7 +23,7 @@ class Injector {
         this.logger = new common_1.Logger('InjectorLogger');
         this.instanceDecorator = (target) => target;
         if (options?.instanceDecorator) {
-            this.instanceDecorator = options.instanceDecorator;
+            this.instanceDecorator = (0, safe_instance_decorator_1.makeSafeInstanceDecorator)(options.instanceDecorator);
         }
     }
     loadPrototype({ token }, collection, contextId = constants_2.STATIC_CONTEXT) {
@@ -266,12 +267,23 @@ class Injector {
              * that eventual lazily created instance will be merged with the prototype
              * instantiated beforehand.
              */
-            instanceHost.donePromise &&
+            if (instanceHost.donePromise) {
                 void instanceHost.donePromise
                     .then(() => this.loadProvider(instanceWrapper, moduleRef, resolutionContext))
                     .catch(err => {
                     instanceWrapper.settlementSignal?.error(err);
                 });
+            }
+            else {
+                /**
+                 * No load has ever been scheduled for this context (e.g., request-scoped
+                 * providers are no longer instantiated during static bootstrap, so a fresh
+                 * durable/request sub-tree host has no inherited `donePromise`).
+                 * Load it now; if a circular dependency is truly in-flight, the nested
+                 * lookup will find this host pending and defer through its `donePromise`.
+                 */
+                await this.loadProvider(instanceWrapper, instanceWrapper.host ?? moduleRef, resolutionContext);
+            }
         }
         if (instanceWrapper.async) {
             const host = instanceWrapper.getInstanceByContextId(this.getContextId(resolutionContext.contextId, instanceWrapper), inquirerId);

package/injector/module.js

@@ -11,6 +11,7 @@ const exceptions_1 = require("../errors/exceptions");
 const context_id_factory_1 = require("../helpers/context-id-factory");
 const get_class_scope_1 = require("../helpers/get-class-scope");
 const is_durable_1 = require("../helpers/is-durable");
+const safe_instance_decorator_1 = require("../helpers/safe-instance-decorator");
 const uuid_factory_1 = require("../inspector/uuid-factory");
 const constants_2 = require("./constants");
 const instance_wrapper_1 = require("./instance-wrapper");
@@ -252,7 +253,9 @@ class Module {
             token: providerToken,
             name: providerToken?.name || providerToken,
             metatype: null,
-            instance: instanceDecorator ? instanceDecorator(value) : value,
+            instance: instanceDecorator
+                ? (0, safe_instance_decorator_1.makeSafeInstanceDecorator)(instanceDecorator)(value)
+                : value,
             isResolved: true,
             async: value instanceof Promise,
             host: this,

package/nest-application.js

@@ -10,6 +10,7 @@ const os_1 = require("os");
 const application_config_1 = require("./application-config");
 const constants_1 = require("./constants");
 const optional_require_1 = require("./helpers/optional-require");
+const safe_instance_decorator_1 = require("./helpers/safe-instance-decorator");
 const injector_1 = require("./injector/injector");
 const container_1 = require("./middleware/container");
 const middleware_module_1 = require("./middleware/middleware-module");
@@ -325,7 +326,8 @@ class NestApplication extends nest_application_context_1.NestApplicationContext
     }
     applyInstanceDecoratorIfRegistered(...instances) {
         if (this.appOptions.instrument?.instanceDecorator) {
-            return instances.map(instance => this.appOptions.instrument.instanceDecorator(instance));
+            const decorate = (0, safe_instance_decorator_1.makeSafeInstanceDecorator)(this.appOptions.instrument.instanceDecorator);
+            return instances.map(instance => decorate(instance));
         }
         return instances;
     }
@@ -333,15 +335,21 @@ class NestApplication extends nest_application_context_1.NestApplicationContext
         if (!this.appOptions.instrument?.instanceDecorator) {
             return args;
         }
-        const [firstArg, secondArg] = args;
-        return [
-            (0, shared_utils_1.isFunction)(firstArg)
-                ? this.appOptions.instrument.instanceDecorator(firstArg)
-                : firstArg,
-            (0, shared_utils_1.isFunction)(secondArg)
-                ? this.appOptions.instrument.instanceDecorator(secondArg)
-                : secondArg,
-        ];
+        const decorate = (0, safe_instance_decorator_1.makeSafeInstanceDecorator)(this.appOptions.instrument.instanceDecorator);
+        // Decorators may return a non-function value for plain middleware
+        // functions; fall back to the original argument so the HTTP adapter
+        // always receives a valid handler.
+        const decorateFunction = (arg) => {
+            if (!(0, shared_utils_1.isFunction)(arg)) {
+                return arg;
+            }
+            const decorated = decorate(arg);
+            return (0, shared_utils_1.isFunction)(decorated) ? decorated : arg;
+        };
+        // Map over the original arguments to preserve arity: appending a trailing
+        // `undefined` to a single-argument `use(fn)` call would make Express 5's
+        // router throw "argument handler must be a function".
+        return args.map(decorateFunction);
     }
 }
 exports.NestApplication = NestApplication;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestjs/core",
-  "version": "11.2.1",
+  "version": "11.2.3",
   "description": "Nest - modern, fast, powerful node.js web framework (@core)",
   "author": "Kamil Mysliwiec",
   "license": "MIT",
@@ -28,7 +28,7 @@
     "uid": "2.0.2"
   },
   "devDependencies": {
-    "@nestjs/common": "11.2.1"
+    "@nestjs/common": "11.2.3"
   },
   "peerDependencies": {
     "@nestjs/common": "^11.0.0",
@@ -49,5 +49,5 @@
       "optional": true
     }
   },
-  "gitHead": "4535f43b4890c9c69c57c5a5a8b49f62c83d1ed6"
+  "gitHead": "2b36ee5fea13dedcedfd9815a9c193b2d21130c1"
 }

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

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

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

@@ -1,7 +0,0 @@
-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/hooks/utils/get-instances-grouped-by-hierarchy-level.d.ts

@@ -1,3 +0,0 @@
-import { InjectionToken } from '@nestjs/common';
-import { InstanceWrapper } from '../../injector/instance-wrapper.js';
-export declare function getInstancesGroupedByHierarchyLevel(...collections: Array<Map<InjectionToken, InstanceWrapper> | Array<[InjectionToken, InstanceWrapper]>>): Map<number, unknown[]>;

package/hooks/utils/get-instances-grouped-by-hierarchy-level.js

@@ -1,27 +0,0 @@
-export function getInstancesGroupedByHierarchyLevel(...collections) {
-    const groupedByHierarchyLevel = new Map();
-    for (const collection of collections) {
-        for (const [_, wrapper] of collection) {
-            if (!wrapper.isDependencyTreeStatic()) {
-                continue;
-            }
-            const level = wrapper.hierarchyLevel;
-            if (!groupedByHierarchyLevel.has(level)) {
-                groupedByHierarchyLevel.set(level, []);
-            }
-            const byHierarchyLevelGroup = groupedByHierarchyLevel.get(level);
-            if (wrapper.isTransient) {
-                const staticTransientInstances = wrapper
-                    .getStaticTransientInstances()
-                    .filter(i => !!i)
-                    .map(i => i.instance);
-                byHierarchyLevelGroup.push(...staticTransientInstances);
-                continue;
-            }
-            if (wrapper.instance) {
-                byHierarchyLevelGroup.push(wrapper.instance);
-            }
-        }
-    }
-    return groupedByHierarchyLevel;
-}

package/hooks/utils/get-sorted-hierarchy-levels.d.ts

@@ -1 +0,0 @@
-export declare function getSortedHierarchyLevels(groups: Map<number, unknown[]>, order?: 'ASC' | 'DESC'): number[];

package/hooks/utils/get-sorted-hierarchy-levels.js

@@ -1,7 +0,0 @@
-export function getSortedHierarchyLevels(groups, order = 'ASC') {
-    const comparator = order === 'ASC'
-        ? (a, b) => a - b
-        : (a, b) => b - a;
-    const levels = Array.from(groups.keys()).sort(comparator);
-    return levels;
-}

package/interfaces/index.d.ts

@@ -1,2 +0,0 @@
-export * from './module-definition.interface.js';
-export * from './module-override.interface.js';

package/interfaces/index.js

@@ -1,2 +0,0 @@
-export * from './module-definition.interface.js';
-export * from './module-override.interface.js';

package/internal.d.ts

@@ -1,38 +0,0 @@
-/**
- * Internal module - not part of the public API.
- * These exports are used by sibling @nestjs packages.
- * Do not depend on these in your application code.
- * @internal
- * @module
- */
-export { RuntimeException } from './errors/exceptions/runtime.exception.js';
-export { InvalidExceptionFilterException } from './errors/exceptions/invalid-exception-filter.exception.js';
-export { MESSAGES } from './constants.js';
-export { DependenciesScanner } from './scanner.js';
-export { Injector, InjectorDependencyContext } from './injector/injector.js';
-export { InstanceLoader } from './injector/instance-loader.js';
-export { InstanceWrapper } from './injector/instance-wrapper.js';
-export { Module } from './injector/module.js';
-export { STATIC_CONTEXT } from './injector/constants.js';
-export { ExecutionContextHost } from './helpers/execution-context-host.js';
-export { ContextUtils, ParamProperties } from './helpers/context-utils.js';
-export { HandlerMetadataStorage } from './helpers/handler-metadata-storage.js';
-export { RouterMethodFactory } from './helpers/router-method-factory.js';
-export { loadAdapter } from './helpers/load-adapter.js';
-export { optionalRequire } from './helpers/optional-require.js';
-export { ParamsMetadata } from './helpers/interfaces/index.js';
-export { GuardsConsumer } from './guards/guards-consumer.js';
-export { GuardsContextCreator } from './guards/guards-context-creator.js';
-export { FORBIDDEN_MESSAGE } from './guards/constants.js';
-export { PipesConsumer } from './pipes/pipes-consumer.js';
-export { PipesContextCreator } from './pipes/pipes-context-creator.js';
-export { ParamsTokenFactory } from './pipes/params-token-factory.js';
-export { InterceptorsConsumer } from './interceptors/interceptors-consumer.js';
-export { InterceptorsContextCreator } from './interceptors/interceptors-context-creator.js';
-export { BaseExceptionFilterContext } from './exceptions/base-exception-filter-context.js';
-export { LegacyRouteConverter } from './router/legacy-route-converter.js';
-export { REQUEST_CONTEXT_ID } from './router/request/request-constants.js';
-export { NoopGraphInspector } from './inspector/noop-graph-inspector.js';
-export { UuidFactory, UuidFactoryMode } from './inspector/uuid-factory.js';
-export { ModuleDefinition } from './interfaces/module-definition.interface.js';
-export { ModuleOverride } from './interfaces/module-override.interface.js';

package/internal.js

@@ -1,46 +0,0 @@
-/**
- * Internal module - not part of the public API.
- * These exports are used by sibling @nestjs packages.
- * Do not depend on these in your application code.
- * @internal
- * @module
- */
-// Errors
-export { RuntimeException } from './errors/exceptions/runtime.exception.js';
-export { InvalidExceptionFilterException } from './errors/exceptions/invalid-exception-filter.exception.js';
-// Constants
-export { MESSAGES } from './constants.js';
-// Scanner
-export { DependenciesScanner } from './scanner.js';
-// Injector
-export { Injector } from './injector/injector.js';
-export { InstanceLoader } from './injector/instance-loader.js';
-export { InstanceWrapper } from './injector/instance-wrapper.js';
-export { Module } from './injector/module.js';
-export { STATIC_CONTEXT } from './injector/constants.js';
-// Helpers
-export { ExecutionContextHost } from './helpers/execution-context-host.js';
-export { ContextUtils } from './helpers/context-utils.js';
-export { HandlerMetadataStorage } from './helpers/handler-metadata-storage.js';
-export { RouterMethodFactory } from './helpers/router-method-factory.js';
-export { loadAdapter } from './helpers/load-adapter.js';
-export { optionalRequire } from './helpers/optional-require.js';
-// Guards
-export { GuardsConsumer } from './guards/guards-consumer.js';
-export { GuardsContextCreator } from './guards/guards-context-creator.js';
-export { FORBIDDEN_MESSAGE } from './guards/constants.js';
-// Pipes
-export { PipesConsumer } from './pipes/pipes-consumer.js';
-export { PipesContextCreator } from './pipes/pipes-context-creator.js';
-export { ParamsTokenFactory } from './pipes/params-token-factory.js';
-// Interceptors
-export { InterceptorsConsumer } from './interceptors/interceptors-consumer.js';
-export { InterceptorsContextCreator } from './interceptors/interceptors-context-creator.js';
-// Exceptions
-export { BaseExceptionFilterContext } from './exceptions/base-exception-filter-context.js';
-// Router
-export { LegacyRouteConverter } from './router/legacy-route-converter.js';
-export { REQUEST_CONTEXT_ID } from './router/request/request-constants.js';
-// Inspector
-export { NoopGraphInspector } from './inspector/noop-graph-inspector.js';
-export { UuidFactory, UuidFactoryMode } from './inspector/uuid-factory.js';

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

@@ -1,32 +0,0 @@
-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

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

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

@@ -1,14 +0,0 @@
-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

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

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

@@ -1,24 +0,0 @@
-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

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

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

@@ -1,71 +0,0 @@
-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

@@ -1,276 +0,0 @@
-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

@@ -1,23 +0,0 @@
-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

@@ -1,59 +0,0 @@
-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];
-    }
-}