@nestjs/common 11.1.16 → 11.1.17

package/Readme.md

@@ -29,7 +29,7 @@ Nest is a framework for building efficient, scalable <a href="https://nodejs.org
 
 ## Philosophy
 
-<p>In recent years, thanks to Node.js, JavaScript has become the “lingua franca” of the web for both front and backend applications, giving rise to awesome projects like <a href="https://angular.io/" target="_blank">Angular</a>, <a href="https://github.com/facebook/react" target="_blank">React</a>, and <a href="https://github.com/vuejs/vue" target="_blank">Vue</a>, which improve developer productivity and enable the construction of fast, testable, and extensible frontend applications. However, on the server-side, while there are a lot of superb libraries, helpers, and tools for Node, none of them effectively solve the main problem - the architecture.</p>
+<p>In recent years, thanks to Node.js, JavaScript has become the “lingua franca” of the web for both front-end and back-end applications, giving rise to awesome projects like <a href="https://angular.io/" target="_blank">Angular</a>, <a href="https://github.com/facebook/react" target="_blank">React</a>, and <a href="https://github.com/vuejs/vue" target="_blank">Vue</a>, which improve developer productivity and enable the construction of fast, testable, and extensible frontend applications. However, on the server-side, while there are a lot of superb libraries, helpers, and tools for Node, none of them effectively solve the main problem - the architecture.</p>
 <p>Nest aims to provide an application architecture out of the box which allows for effortless creation of highly testable, scalable, and loosely coupled and easily maintainable applications. The architecture is heavily inspired by Angular.</p>
 
 ## Getting started

package/interfaces/microservices/pre-request-hook.interface.d.ts

@@ -0,0 +1,22 @@
+import { Observable } from 'rxjs';
+import { ExecutionContext } from '../features/execution-context.interface.js';
+/**
+ * Interface describing a global preRequest hook for microservices.
+ *
+ * Hooks are executed before guards, allowing setup of context (e.g. AsyncLocalStorage)
+ * that is available to all downstream enhancers.
+ *
+ * @example
+ * ```typescript
+ * const als = new AsyncLocalStorage();
+ * app.registerPreRequestHook((context, next) => {
+ *   als.enterWith({ correlationId: uuid() });
+ *   return next();
+ * });
+ * ```
+ *
+ * @publicApi
+ */
+export interface PreRequestHook {
+    (context: ExecutionContext, next: () => Observable<unknown>): Observable<unknown>;
+}

package/interfaces/microservices/pre-request-hook.interface.js

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

package/internal.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Internal module - not part of the public API.
+ * These exports are used by sibling @nestjs packages.
+ * Do not depend on these in your application code.
+ * @internal
+ * @module
+ */
+export * from './constants.js';
+export { RouteParamtypes } from './enums/route-paramtypes.enum.js';
+export * from './utils/shared.utils.js';
+export * from './utils/load-package.util.js';
+export * from './utils/cli-colors.util.js';
+export * from './utils/random-string-generator.util.js';
+export * from './utils/select-exception-filter-metadata.util.js';
+export type { Controller, Injectable } from './interfaces/index.js';
+export type { NestApplicationContextOptions } from './interfaces/nest-application-context-options.interface.js';
+export type { NestMicroserviceOptions } from './interfaces/microservices/nest-microservice-options.interface.js';
+export type { CorsOptions, CorsOptionsDelegate, CustomOrigin, } from './interfaces/external/cors-options.interface.js';
+export type { ExceptionFilterMetadata } from './interfaces/exceptions/exception-filter-metadata.interface.js';
+export type { RpcExceptionFilterMetadata } from './interfaces/exceptions/rpc-exception-filter-metadata.interface.js';
+export type { VersionValue } from './interfaces/version-options.interface.js';
+export type { GlobalPrefixOptions } from './interfaces/global-prefix-options.interface.js';
+export type { MiddlewareConfiguration, RouteInfo, } from './interfaces/middleware/middleware-configuration.interface.js';
+export type { MiddlewareConfigProxy } from './interfaces/middleware/middleware-config-proxy.interface.js';
+export type { ModuleMetadata } from './interfaces/modules/module-metadata.interface.js';
+export type { HttpArgumentsHost, RpcArgumentsHost, WsArgumentsHost, } from './interfaces/features/arguments-host.interface.js';
+export type { RequestHandler } from './interfaces/http/http-server.interface.js';
+export type { GetOrResolveOptions, SelectOptions, } from './interfaces/nest-application-context.interface.js';
+export type { ShutdownHooksOptions } from './interfaces/shutdown-hooks-options.interface.js';
+export { assignMetadata } from './decorators/http/route-params.decorator.js';

package/internal.js

@@ -0,0 +1,19 @@
+/**
+ * Internal module - not part of the public API.
+ * These exports are used by sibling @nestjs packages.
+ * Do not depend on these in your application code.
+ * @internal
+ * @module
+ */
+// Constants
+export * from './constants.js';
+// Enums (internal)
+export { RouteParamtypes } from './enums/route-paramtypes.enum.js';
+// Utils
+export * from './utils/shared.utils.js';
+export * from './utils/load-package.util.js';
+export * from './utils/cli-colors.util.js';
+export * from './utils/random-string-generator.util.js';
+export * from './utils/select-exception-filter-metadata.util.js';
+// Decorators (internal)
+export { assignMetadata } from './decorators/http/route-params.decorator.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestjs/common",
-  "version": "11.1.16",
+  "version": "11.1.17",
   "description": "Nest - modern, fast, powerful node.js web framework (@common)",
   "author": "Kamil Mysliwiec",
   "homepage": "https://nestjs.com",
@@ -18,7 +18,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "file-type": "21.3.0",
+    "file-type": "21.3.2",
     "iterare": "1.2.1",
     "load-esm": "1.0.3",
     "tslib": "2.8.1",
@@ -38,5 +38,5 @@
       "optional": true
     }
   },
-  "gitHead": "315e698096208868b43dda25f2db9ac9d7c1d822"
+  "gitHead": "447a373ebebd2c58b5b3c8d718f25922a025f2fe"
 }

package/pipes/standard-schema-validation.pipe.d.ts

@@ -0,0 +1,86 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { ArgumentMetadata, PipeTransform } from '../interfaces/features/pipe-transform.interface.js';
+import { ErrorHttpStatusCode } from '../utils/http-error-by-code.util.js';
+/**
+ * @publicApi
+ */
+export interface StandardSchemaValidationPipeOptions {
+    /**
+     * If true, the pipe will return the value produced by the schema
+     * (which may differ from the input if the schema coerces/transforms values).
+     * If false, the original input value is returned after successful validation.
+     * @default true
+     */
+    transform?: boolean;
+    /**
+     * If true, the pipe will also validate parameters decorated with custom decorators
+     * (created with `createParamDecorator`). When false, custom parameters are skipped.
+     * @default false
+     */
+    validateCustomDecorators?: boolean;
+    /**
+     * Options to pass to the standard schema `validate` function.
+     * These options are forwarded as the second argument to the schema's `~standard.validate` method.
+     */
+    validateOptions?: Record<string, unknown>;
+    /**
+     * The HTTP status code to be used in the response when the validation fails.
+     * @default HttpStatus.BAD_REQUEST
+     */
+    errorHttpStatusCode?: ErrorHttpStatusCode;
+    /**
+     * A factory function that returns an exception object to be thrown
+     * if validation fails.
+     * @param issues The issues returned by the standard schema validation
+     * @returns The exception object
+     */
+    exceptionFactory?: (issues: readonly StandardSchemaV1.Issue[]) => any;
+}
+/**
+ * Defines the built-in StandardSchemaValidation Pipe.
+ *
+ * Uses a standard schema object (conforming to the Standard Schema spec)
+ * attached to the parameter metadata to validate incoming values.
+ *
+ * @see [Standard Schema](https://github.com/standard-schema/standard-schema)
+ *
+ * @publicApi
+ */
+export declare class StandardSchemaValidationPipe implements PipeTransform {
+    protected readonly options?: StandardSchemaValidationPipeOptions | undefined;
+    protected isTransformEnabled: boolean;
+    protected validateCustomDecorators: boolean;
+    protected validateOptions: Record<string, unknown> | undefined;
+    protected exceptionFactory: (issues: readonly StandardSchemaV1.Issue[]) => any;
+    constructor(options?: StandardSchemaValidationPipeOptions | undefined);
+    /**
+     * Method that validates the incoming value against the standard schema
+     * provided in the parameter metadata.
+     *
+     * @param value currently processed route argument
+     * @param metadata contains metadata about the currently processed route argument
+     */
+    transform<T = any>(value: T, metadata: ArgumentMetadata): Promise<T>;
+    /**
+     * Determines whether validation should be performed for the given metadata.
+     * Skips validation for custom decorators unless `validateCustomDecorators` is enabled.
+     *
+     * @param metadata contains metadata about the currently processed route argument
+     * @returns `true` if validation should be performed
+     */
+    protected toValidate(metadata: ArgumentMetadata): boolean;
+    /**
+     * Validates a value against a standard schema.
+     * Can be overridden to customize validation behavior.
+     *
+     * @param value The value to validate
+     * @param schema The standard schema to validate against
+     * @param options Optional options forwarded to the schema's validate method
+     * @returns The validation result
+     */
+    protected validate<T = unknown>(value: unknown, schema: StandardSchemaV1, options?: Record<string, unknown>): Promise<StandardSchemaV1.Result<T>> | StandardSchemaV1.Result<T>;
+    /**
+     * Strips dangerous prototype pollution keys from an object.
+     */
+    protected stripProtoKeys(value: any): void;
+}

package/pipes/standard-schema-validation.pipe.js

@@ -0,0 +1,120 @@
+import { __decorate, __metadata, __param } from "tslib";
+import { types } from 'util';
+import { Injectable } from '../decorators/core/injectable.decorator.js';
+import { Optional } from '../decorators/core/optional.decorator.js';
+import { HttpStatus } from '../enums/http-status.enum.js';
+import { HttpErrorByCode, } from '../utils/http-error-by-code.util.js';
+/**
+ * Built-in JavaScript types that should be excluded from prototype stripping
+ * to avoid conflicts with test frameworks like Jest's useFakeTimers
+ */
+const BUILT_IN_TYPES = [Date, RegExp, Error, Map, Set, WeakMap, WeakSet];
+/**
+ * Defines the built-in StandardSchemaValidation Pipe.
+ *
+ * Uses a standard schema object (conforming to the Standard Schema spec)
+ * attached to the parameter metadata to validate incoming values.
+ *
+ * @see [Standard Schema](https://github.com/standard-schema/standard-schema)
+ *
+ * @publicApi
+ */
+let StandardSchemaValidationPipe = class StandardSchemaValidationPipe {
+    options;
+    isTransformEnabled;
+    validateCustomDecorators;
+    validateOptions;
+    exceptionFactory;
+    constructor(options) {
+        this.options = options;
+        const { transform = true, validateCustomDecorators = false, validateOptions, exceptionFactory, errorHttpStatusCode = HttpStatus.BAD_REQUEST, } = options || {};
+        this.isTransformEnabled = transform;
+        this.validateCustomDecorators = validateCustomDecorators;
+        this.validateOptions = validateOptions;
+        this.exceptionFactory =
+            exceptionFactory ||
+                (issues => {
+                    const messages = issues.map(issue => issue.message);
+                    return new HttpErrorByCode[errorHttpStatusCode](messages);
+                });
+    }
+    /**
+     * Method that validates the incoming value against the standard schema
+     * provided in the parameter metadata.
+     *
+     * @param value currently processed route argument
+     * @param metadata contains metadata about the currently processed route argument
+     */
+    async transform(value, metadata) {
+        const schema = metadata.schema;
+        if (!schema || !this.toValidate(metadata)) {
+            return value;
+        }
+        this.stripProtoKeys(value);
+        const result = await this.validate(value, schema, this.validateOptions);
+        if (result.issues) {
+            throw this.exceptionFactory(result.issues);
+        }
+        return this.isTransformEnabled ? result.value : value;
+    }
+    /**
+     * Determines whether validation should be performed for the given metadata.
+     * Skips validation for custom decorators unless `validateCustomDecorators` is enabled.
+     *
+     * @param metadata contains metadata about the currently processed route argument
+     * @returns `true` if validation should be performed
+     */
+    toValidate(metadata) {
+        const { type } = metadata;
+        if (type === 'custom' && !this.validateCustomDecorators) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Validates a value against a standard schema.
+     * Can be overridden to customize validation behavior.
+     *
+     * @param value The value to validate
+     * @param schema The standard schema to validate against
+     * @param options Optional options forwarded to the schema's validate method
+     * @returns The validation result
+     */
+    validate(value, schema, options) {
+        return schema['~standard'].validate(value, options);
+    }
+    /**
+     * Strips dangerous prototype pollution keys from an object.
+     */
+    stripProtoKeys(value) {
+        if (value == null ||
+            typeof value !== 'object' ||
+            types.isTypedArray(value)) {
+            return;
+        }
+        if (BUILT_IN_TYPES.some(type => value instanceof type)) {
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const v of value) {
+                this.stripProtoKeys(v);
+            }
+            return;
+        }
+        delete value.__proto__;
+        delete value.prototype;
+        const constructorType = value?.constructor;
+        if (constructorType && !BUILT_IN_TYPES.includes(constructorType)) {
+            delete value.constructor;
+        }
+        for (const key in value) {
+            this.stripProtoKeys(value[key]);
+        }
+    }
+};
+StandardSchemaValidationPipe = __decorate([
+    Injectable(),
+    __param(0, Optional()),
+    __metadata("design:paramtypes", [Object])
+], StandardSchemaValidationPipe);
+export { StandardSchemaValidationPipe };

package/serializer/standard-schema-serializer.interceptor.d.ts

@@ -0,0 +1,50 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { Observable } from 'rxjs';
+import { CallHandler, ExecutionContext, NestInterceptor } from '../interfaces/index.js';
+import { StandardSchemaSerializerContextOptions } from './standard-schema-serializer.interfaces.js';
+interface PlainLiteralObject {
+    [key: string]: any;
+}
+/**
+ * @publicApi
+ */
+export interface StandardSchemaSerializerInterceptorOptions {
+    /**
+     * A default standard schema to use for serialization when no schema
+     * is provided via `@SerializeOptions()`.
+     */
+    schema?: StandardSchemaV1;
+    /**
+     * Default options forwarded to the schema's `~standard.validate()` call.
+     * Can be overridden per-handler via `@SerializeOptions({ validateOptions })`.
+     */
+    validateOptions?: StandardSchemaV1.Options;
+}
+/**
+ * An interceptor that serializes outgoing responses using a Standard Schema.
+ *
+ * The schema can be provided either:
+ * - As a default option in the interceptor constructor
+ * - Per-handler or per-class via `@SerializeOptions({ schema })` decorator
+ *
+ * When a schema is present, the interceptor validates/transforms the response
+ * through the schema's `~standard.validate()` method. If validation fails,
+ * the issues are thrown as an error.
+ *
+ * @see [Standard Schema](https://github.com/standard-schema/standard-schema)
+ *
+ * @publicApi
+ */
+export declare class StandardSchemaSerializerInterceptor implements NestInterceptor {
+    protected readonly reflector: any;
+    protected readonly defaultOptions: StandardSchemaSerializerInterceptorOptions;
+    constructor(reflector: any, defaultOptions?: StandardSchemaSerializerInterceptorOptions);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<any>;
+    /**
+     * Serializes responses that are non-null objects nor streamable files.
+     */
+    serialize(response: PlainLiteralObject | Array<PlainLiteralObject>, schema: StandardSchemaV1 | undefined, validateOptions?: StandardSchemaV1.Options): PlainLiteralObject | Array<PlainLiteralObject> | Promise<PlainLiteralObject | Array<PlainLiteralObject>>;
+    transformToPlain(plainOrClass: any, schema: StandardSchemaV1, validateOptions?: StandardSchemaV1.Options): Promise<PlainLiteralObject>;
+    protected getContextOptions(context: ExecutionContext): StandardSchemaSerializerContextOptions | undefined;
+}
+export {};

package/serializer/standard-schema-serializer.interceptor.js

@@ -0,0 +1,75 @@
+import { __decorate, __metadata, __param } from "tslib";
+import { map } from 'rxjs/operators';
+import { Inject, Injectable, Optional } from '../decorators/core/index.js';
+import { StreamableFile } from '../file-stream/index.js';
+import { isObject } from '../utils/shared.utils.js';
+import { CLASS_SERIALIZER_OPTIONS } from './class-serializer.constants.js';
+// NOTE (external)
+// We need to deduplicate them here due to the circular dependency
+// between core and common packages
+const REFLECTOR = 'Reflector';
+/**
+ * An interceptor that serializes outgoing responses using a Standard Schema.
+ *
+ * The schema can be provided either:
+ * - As a default option in the interceptor constructor
+ * - Per-handler or per-class via `@SerializeOptions({ schema })` decorator
+ *
+ * When a schema is present, the interceptor validates/transforms the response
+ * through the schema's `~standard.validate()` method. If validation fails,
+ * the issues are thrown as an error.
+ *
+ * @see [Standard Schema](https://github.com/standard-schema/standard-schema)
+ *
+ * @publicApi
+ */
+let StandardSchemaSerializerInterceptor = class StandardSchemaSerializerInterceptor {
+    reflector;
+    defaultOptions;
+    constructor(reflector, defaultOptions = {}) {
+        this.reflector = reflector;
+        this.defaultOptions = defaultOptions;
+    }
+    intercept(context, next) {
+        const contextOptions = this.getContextOptions(context);
+        const schema = contextOptions?.schema ?? this.defaultOptions.schema;
+        const validateOptions = contextOptions?.validateOptions ?? this.defaultOptions.validateOptions;
+        return next
+            .handle()
+            .pipe(map((res) => this.serialize(res, schema, validateOptions)));
+    }
+    /**
+     * Serializes responses that are non-null objects nor streamable files.
+     */
+    serialize(response, schema, validateOptions) {
+        if (!schema || !isObject(response) || response instanceof StreamableFile) {
+            return response;
+        }
+        return Array.isArray(response)
+            ? Promise.all(response.map(item => this.transformToPlain(item, schema, validateOptions)))
+            : this.transformToPlain(response, schema, validateOptions);
+    }
+    async transformToPlain(plainOrClass, schema, validateOptions) {
+        if (!plainOrClass) {
+            return plainOrClass;
+        }
+        const result = await schema['~standard'].validate(plainOrClass, validateOptions);
+        if (result.issues) {
+            throw new Error(`Serialization failed: ${result.issues.map(i => i.message).join(', ')}`);
+        }
+        return result.value;
+    }
+    getContextOptions(context) {
+        return this.reflector.getAllAndOverride(CLASS_SERIALIZER_OPTIONS, [
+            context.getHandler(),
+            context.getClass(),
+        ]);
+    }
+};
+StandardSchemaSerializerInterceptor = __decorate([
+    Injectable(),
+    __param(0, Inject(REFLECTOR)),
+    __param(1, Optional()),
+    __metadata("design:paramtypes", [Object, Object])
+], StandardSchemaSerializerInterceptor);
+export { StandardSchemaSerializerInterceptor };

package/serializer/standard-schema-serializer.interfaces.d.ts

@@ -0,0 +1,18 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+/**
+ * Options for the `StandardSchemaSerializerInterceptor`, passed via
+ * `@SerializeOptions({ schema })`.
+ *
+ * @publicApi
+ */
+export interface StandardSchemaSerializerContextOptions {
+    /**
+     * A standard schema to use for serialization.
+     * Used by `StandardSchemaSerializerInterceptor` to validate/transform the response.
+     */
+    schema?: StandardSchemaV1;
+    /**
+     * Optional options forwarded to the schema's `~standard.validate()` call.
+     */
+    validateOptions?: StandardSchemaV1.Options;
+}

package/serializer/standard-schema-serializer.interfaces.js

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