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

package/Readme.md

@@ -129,6 +129,7 @@ Nest is an MIT-licensed open source project. It can grow thanks to the sponsors
 <tr>
 <td align="center" valign="middle"><a href="https://solcellsforetag.se/" target="_blank"><img src="https://nestjs.com/img/logos/solcellsforetag-logo.svg" width="140" valign="middle" /></a></td>
 <td align="center" valign="middle"><a href="https://www.route4me.com/" target="_blank"><img src="https://nestjs.com/img/logos/route4me-logo.svg" width="100" valign="middle" /></a></td>
+<td align="center" valign="middle"><a href="https://memory2.co/" target="_blank"><img src="https://images.opencollective.com/memory-squared/bbe37f5/avatar/256.png?height=50" width="50" valign="middle" /></a></td>
 </tr>
 </table>
 

package/application-config.d.ts

@@ -1,7 +1,7 @@
-import type { CanActivate, ExceptionFilter, NestInterceptor, PipeTransform, PreRequestHook, VersioningOptions, WebSocketAdapter } from '@nestjs/common';
+import type { CanActivate, ExceptionFilter, NestInterceptor, PipeTransform, PreRequestHook, RouteConflictPolicy, RouteResolutionStrategy, VersioningOptions, WebSocketAdapter } from '@nestjs/common';
+import type { GlobalPrefixOptions } from '@nestjs/common/internal';
 import { InstanceWrapper } from './injector/instance-wrapper.js';
 import { ExcludeRouteMetadata } from './router/interfaces/exclude-route-metadata.interface.js';
-import type { GlobalPrefixOptions } from '@nestjs/common/internal';
 export declare class ApplicationConfig {
     private ioAdapter;
     private globalPrefix;
@@ -12,6 +12,8 @@ export declare class ApplicationConfig {
     private globalGuards;
     private globalPreRequestHooks;
     private versioningOptions;
+    private routeConflictPolicy;
+    private routeResolutionStrategy;
     private readonly globalRequestPipes;
     private readonly globalRequestFilters;
     private readonly globalRequestInterceptors;
@@ -47,4 +49,8 @@ export declare class ApplicationConfig {
     getGlobalPreRequestHooks(): PreRequestHook[];
     enableVersioning(options: VersioningOptions): void;
     getVersioning(): VersioningOptions | undefined;
+    setRouteConflictPolicy(policy: RouteConflictPolicy | undefined): void;
+    getRouteConflictPolicy(): RouteConflictPolicy | undefined;
+    setRouteResolutionStrategy(strategy: RouteResolutionStrategy | undefined): void;
+    getRouteResolutionStrategy(): RouteResolutionStrategy | undefined;
 }

package/application-config.js

@@ -8,6 +8,8 @@ export class ApplicationConfig {
     globalGuards = [];
     globalPreRequestHooks = [];
     versioningOptions;
+    routeConflictPolicy;
+    routeResolutionStrategy;
     globalRequestPipes = [];
     globalRequestFilters = [];
     globalRequestInterceptors = [];
@@ -109,4 +111,16 @@ export class ApplicationConfig {
     getVersioning() {
         return this.versioningOptions;
     }
+    setRouteConflictPolicy(policy) {
+        this.routeConflictPolicy = policy;
+    }
+    getRouteConflictPolicy() {
+        return this.routeConflictPolicy;
+    }
+    setRouteResolutionStrategy(strategy) {
+        this.routeResolutionStrategy = strategy;
+    }
+    getRouteResolutionStrategy() {
+        return this.routeResolutionStrategy;
+    }
 }

package/errors/exceptions/index.d.ts

@@ -3,6 +3,7 @@ export * from './runtime.exception.js';
 export * from './unknown-element.exception.js';
 export * from './invalid-class-scope.exception.js';
 export * from './invalid-class.exception.js';
+export * from './route-conflict.exception.js';
 export * from './unknown-export.exception.js';
 export * from './unknown-module.exception.js';
 export * from './undefined-forwardref.exception.js';

package/errors/exceptions/index.js

@@ -3,6 +3,7 @@ export * from './runtime.exception.js';
 export * from './unknown-element.exception.js';
 export * from './invalid-class-scope.exception.js';
 export * from './invalid-class.exception.js';
+export * from './route-conflict.exception.js';
 export * from './unknown-export.exception.js';
 export * from './unknown-module.exception.js';
 export * from './undefined-forwardref.exception.js';

package/errors/exceptions/invalid-class-module.exception.d.ts

@@ -1,4 +1,4 @@
 import { RuntimeException } from './runtime.exception.js';
 export declare class InvalidClassModuleException extends RuntimeException {
-    constructor(metatypeUsedAsAModule: any, scope: any[]);
+    constructor(metatypeUsedAsAModule: any, scope: any[], classKind: 'provider' | 'controller' | 'filter');
 }

package/errors/exceptions/invalid-class-module.exception.js

@@ -1,7 +1,7 @@
 import { USING_INVALID_CLASS_AS_A_MODULE_MESSAGE } from '../messages.js';
 import { RuntimeException } from './runtime.exception.js';
 export class InvalidClassModuleException extends RuntimeException {
-    constructor(metatypeUsedAsAModule, scope) {
-        super(USING_INVALID_CLASS_AS_A_MODULE_MESSAGE(metatypeUsedAsAModule, scope));
+    constructor(metatypeUsedAsAModule, scope, classKind) {
+        super(USING_INVALID_CLASS_AS_A_MODULE_MESSAGE(metatypeUsedAsAModule, scope, classKind));
     }
 }

package/errors/exceptions/invalid-module.exception.d.ts

@@ -1,4 +1,4 @@
 import { RuntimeException } from './runtime.exception.js';
 export declare class InvalidModuleException extends RuntimeException {
-    constructor(parentModule: any, index: number, scope: any[]);
+    constructor(parentModule: any, index: number, scope: any[], receivedValue: unknown);
 }

package/errors/exceptions/invalid-module.exception.js

@@ -1,7 +1,7 @@
 import { INVALID_MODULE_MESSAGE } from '../messages.js';
 import { RuntimeException } from './runtime.exception.js';
 export class InvalidModuleException extends RuntimeException {
-    constructor(parentModule, index, scope) {
-        super(INVALID_MODULE_MESSAGE(parentModule, index, scope));
+    constructor(parentModule, index, scope, receivedValue) {
+        super(INVALID_MODULE_MESSAGE(parentModule, index, scope, receivedValue));
     }
 }

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/errors/messages.d.ts

@@ -4,13 +4,16 @@ import { Module } from '../injector/module.js';
 export declare const UNKNOWN_DEPENDENCIES_MESSAGE: (type: string | symbol, unknownDependencyContext: InjectorDependencyContext, moduleRef: Module | undefined) => string;
 export declare const INVALID_MIDDLEWARE_MESSAGE: (text: TemplateStringsArray, name: string) => string;
 export declare const UNDEFINED_FORWARDREF_MESSAGE: (scope: Type<any>[]) => string;
-export declare const INVALID_MODULE_MESSAGE: (parentModule: any, index: number, scope: any[]) => string;
-export declare const USING_INVALID_CLASS_AS_A_MODULE_MESSAGE: (metatypeUsedAsAModule: Type | ForwardReference, scope: any[]) => string;
+export declare const INVALID_MODULE_MESSAGE: (parentModule: any, index: number, scope: any[], receivedValue: unknown) => string;
+export declare const USING_INVALID_CLASS_AS_A_MODULE_MESSAGE: (metatypeUsedAsAModule: Type | ForwardReference, scope: any[], classKind: "provider" | "controller" | "filter") => string;
 export declare const UNDEFINED_MODULE_MESSAGE: (parentModule: any, index: number, scope: any[]) => string;
 export declare const UNKNOWN_EXPORT_MESSAGE: (token: string | symbol | undefined, module: string) => string;
 export declare const INVALID_CLASS_MESSAGE: (text: TemplateStringsArray, value: any) => string;
 export declare const INVALID_CLASS_SCOPE_MESSAGE: (text: TemplateStringsArray, name: string | undefined) => string;
 export declare const UNKNOWN_REQUEST_MAPPING: (metatype: Type) => string;
+export declare const ROUTE_CONFLICT_MESSAGE: (messages: string[]) => string;
+export declare const DUPLICATE_ROUTE_MESSAGE: (method: string, path: string, firstHandlerLabel: string, secondHandlerLabel: string) => string;
+export declare const SHADOWED_ROUTE_MESSAGE: (method: string, shadowedPath: string, shadowedHandlerLabel: string, winnerPath: string, winnerHandlerLabel: string) => string;
 export declare const INVALID_MIDDLEWARE_CONFIGURATION = "An invalid middleware configuration has been passed inside the module 'configure()' method.";
 export declare const UNHANDLED_RUNTIME_EXCEPTION = "Unhandled Runtime Exception.";
 export declare const INVALID_EXCEPTION_FILTER = "Invalid exception filters (@UseFilters()).";

package/errors/messages.js

@@ -111,17 +111,43 @@ export const UNDEFINED_FORWARDREF_MESSAGE = (scope) => `Nest cannot create the m
 (Read more: https://docs.nestjs.com/fundamentals/circular-dependency)
 Scope [${stringifyScope(scope)}]
 `;
-export const INVALID_MODULE_MESSAGE = (parentModule, index, scope) => {
+export const INVALID_MODULE_MESSAGE = (parentModule, index, scope, receivedValue) => {
     const parentModuleName = parentModule?.name || 'module';
+    let formattedValue;
+    let receivedType;
+    if (receivedValue === null) {
+        formattedValue = 'null';
+        receivedType = 'null';
+    }
+    else if (typeof receivedValue === 'string') {
+        formattedValue = `"${receivedValue}"`;
+        receivedType = 'string';
+    }
+    else {
+        formattedValue = String(receivedValue);
+        receivedType = typeof receivedValue;
+    }
     return `Nest cannot create the ${parentModuleName} instance.
 Received an unexpected value at index [${index}] of the ${parentModuleName} "imports" array.
+The received value \`${formattedValue}\` is of type "${receivedType}".
 
 Scope [${stringifyScope(scope)}]`;
 };
-export const USING_INVALID_CLASS_AS_A_MODULE_MESSAGE = (metatypeUsedAsAModule, scope) => {
+export const USING_INVALID_CLASS_AS_A_MODULE_MESSAGE = (metatypeUsedAsAModule, scope, classKind) => {
     const metatypeNameQuote = `"${getInstanceName(metatypeUsedAsAModule)}"`;
-    return `Classes annotated with @Injectable(), @Catch(), and @Controller() decorators must not appear in the "imports" array of a module.
-Please remove ${metatypeNameQuote} (including forwarded occurrences, if any) from all of the "imports" arrays.
+    let hint;
+    switch (classKind) {
+        case 'controller':
+            hint = `${metatypeNameQuote} is decorated with @Controller() and cannot appear in the "imports" array of a module. Please move ${metatypeNameQuote} to the "controllers" array of the importing module instead.`;
+            break;
+        case 'provider':
+            hint = `${metatypeNameQuote} is decorated with @Injectable() and cannot appear in the "imports" array of a module. Please move ${metatypeNameQuote} to the "providers" array of the importing module instead.`;
+            break;
+        case 'filter':
+            hint = `${metatypeNameQuote} is decorated with @Catch() and cannot appear in the "imports" array of a module. Please move ${metatypeNameQuote} to the "providers" array (using the APP_FILTER token to apply it globally) or apply it via @UseFilters() instead.`;
+            break;
+    }
+    return `${hint}
 
 Scope [${stringifyScope(scope)}]
 `;
@@ -155,6 +181,13 @@ export const UNKNOWN_REQUEST_MAPPING = (metatype) => {
         ? `An invalid controller has been detected. "${className}" does not have the @Controller() decorator but it is being listed in the "controllers" array of some module.`
         : `An invalid controller has been detected. Perhaps, one of your controllers is missing the @Controller() decorator.`;
 };
+export const ROUTE_CONFLICT_MESSAGE = (messages) => [
+    'Conflicting HTTP routes detected:',
+    ...messages.map(message => `  - ${message}`),
+    `Adjust route declarations or relax the 'routeConflictPolicy' option passed to NestFactory.create() to allow the application to start.`,
+].join('\n');
+export const DUPLICATE_ROUTE_MESSAGE = (method, path, firstHandlerLabel, secondHandlerLabel) => `Duplicate route: ${method} ${path} is registered by both ${firstHandlerLabel} and ${secondHandlerLabel}.`;
+export const SHADOWED_ROUTE_MESSAGE = (method, shadowedPath, shadowedHandlerLabel, winnerPath, winnerHandlerLabel) => `Route ${method} ${shadowedPath} (${shadowedHandlerLabel}) is shadowed by ${method} ${winnerPath} (${winnerHandlerLabel}). The first-registered route will match all matching requests on order-sensitive adapters.`;
 export const INVALID_MIDDLEWARE_CONFIGURATION = `An invalid middleware configuration has been passed inside the module 'configure()' method.`;
 export const UNHANDLED_RUNTIME_EXCEPTION = `Unhandled Runtime Exception.`;
 export const INVALID_EXCEPTION_FILTER = `Invalid exception filters (@UseFilters()).`;

package/injector/injector.d.ts

@@ -73,9 +73,9 @@ export declare class Injector {
     resolveConstructorParams<T>(wrapper: InstanceWrapper<T>, moduleRef: Module, inject: InjectorDependency[] | undefined, callback: (args: unknown[], depth?: number) => void | Promise<void>, resolutionContext?: ResolutionContext, parentInquirer?: InstanceWrapper): Promise<void>;
     getClassDependencies<T>(wrapper: InstanceWrapper<T>): [InjectorDependency[], number[]];
     getFactoryProviderDependencies<T>(wrapper: InstanceWrapper<T>): [InjectorDependency[], number[]];
-    reflectConstructorParams<T>(type: Type<T>): any[];
-    reflectOptionalParams<T>(type: Type<T>): any[];
-    reflectSelfParams<T>(type: Type<T>): any[];
+    reflectConstructorParams(type: Type<unknown> | Function): any[];
+    reflectOptionalParams(type: Type<unknown> | Function): any[];
+    reflectSelfParams(type: Type<unknown> | Function): any[];
     resolveSingleParam<T>(wrapper: InstanceWrapper<T>, param: Type<any> | string | symbol, dependencyContext: InjectorDependencyContext, moduleRef: Module, resolutionContext?: ResolutionContext, keyOrIndex?: symbol | string | number): Promise<InstanceWrapper<any>>;
     resolveParamToken<T>(wrapper: InstanceWrapper<T>, param: Type<any> | string | symbol | ForwardReference): any;
     resolveComponentWrapper<T>(moduleRef: Module, token: InjectionToken, dependencyContext: InjectorDependencyContext, wrapper: InstanceWrapper<T>, resolutionContext?: ResolutionContext, keyOrIndex?: symbol | string | number): Promise<InstanceWrapper>;
@@ -107,6 +107,7 @@ export declare class Injector {
     private getEffectiveInquirerId;
     private getStaticTransientResolutionContext;
     private getEffectiveResolutionContext;
+    private hasDenseCtorMetadata;
     private resolveScopedComponentHost;
     private isInquirerRequest;
     private isInquirer;

package/injector/injector.js

@@ -72,6 +72,9 @@ export class Injector {
                 settlementSignal.complete();
             };
             await this.resolveConstructorParams(wrapper, moduleRef, inject, callback, localResolutionContext, resolutionContext.inquirer);
+            if (!instanceHost.isResolved) {
+                settlementSignal.complete();
+            }
         }
         catch (err) {
             wrapper.removeInstanceByContextId(this.getContextId(resolutionContext.contextId, wrapper), inquirerId);
@@ -114,7 +117,8 @@ export class Injector {
     }
     async resolveConstructorParams(wrapper, moduleRef, inject, callback, resolutionContext = { contextId: STATIC_CONTEXT }, parentInquirer) {
         const metadata = wrapper.getCtorMetadata();
-        if (metadata && resolutionContext.contextId !== STATIC_CONTEXT) {
+        if (resolutionContext.contextId !== STATIC_CONTEXT &&
+            this.hasDenseCtorMetadata(wrapper, inject, metadata)) {
             const deps = await this.loadCtorMetadata(metadata, resolutionContext.contextId, resolutionContext.inquirer, parentInquirer);
             return callback(deps);
         }
@@ -501,7 +505,6 @@ export class Injector {
             wrapper.isExplicitlyRequested(resolutionContext.contextId, resolutionContext.inquirer));
     }
     shouldSkipProviderLoading(wrapper, resolutionContext) {
-        const isSnapshotGraphCompilation = !!this.options?.snapshot;
         const isStaticContext = resolutionContext.contextId === STATIC_CONTEXT;
         const hasNoInquirer = !resolutionContext.inquirer;
         const isTopLevelStaticTransientOrRequestProvider = hasNoInquirer && (wrapper.isTransient || wrapper.scope === Scope.REQUEST);
@@ -510,7 +513,7 @@ export class Injector {
         const shouldSkipForStaticBootstrap = isStaticContext &&
             (isTopLevelStaticTransientOrRequestProvider ||
                 isStaticInquirerOutsideResolutionContext);
-        return !isSnapshotGraphCompilation && shouldSkipForStaticBootstrap;
+        return shouldSkipForStaticBootstrap;
     }
     /**
      * For nested TRANSIENT dependencies (TRANSIENT -> TRANSIENT) in non-static contexts,
@@ -554,6 +557,28 @@ export class Injector {
     getEffectiveResolutionContext(dependency, resolutionContext, parentInquirer) {
         return this.createResolutionContext(resolutionContext.contextId, this.getEffectiveInquirer(dependency, resolutionContext, parentInquirer), this.getEffectiveInquirerId(dependency, resolutionContext, parentInquirer));
     }
+    hasDenseCtorMetadata(wrapper, inject, metadata) {
+        if (!metadata) {
+            return false;
+        }
+        // The fast path requires a fully populated metadata array.
+        // While another request is still registering dependency metadata,
+        // sparse entries here would feed request-scoped factories `undefined`.
+        const expectedDepsLength = !isNil(inject)
+            ? inject.length
+            : wrapper.metatype
+                ? this.reflectConstructorParams(wrapper.metatype).length
+                : 0;
+        if (metadata.length !== expectedDepsLength) {
+            return false;
+        }
+        for (let index = 0; index < expectedDepsLength; index++) {
+            if (metadata[index] === undefined) {
+                return false;
+            }
+        }
+        return true;
+    }
     resolveScopedComponentHost(item, contextId, inquirer, parentInquirer) {
         return this.isInquirerRequest(item, parentInquirer)
             ? parentInquirer

package/injector/instance-wrapper.d.ts

@@ -94,6 +94,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

@@ -6,6 +6,7 @@ import { STATIC_CONTEXT } from './constants.js';
 import { isClassProvider, isFactoryProvider, isValueProvider, } from './helpers/provider-classifier.js';
 export const INSTANCE_METADATA_SYMBOL = Symbol.for('instance_metadata:cache');
 export const INSTANCE_ID_SYMBOL = Symbol.for('instance_metadata:id');
+const dependencyTreeParents = new WeakMap();
 export class InstanceWrapper {
     name;
     token;
@@ -121,6 +122,8 @@ export class InstanceWrapper {
             this[INSTANCE_METADATA_SYMBOL].dependencies = [];
         }
         this[INSTANCE_METADATA_SYMBOL].dependencies[index] = wrapper;
+        this.registerDependencyTreeParent(wrapper);
+        this.resetDependencyTreeState();
     }
     getCtorMetadata() {
         return this[INSTANCE_METADATA_SYMBOL].dependencies;
@@ -133,6 +136,8 @@ export class InstanceWrapper {
             key,
             wrapper,
         });
+        this.registerDependencyTreeParent(wrapper);
+        this.resetDependencyTreeState();
     }
     getPropertiesMetadata() {
         return this[INSTANCE_METADATA_SYMBOL].properties;
@@ -142,6 +147,8 @@ export class InstanceWrapper {
             this[INSTANCE_METADATA_SYMBOL].enhancers = [];
         }
         this[INSTANCE_METADATA_SYMBOL].enhancers.push(wrapper);
+        this.registerDependencyTreeParent(wrapper);
+        this.resetDependencyTreeState();
     }
     getEnhancersMetadata() {
         return this[INSTANCE_METADATA_SYMBOL].enhancers;
@@ -333,6 +340,24 @@ export class InstanceWrapper {
     isNewable() {
         return 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[INSTANCE_ID_SYMBOL])) {
+            return;
+        }
+        lookupRegistry.add(this[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 prepareClose(): Promise<void>;
     protected dispose(): Promise<void>;

package/nest-application.js

@@ -12,6 +12,8 @@ import { NestApplicationContext } from './nest-application-context.js';
 import { RoutesResolver } from './router/routes-resolver.js';
 import { Logger } from '@nestjs/common';
 import { loadPackage, loadPackageCached, tryLoadPackage, addLeadingSlash, isFunction, isObject, isString, } from '@nestjs/common/internal';
+import { RouteConflictDetector } from './router/route-conflict-detector.js';
+import { RouteSpecificitySorter } from './router/route-specificity-sorter.js';
 /**
  * @publicApi
  */
@@ -30,11 +32,14 @@ export class NestApplication extends NestApplicationContext {
     microservices = [];
     httpServer;
     isListening = false;
+    isWsModuleRegistered = false;
     constructor(container, httpAdapter, config, graphInspector, appOptions = {}) {
         super(container, appOptions);
         this.httpAdapter = httpAdapter;
         this.config = config;
         this.graphInspector = graphInspector;
+        this.config.setRouteConflictPolicy(appOptions.routeConflictPolicy);
+        this.config.setRouteResolutionStrategy(appOptions.routeResolutionStrategy);
         this.selectContextModule();
         this.registerHttpServer();
         this.injector = new Injector({
@@ -92,6 +97,7 @@ export class NestApplication extends NestApplicationContext {
             return;
         }
         this.socketModule.register(this.container, this.config, this.graphInspector, this.appOptions, this.httpServer);
+        this.isWsModuleRegistered = true;
     }
     async init() {
         if (this.isInitialized) {
@@ -124,7 +130,74 @@ export class NestApplication extends NestApplicationContext {
         await this.registerMiddleware(this.httpAdapter);
         const prefix = this.config.getGlobalPrefix();
         const basePath = addLeadingSlash(prefix);
-        this.routesResolver.resolve(this.httpAdapter, basePath);
+        const conflictPolicy = this.config.getRouteConflictPolicy();
+        const resolutionStrategy = this.config.getRouteResolutionStrategy();
+        const adapterIsOrderSensitive = this.httpAdapter.isRouteOrderSensitive?.() ?? true;
+        const shouldSortBySpecificity = resolutionStrategy === 'specificity' && adapterIsOrderSensitive;
+        // Adapters that are not order-sensitive (e.g. Fastify) currently
+        // also reject duplicate (method, URL) registrations synchronously
+        // from the underlying router. Treat the two properties as one
+        // signal until a separate capability flag is introduced.
+        const adapterRejectsDuplicates = !adapterIsOrderSensitive;
+        if (!conflictPolicy && !shouldSortBySpecificity) {
+            this.routesResolver.resolve(this.httpAdapter, basePath);
+            return;
+        }
+        // Defer registration whenever we collect routes for diagnostics or
+        // re-ordering. In particular, when a conflict policy is set we
+        // must run detection *before* the adapter sees any route, because
+        // duplicate-rejecting adapters like Fastify throw synchronously
+        // from `instance.route()` and would short-circuit both the resolve
+        // loop and the aggregated `RouteConflictException`.
+        const resolvedRoutes = [];
+        this.routesResolver.resolve(this.httpAdapter, basePath, {
+            onRouteResolved: route => resolvedRoutes.push(route),
+            deferRegistration: true,
+        });
+        // Sort before conflict detection so that winner/shadowed pairs in every
+        // conflict record reflect actual adapter registration order. Without this,
+        // the reported winner could be the declaration-first (less-specific) route
+        // even though the sorted-first (more-specific) route is what really wins.
+        const orderedRoutes = shouldSortBySpecificity
+            ? RouteSpecificitySorter.sort(resolvedRoutes)
+            : resolvedRoutes;
+        const routesToSkip = new Set();
+        if (conflictPolicy) {
+            const filteredPolicy = adapterIsOrderSensitive
+                ? conflictPolicy
+                : { duplicate: conflictPolicy.duplicate };
+            const conflicts = RouteConflictDetector.detect(orderedRoutes, this.config.getVersioning());
+            // On adapters that reject duplicate registrations the policy
+            // cannot be honoured by simply logging — the adapter would
+            // throw on the second `instance.route()` call. Drop the
+            // shadowed route of every duplicate conflict so the detector
+            // (not the adapter) decides which one wins. The detector
+            // always picks the earlier-registered route as the winner.
+            if (adapterRejectsDuplicates) {
+                conflicts.forEach(conflict => {
+                    if (conflict.kind === 'duplicate') {
+                        routesToSkip.add(conflict.shadowed);
+                    }
+                });
+            }
+            // When specificity sorting is active, shadow conflicts where the sort
+            // promoted the winner (declared later but more specific) are resolved
+            // at runtime: the more-specific route is first-registered and handles
+            // its requests, the less-specific route handles the rest. Filtering
+            // these out prevents shadow: 'error' from aborting an app whose routes
+            // work correctly after specificity ordering. Genuine shadows — where the
+            // winner was already first in declaration order and the sort did not help
+            // — are kept and still apply the configured policy.
+            const effectiveConflicts = shouldSortBySpecificity
+                ? RouteConflictDetector.filterSortResolvedShadows(conflicts, resolvedRoutes)
+                : conflicts;
+            RouteConflictDetector.handle(effectiveConflicts, filteredPolicy, this.logger);
+        }
+        orderedRoutes.forEach(route => {
+            if (routesToSkip.has(route))
+                return;
+            this.routesResolver.registerResolvedRoute(this.httpAdapter, route);
+        });
     }
     async registerRouterHooks() {
         this.routesResolver.registerNotFoundHandler();
@@ -260,6 +333,9 @@ export class NestApplication extends 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": "12.0.0-alpha.3",
+  "version": "12.0.0-alpha.5",
   "description": "Nest - modern, fast, powerful node.js web framework (@core)",
   "author": "Kamil Mysliwiec",
   "license": "MIT",
@@ -47,7 +47,7 @@
     "uid": "2.0.2"
   },
   "devDependencies": {
-    "@nestjs/common": "^12.0.0-alpha.3"
+    "@nestjs/common": "^12.0.0-alpha.5"
   },
   "peerDependencies": {
     "@nestjs/common": "^11.0.0",
@@ -68,5 +68,5 @@
       "optional": true
     }
   },
-  "gitHead": "1c9d5482a65a446ede8dd1195bfa1cbbc16e0857"
+  "gitHead": "d91b72cc9567e6a09e3ad6075b2fb801e71adfc8"
 }

package/router/interfaces/index.d.ts

@@ -1 +1,4 @@
+export * from './resolved-route.interface.js';
+export * from './route-conflict.interface.js';
+export * from './route-resolution-options.interface.js';
 export * from './routes.interface.js';

package/router/interfaces/index.js

@@ -1 +1,4 @@
+export * from './resolved-route.interface.js';
+export * from './route-conflict.interface.js';
+export * from './route-resolution-options.interface.js';
 export * from './routes.interface.js';

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/resolver.interface.d.ts

@@ -1,5 +1,9 @@
+import { HttpServer } from '@nestjs/common';
+import { ResolvedRoute } from './resolved-route.interface.js';
+import { RouteResolutionOptions } from './route-resolution-options.interface.js';
 export interface Resolver {
-    resolve(instance: any, basePath: string): void;
+    resolve(applicationRef: HttpServer, basePath: string, options?: RouteResolutionOptions): void;
+    registerResolvedRoute(applicationRef: HttpServer, route: ResolvedRoute): void;
     registerNotFoundHandler(): void;
     registerExceptionHandler(): void;
 }

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 {};