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

package/router/router-explorer.js

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

package/router/router-response-controller.d.ts

@@ -26,4 +26,5 @@ export declare class RouterResponseController {
         statusCode?: number;
     }): Promise<void>;
     private assertObservable;
+    private getOrCreateAbortController;
 }

package/router/router-response-controller.js

@@ -1,4 +1,4 @@
-import { HttpStatus, Logger, RequestMethod, } from '@nestjs/common';
+import { HttpStatus, Logger, RequestMethod, SSE_ABORT_CONTROLLER, } from '@nestjs/common';
 import { EMPTY, lastValueFrom, isObservable } from 'rxjs';
 import { catchError, concatMap, map } from 'rxjs/operators';
 import { SseStream, } from './sse-stream.js';
@@ -49,76 +49,146 @@ export class RouterResponseController {
     async sse(result, response, request, options) {
         // It's possible that we sent headers already so don't use a stream
         if (response.writableEnded) {
+            // The response is already gone: abort the request-scoped signal so
+            // handler cleanup wired to @SseSignal() still runs, and swallow late
+            // handler rejections that can no longer be delivered to the client.
+            this.getOrCreateAbortController(request).abort();
+            Promise.resolve(result).catch((err) => this.logger.error(err));
             return;
         }
-        const observableResult = await Promise.resolve(result);
-        this.assertObservable(observableResult);
         const stream = new SseStream(request);
         const statusCode = options?.statusCode ??
             response.statusCode ??
             200;
-        stream.pipe(response, {
-            additionalHeaders: options?.additionalHeaders,
-            statusCode,
-        });
+        // Create a per-request AbortController and expose its signal on the request
+        // object so async @Sse() handlers can observe client disconnects (via the
+        // @SseSignal() parameter decorator) and stop/clean up in-flight setup work.
+        // The controller is reused if one was already attached upstream (e.g. when the
+        // handler is wrapped by interceptors and the signal was created earlier).
+        const abortController = this.getOrCreateAbortController(request);
         return new Promise((resolve, reject) => {
             let settled = false;
-            const onClose = () => {
-                settled = true;
-                subscription.unsubscribe();
+            let closeRequested = false;
+            let subscription;
+            const disconnectSource = request.socket ?? response;
+            // Ends the request-scoped lifetime: stops listening for disconnects and
+            // aborts the signal handed to the route handler. Every terminal path of
+            // the SSE lifecycle (disconnect, completion, error) funnels through here,
+            // so a handler that ties its resources to the signal releases them once,
+            // regardless of how the stream ended. `abort()` is idempotent, so paths
+            // that already aborted on disconnect are unaffected.
+            const finalize = () => {
+                disconnectSource.removeListener('close', onClose);
+                abortController.abort();
+            };
+            const endStream = () => {
                 if (!stream.writableEnded) {
                     stream.end();
                 }
+            };
+            const onClose = () => {
+                if (settled || closeRequested) {
+                    return;
+                }
+                closeRequested = true;
+                if (!subscription) {
+                    finalize();
+                    return;
+                }
+                settled = true;
+                finalize();
+                subscription?.unsubscribe();
+                endStream();
                 response.end();
                 resolve();
             };
-            const subscription = observableResult
-                .pipe(map((message) => {
-                if (isObject(message)) {
-                    return message;
+            disconnectSource.once('close', onClose);
+            Promise.resolve(result)
+                .then(observableResult => {
+                if (settled) {
+                    return;
                 }
-                return { data: message };
-            }), concatMap(message => new Promise(resolve => stream.writeMessage(message, () => resolve()))), catchError(err => {
-                if (!stream.headersCommitted) {
-                    throw err;
+                this.assertObservable(observableResult);
+                if (closeRequested) {
+                    // The client disconnected while the async handler was resolving.
+                    // Do not subscribe the producer Observable after the consumer has
+                    // already gone away — subscribing only to abort it in the same tick
+                    // would start producer side effects just to immediately cancel them.
+                    settled = true;
+                    endStream();
+                    response.end();
+                    resolve();
+                    return;
                 }
-                const data = err instanceof Error ? err.message : err;
-                stream.writeMessage({ type: 'error', data }, writeError => {
-                    if (writeError) {
-                        this.logger.error(writeError);
+                stream.pipe(response, {
+                    additionalHeaders: options?.additionalHeaders,
+                    statusCode,
+                });
+                subscription = observableResult
+                    .pipe(map((message) => {
+                    if (isObject(message)) {
+                        return message;
+                    }
+                    return { data: message };
+                }), concatMap(message => new Promise(resolve => stream.writeMessage(message, () => resolve()))), catchError(err => {
+                    if (!stream.headersCommitted) {
+                        throw err;
                     }
+                    const data = err instanceof Error ? err.message : err;
+                    stream.writeMessage({ type: 'error', data }, writeError => {
+                        if (writeError) {
+                            this.logger.error(writeError);
+                        }
+                    });
+                    return EMPTY;
+                }))
+                    .subscribe({
+                    error: err => {
+                        if (settled) {
+                            return;
+                        }
+                        settled = true;
+                        finalize();
+                        endStream();
+                        reject(err);
+                    },
+                    complete: () => {
+                        if (settled) {
+                            return;
+                        }
+                        settled = true;
+                        finalize();
+                        endStream();
+                        resolve();
+                    },
                 });
-                return EMPTY;
-            }))
-                .subscribe({
-                error: err => {
-                    settled = true;
-                    request.removeListener('close', onClose);
-                    if (!stream.writableEnded) {
-                        stream.end();
+                // Commit SSE headers on the next macrotask. Pipe validation errors
+                // propagate through microtasks (which complete before macrotasks),
+                // so if the lifecycle errored, `settled` is already true and we
+                // skip the write. Otherwise headers are sent immediately rather
+                // than waiting for the first Observable emission.
+                setTimeout(() => {
+                    if (!settled) {
+                        stream.commitHeaders();
                     }
-                    reject(err);
-                },
-                complete: () => {
+                }, 0);
+            })
+                .catch(err => {
+                if (settled) {
+                    return;
+                }
+                if (closeRequested) {
                     settled = true;
-                    request.removeListener('close', onClose);
-                    if (!stream.writableEnded) {
-                        stream.end();
-                    }
+                    endStream();
+                    response.end();
                     resolve();
-                },
-            });
-            // Commit SSE headers on the next macrotask. Pipe validation errors
-            // propagate through microtasks (which complete before macrotasks),
-            // so if the lifecycle errored, `settled` is already true and we
-            // skip the write. Otherwise headers are sent immediately rather
-            // than waiting for the first Observable emission.
-            setTimeout(() => {
-                if (!settled) {
-                    stream.commitHeaders();
+                    return;
                 }
-            }, 0);
-            request.on('close', onClose);
+                settled = true;
+                finalize();
+                endStream();
+                reject(err);
+            });
         });
     }
     assertObservable(value) {
@@ -126,4 +196,11 @@ export class RouterResponseController {
             throw new ReferenceError('You must return an Observable stream to use Server-Sent Events (SSE).');
         }
     }
+    getOrCreateAbortController(request) {
+        const carrier = request;
+        if (!carrier[SSE_ABORT_CONTROLLER]) {
+            carrier[SSE_ABORT_CONTROLLER] = new AbortController();
+        }
+        return carrier[SSE_ABORT_CONTROLLER];
+    }
 }

package/router/routes-resolver.d.ts

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

package/router/routes-resolver.js

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

package/router/sse-stream.d.ts

@@ -22,6 +22,7 @@ export type HeaderStream = WritableHeaderStream & ReadHeaders;
  * - type
  * - id
  * - retry
+ * - comment
  *
  * If constructed with a HTTP Request, it will optimise the socket for streaming.
  * If this stream is piped to an HTTP Response, it will set appropriate headers.

package/router/sse-stream.js

@@ -1,13 +1,25 @@
 import { Transform } from 'stream';
-import { isObject } from '@nestjs/common/internal';
+import { isNil, isObject, isUndefined } from '@nestjs/common/internal';
+function serializeSseLines(value, prefix) {
+    return value
+        .split(/\r\n|\r|\n/)
+        .map(line => `${prefix}${line}\n`)
+        .join('');
+}
 function toDataString(data) {
     if (isObject(data)) {
         return toDataString(JSON.stringify(data));
     }
-    return data
-        .split(/\r\n|\r|\n/)
-        .map(line => `data: ${line}\n`)
-        .join('');
+    return serializeSseLines(data, 'data: ');
+}
+function toCommentString(comment) {
+    return serializeSseLines(comment, ': ');
+}
+function isCommentOnly(message) {
+    return (!isNil(message.comment) &&
+        isUndefined(message.data) &&
+        isUndefined(message.type) &&
+        isUndefined(message.retry));
 }
 /**
  * Adapted from https://raw.githubusercontent.com/EventSource/node-ssestream
@@ -18,6 +30,7 @@ function toDataString(data) {
  * - type
  * - id
  * - retry
+ * - comment
  *
  * If constructed with a HTTP Request, it will optimise the socket for streaming.
  * If this stream is piped to an HTTP Response, it will set appropriate headers.
@@ -64,7 +77,7 @@ export class SseStream extends Transform {
         if (this._destination.writeHead) {
             this._destination.writeHead(statusCode, {
                 ...additionalHeaders,
-                // See https://github.com/dunglas/mercure/blob/master/hub/subscribe.go#L124-L130
+                // See https://github.com/dunglas/mercure/blob/main/subscribe.go#L347-L362
                 'Content-Type': 'text/event-stream',
                 Connection: 'keep-alive',
                 // Disable cache, even for old browsers and proxies
@@ -82,12 +95,10 @@ export class SseStream extends Transform {
         this.commitHeaders();
         const sanitize = (val) => String(val).replace(/[\r\n]/g, '');
         let data = message.type ? `event: ${sanitize(message.type)}\n` : '';
-        data +=
-            message.id !== undefined && message.id !== null
-                ? `id: ${sanitize(message.id)}\n`
-                : '';
-        data += message.retry ? `retry: ${sanitize(message.retry)}\n` : '';
-        data += message.data ? toDataString(message.data) : '';
+        data += !isNil(message.id) ? `id: ${sanitize(message.id)}\n` : '';
+        data += !isNil(message.retry) ? `retry: ${sanitize(message.retry)}\n` : '';
+        data += !isNil(message.comment) ? toCommentString(message.comment) : '';
+        data += !isNil(message.data) ? toDataString(message.data) : '';
         data += '\n';
         this.push(data);
         callback();
@@ -96,7 +107,7 @@ export class SseStream extends Transform {
      * Calls `.write` but handles the drain if needed
      */
     writeMessage(message, cb) {
-        if (message.id === undefined || message.id === null) {
+        if (isNil(message.id) && !isCommentOnly(message)) {
             this.lastEventId++;
             message.id = this.lastEventId.toString();
         }

package/scanner.js

@@ -40,6 +40,9 @@ export class DependenciesScanner {
     async scanForModules({ moduleDefinition, lazy, scope = [], ctxRegistry = [], overrides = [], }) {
         const { moduleRef: moduleInstance, inserted: moduleInserted } = (await this.insertOrOverrideModule(moduleDefinition, overrides, scope)) ??
             {};
+        if (lazy && !moduleInserted && moduleInstance?.isInstantiated) {
+            return [];
+        }
         moduleDefinition =
             this.getOverrideModuleByModule(moduleDefinition, overrides)?.newModule ??
                 moduleDefinition;
@@ -64,7 +67,7 @@ export class DependenciesScanner {
                 throw new UndefinedModuleException(moduleDefinition, index, scope);
             }
             if (!innerModule) {
-                throw new InvalidModuleException(moduleDefinition, index, scope);
+                throw new InvalidModuleException(moduleDefinition, index, scope, innerModule);
             }
             if (ctxRegistry.includes(innerModule)) {
                 continue;
@@ -81,7 +84,7 @@ export class DependenciesScanner {
         if (!moduleInstance) {
             return registeredModuleRefs;
         }
-        if (lazy && moduleInserted) {
+        if (lazy) {
             this.container.bindGlobalsToImports(moduleInstance);
         }
         return [moduleInstance].concat(registeredModuleRefs);
@@ -90,10 +93,14 @@ export class DependenciesScanner {
         const moduleToAdd = this.isForwardReference(moduleDefinition)
             ? moduleDefinition.forwardRef()
             : moduleDefinition;
-        if (this.isInjectable(moduleToAdd) ||
-            this.isController(moduleToAdd) ||
-            this.isExceptionFilter(moduleToAdd)) {
-            throw new InvalidClassModuleException(moduleDefinition, scope);
+        if (this.isInjectable(moduleToAdd)) {
+            throw new InvalidClassModuleException(moduleDefinition, scope, 'provider');
+        }
+        if (this.isController(moduleToAdd)) {
+            throw new InvalidClassModuleException(moduleDefinition, scope, 'controller');
+        }
+        if (this.isExceptionFilter(moduleToAdd)) {
+            throw new InvalidClassModuleException(moduleDefinition, scope, 'filter');
         }
         return this.container.addModule(moduleToAdd, scope);
     }