@nestjs/core 12.0.1 → 12.0.3

package/adapters/http-adapter.d.ts

@@ -2,83 +2,450 @@ import type { HttpServer, RequestMethod, VersioningOptions } from '@nestjs/commo
 import type { RequestHandler, VersionValue } from '@nestjs/common/internal';
 import type { NestApplicationOptions } from '@nestjs/common';
 /**
+ * Base class for HTTP platform adapters (see `ExpressAdapter` and
+ * `FastifyAdapter` for reference implementations).
+ *
+ * It implements the {@link HttpServer} contract that the Nest core relies on,
+ * and that interface is where each method's calling conventions are
+ * documented: when the core invokes it, with which arguments, and what it
+ * expects back. This class only adds:
+ *
+ * - default implementations that delegate to the wrapped framework
+ *   `instance` (`use()`, the HTTP-verb methods, `listen()`) or are inert
+ *   (`init()`, `normalizePath()`, `mapException()`, `beforeClose()`, the
+ *   `setOn*Hook()` setters);
+ * - storage for the native server (`httpServer`) and the framework instance
+ *   (`instance`), with their accessors;
+ * - the introspection hooks used by instrumentation tooling.
+ *
+ * Every remaining {@link HttpServer} member is declared abstract here, even
+ * the ones the interface marks optional, so subclasses cannot forget them.
+ * `setBaseViewsDir()`, `useBodyParser()` and `isRouteOrderSensitive()` are
+ * not declared on this class; implement them when the platform supports
+ * them (see {@link HttpServer} for what the core does when they are absent).
+ *
+ * Keep in mind that the core also reads and writes properties of the request
+ * object (`body`, `params`, `query`, `headers`, ...), that Server-Sent Events
+ * write directly to the Node.js response, and that `app.listen()` and the
+ * WebSocket adapters use the value returned by
+ * {@link AbstractHttpAdapter.getHttpServer} as a Node.js `net.Server`; see the
+ * {@link HttpServer} documentation for details.
+ *
+ * @typeParam TServer - Type of the native HTTP server stored in `httpServer`
+ * (e.g. `http.Server | https.Server`).
+ * @typeParam TRequest - Type of the framework request object.
+ * @typeParam TResponse - Type of the framework response object.
+ *
+ * @see [HTTP adapter](https://docs.nestjs.com/faq/http-adapter)
+ *
  * @publicApi
  */
 export declare abstract class AbstractHttpAdapter<TServer = any, TRequest = any, TResponse = any> implements HttpServer<TRequest, TResponse> {
     protected instance?: any | undefined;
+    /**
+     * Native HTTP server created by {@link AbstractHttpAdapter.initHttpServer}
+     * and returned by {@link AbstractHttpAdapter.getHttpServer}.
+     */
     protected httpServer: TServer;
+    /**
+     * Callback registered through
+     * {@link AbstractHttpAdapter.setOnRouteTriggered}, if any.
+     */
     protected onRouteTriggered: ((requestMethod: RequestMethod, path: string) => void) | undefined;
+    /**
+     * @param instance The framework application instance to delegate to (e.g.
+     * an Express `Application`). Subclasses typically create a default one
+     * when none is given.
+     */
     constructor(instance?: any | undefined);
+    /**
+     * Asynchronous setup hook, awaited by `NestFactory.create()` and again by
+     * `app.init()`, so overrides must be idempotent. No-op by default.
+     *
+     * @see {@link HttpServer.init}
+     */
     init(): Promise<void>;
+    /**
+     * Registers a global middleware by delegating to `instance.use(...args)`.
+     *
+     * @see {@link HttpServer.use}
+     */
     use(...args: any[]): any;
+    /**
+     * Registers a `GET` route by delegating to `instance.get(...args)`.
+     *
+     * @see {@link HttpServer.get}
+     */
     get(handler: RequestHandler): any;
     get(path: any, handler: RequestHandler): any;
+    /**
+     * Registers a `POST` route by delegating to `instance.post(...args)`.
+     *
+     * @see {@link HttpServer.post}
+     */
     post(handler: RequestHandler): any;
     post(path: any, handler: RequestHandler): any;
+    /**
+     * Registers a `HEAD` route by delegating to `instance.head(...args)`.
+     *
+     * @see {@link HttpServer.head}
+     */
     head(handler: RequestHandler): any;
     head(path: any, handler: RequestHandler): any;
+    /**
+     * Registers a `DELETE` route by delegating to `instance.delete(...args)`.
+     *
+     * @see {@link HttpServer.delete}
+     */
     delete(handler: RequestHandler): any;
     delete(path: any, handler: RequestHandler): any;
+    /**
+     * Registers a `PUT` route by delegating to `instance.put(...args)`.
+     *
+     * @see {@link HttpServer.put}
+     */
     put(handler: RequestHandler): any;
     put(path: any, handler: RequestHandler): any;
+    /**
+     * Registers a `PATCH` route by delegating to `instance.patch(...args)`.
+     *
+     * @see {@link HttpServer.patch}
+     */
     patch(handler: RequestHandler): any;
     patch(path: any, handler: RequestHandler): any;
+    /**
+     * Registers a WebDAV `PROPFIND` route by delegating to
+     * `instance.propfind(...args)`. Override when the framework exposes the
+     * verb under a different API.
+     *
+     * @see {@link HttpServer.propfind}
+     */
     propfind(handler: RequestHandler): any;
     propfind(path: any, handler: RequestHandler): any;
+    /**
+     * Registers a WebDAV `PROPPATCH` route by delegating to
+     * `instance.proppatch(...args)`. Override when the framework exposes the
+     * verb under a different API.
+     *
+     * @see {@link HttpServer.proppatch}
+     */
     proppatch(handler: RequestHandler): any;
     proppatch(path: any, handler: RequestHandler): any;
+    /**
+     * Registers a WebDAV `MKCOL` route by delegating to
+     * `instance.mkcol(...args)`. Override when the framework exposes the verb
+     * under a different API.
+     *
+     * @see {@link HttpServer.mkcol}
+     */
     mkcol(handler: RequestHandler): any;
     mkcol(path: any, handler: RequestHandler): any;
+    /**
+     * Registers a WebDAV `COPY` route by delegating to
+     * `instance.copy(...args)`. Override when the framework exposes the verb
+     * under a different API.
+     *
+     * @see {@link HttpServer.copy}
+     */
     copy(handler: RequestHandler): any;
     copy(path: any, handler: RequestHandler): any;
+    /**
+     * Registers a WebDAV `MOVE` route by delegating to
+     * `instance.move(...args)`. Override when the framework exposes the verb
+     * under a different API.
+     *
+     * @see {@link HttpServer.move}
+     */
     move(handler: RequestHandler): any;
     move(path: any, handler: RequestHandler): any;
+    /**
+     * Registers a WebDAV `LOCK` route by delegating to
+     * `instance.lock(...args)`. Override when the framework exposes the verb
+     * under a different API.
+     *
+     * @see {@link HttpServer.lock}
+     */
     lock(handler: RequestHandler): any;
     lock(path: any, handler: RequestHandler): any;
+    /**
+     * Registers a WebDAV `UNLOCK` route by delegating to
+     * `instance.unlock(...args)`. Override when the framework exposes the verb
+     * under a different API.
+     *
+     * @see {@link HttpServer.unlock}
+     */
     unlock(handler: RequestHandler): any;
     unlock(path: any, handler: RequestHandler): any;
+    /**
+     * Registers a route for every HTTP method by delegating to
+     * `instance.all(...args)`.
+     *
+     * @see {@link HttpServer.all}
+     */
     all(handler: RequestHandler): any;
     all(path: any, handler: RequestHandler): any;
+    /**
+     * Registers a `SEARCH` route by delegating to `instance.search(...args)`.
+     * Override when the framework exposes the verb under a different API.
+     *
+     * @see {@link HttpServer.search}
+     */
     search(handler: RequestHandler): any;
     search(path: any, handler: RequestHandler): any;
+    /**
+     * Registers a `QUERY` route by delegating to `instance.query(...args)`.
+     * Override when the framework exposes the verb under a different API.
+     *
+     * @see {@link HttpServer.query}
+     */
     query(handler: RequestHandler): any;
     query(path: any, handler: RequestHandler): any;
+    /**
+     * Registers an `OPTIONS` route by delegating to
+     * `instance.options(...args)`.
+     *
+     * @see {@link HttpServer.options}
+     */
     options(handler: RequestHandler): any;
     options(path: any, handler: RequestHandler): any;
+    /**
+     * Starts listening by delegating to
+     * `instance.listen(port, hostname, callback)`. The core always passes its
+     * own callback as the last argument and expects it to be invoked once the
+     * server is bound, or with an `Error` on failure. Override when the
+     * framework instance does not expose a Node-style `listen()`, e.g. to call
+     * `httpServer.listen()` instead.
+     *
+     * @see {@link HttpServer.listen}
+     */
     listen(port: string | number, callback?: () => void): any;
     listen(port: string | number, hostname: string, callback?: () => void): any;
+    /**
+     * Returns the native HTTP server stored by
+     * {@link AbstractHttpAdapter.initHttpServer} (or
+     * {@link AbstractHttpAdapter.setHttpServer}).
+     *
+     * @see {@link HttpServer.getHttpServer}
+     */
     getHttpServer(): TServer;
+    /**
+     * Replaces the native HTTP server returned by
+     * {@link AbstractHttpAdapter.getHttpServer}. Mostly useful for tests and
+     * for adapters that obtain the server from elsewhere.
+     */
     setHttpServer(httpServer: TServer): void;
+    /**
+     * Replaces the framework application instance that the default method
+     * implementations delegate to.
+     */
     setInstance<T = any>(instance: T): void;
+    /**
+     * Returns the framework application instance passed to the constructor
+     * (or set through {@link AbstractHttpAdapter.setInstance}).
+     *
+     * @see {@link HttpServer.getInstance}
+     */
     getInstance<T = any>(): T;
+    /**
+     * Converts and validates a route path before registration. Returns the
+     * path unchanged by default; override to translate Nest's path syntax to
+     * the router's and to throw on invalid paths.
+     *
+     * @see {@link HttpServer.normalizePath}
+     */
     normalizePath(path: string): string;
+    /**
+     * Registers a callback that the router invokes right before each route
+     * handler runs, with the resolved `RequestMethod` and the route path as
+     * declared (before {@link AbstractHttpAdapter.normalizePath}). The router
+     * wraps every handler at registration time, so the callback must be set
+     * before `app.init()` to take effect. Intended for instrumentation and
+     * devtools; there is no need to override it.
+     */
     setOnRouteTriggered(onRouteTriggered: (requestMethod: RequestMethod, path: string) => void): void;
+    /**
+     * Returns the callback registered through
+     * {@link AbstractHttpAdapter.setOnRouteTriggered}, if any. Read by the
+     * router when registering routes.
+     */
     getOnRouteTriggered(): ((requestMethod: RequestMethod, path: string) => void) | undefined;
+    /**
+     * Registers a hook to run at the start of every request. No-op by default;
+     * the built-in adapters accept a `(req, res, done) => void | Promise<void>`
+     * function and call `done()` to continue processing. Intended for
+     * instrumentation and devtools.
+     */
     setOnRequestHook(onRequestHook: Function): void;
+    /**
+     * Registers a hook to run once a response has been sent. No-op by default;
+     * the built-in adapters accept a `(req, res) => void | Promise<void>`
+     * function. Intended for instrumentation and devtools.
+     */
     setOnResponseHook(onResponseHook: Function): void;
+    /**
+     * Called by `app.close()` before the shutdown hooks run. No-op by default;
+     * override to enter a "shutting down" state.
+     *
+     * @see {@link HttpServer.beforeClose}
+     */
     beforeClose(): void;
+    /**
+     * Translates a framework-native error into something the exception filters
+     * understand. Invoked by the global exception layer with every error it
+     * receives, before it reaches the filters; the returned value is what the
+     * filters see. Returns the error unchanged by default. The built-in
+     * adapters map, for instance, body-parser `SyntaxError`s to
+     * `BadRequestException`.
+     */
     mapException(error: unknown): unknown;
+    /**
+     * Stops the server; called by `app.close()`. May return a promise.
+     *
+     * @see {@link HttpServer.close}
+     */
     abstract close(): any;
+    /**
+     * Creates the native server and stores it in `httpServer`, honoring the
+     * `httpsOptions`, `forceCloseConnections` and `return503OnClosing`
+     * application options. Called once when the application is constructed.
+     *
+     * @see {@link HttpServer.initHttpServer}
+     */
     abstract initHttpServer(options: NestApplicationOptions): any;
+    /**
+     * Serves static files; pass-through for `app.useStaticAssets()`.
+     *
+     * @see {@link HttpServer.useStaticAssets}
+     */
     abstract useStaticAssets(...args: any[]): any;
+    /**
+     * Configures the template engine used by
+     * {@link AbstractHttpAdapter.render}; pass-through for
+     * `app.setViewEngine()`.
+     *
+     * @see {@link HttpServer.setViewEngine}
+     */
     abstract setViewEngine(engine: string): any;
+    /**
+     * Returns the request host name, used for `@Controller({ host })`.
+     *
+     * @see {@link HttpServer.getRequestHostname}
+     */
     abstract getRequestHostname(request: any): any;
+    /**
+     * Returns the upper-case request method (`'GET'`, `'POST'`, ...).
+     *
+     * @see {@link HttpServer.getRequestMethod}
+     */
     abstract getRequestMethod(request: any): any;
+    /**
+     * Returns the original request URL, including the query string.
+     *
+     * @see {@link HttpServer.getRequestUrl}
+     */
     abstract getRequestUrl(request: any): any;
+    /**
+     * Sets the status code without sending the response.
+     *
+     * @see {@link HttpServer.status}
+     */
     abstract status(response: any, statusCode: number): any;
+    /**
+     * Sends the response body, handling empty bodies, `StreamableFile`,
+     * objects (as JSON) and primitives.
+     *
+     * @see {@link HttpServer.reply}
+     */
     abstract reply(response: any, body: any, statusCode?: number): any;
+    /**
+     * Terminates the response, optionally writing `message` first.
+     *
+     * @see {@link HttpServer.end}
+     */
     abstract end(response: any, message?: string): any;
+    /**
+     * Renders a view template (`@Render()`).
+     *
+     * @see {@link HttpServer.render}
+     */
     abstract render(response: any, view: string, options: any): any;
+    /**
+     * Issues a redirect (`@Redirect()`).
+     *
+     * @see {@link HttpServer.redirect}
+     */
     abstract redirect(response: any, statusCode: number, url: string): any;
+    /**
+     * Installs the global exception layer.
+     *
+     * @see {@link HttpServer.setErrorHandler}
+     */
     abstract setErrorHandler(handler: Function, prefix?: string): any;
+    /**
+     * Installs the catch-all handler for unmatched requests.
+     *
+     * @see {@link HttpServer.setNotFoundHandler}
+     */
     abstract setNotFoundHandler(handler: Function, prefix?: string): any;
+    /**
+     * Reports whether response headers have already been flushed. Must return
+     * synchronously.
+     *
+     * @see {@link HttpServer.isHeadersSent}
+     */
     abstract isHeadersSent(response: any): any;
+    /**
+     * Reads a response header that was set earlier. Not used by the core
+     * router; part of the base class so ecosystem packages can read headers
+     * through the adapter regardless of the platform.
+     */
     abstract getHeader(response: any, name: string): any;
+    /**
+     * Sets (replaces) a response header (`@Header()`).
+     *
+     * @see {@link HttpServer.setHeader}
+     */
     abstract setHeader(response: any, name: string, value: string): any;
+    /**
+     * Appends a value to a response header, turning it into a multi-value
+     * header (e.g. several `Set-Cookie` entries) instead of replacing it. Not
+     * used by the core router; part of the base class so ecosystem packages
+     * can append headers through the adapter regardless of the platform.
+     */
     abstract appendHeader(response: any, name: string, value: string): any;
+    /**
+     * Registers the default JSON and URL-encoded body parsers, exposing
+     * `req.rawBody` when `rawBody` is `true`.
+     *
+     * @see {@link HttpServer.registerParserMiddleware}
+     */
     abstract registerParserMiddleware(prefix?: string, rawBody?: boolean): any;
+    /**
+     * Enables CORS. The core currently calls this with `options` only; the
+     * `prefix` parameter is reserved.
+     *
+     * @see {@link HttpServer.enableCors}
+     */
     abstract enableCors(options?: any, prefix?: string): any;
+    /**
+     * Returns the function used to mount Nest middleware for one HTTP method.
+     * May be asynchronous.
+     *
+     * @see {@link HttpServer.createMiddlewareFactory}
+     */
     abstract createMiddlewareFactory(requestMethod: RequestMethod): ((path: string, callback: Function) => any) | Promise<(path: string, callback: Function) => any>;
+    /**
+     * Returns the platform identifier (`'express'`, `'fastify'`) that
+     * ecosystem packages branch on.
+     *
+     * @see {@link HttpServer.getType}
+     */
     abstract getType(): string;
+    /**
+     * Guards a route handler by request version for header, media-type and
+     * custom versioning.
+     *
+     * @see {@link HttpServer.applyVersionFilter}
+     */
     abstract applyVersionFilter(handler: Function, version: VersionValue, versioningOptions: VersioningOptions): (req: TRequest, res: TResponse, next: () => void) => Function;
 }

package/adapters/http-adapter.js

@@ -1,14 +1,74 @@
 /**
+ * Base class for HTTP platform adapters (see `ExpressAdapter` and
+ * `FastifyAdapter` for reference implementations).
+ *
+ * It implements the {@link HttpServer} contract that the Nest core relies on,
+ * and that interface is where each method's calling conventions are
+ * documented: when the core invokes it, with which arguments, and what it
+ * expects back. This class only adds:
+ *
+ * - default implementations that delegate to the wrapped framework
+ *   `instance` (`use()`, the HTTP-verb methods, `listen()`) or are inert
+ *   (`init()`, `normalizePath()`, `mapException()`, `beforeClose()`, the
+ *   `setOn*Hook()` setters);
+ * - storage for the native server (`httpServer`) and the framework instance
+ *   (`instance`), with their accessors;
+ * - the introspection hooks used by instrumentation tooling.
+ *
+ * Every remaining {@link HttpServer} member is declared abstract here, even
+ * the ones the interface marks optional, so subclasses cannot forget them.
+ * `setBaseViewsDir()`, `useBodyParser()` and `isRouteOrderSensitive()` are
+ * not declared on this class; implement them when the platform supports
+ * them (see {@link HttpServer} for what the core does when they are absent).
+ *
+ * Keep in mind that the core also reads and writes properties of the request
+ * object (`body`, `params`, `query`, `headers`, ...), that Server-Sent Events
+ * write directly to the Node.js response, and that `app.listen()` and the
+ * WebSocket adapters use the value returned by
+ * {@link AbstractHttpAdapter.getHttpServer} as a Node.js `net.Server`; see the
+ * {@link HttpServer} documentation for details.
+ *
+ * @typeParam TServer - Type of the native HTTP server stored in `httpServer`
+ * (e.g. `http.Server | https.Server`).
+ * @typeParam TRequest - Type of the framework request object.
+ * @typeParam TResponse - Type of the framework response object.
+ *
+ * @see [HTTP adapter](https://docs.nestjs.com/faq/http-adapter)
+ *
  * @publicApi
  */
 export class AbstractHttpAdapter {
     instance;
+    /**
+     * Native HTTP server created by {@link AbstractHttpAdapter.initHttpServer}
+     * and returned by {@link AbstractHttpAdapter.getHttpServer}.
+     */
     httpServer;
+    /**
+     * Callback registered through
+     * {@link AbstractHttpAdapter.setOnRouteTriggered}, if any.
+     */
     onRouteTriggered;
+    /**
+     * @param instance The framework application instance to delegate to (e.g.
+     * an Express `Application`). Subclasses typically create a default one
+     * when none is given.
+     */
     constructor(instance) {
         this.instance = instance;
     }
+    /**
+     * Asynchronous setup hook, awaited by `NestFactory.create()` and again by
+     * `app.init()`, so overrides must be idempotent. No-op by default.
+     *
+     * @see {@link HttpServer.init}
+     */
     async init() { }
+    /**
+     * Registers a global middleware by delegating to `instance.use(...args)`.
+     *
+     * @see {@link HttpServer.use}
+     */
     use(...args) {
         return this.instance.use(...args);
     }
@@ -66,30 +126,97 @@ export class AbstractHttpAdapter {
     listen(port, hostname, callback) {
         return this.instance.listen(port, hostname, callback);
     }
+    /**
+     * Returns the native HTTP server stored by
+     * {@link AbstractHttpAdapter.initHttpServer} (or
+     * {@link AbstractHttpAdapter.setHttpServer}).
+     *
+     * @see {@link HttpServer.getHttpServer}
+     */
     getHttpServer() {
         return this.httpServer;
     }
+    /**
+     * Replaces the native HTTP server returned by
+     * {@link AbstractHttpAdapter.getHttpServer}. Mostly useful for tests and
+     * for adapters that obtain the server from elsewhere.
+     */
     setHttpServer(httpServer) {
         this.httpServer = httpServer;
     }
+    /**
+     * Replaces the framework application instance that the default method
+     * implementations delegate to.
+     */
     setInstance(instance) {
         this.instance = instance;
     }
+    /**
+     * Returns the framework application instance passed to the constructor
+     * (or set through {@link AbstractHttpAdapter.setInstance}).
+     *
+     * @see {@link HttpServer.getInstance}
+     */
     getInstance() {
         return this.instance;
     }
+    /**
+     * Converts and validates a route path before registration. Returns the
+     * path unchanged by default; override to translate Nest's path syntax to
+     * the router's and to throw on invalid paths.
+     *
+     * @see {@link HttpServer.normalizePath}
+     */
     normalizePath(path) {
         return path;
     }
+    /**
+     * Registers a callback that the router invokes right before each route
+     * handler runs, with the resolved `RequestMethod` and the route path as
+     * declared (before {@link AbstractHttpAdapter.normalizePath}). The router
+     * wraps every handler at registration time, so the callback must be set
+     * before `app.init()` to take effect. Intended for instrumentation and
+     * devtools; there is no need to override it.
+     */
     setOnRouteTriggered(onRouteTriggered) {
         this.onRouteTriggered = onRouteTriggered;
     }
+    /**
+     * Returns the callback registered through
+     * {@link AbstractHttpAdapter.setOnRouteTriggered}, if any. Read by the
+     * router when registering routes.
+     */
     getOnRouteTriggered() {
         return this.onRouteTriggered;
     }
+    /**
+     * Registers a hook to run at the start of every request. No-op by default;
+     * the built-in adapters accept a `(req, res, done) => void | Promise<void>`
+     * function and call `done()` to continue processing. Intended for
+     * instrumentation and devtools.
+     */
     setOnRequestHook(onRequestHook) { }
+    /**
+     * Registers a hook to run once a response has been sent. No-op by default;
+     * the built-in adapters accept a `(req, res) => void | Promise<void>`
+     * function. Intended for instrumentation and devtools.
+     */
     setOnResponseHook(onResponseHook) { }
+    /**
+     * Called by `app.close()` before the shutdown hooks run. No-op by default;
+     * override to enter a "shutting down" state.
+     *
+     * @see {@link HttpServer.beforeClose}
+     */
     beforeClose() { }
+    /**
+     * Translates a framework-native error into something the exception filters
+     * understand. Invoked by the global exception layer with every error it
+     * receives, before it reaches the filters; the returned value is what the
+     * filters see. Returns the error unchanged by default. The built-in
+     * adapters map, for instance, body-parser `SyntaxError`s to
+     * `BadRequestException`.
+     */
     mapException(error) {
         return error;
     }

package/discovery/discoverable-meta-host-collection.js

@@ -44,6 +44,15 @@ export class DiscoverableMetaHostCollection {
     static insertByMetaKey(metaKey, instanceWrapper, collection) {
         if (collection.has(metaKey)) {
             const wrappers = collection.get(metaKey);
+            // provider wrappers are re-created between registration and instantiation
+            // (the prototype phase replaces the map entry with a copy), so entries
+            // are keyed by the wrapper instance id to keep one entry per provider
+            for (const existing of wrappers) {
+                if (existing.id === instanceWrapper.id) {
+                    wrappers.delete(existing);
+                    break;
+                }
+            }
             wrappers.add(instanceWrapper);
         }
         else {
@@ -87,7 +96,7 @@ export class DiscoverableMetaHostCollection {
         // of `wrapper.metatype` to resolve processor's class properly.
         // But since calling `wrapper.instance` could degrade overall performance
         // we must defer it as much we can.
-        instanceWrapper.metatype || instanceWrapper.inject
+        !instanceWrapper.metatype || instanceWrapper.inject
             ? (instanceWrapper.instance?.constructor ?? instanceWrapper.metatype)
             : instanceWrapper.metatype);
     }

package/exceptions/base-exception-filter.js

@@ -22,6 +22,9 @@ export class BaseExceptionFilter {
             : {
                 statusCode: exception.getStatus(),
                 message: res,
+                ...(exception.errorCode !== undefined && {
+                    errorCode: exception.errorCode,
+                }),
             };
         const response = host.getArgByIndex(1);
         if (!applicationRef.isHeadersSent(response)) {
@@ -75,9 +78,14 @@ export class BaseExceptionFilter {
             err instanceof Error) {
             return true;
         }
-        // Plain "http error"-shaped values (e.g. objects thrown by third-party
-        // middleware) that carry a status code and a message
-        return !!(err.statusCode && err.message);
+        // Plain "http error"-shaped values (e.g. non-Error objects thrown by third-party
+        // middleware) that carry a valid HTTP status code and a message
+        return (!(err instanceof Error) &&
+            Number.isInteger(err.statusCode) &&
+            err.statusCode >= 400 &&
+            err.statusCode < 600 &&
+            typeof err.message === 'string' &&
+            err.message !== '');
     }
 }
 __decorate([

package/injector/helpers/is-debug-mode.util.d.ts

@@ -0,0 +1 @@
+export declare function isDebugMode(): boolean;

package/injector/helpers/is-debug-mode.util.js

@@ -0,0 +1,3 @@
+export function isDebugMode() {
+    return !!process.env.NEST_DEBUG;
+}

package/injector/injector.d.ts

@@ -116,7 +116,6 @@ export declare class Injector {
     private printResolvingDependenciesLog;
     private printLookingForProviderLog;
     private printFoundInModuleLog;
-    private isDebugMode;
     private getContextId;
     private getNowTimestamp;
 }

package/injector/injector.js

@@ -9,6 +9,7 @@ import { UnknownDependenciesException } from '../errors/exceptions/unknown-depen
 import { Barrier } from '../helpers/barrier.js';
 import { makeSafeInstanceDecorator } from '../helpers/safe-instance-decorator.js';
 import { STATIC_CONTEXT } from './constants.js';
+import { isDebugMode } from './helpers/is-debug-mode.util.js';
 import { INQUIRER } from './inquirer/index.js';
 import { InstanceWrapper, } from './instance-wrapper.js';
 import { SettlementSignal } from './settlement-signal.js';
@@ -195,11 +196,24 @@ export class Injector {
          * We are duplicating it here because that one is not supposed to be exported.
          */
         function isOptionalFactoryDependency(value) {
-            return (!isUndefined(value.token) &&
-                !isUndefined(value.optional) &&
+            const token = value?.token;
+            if (isNil(token)) {
+                return false;
+            }
+            return (!isUndefined(value.optional) &&
                 !value.prototype);
         }
         const mapFactoryProviderInjectArray = (item, index) => {
+            const isWrappedDependency = !isNil(item) && typeof item === 'object' && 'token' in item;
+            const token = isWrappedDependency
+                ? item.token
+                : item;
+            if (isNil(token)) {
+                throw new UndefinedDependencyException(wrapper.name, {
+                    index,
+                    dependencies: (wrapper.inject ?? undefined),
+                });
+            }
             if (typeof item !== 'object') {
                 return item;
             }
@@ -270,7 +284,7 @@ export class Injector {
              */
             if (instanceHost.donePromise) {
                 void instanceHost.donePromise
-                    .then(() => this.loadProvider(instanceWrapper, moduleRef, resolutionContext))
+                    .then(() => this.loadProvider(instanceWrapper, instanceWrapper.host ?? moduleRef, resolutionContext))
                     .catch(err => {
                     instanceWrapper.settlementSignal?.error(err);
                 });
@@ -610,7 +624,7 @@ export class Injector {
         return isFunction(token) ? token.name : token.toString();
     }
     printResolvingDependenciesLog(token, inquirer) {
-        if (!this.isDebugMode()) {
+        if (!isDebugMode()) {
             return;
         }
         const tokenName = this.getTokenName(token);
@@ -620,7 +634,7 @@ export class Injector {
         this.logger.log(messageToPrint);
     }
     printLookingForProviderLog(token, moduleRef) {
-        if (!this.isDebugMode()) {
+        if (!isDebugMode()) {
             return;
         }
         const tokenName = this.getTokenName(token);
@@ -628,16 +642,13 @@ export class Injector {
         this.logger.log(`Looking for ${clc.cyanBright(tokenName)}${clc.green(' in ')}${clc.magentaBright(moduleRefName)}`);
     }
     printFoundInModuleLog(token, moduleRef) {
-        if (!this.isDebugMode()) {
+        if (!isDebugMode()) {
             return;
         }
         const tokenName = this.getTokenName(token);
         const moduleRefName = moduleRef?.metatype?.name ?? 'unknown';
         this.logger.log(`Found ${clc.cyanBright(tokenName)}${clc.green(' in ')}${clc.magentaBright(moduleRefName)}`);
     }
-    isDebugMode() {
-        return !!process.env.NEST_DEBUG;
-    }
     getContextId(contextId, instanceWrapper) {
         return contextId.getParent
             ? contextId.getParent({

package/injector/instance-loader.js

@@ -1,4 +1,5 @@
 import { Logger } from '@nestjs/common';
+import { DiscoverableMetaHostCollection } from '../discovery/discoverable-meta-host-collection.js';
 import { MODULE_INIT_MESSAGE } from '../helpers/messages.js';
 import { InternalCoreModule } from './internal-core-module/internal-core-module.js';
 export class InstanceLoader {
@@ -56,6 +57,11 @@ export class InstanceLoader {
         await Promise.all(wrappers.map(async (item) => {
             await this.injector.loadProvider(item, moduleRef);
             this.graphInspector.inspectInstanceWrapper(item, moduleRef);
+            if (!item.isAlias) {
+                // an alias wrapper is factory-shaped, so inspecting it would
+                // discover the aliased provider twice
+                DiscoverableMetaHostCollection.inspectProvider(this.container.getModules(), item);
+            }
         }));
     }
     createPrototypesOfControllers(moduleRef) {

package/injector/instance-wrapper.d.ts

@@ -99,6 +99,5 @@ export declare class InstanceWrapper<T = any> {
     private initialize;
     private printIntrospectedAsRequestScoped;
     private printIntrospectedAsDurable;
-    private isDebugMode;
     private generateUuid;
 }

package/injector/instance-wrapper.js

@@ -3,6 +3,7 @@ import { clc, isNil, isString, isUndefined, randomStringGenerator, } from '@nest
 import { iterate } from 'iterare';
 import { UuidFactory } from '../inspector/uuid-factory.js';
 import { STATIC_CONTEXT } from './constants.js';
+import { isDebugMode } from './helpers/is-debug-mode.util.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');
@@ -368,7 +369,7 @@ export class InstanceWrapper {
         this.scope === Scope.TRANSIENT && (this.transientMap = new Map());
     }
     printIntrospectedAsRequestScoped() {
-        if (!this.isDebugMode() || this.name === 'REQUEST') {
+        if (!isDebugMode() || this.name === 'REQUEST') {
             return;
         }
         if (isString(this.name)) {
@@ -376,16 +377,13 @@ export class InstanceWrapper {
         }
     }
     printIntrospectedAsDurable() {
-        if (!this.isDebugMode()) {
+        if (!isDebugMode()) {
             return;
         }
         if (isString(this.name)) {
             InstanceWrapper.logger.log(`${clc.cyanBright(this.name)}${clc.green(' introspected as ')}${clc.magentaBright('durable')}`);
         }
     }
-    isDebugMode() {
-        return !!process.env.NEST_DEBUG;
-    }
     generateUuid() {
         let key = this.name?.toString() ?? this.token?.toString();
         key += this.host?.name ?? '';

package/injector/lazy-module-loader/lazy-module-loader.js

@@ -14,25 +14,33 @@ export class LazyModuleLoader {
         this.moduleOverrides = moduleOverrides;
     }
     async load(loaderFn, loadOpts) {
-        this.registerLoggerConfiguration(loadOpts);
-        const moduleClassOrDynamicDefinition = await loaderFn();
-        const moduleInstances = await this.dependenciesScanner.scanForModules({
-            moduleDefinition: moduleClassOrDynamicDefinition,
-            overrides: this.moduleOverrides,
-            lazy: true,
-        });
-        if (moduleInstances.length === 0) {
-            // The module has been loaded already. In this case, we must
-            // retrieve a module reference from the existing container.
-            const { token } = await this.moduleCompiler.compile(moduleClassOrDynamicDefinition);
-            const moduleInstance = this.modulesContainer.get(token);
-            return moduleInstance && this.getTargetModuleRef(moduleInstance);
+        const originalLogger = this.instanceLoader.logger;
+        try {
+            this.registerLoggerConfiguration(loadOpts);
+            const moduleClassOrDynamicDefinition = await loaderFn();
+            const moduleInstances = await this.dependenciesScanner.scanForModules({
+                moduleDefinition: moduleClassOrDynamicDefinition,
+                overrides: this.moduleOverrides,
+                lazy: true,
+            });
+            if (moduleInstances.length === 0) {
+                // The module has been loaded already. In this case, we must
+                // retrieve a module reference from the existing container.
+                const { token } = await this.moduleCompiler.compile(moduleClassOrDynamicDefinition);
+                const moduleInstance = this.modulesContainer.get(token);
+                return moduleInstance && this.getTargetModuleRef(moduleInstance);
+            }
+            const lazyModulesContainer = this.createLazyModulesContainer(moduleInstances);
+            await this.dependenciesScanner.scanModulesForDependencies(lazyModulesContainer);
+            await this.instanceLoader.createInstancesOfDependencies(lazyModulesContainer);
+            const [targetModule] = moduleInstances;
+            return this.getTargetModuleRef(targetModule);
+        }
+        finally {
+            if (loadOpts?.logger === false) {
+                this.instanceLoader.setLogger(originalLogger);
+            }
         }
-        const lazyModulesContainer = this.createLazyModulesContainer(moduleInstances);
-        await this.dependenciesScanner.scanModulesForDependencies(lazyModulesContainer);
-        await this.instanceLoader.createInstancesOfDependencies(lazyModulesContainer);
-        const [targetModule] = moduleInstances;
-        return this.getTargetModuleRef(targetModule);
     }
     registerLoggerConfiguration(loadOpts) {
         if (loadOpts?.logger === false) {

package/injector/module.js

@@ -208,17 +208,17 @@ export class Module {
         return provider.provide;
     }
     isCustomClass(provider) {
-        return !isUndefined(provider.useClass);
+        return !isNil(provider.useClass);
     }
     isCustomValue(provider) {
         return (isObject(provider) &&
-            Object.prototype.hasOwnProperty.call(provider, 'useValue'));
+            Object.hasOwn(provider, 'useValue'));
     }
     isCustomFactory(provider) {
-        return !isUndefined(provider.useFactory);
+        return !isNil(provider.useFactory);
     }
     isCustomUseExisting(provider) {
-        return !isUndefined(provider.useExisting);
+        return !isNil(provider.useExisting);
     }
     isDynamicModule(exported) {
         return exported && exported.module;

package/nest-application-context.d.ts

@@ -19,9 +19,9 @@ export declare class NestApplicationContext<TOptions extends NestApplicationCont
     protected injector: Injector;
     protected readonly logger: Logger;
     private shouldFlushLogsOnOverride;
-    private readonly activeShutdownSignals;
+    private readonly shutdownCleanupRefs;
     private readonly moduleCompiler;
-    private shutdownCleanupRef?;
+    private shutdownPromise?;
     private _instanceLinksHost;
     private _moduleRefsForHooksByDistance?;
     private initializationPromise?;
@@ -103,6 +103,17 @@ export declare class NestApplicationContext<TOptions extends NestApplicationCont
      * @returns {Promise<void>}
      */
     close(signal?: string): Promise<void>;
+    /**
+     * Runs the shutdown sequence, at most once per cycle. Callers that arrive
+     * while a shutdown is already in flight - a process signal delivered during
+     * an explicit `close()`, or the other way round - await the very same
+     * promise instead of starting a second, concurrent teardown.
+     *
+     * @param {string} [signal] The system signal that triggered the shutdown
+     * @returns {Promise<void>}
+     */
+    protected shutdown(signal?: string): Promise<void>;
+    private runShutdownSequence;
     /**
      * Sets custom logger service.
      * Flushes buffered logs if auto flush is on.
@@ -123,6 +134,9 @@ export declare class NestApplicationContext<TOptions extends NestApplicationCont
      * `onApplicationShutdown` function of a provider if the
      * process receives a shutdown signal.
      *
+     * Repeated calls are idempotent per signal. Shutdown hooks can be
+     * re-enabled after the application context has been closed.
+     *
      * @param {ShutdownSignal[]} [signals=[]] The system signals it should listen to
      * @param {ShutdownHooksOptions} [options={}] Options for configuring shutdown hooks behavior
      *

package/nest-application-context.js

@@ -1,5 +1,4 @@
 import { Logger, ShutdownSignal, } from '@nestjs/common';
-import { iterate } from 'iterare';
 import { MESSAGES } from './constants.js';
 import { UnknownModuleException } from './errors/exceptions/index.js';
 import { createContextId } from './helpers/context-id-factory.js';
@@ -22,9 +21,9 @@ export class NestApplicationContext extends AbstractInstanceResolver {
         timestamp: true,
     });
     shouldFlushLogsOnOverride = false;
-    activeShutdownSignals = new Array();
+    shutdownCleanupRefs = new Map();
     moduleCompiler;
-    shutdownCleanupRef;
+    shutdownPromise;
     _instanceLinksHost;
     _moduleRefsForHooksByDistance;
     initializationPromise;
@@ -121,6 +120,26 @@ export class NestApplicationContext extends AbstractInstanceResolver {
      * @returns {Promise<void>}
      */
     async close(signal) {
+        await this.shutdown(signal);
+    }
+    /**
+     * Runs the shutdown sequence, at most once per cycle. Callers that arrive
+     * while a shutdown is already in flight - a process signal delivered during
+     * an explicit `close()`, or the other way round - await the very same
+     * promise instead of starting a second, concurrent teardown.
+     *
+     * @param {string} [signal] The system signal that triggered the shutdown
+     * @returns {Promise<void>}
+     */
+    shutdown(signal) {
+        this.shutdownPromise ??= this.runShutdownSequence(signal).finally(() => {
+            // Let the context be shut down again once this cycle has settled,
+            // successfully or not.
+            this.shutdownPromise = undefined;
+        });
+        return this.shutdownPromise;
+    }
+    async runShutdownSequence(signal) {
         await this.initializationPromise;
         await this.prepareClose();
         await this.callDestroyHook();
@@ -158,6 +177,9 @@ export class NestApplicationContext extends AbstractInstanceResolver {
      * `onApplicationShutdown` function of a provider if the
      * process receives a shutdown signal.
      *
+     * Repeated calls are idempotent per signal. Shutdown hooks can be
+     * re-enabled after the application context has been closed.
+     *
      * @param {ShutdownSignal[]} [signals=[]] The system signals it should listen to
      * @param {ShutdownHooksOptions} [options={}] Options for configuring shutdown hooks behavior
      *
@@ -167,16 +189,7 @@ export class NestApplicationContext extends AbstractInstanceResolver {
         if (!signals || isEmptyArray(signals)) {
             signals = Object.values(ShutdownSignal);
         }
-        else {
-            // given signals array should be unique because
-            // process shouldn't listen to the same signal more than once.
-            signals = Array.from(new Set(signals));
-        }
-        signals = iterate(signals)
-            .map((signal) => signal.toString().toUpperCase().trim())
-            // filter out the signals which is already listening to
-            .filter(signal => !this.activeShutdownSignals.includes(signal))
-            .toArray();
+        signals = Array.from(new Set(signals.map((signal) => signal.toString().toUpperCase().trim()))).filter(signal => !this.shutdownCleanupRefs.has(signal));
         this.listenToShutdownSignals(signals, options);
         return this;
     }
@@ -198,22 +211,14 @@ export class NestApplicationContext extends AbstractInstanceResolver {
      * @param {ShutdownHooksOptions} options Options for configuring shutdown hooks behavior
      */
     listenToShutdownSignals(signals, options = {}) {
-        let receivedSignal = false;
         const cleanup = async (signal) => {
             try {
-                if (receivedSignal) {
-                    // If we receive another signal while we're waiting
-                    // for the server to stop, just ignore it.
+                if (this.shutdownPromise) {
+                    // If a shutdown is already under way - because of another signal or
+                    // an explicit `close()` call - just ignore this one.
                     return;
                 }
-                receivedSignal = true;
-                await this.initializationPromise;
-                await this.prepareClose();
-                await this.callDestroyHook();
-                await this.callBeforeShutdownHook(signal);
-                await this.dispose();
-                await this.callShutdownHook(signal);
-                signals.forEach(sig => process.removeListener(sig, cleanup));
+                await this.shutdown(signal);
                 if (options.useProcessExit) {
                     // Use process.exit() to ensure the 'exit' event is properly triggered.
                     // This is required for async loggers (like Pino with transports)
@@ -229,9 +234,8 @@ export class NestApplicationContext extends AbstractInstanceResolver {
                 process.exit(1);
             }
         };
-        this.shutdownCleanupRef = cleanup;
         signals.forEach((signal) => {
-            this.activeShutdownSignals.push(signal);
+            this.shutdownCleanupRefs.set(signal, cleanup);
             process.on(signal, cleanup);
         });
     }
@@ -239,12 +243,10 @@ export class NestApplicationContext extends AbstractInstanceResolver {
      * Unsubscribes from shutdown signals (process events)
      */
     unsubscribeFromProcessSignals() {
-        if (!this.shutdownCleanupRef) {
-            return;
-        }
-        this.activeShutdownSignals.forEach(signal => {
-            process.removeListener(signal, this.shutdownCleanupRef);
+        this.shutdownCleanupRefs.forEach((cleanup, signal) => {
+            process.removeListener(signal, cleanup);
         });
+        this.shutdownCleanupRefs.clear();
     }
     /**
      * Calls the `onModuleInit` function on the registered

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestjs/core",
-  "version": "12.0.1",
+  "version": "12.0.3",
   "description": "Nest - modern, fast, powerful node.js web framework (@core)",
   "author": "Kamil Mysliwiec",
   "license": "MIT",
@@ -36,7 +36,7 @@
     "uid": "2.0.2"
   },
   "devDependencies": {
-    "@nestjs/common": "12.0.1"
+    "@nestjs/common": "12.0.3"
   },
   "peerDependencies": {
     "@nestjs/common": "^12.0.0",
@@ -57,5 +57,5 @@
       "optional": true
     }
   },
-  "gitHead": "4c751c503bc753095f4b4f052e106f95218cc33f"
+  "gitHead": "14151790e1abe870abc3bbf00f88786fc3ebe509"
 }

package/router/sse-stream.d.ts

@@ -33,6 +33,7 @@ export declare class SseStream extends Transform {
     private _destination;
     private _statusCode;
     private _additionalHeaders;
+    private readonly _isHttp2;
     constructor(req?: IncomingMessage);
     get headersCommitted(): boolean;
     pipe<T extends WritableHeaderStream>(destination: T, options?: {

package/router/sse-stream.js

@@ -41,9 +41,15 @@ export class SseStream extends Transform {
     _destination = null;
     _statusCode = 200;
     _additionalHeaders;
+    _isHttp2;
     constructor(req) {
         super({ objectMode: true });
-        if (req && req.socket) {
+        this._isHttp2 = (req?.httpVersionMajor ?? 1) > 1;
+        // Under HTTP/2 these calls are not request-scoped: `setTimeout` is routed
+        // to the shared `Http2Session` and the rest to the shared TCP socket, so
+        // tuning one SSE request would disable the idle timeout for every stream
+        // on that connection. See https://nodejs.org/api/http2.html#requestsocket
+        if (req && req.socket && !this._isHttp2) {
             req.socket.setKeepAlive(true);
             req.socket.setNoDelay(true);
             req.socket.setTimeout(0);
@@ -79,7 +85,9 @@ export class SseStream extends Transform {
                 ...additionalHeaders,
                 // See https://github.com/dunglas/mercure/blob/main/subscribe.go#L347-L362
                 'Content-Type': 'text/event-stream',
-                Connection: 'keep-alive',
+                // Hop-by-hop header, forbidden in HTTP/2
+                // https://www.rfc-editor.org/rfc/rfc9113#section-8.2.2
+                ...(!this._isHttp2 && { Connection: 'keep-alive' }),
                 // Disable cache, even for old browsers and proxies
                 'Cache-Control': 'private, no-cache, no-store, must-revalidate, max-age=0, no-transform',
                 Pragma: 'no-cache',