@nest-openapi/validator 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,178 @@
+import * as _nestjs_common from '@nestjs/common';
+import { ExecutionContext, DynamicModule, OnApplicationBootstrap } from '@nestjs/common';
+import Ajv, { ErrorObject, Options } from 'ajv';
+import { SpecSource, OpenAPISpec, OpenApiRuntimeService } from '@nest-openapi/runtime';
+import { HttpArgumentsHost } from '@nestjs/common/interfaces';
+
+interface ValidationError extends ErrorObject {
+    validationType: 'path' | 'query' | 'body' | 'response';
+}
+interface ValidationErrorResponse {
+    message: string;
+    errors: ValidationError[];
+}
+
+interface ValidatorOptions {
+    /**
+     * Provide your OpenAPI spec as an object, or point to it via URL or file path.
+     *
+     * Examples:
+     * ```
+     *   { type: "object", spec: {...} }
+     *   { type: "url",    spec: "https://…" }
+     *   { type: "file",   spec: "./openapi.json" }
+     * ```
+     */
+    specSource: SpecSource;
+    requestValidation?: {
+        /**
+         * Enable request validation
+         * @default true
+         */
+        enable?: boolean;
+        /**
+         * Transform request data after validation
+         * @default false
+         */
+        transform?: boolean;
+        /**
+         * Custom error handler for request validation failures.
+         *
+         * You can:
+         * - Transform errors and throw a custom exception
+         * - Log and Ignore errors (return without throwing)
+         *
+         * If not provided, throws `BadRequestException` with validation errors
+         */
+        onValidationFailed?: (context: ExecutionContext, errors: ValidationError[]) => void | never;
+    };
+    responseValidation?: {
+        /**
+         * Enable response validation
+         * @default false
+         */
+        enable?: boolean;
+        /**
+         * Skip validation for error responses (4xx and 5xx status codes).
+         * @default true
+         */
+        skipErrorResponses?: boolean;
+        /**
+         * Custom error handler for response validation failures.
+         *
+         * You can:
+         * - Transform errors and throw a custom exception
+         * - Log and ignore errors (return without throwing)
+         *
+         * If not provided, warns and throws `InternalServerErrorException` without validation errors
+         */
+        onValidationFailed?: (context: ExecutionContext, errors: ValidationError[]) => void | never;
+    };
+    /**
+     * Override the default ajv instance or configure it
+     */
+    ajv?: Ajv | {
+        options?: Options;
+        configure?: (ajv: Ajv) => void;
+    };
+    /**
+     * Compile every request/parameter schema during application bootstrap.
+     * This removes the first-request latency at the cost of longer start-up time.
+     * @default false
+     */
+    precompileSchemas?: boolean;
+    /**
+     * Verbose logs for troubleshooting
+     * @default false
+     */
+    debug?: boolean;
+}
+
+declare class OpenApiValidatorModule {
+    /**
+     * Configure the OpenAPI validator module with static options
+     */
+    static forRoot(options: ValidatorOptions): DynamicModule;
+    /**
+     * Configure the OpenAPI validator module with async options
+     */
+    static forRootAsync(options: {
+        imports?: any[];
+        useFactory?: (...args: any[]) => ValidatorOptions | Promise<ValidatorOptions>;
+        inject?: any[];
+    }): DynamicModule;
+}
+
+declare const OPENAPI_VALIDATOR = "OPENAPI_VALIDATOR";
+declare class OpenApiValidatorService implements OnApplicationBootstrap {
+    private readonly runtime;
+    private readonly options;
+    private readonly logger;
+    private ajv;
+    openApiSpec: OpenAPISpec;
+    private debugLog;
+    constructor(runtime: OpenApiRuntimeService, options: ValidatorOptions);
+    onApplicationBootstrap(): Promise<void>;
+    private get isSpecLoaded();
+    get validationOptions(): ValidatorOptions;
+    /**
+     * Register all component schemas with AJV so it can resolve $ref references
+     */
+    private registerComponentSchemas;
+    /**
+     * Walk the OpenAPI spec and eagerly compile all requestBody and parameter
+     * schemas. This is triggered when `options.performance.precompileSchemas === true` and
+     * eliminates runtime compilation overhead.
+     */
+    private precompileSchemas;
+    private findOperation;
+    private validateWithSchema;
+    validateRequest(httpContext: HttpArgumentsHost, options?: {
+        body?: boolean;
+        params?: boolean;
+        query?: boolean;
+    }): ValidationError[];
+    private validateParameters;
+    validateResponse(httpContext: HttpArgumentsHost, statusCode: number, responseBody: any): ValidationError[];
+    private getParameterSchema;
+}
+
+interface ValidateOptions {
+    request?: boolean | {
+        params?: boolean;
+        query?: boolean;
+        body?: boolean;
+    };
+    response?: boolean;
+}
+/**
+ * Decorator to configure validation behavior for a specific route
+ *
+ * @param options - Validation configuration options
+ * @param options.request - Request validation settings:
+ *   - `true`: Validate all request parts (params, query, body)
+ *   - `false`: Skip request validation entirely
+ *   - `{ params?, query?, body? }`: Validate only specified request parts
+ *   - `undefined`: Use default configuration
+ * @param options.response - Response validation settings:
+ *   - `true`: Enable response validation
+ *   - `false`: Skip response validation
+ *   - `undefined`: Use default configuration
+ *
+ * @example In controller:
+ *
+ * ```typescript
+ * @Controller('users')
+ * export class UsersController {
+ *   // Validate body and response
+ *   @Put(':id')
+ *   @Validate({ request: { body: true }, response: true })
+ *   update(@Param('id') id: string, @Body() user: UpdateUserDto): User {
+ *     return this.usersService.update(id, user);
+ *   }
+ * }
+ * ```
+ */
+declare const Validate: (options?: ValidateOptions) => _nestjs_common.CustomDecorator<string>;
+
+export { OPENAPI_VALIDATOR, OpenApiValidatorModule, OpenApiValidatorService, Validate, type ValidateOptions, type ValidationError, type ValidationErrorResponse, type ValidatorOptions };

package/dist/index.d.ts

@@ -0,0 +1,178 @@
+import * as _nestjs_common from '@nestjs/common';
+import { ExecutionContext, DynamicModule, OnApplicationBootstrap } from '@nestjs/common';
+import Ajv, { ErrorObject, Options } from 'ajv';
+import { SpecSource, OpenAPISpec, OpenApiRuntimeService } from '@nest-openapi/runtime';
+import { HttpArgumentsHost } from '@nestjs/common/interfaces';
+
+interface ValidationError extends ErrorObject {
+    validationType: 'path' | 'query' | 'body' | 'response';
+}
+interface ValidationErrorResponse {
+    message: string;
+    errors: ValidationError[];
+}
+
+interface ValidatorOptions {
+    /**
+     * Provide your OpenAPI spec as an object, or point to it via URL or file path.
+     *
+     * Examples:
+     * ```
+     *   { type: "object", spec: {...} }
+     *   { type: "url",    spec: "https://…" }
+     *   { type: "file",   spec: "./openapi.json" }
+     * ```
+     */
+    specSource: SpecSource;
+    requestValidation?: {
+        /**
+         * Enable request validation
+         * @default true
+         */
+        enable?: boolean;
+        /**
+         * Transform request data after validation
+         * @default false
+         */
+        transform?: boolean;
+        /**
+         * Custom error handler for request validation failures.
+         *
+         * You can:
+         * - Transform errors and throw a custom exception
+         * - Log and Ignore errors (return without throwing)
+         *
+         * If not provided, throws `BadRequestException` with validation errors
+         */
+        onValidationFailed?: (context: ExecutionContext, errors: ValidationError[]) => void | never;
+    };
+    responseValidation?: {
+        /**
+         * Enable response validation
+         * @default false
+         */
+        enable?: boolean;
+        /**
+         * Skip validation for error responses (4xx and 5xx status codes).
+         * @default true
+         */
+        skipErrorResponses?: boolean;
+        /**
+         * Custom error handler for response validation failures.
+         *
+         * You can:
+         * - Transform errors and throw a custom exception
+         * - Log and ignore errors (return without throwing)
+         *
+         * If not provided, warns and throws `InternalServerErrorException` without validation errors
+         */
+        onValidationFailed?: (context: ExecutionContext, errors: ValidationError[]) => void | never;
+    };
+    /**
+     * Override the default ajv instance or configure it
+     */
+    ajv?: Ajv | {
+        options?: Options;
+        configure?: (ajv: Ajv) => void;
+    };
+    /**
+     * Compile every request/parameter schema during application bootstrap.
+     * This removes the first-request latency at the cost of longer start-up time.
+     * @default false
+     */
+    precompileSchemas?: boolean;
+    /**
+     * Verbose logs for troubleshooting
+     * @default false
+     */
+    debug?: boolean;
+}
+
+declare class OpenApiValidatorModule {
+    /**
+     * Configure the OpenAPI validator module with static options
+     */
+    static forRoot(options: ValidatorOptions): DynamicModule;
+    /**
+     * Configure the OpenAPI validator module with async options
+     */
+    static forRootAsync(options: {
+        imports?: any[];
+        useFactory?: (...args: any[]) => ValidatorOptions | Promise<ValidatorOptions>;
+        inject?: any[];
+    }): DynamicModule;
+}
+
+declare const OPENAPI_VALIDATOR = "OPENAPI_VALIDATOR";
+declare class OpenApiValidatorService implements OnApplicationBootstrap {
+    private readonly runtime;
+    private readonly options;
+    private readonly logger;
+    private ajv;
+    openApiSpec: OpenAPISpec;
+    private debugLog;
+    constructor(runtime: OpenApiRuntimeService, options: ValidatorOptions);
+    onApplicationBootstrap(): Promise<void>;
+    private get isSpecLoaded();
+    get validationOptions(): ValidatorOptions;
+    /**
+     * Register all component schemas with AJV so it can resolve $ref references
+     */
+    private registerComponentSchemas;
+    /**
+     * Walk the OpenAPI spec and eagerly compile all requestBody and parameter
+     * schemas. This is triggered when `options.performance.precompileSchemas === true` and
+     * eliminates runtime compilation overhead.
+     */
+    private precompileSchemas;
+    private findOperation;
+    private validateWithSchema;
+    validateRequest(httpContext: HttpArgumentsHost, options?: {
+        body?: boolean;
+        params?: boolean;
+        query?: boolean;
+    }): ValidationError[];
+    private validateParameters;
+    validateResponse(httpContext: HttpArgumentsHost, statusCode: number, responseBody: any): ValidationError[];
+    private getParameterSchema;
+}
+
+interface ValidateOptions {
+    request?: boolean | {
+        params?: boolean;
+        query?: boolean;
+        body?: boolean;
+    };
+    response?: boolean;
+}
+/**
+ * Decorator to configure validation behavior for a specific route
+ *
+ * @param options - Validation configuration options
+ * @param options.request - Request validation settings:
+ *   - `true`: Validate all request parts (params, query, body)
+ *   - `false`: Skip request validation entirely
+ *   - `{ params?, query?, body? }`: Validate only specified request parts
+ *   - `undefined`: Use default configuration
+ * @param options.response - Response validation settings:
+ *   - `true`: Enable response validation
+ *   - `false`: Skip response validation
+ *   - `undefined`: Use default configuration
+ *
+ * @example In controller:
+ *
+ * ```typescript
+ * @Controller('users')
+ * export class UsersController {
+ *   // Validate body and response
+ *   @Put(':id')
+ *   @Validate({ request: { body: true }, response: true })
+ *   update(@Param('id') id: string, @Body() user: UpdateUserDto): User {
+ *     return this.usersService.update(id, user);
+ *   }
+ * }
+ * ```
+ */
+declare const Validate: (options?: ValidateOptions) => _nestjs_common.CustomDecorator<string>;
+
+export { OPENAPI_VALIDATOR, OpenApiValidatorModule, OpenApiValidatorService, Validate, type ValidateOptions, type ValidationError, type ValidationErrorResponse, type ValidatorOptions };