@digitaldefiance/node-express-suite 3.11.31 → 3.12.0

package/src/decorators/schema.js

@@ -0,0 +1,329 @@
+"use strict";
+/**
+ * @fileoverview Schema decorators for Express Suite.
+ * Provides @ApiSchema and @ApiProperty decorators for registering
+ * OpenAPI schemas declaratively from TypeScript classes.
+ * @module decorators/schema
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiSchema = ApiSchema;
+exports.ApiProperty = ApiProperty;
+exports.getSchemaMetadata = getSchemaMetadata;
+exports.getPropertyMetadata = getPropertyMetadata;
+exports.getAllPropertyMetadata = getAllPropertyMetadata;
+exports.hasSchemaMetadata = hasSchemaMetadata;
+exports.registerSchema = registerSchema;
+require("reflect-metadata");
+const schemas_1 = require("../openapi/schemas");
+const metadata_keys_1 = require("./metadata-keys");
+const metadata_collector_1 = require("./metadata-collector");
+/**
+ * Symbol key for storing property metadata on a class.
+ */
+const SCHEMA_PROPERTIES_METADATA = Symbol('schema:properties');
+/**
+ * Decorator that registers a class as an OpenAPI schema.
+ * The class properties decorated with @ApiProperty will be converted
+ * to OpenAPI schema properties.
+ *
+ * @param options - Schema options including name, description, and example
+ * @returns Class decorator
+ *
+ * @example
+ * ```typescript
+ * @ApiSchema({ description: 'User entity' })
+ * class User {
+ *   @ApiProperty({ type: 'string', description: 'User ID' })
+ *   id: string;
+ *
+ *   @ApiProperty({ type: 'string', format: 'email' })
+ *   email: string;
+ * }
+ * ```
+ */
+function ApiSchema(options = {}) {
+    return (target) => {
+        const constructor = target;
+        // Get schema name from options or class name
+        const schemaName = options.name ?? constructor.name;
+        // Collect properties from this class and parent classes
+        const properties = collectAllProperties(constructor);
+        // Create schema metadata
+        const schemaMetadata = {
+            name: schemaName,
+            options,
+            properties,
+        };
+        // Store metadata on the class
+        (0, metadata_collector_1.setMetadata)(metadata_keys_1.SCHEMA_METADATA, schemaMetadata, target);
+        // Build and register the OpenAPI schema
+        const openApiSchema = buildOpenAPISchema(schemaMetadata);
+        schemas_1.OpenAPISchemaRegistry.registerSchema(schemaName, openApiSchema);
+    };
+}
+/**
+ * Decorator that marks a class property for inclusion in the OpenAPI schema.
+ * Must be used in conjunction with @ApiSchema on the class.
+ *
+ * @param options - Property options including type, format, description, etc.
+ * @returns Property decorator
+ *
+ * @example
+ * ```typescript
+ * class User {
+ *   @ApiProperty({
+ *     type: 'string',
+ *     description: 'Unique identifier',
+ *     example: '123e4567-e89b-12d3-a456-426614174000'
+ *   })
+ *   id: string;
+ *
+ *   @ApiProperty({
+ *     type: 'string',
+ *     format: 'email',
+ *     required: true
+ *   })
+ *   email: string;
+ *
+ *   @ApiProperty({
+ *     type: 'integer',
+ *     minimum: 0,
+ *     maximum: 150
+ *   })
+ *   age?: number;
+ * }
+ * ```
+ */
+function ApiProperty(options = {}) {
+    return (target, propertyKey) => {
+        // Get the constructor (class) from the prototype
+        const constructor = target.constructor;
+        // Get existing properties or create new array
+        const existingProperties = Reflect.getMetadata(SCHEMA_PROPERTIES_METADATA, constructor) ?? [];
+        // Infer type from TypeScript metadata if not provided
+        const inferredOptions = inferPropertyType(target, propertyKey, options);
+        // Add this property
+        const propertyMetadata = {
+            propertyKey: String(propertyKey),
+            options: inferredOptions,
+        };
+        existingProperties.push(propertyMetadata);
+        // Store updated properties
+        Reflect.defineMetadata(SCHEMA_PROPERTIES_METADATA, existingProperties, constructor);
+    };
+}
+/**
+ * Collects all properties from a class and its parent classes.
+ * Supports inheritance by walking up the prototype chain.
+ * Child class properties override parent class properties with the same name.
+ *
+ * @param target - The class constructor
+ * @returns Array of all property metadata
+ */
+function collectAllProperties(target) {
+    const propertyMap = new Map();
+    // Collect classes in order from parent to child
+    const classChain = [];
+    let currentClass = target;
+    while (currentClass && currentClass !== Function.prototype) {
+        classChain.unshift(currentClass); // Add to beginning so parents come first
+        currentClass = Object.getPrototypeOf(currentClass);
+    }
+    // Process from parent to child, so child properties override parent
+    for (const cls of classChain) {
+        const properties = Reflect.getMetadata(SCHEMA_PROPERTIES_METADATA, cls) ?? [];
+        for (const prop of properties) {
+            propertyMap.set(prop.propertyKey, prop);
+        }
+    }
+    return Array.from(propertyMap.values());
+}
+/**
+ * Infers the OpenAPI type from TypeScript design:type metadata.
+ *
+ * @param target - The class prototype
+ * @param propertyKey - The property name
+ * @param options - User-provided options
+ * @returns Options with inferred type if not provided
+ */
+function inferPropertyType(target, propertyKey, options) {
+    // If type is already provided, use it
+    if (options.type) {
+        return options;
+    }
+    // Try to get TypeScript design:type metadata
+    const designType = Reflect.getMetadata('design:type', target, propertyKey);
+    if (!designType) {
+        return options;
+    }
+    // Map TypeScript types to OpenAPI types
+    const typeMap = {
+        String: 'string',
+        Number: 'number',
+        Boolean: 'boolean',
+        Array: 'array',
+        Object: 'object',
+        Date: 'string',
+    };
+    const inferredType = typeMap[designType.name];
+    if (inferredType) {
+        const result = { ...options, type: inferredType };
+        // Add format for Date
+        if (designType.name === 'Date' && !options.format) {
+            result.format = 'date-time';
+        }
+        return result;
+    }
+    return options;
+}
+/**
+ * Builds an OpenAPI schema object from schema metadata.
+ *
+ * @param metadata - The schema metadata
+ * @returns OpenAPI schema object
+ */
+function buildOpenAPISchema(metadata) {
+    const schema = {
+        type: 'object',
+    };
+    // Add description if provided
+    if (metadata.options.description) {
+        schema.description = metadata.options.description;
+    }
+    // Add example if provided
+    if (metadata.options.example !== undefined) {
+        schema.example = metadata.options.example;
+    }
+    // Build properties
+    const properties = {};
+    const required = [];
+    for (const prop of metadata.properties) {
+        const propSchema = buildPropertySchema(prop.options);
+        properties[prop.propertyKey] = propSchema;
+        // Track required properties
+        if (prop.options.required) {
+            required.push(prop.propertyKey);
+        }
+    }
+    if (Object.keys(properties).length > 0) {
+        schema.properties = properties;
+    }
+    if (required.length > 0) {
+        schema.required = required;
+    }
+    return schema;
+}
+/**
+ * Builds an OpenAPI property schema from property options.
+ *
+ * @param options - The property options
+ * @returns OpenAPI property schema
+ */
+function buildPropertySchema(options) {
+    const schema = {};
+    // Handle $ref separately
+    if (options.$ref) {
+        return { $ref: `#/components/schemas/${options.$ref}` };
+    }
+    // Type
+    if (options.type) {
+        schema.type = options.type;
+    }
+    // Format
+    if (options.format) {
+        schema.format = options.format;
+    }
+    // Description
+    if (options.description) {
+        schema.description = options.description;
+    }
+    // Example
+    if (options.example !== undefined) {
+        schema.example = options.example;
+    }
+    // Enum
+    if (options.enum && options.enum.length > 0) {
+        schema.enum = options.enum;
+    }
+    // Nullable
+    if (options.nullable) {
+        schema.nullable = options.nullable;
+    }
+    // Numeric constraints
+    if (options.minimum !== undefined) {
+        schema.minimum = options.minimum;
+    }
+    if (options.maximum !== undefined) {
+        schema.maximum = options.maximum;
+    }
+    // String constraints
+    if (options.minLength !== undefined) {
+        schema.minLength = options.minLength;
+    }
+    if (options.maxLength !== undefined) {
+        schema.maxLength = options.maxLength;
+    }
+    if (options.pattern) {
+        schema.pattern = options.pattern;
+    }
+    // Array items
+    if (options.items) {
+        if (typeof options.items === 'string') {
+            schema.items = { $ref: `#/components/schemas/${options.items}` };
+        }
+        else {
+            schema.items = options.items;
+        }
+    }
+    return schema;
+}
+/**
+ * Gets the schema metadata for a class.
+ *
+ * @param target - The class constructor
+ * @returns The schema metadata or undefined
+ */
+function getSchemaMetadata(target) {
+    return (0, metadata_collector_1.getMetadata)(metadata_keys_1.SCHEMA_METADATA, target);
+}
+/**
+ * Gets the property metadata for a class (without inheritance).
+ *
+ * @param target - The class constructor
+ * @returns Array of property metadata
+ */
+function getPropertyMetadata(target) {
+    return (Reflect.getMetadata(SCHEMA_PROPERTIES_METADATA, target) ?? []);
+}
+/**
+ * Gets all property metadata for a class including inherited properties.
+ *
+ * @param target - The class constructor
+ * @returns Array of all property metadata
+ */
+function getAllPropertyMetadata(target) {
+    return collectAllProperties(target);
+}
+/**
+ * Checks if a class has been decorated with @ApiSchema.
+ *
+ * @param target - The class constructor
+ * @returns True if the class has schema metadata
+ */
+function hasSchemaMetadata(target) {
+    return getSchemaMetadata(target) !== undefined;
+}
+/**
+ * Manually registers a schema from a decorated class.
+ * Useful when you need to re-register or update a schema.
+ *
+ * @param target - The class constructor decorated with @ApiSchema
+ */
+function registerSchema(target) {
+    const metadata = getSchemaMetadata(target);
+    if (metadata) {
+        const openApiSchema = buildOpenAPISchema(metadata);
+        schemas_1.OpenAPISchemaRegistry.registerSchema(metadata.name, openApiSchema);
+    }
+}
+//# sourceMappingURL=schema.js.map

package/src/decorators/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/decorators/schema.ts"],"names":[],"mappings":"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"}

package/src/decorators/transaction.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview Transaction decorator for Express Suite.
+ * Provides @Transactional decorator for MongoDB transaction support.
+ * @module decorators/transaction
+ */
+import 'reflect-metadata';
+import { TransactionalDecoratorOptions } from '../interfaces/openApi/decoratorOptions';
+/**
+ * Metadata stored for transaction settings.
+ */
+export interface TransactionMetadata {
+    /**
+     * Whether the route should use a transaction.
+     */
+    useTransaction: boolean;
+    /**
+     * Transaction timeout in milliseconds.
+     */
+    timeout?: number;
+}
+/**
+ * Decorator that wraps a route handler in a MongoDB transaction.
+ * The transaction is automatically committed on success and rolled back on error.
+ *
+ * @param options - Optional transaction options including timeout
+ * @returns Method decorator
+ *
+ * @example
+ * ```typescript
+ * @ApiController('/api/orders')
+ * class OrderController {
+ *   // Basic transaction
+ *   @Transactional()
+ *   @Post('/')
+ *   createOrder() {}
+ *
+ *   // Transaction with timeout
+ *   @Transactional({ timeout: 30000 })
+ *   @Post('/bulk')
+ *   bulkCreateOrders() {}
+ * }
+ * ```
+ */
+export declare function Transactional(options?: TransactionalDecoratorOptions): MethodDecorator;
+/**
+ * Gets transaction metadata for a method.
+ *
+ * @param target - The class constructor
+ * @param propertyKey - The method name
+ * @returns Transaction metadata or undefined if not transactional
+ */
+export declare function getTransactionMetadata(target: object, propertyKey: string | symbol): TransactionMetadata | undefined;
+/**
+ * Checks if a method is transactional.
+ *
+ * @param target - The class constructor
+ * @param propertyKey - The method name
+ * @returns True if the method uses transactions
+ */
+export declare function isTransactional(target: object, propertyKey: string | symbol): boolean;
+/**
+ * Gets the transaction timeout for a method.
+ *
+ * @param target - The class constructor
+ * @param propertyKey - The method name
+ * @returns Transaction timeout in milliseconds or undefined
+ */
+export declare function getTransactionTimeout(target: object, propertyKey: string | symbol): number | undefined;
+//# sourceMappingURL=transaction.d.ts.map

package/src/decorators/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/decorators/transaction.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,6BAA6B,EAAE,MAAM,wCAAwC,CAAC;AAIvF;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,cAAc,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAC3B,OAAO,CAAC,EAAE,6BAA6B,GACtC,eAAe,CAoBjB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAAG,MAAM,GAC3B,mBAAmB,GAAG,SAAS,CAMjC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAAG,MAAM,GAC3B,OAAO,CAGT;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAAG,MAAM,GAC3B,MAAM,GAAG,SAAS,CAGpB"}

package/src/decorators/transaction.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * @fileoverview Transaction decorator for Express Suite.
+ * Provides @Transactional decorator for MongoDB transaction support.
+ * @module decorators/transaction
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Transactional = Transactional;
+exports.getTransactionMetadata = getTransactionMetadata;
+exports.isTransactional = isTransactional;
+exports.getTransactionTimeout = getTransactionTimeout;
+require("reflect-metadata");
+const metadata_keys_1 = require("./metadata-keys");
+const metadata_collector_1 = require("./metadata-collector");
+/**
+ * Decorator that wraps a route handler in a MongoDB transaction.
+ * The transaction is automatically committed on success and rolled back on error.
+ *
+ * @param options - Optional transaction options including timeout
+ * @returns Method decorator
+ *
+ * @example
+ * ```typescript
+ * @ApiController('/api/orders')
+ * class OrderController {
+ *   // Basic transaction
+ *   @Transactional()
+ *   @Post('/')
+ *   createOrder() {}
+ *
+ *   // Transaction with timeout
+ *   @Transactional({ timeout: 30000 })
+ *   @Post('/bulk')
+ *   bulkCreateOrders() {}
+ * }
+ * ```
+ */
+function Transactional(options) {
+    return function (target, propertyKey, descriptor) {
+        const metadata = {
+            useTransaction: true,
+            timeout: options?.timeout,
+        };
+        (0, metadata_collector_1.setMetadata)(metadata_keys_1.TRANSACTION_METADATA, metadata, target.constructor, propertyKey);
+        return descriptor;
+    };
+}
+/**
+ * Gets transaction metadata for a method.
+ *
+ * @param target - The class constructor
+ * @param propertyKey - The method name
+ * @returns Transaction metadata or undefined if not transactional
+ */
+function getTransactionMetadata(target, propertyKey) {
+    return (0, metadata_collector_1.getMetadata)(metadata_keys_1.TRANSACTION_METADATA, target, propertyKey);
+}
+/**
+ * Checks if a method is transactional.
+ *
+ * @param target - The class constructor
+ * @param propertyKey - The method name
+ * @returns True if the method uses transactions
+ */
+function isTransactional(target, propertyKey) {
+    const metadata = getTransactionMetadata(target, propertyKey);
+    return metadata?.useTransaction === true;
+}
+/**
+ * Gets the transaction timeout for a method.
+ *
+ * @param target - The class constructor
+ * @param propertyKey - The method name
+ * @returns Transaction timeout in milliseconds or undefined
+ */
+function getTransactionTimeout(target, propertyKey) {
+    const metadata = getTransactionMetadata(target, propertyKey);
+    return metadata?.timeout;
+}
+//# sourceMappingURL=transaction.js.map

package/src/decorators/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/decorators/transaction.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AA6CH,sCAsBC;AASD,wDASC;AASD,0CAMC;AASD,sDAMC;AAjHD,4BAA0B;AAE1B,mDAAuD;AACvD,6DAAgE;AAiBhE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,SAAgB,aAAa,CAC3B,OAAuC;IAEvC,OAAO,UACL,MAAc,EACd,WAA4B,EAC5B,UAA8B;QAE9B,MAAM,QAAQ,GAAwB;YACpC,cAAc,EAAE,IAAI;YACpB,OAAO,EAAE,OAAO,EAAE,OAAO;SAC1B,CAAC;QAEF,IAAA,gCAAW,EACT,oCAAoB,EACpB,QAAQ,EACR,MAAM,CAAC,WAAW,EAClB,WAAW,CACZ,CAAC;QAEF,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,sBAAsB,CACpC,MAAc,EACd,WAA4B;IAE5B,OAAO,IAAA,gCAAW,EAChB,oCAAoB,EACpB,MAAM,EACN,WAAW,CACZ,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,eAAe,CAC7B,MAAc,EACd,WAA4B;IAE5B,MAAM,QAAQ,GAAG,sBAAsB,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC7D,OAAO,QAAQ,EAAE,cAAc,KAAK,IAAI,CAAC;AAC3C,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,qBAAqB,CACnC,MAAc,EACd,WAA4B;IAE5B,MAAM,QAAQ,GAAG,sBAAsB,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC7D,OAAO,QAAQ,EAAE,OAAO,CAAC;AAC3B,CAAC"}

package/src/decorators/validation.d.ts

@@ -0,0 +1,188 @@
+/**
+ * @fileoverview Validation decorators for Express Suite.
+ * Provides @ValidateBody, @ValidateParams, @ValidateQuery decorators.
+ * Supports Zod schemas, express-validator chains, and language-aware validation functions.
+ * Automatically adds 400 response to OpenAPI spec.
+ * @module decorators/validation
+ */
+import 'reflect-metadata';
+import { ValidationChain } from 'express-validator';
+import { z } from 'zod';
+import { CoreLanguageCode } from '@digitaldefiance/i18n-lib';
+import { IConstants } from '../interfaces/constants';
+import { ValidationContext, ValidationMetadata } from '../interfaces/openApi/decoratorOptions';
+/**
+ * Type for validation input - can be Zod schema, validation chains, or language-aware function.
+ */
+export type ValidationInput<TLanguage extends CoreLanguageCode = CoreLanguageCode, TConstants extends IConstants = IConstants> = z.ZodSchema | ValidationChain[] | ((this: ValidationContext<TConstants>, lang: TLanguage) => ValidationChain[]);
+/**
+ * Decorator that validates the request body.
+ * Supports Zod schemas, express-validator chains, and language-aware validation functions.
+ * Automatically adds 400 response to OpenAPI spec.
+ *
+ * @param validation - Zod schema, ValidationChain[], or language-aware validation function
+ * @returns Class or method decorator
+ *
+ * @example
+ * ```typescript
+ * // With Zod schema
+ * const CreateUserSchema = z.object({
+ *   name: z.string().min(1),
+ *   email: z.string().email(),
+ * });
+ *
+ * @ApiController('/api/users')
+ * class UserController {
+ *   @ValidateBody(CreateUserSchema)
+ *   @Post('/')
+ *   createUser(@Body() data: z.infer<typeof CreateUserSchema>) {
+ *     return this.userService.create(data);
+ *   }
+ * }
+ *
+ * // With express-validator chains
+ * @ApiController('/api/items')
+ * class ItemController {
+ *   @ValidateBody([
+ *     body('name').isString().notEmpty(),
+ *     body('price').isNumeric(),
+ *   ])
+ *   @Post('/')
+ *   createItem(@Body() data: CreateItemDto) {
+ *     return this.itemService.create(data);
+ *   }
+ * }
+ *
+ * // With language-aware validation function
+ * @ApiController('/api/products')
+ * class ProductController {
+ *   @ValidateBody(function(lang) {
+ *     return [
+ *       body('name').isString().withMessage(this.constants.messages[lang].nameRequired),
+ *     ];
+ *   })
+ *   @Post('/')
+ *   createProduct(@Body() data: CreateProductDto) {
+ *     return this.productService.create(data);
+ *   }
+ * }
+ * ```
+ */
+export declare function ValidateBody<TLanguage extends CoreLanguageCode = CoreLanguageCode, TConstants extends IConstants = IConstants>(validation: ValidationInput<TLanguage, TConstants>): ClassDecorator & MethodDecorator;
+/**
+ * Decorator that validates path parameters.
+ * Supports Zod schemas, express-validator chains, and language-aware validation functions.
+ * Automatically adds 400 response to OpenAPI spec.
+ *
+ * @param validation - Zod schema, ValidationChain[], or language-aware validation function
+ * @returns Class or method decorator
+ *
+ * @example
+ * ```typescript
+ * // With Zod schema
+ * const IdParamSchema = z.object({
+ *   id: z.string().uuid(),
+ * });
+ *
+ * @ApiController('/api/users')
+ * class UserController {
+ *   @ValidateParams(IdParamSchema)
+ *   @Get('/:id')
+ *   getUser(@Param('id') id: string) {
+ *     return this.userService.findById(id);
+ *   }
+ * }
+ *
+ * // With express-validator chains
+ * @ApiController('/api/items')
+ * class ItemController {
+ *   @ValidateParams([
+ *     param('id').isMongoId().withMessage('Invalid item ID'),
+ *   ])
+ *   @Get('/:id')
+ *   getItem(@Param('id') id: string) {
+ *     return this.itemService.findById(id);
+ *   }
+ * }
+ * ```
+ */
+export declare function ValidateParams<TLanguage extends CoreLanguageCode = CoreLanguageCode, TConstants extends IConstants = IConstants>(validation: ValidationInput<TLanguage, TConstants>): ClassDecorator & MethodDecorator;
+/**
+ * Decorator that validates query parameters.
+ * Supports Zod schemas, express-validator chains, and language-aware validation functions.
+ * Automatically adds 400 response to OpenAPI spec.
+ *
+ * @param validation - Zod schema, ValidationChain[], or language-aware validation function
+ * @returns Class or method decorator
+ *
+ * @example
+ * ```typescript
+ * // With Zod schema
+ * const PaginationSchema = z.object({
+ *   page: z.coerce.number().int().positive().optional().default(1),
+ *   limit: z.coerce.number().int().positive().max(100).optional().default(10),
+ * });
+ *
+ * @ApiController('/api/users')
+ * class UserController {
+ *   @ValidateQuery(PaginationSchema)
+ *   @Get('/')
+ *   listUsers(@Query('page') page: number, @Query('limit') limit: number) {
+ *     return this.userService.findAll({ page, limit });
+ *   }
+ * }
+ *
+ * // With express-validator chains
+ * @ApiController('/api/search')
+ * class SearchController {
+ *   @ValidateQuery([
+ *     query('q').isString().notEmpty().withMessage('Search query is required'),
+ *     query('page').optional().isInt({ min: 1 }),
+ *   ])
+ *   @Get('/')
+ *   search(@Query('q') q: string, @Query('page') page?: number) {
+ *     return this.searchService.search(q, page);
+ *   }
+ * }
+ * ```
+ */
+export declare function ValidateQuery<TLanguage extends CoreLanguageCode = CoreLanguageCode, TConstants extends IConstants = IConstants>(validation: ValidationInput<TLanguage, TConstants>): ClassDecorator & MethodDecorator;
+/**
+ * Gets the effective validation metadata for a method, merging class-level and method-level settings.
+ * Method-level settings override class-level settings for the same field.
+ *
+ * @param target - The class constructor
+ * @param propertyKey - The method name
+ * @returns The merged validation metadata
+ */
+export declare function getEffectiveValidationMetadata<TLanguage extends CoreLanguageCode = CoreLanguageCode, TConstants extends IConstants = IConstants>(target: object, propertyKey: string | symbol): ValidationMetadata<TLanguage, TConstants>;
+/**
+ * Checks if a route has any validation configured.
+ *
+ * @param target - The class constructor
+ * @param propertyKey - The method name
+ * @returns True if the route has any validation
+ */
+export declare function hasValidation(target: object, propertyKey: string | symbol): boolean;
+/**
+ * Checks if a validation input is a Zod schema.
+ *
+ * @param validation - The validation input to check
+ * @returns True if the validation is a Zod schema
+ */
+export declare function isZodSchema(validation: ValidationInput): validation is z.ZodSchema;
+/**
+ * Checks if a validation input is an array of ValidationChains.
+ *
+ * @param validation - The validation input to check
+ * @returns True if the validation is an array of ValidationChains
+ */
+export declare function isValidationChainArray(validation: ValidationInput): validation is ValidationChain[];
+/**
+ * Checks if a validation input is a language-aware validation function.
+ *
+ * @param validation - The validation input to check
+ * @returns True if the validation is a function
+ */
+export declare function isValidationFunction<TLanguage extends CoreLanguageCode = CoreLanguageCode, TConstants extends IConstants = IConstants>(validation: ValidationInput<TLanguage, TConstants>): validation is (this: ValidationContext<TConstants>, lang: TLanguage) => ValidationChain[];
+//# sourceMappingURL=validation.d.ts.map