@nestjs/core 12.0.0-alpha.4 → 12.0.0-alpha.6

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);
         }
@@ -325,16 +329,12 @@ export class Injector {
             this.printFoundInModuleLog(name, relatedModule);
             instanceWrapperRef = providers.get(name);
             this.addDependencyMetadata(keyOrIndex, wrapper, instanceWrapperRef);
-            const inquirerId = this.getContextInquirerId(resolutionContext);
-            const instanceHost = instanceWrapperRef.getInstanceByContextId(this.getContextId(resolutionContext.contextId, instanceWrapperRef), inquirerId);
-            if (!instanceHost.isResolved && !instanceWrapperRef.forwardRef) {
-                /*
-                 * Provider will be loaded shortly in resolveComponentHost() once we pass the current
-                 * Barrier. We cannot load it here because doing so could incorrectly evaluate the
-                 * staticity of the dependency tree and lead to undefined / null injection.
-                 */
-                break;
-            }
+            /*
+             * Stop at the first direct export match. Continuing when the provider is
+             * already resolved would let a later import (e.g. a global forRoot module)
+             * override an explicit forFeature import for the same token.
+             */
+            break;
         }
         return instanceWrapperRef;
     }
@@ -501,7 +501,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 +509,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 +553,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/injector/internal-core-module/internal-core-module-factory.js

@@ -15,7 +15,7 @@ export class InternalCoreModuleFactory {
                 timestamp: false,
             });
             const injector = new Injector({
-                preview: container.contextOptions?.preview,
+                preview: container.contextOptions?.preview ?? false,
                 instanceDecorator: container.contextOptions?.instrument?.instanceDecorator,
             });
             const instanceLoader = new InstanceLoader(container, injector, graphInspector, logger);

package/injector/module.d.ts

@@ -35,6 +35,12 @@ export declare class Module {
     get entryProviders(): Array<InstanceWrapper<Injectable>>;
     get exports(): Set<InjectionToken>;
     get instance(): NestModule;
+    /**
+     * Modules are registered in the container before they are scanned (dynamic
+     * `imports` are pre-registered by `NestContainer#addDynamicMetadata`), so
+     * registration alone does not imply the module was ever instantiated.
+     */
+    get isInstantiated(): boolean;
     get metatype(): Type<any>;
     get distance(): number;
     set distance(value: number);

package/injector/module.js

@@ -83,6 +83,14 @@ export class Module {
         const moduleRef = this._providers.get(this._metatype);
         return moduleRef.instance;
     }
+    /**
+     * Modules are registered in the container before they are scanned (dynamic
+     * `imports` are pre-registered by `NestContainer#addDynamicMetadata`), so
+     * registration alone does not imply the module was ever instantiated.
+     */
+    get isInstantiated() {
+        return !isNil(this._providers.get(this._metatype)?.instance);
+    }
     get metatype() {
         return this._metatype;
     }

package/interceptors/interceptors-consumer.js

@@ -1,11 +1,11 @@
 import { AsyncResource } from 'async_hooks';
-import { Observable, defer, from as fromPromise } from 'rxjs';
-import { mergeAll, switchMap } from 'rxjs/operators';
+import { Observable, defer, from } from 'rxjs';
+import { mergeAll } from 'rxjs/operators';
 import { ExecutionContextHost } from '../helpers/execution-context-host.js';
 import { isEmptyArray } from '@nestjs/common/internal';
 export class InterceptorsConsumer {
     async intercept(interceptors, args, instance, callback, next, type) {
-        if (isEmptyArray(interceptors)) {
+        if (!interceptors || isEmptyArray(interceptors)) {
             return next();
         }
         const context = this.createContext(args, instance, callback);
@@ -25,9 +25,34 @@ export class InterceptorsConsumer {
         return new ExecutionContextHost(args, instance.constructor, callback);
     }
     transformDeferred(next) {
-        return fromPromise(next()).pipe(switchMap(res => {
-            const isDeferred = res instanceof Promise || res instanceof Observable;
-            return isDeferred ? res : Promise.resolve(res);
-        }));
+        // Call next() eagerly here — this method is invoked inside
+        // defer(AsyncResource.bind(...)), so the async context (e.g. AsyncLocalStorage)
+        // is correctly inherited. Deferring next() into the subscriber function would
+        // lose that context because the subscriber is called outside the bound scope.
+        const nextPromise = next();
+        return new Observable(subscriber => {
+            let innerSub;
+            nextPromise
+                .then(res => {
+                if (subscriber.closed) {
+                    // The outer subscription was torn down (e.g. an SSE client disconnect)
+                    // before the async handler resolved. Do not subscribe the producer
+                    // Observable after the consumer has already gone away — subscribing
+                    // only to unsubscribe in the same tick would start producer side
+                    // effects just to immediately abort them.
+                    return;
+                }
+                const isDeferred = res instanceof Promise || res instanceof Observable;
+                innerSub = from(isDeferred ? res : Promise.resolve(res)).subscribe(subscriber);
+            })
+                .catch(err => {
+                if (!subscriber.closed) {
+                    subscriber.error(err);
+                }
+            });
+            return () => {
+                innerSub?.unsubscribe();
+            };
+        });
     }
 }

package/middleware/builder.js

@@ -74,7 +74,11 @@ export class MiddlewareBuilder {
                 .map(route => ({
                 method: route.method,
                 path: route.path,
-                regex: new RegExp('^(' + route.path.replace(regexMatchParams, wildcard) + ')$', 'g'),
+                // No `g` flag: each regex is reused across every route below, and a
+                // global regex advances `lastIndex` on a match, so the next `test()`
+                // would resume mid-string and fail the `^` anchor. The pattern is
+                // anchored and only used with `test()`, so `g` buys nothing anyway.
+                regex: new RegExp('^(' + route.path.replace(regexMatchParams, wildcard) + ')$'),
             }));
             return routes.filter(route => {
                 const isOverlapped = (item) => {

package/nest-application-context.js

@@ -164,7 +164,7 @@ export class NestApplicationContext extends AbstractInstanceResolver {
      * @returns {this} The Nest application context instance
      */
     enableShutdownHooks(signals = [], options = {}) {
-        if (isEmptyArray(signals)) {
+        if (!signals || isEmptyArray(signals)) {
             signals = Object.values(ShutdownSignal);
         }
         else {

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>;
@@ -31,7 +32,7 @@ export declare class NestApplication extends NestApplicationContext<NestApplicat
     applyOptions(): void;
     createServer<T = any>(): T;
     registerModules(): Promise<void>;
-    registerWsModule(): void;
+    registerWsModule(): Promise<void>;
     init(): Promise<this>;
     registerParserMiddleware(): void;
     registerRouter(): Promise<void>;
@@ -67,6 +68,7 @@ export declare class NestApplication extends NestApplicationContext<NestApplicat
     private getProtocol;
     private registerMiddleware;
     private applyInstanceDecoratorIfRegistered;
+    private applyFunctionDecoratorIfRegistered;
     private loadSocketModule;
     private loadMicroservicesModule;
 }

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({
@@ -80,18 +85,19 @@ export class NestApplication extends NestApplicationContext {
         return this.httpAdapter.getHttpServer();
     }
     async registerModules() {
-        this.registerWsModule();
+        await this.registerWsModule();
         if (this.microservicesModule) {
             this.microservicesModule.register(this.container, this.graphInspector, this.config, this.appOptions);
             this.microservicesModule.setupClients(this.container);
         }
         await this.middlewareModule.register(this.middlewareContainer, this.container, this.config, this.injector, this.httpAdapter, this.graphInspector, this.appOptions);
     }
-    registerWsModule() {
+    async registerWsModule() {
         if (!this.socketModule) {
             return;
         }
-        this.socketModule.register(this.container, this.config, this.graphInspector, this.appOptions, this.httpServer);
+        await this.socketModule.register(this.container, this.config, this.graphInspector, this.appOptions, this.httpServer);
+        this.isWsModuleRegistered = true;
     }
     async init() {
         if (this.isInitialized) {
@@ -124,14 +130,81 @@ 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();
         this.routesResolver.registerExceptionHandler();
     }
     connectMicroservice(microserviceOptions, hybridAppOptions = {}) {
-        const { NestMicroservice } = loadPackageCached('@nestjs/microservices');
+        const { NestMicroservice } = loadPackageCached('@nestjs/microservices', 'NestFactory');
         const { inheritAppConfig } = hybridAppOptions;
         const applicationConfig = inheritAppConfig
             ? this.config
@@ -157,7 +230,7 @@ export class NestApplication extends NestApplicationContext {
         return this;
     }
     use(...args) {
-        this.httpAdapter.use(...args);
+        this.httpAdapter.use(...this.applyFunctionDecoratorIfRegistered(args));
         return this;
     }
     useBodyParser(...args) {
@@ -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;
     }
@@ -339,6 +415,20 @@ export class NestApplication extends NestApplicationContext {
         }
         return instances;
     }
+    applyFunctionDecoratorIfRegistered(args) {
+        if (!this.appOptions.instrument?.instanceDecorator) {
+            return args;
+        }
+        const [firstArg, secondArg] = args;
+        return [
+            isFunction(firstArg)
+                ? this.appOptions.instrument.instanceDecorator(firstArg)
+                : firstArg,
+            isFunction(secondArg)
+                ? this.appOptions.instrument.instanceDecorator(secondArg)
+                : secondArg,
+        ];
+    }
     async loadSocketModule() {
         if (!this.socketModule) {
             const socketModule = await optionalRequire('@nestjs/websockets/socket-module', () => import('@nestjs/websockets/socket-module.js'));

package/package.json

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

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

package/router/legacy-route-converter.d.ts

@@ -12,5 +12,5 @@ export declare class LegacyRouteConverter {
         logs?: boolean;
     }): string;
     static printError(route: string): void;
-    static printWarning(route: string): void;
+    static printWarning(route: string, convertedRoute?: string): void;
 }