@decaf-ts/decorator-validation/lib/validation/decorators.d.ts

simple decorator based validation engine

import "reflect-metadata";
import { ComparisonValidatorOptions, DateValidatorOptions, ListValidatorOptions, ValidatorOptions } from "./types";
import { Constructor, ModelConstructor } from "../model/types";
/**
 * @description Combined property decorator factory for metadata and attribute marking
 * @summary Creates a decorator that both marks a property as a model attribute and assigns metadata to it
 *
 * @template V
 * @param {PropertyDecorator} decorator - The metadata key
 * @param {string} key - The metadata key
 * @param {V} value - The metadata value to associate with the property
 * @return {Function} - Combined decorator function
 * @function validationMetadata
 * @category Property Decorators
 */
export declare function validationMetadata<V>(decorator: any, key: string, value: V): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor) => void;
export declare function async(): (model: object) => void;
/**
 * @description Property decorator that marks a field as required
 * @summary Marks the property as required, causing validation to fail if the property is undefined, null, or empty.
 * Validators to validate a decorated property must use key {@link ValidationKeys#REQUIRED}.
 * This decorator is commonly used as the first validation step for important fields.
 *
 * @param {string} [message] - The error message to display when validation fails. Defaults to {@link DEFAULT_ERROR_MESSAGES#REQUIRED}
 * @return {PropertyDecorator} A decorator function that can be applied to class properties
 *
 * @function required
 * @category Property Decorators
 *
 * @example
 * ```typescript
 * class User {
 *   @required()
 *   username: string;
 *
 *   @required("Email address is mandatory")
 *   email: string;
 * }
 * ```
 */
export declare function required(message?: string): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
/**
 * @description Property decorator that enforces a minimum value constraint
 * @summary Defines a minimum value for the property, causing validation to fail if the property value is less than the specified minimum.
 * Validators to validate a decorated property must use key {@link ValidationKeys#MIN}.
 * This decorator works with numeric values and dates.
 *
 * @param {number | Date | string} value - The minimum value allowed. For dates, can be a Date object or a string that can be converted to a date
 * @param {string} [message] - The error message to display when validation fails. Defaults to {@link DEFAULT_ERROR_MESSAGES#MIN}
 * @return {PropertyDecorator} A decorator function that can be applied to class properties
 *
 * @function min
 * @category Property Decorators
 *
 * @example
 * ```typescript
 * class Product {
 *   @min(0)
 *   price: number;
 *
 *   @min(new Date(2023, 0, 1), "Date must be after January 1, 2023")
 *   releaseDate: Date;
 * }
 * ```
 */
export declare function min(value: number | Date | string, message?: string): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
/**
 * @summary Defines a maximum value for the property
 * @description Validators to validate a decorated property must use key {@link ValidationKeys#MAX}
 *
 * @param {number | Date} value
 * @param {string} [message] the error message. Defaults to {@link DEFAULT_ERROR_MESSAGES#MAX}
 *
 * @function max
 * @category Property Decorators
 */
export declare function max(value: number | Date | string, message?: string): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
/**
 * @summary Defines a step value for the property
 * @description Validators to validate a decorated property must use key {@link ValidationKeys#STEP}
 *
 * @param {number} value
 * @param {string} [message] the error message. Defaults to {@link DEFAULT_ERROR_MESSAGES#STEP}
 *
 * @function step
 * @category Property Decorators
 */
export declare function step(value: number, message?: string): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
/**
 * @summary Defines a minimum length for the property
 * @description Validators to validate a decorated property must use key {@link ValidationKeys#MIN_LENGTH}
 *
 * @param {string} value
 * @param {string} [message] the error message. Defaults to {@link DEFAULT_ERROR_MESSAGES#MIN_LENGTH}
 *
 * @function minlength
 * @category Property Decorators
 */
export declare function minlength(value: number, message?: string): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
/**
 * @summary Defines a maximum length for the property
 * @description Validators to validate a decorated property must use key {@link ValidationKeys#MAX_LENGTH}
 *
 * @param {string} value
 * @param {string} [message] the error message. Defaults to {@link DEFAULT_ERROR_MESSAGES#MAX_LENGTH}
 *
 * @function maxlength
 * @category Property Decorators
 */
export declare function maxlength(value: number, message?: string): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
/**
 * @summary Defines a RegExp pattern the property must respect
 * @description Validators to validate a decorated property must use key {@link ValidationKeys#PATTERN}
 *
 * @param {string} value
 * @param {string} [message] the error message. Defaults to {@link DEFAULT_ERROR_MESSAGES#PATTERN}
 *
 * @function pattern
 * @category Property Decorators
 */
export declare function pattern(value: RegExp | string, message?: string): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
/**
 * @summary Defines the property as an email
 * @description Validators to validate a decorated property must use key {@link ValidationKeys#EMAIL}
 *
 * @param {string} [message] the error message. Defaults to {@link DEFAULT_ERROR_MESSAGES#EMAIL}
 *
 * @function email
 * @category Property Decorators
 */
export declare function email(message?: string): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
/**
 * @summary Defines the property as an URL
 * @description Validators to validate a decorated property must use key {@link ValidationKeys#URL}
 *
 * @param {string} [message] the error message. Defaults to {@link DEFAULT_ERROR_MESSAGES#URL}
 *
 * @function url
 * @category Property Decorators
 */
export declare function url(message?: string): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
export interface TypeMetadata extends ValidatorOptions {
    customTypes: (string | (() => string))[] | string | (() => string);
}
/**
 * @summary Enforces type verification
 * @description Validators to validate a decorated property must use key {@link ValidationKeys#TYPE}
 *
 * @param {string[] | string} types accepted types
 * @param {string} [message] the error message. Defaults to {@link DEFAULT_ERROR_MESSAGES#TYPE}
 *
 * @function type
 * @category Property Decorators
 */
export declare function type(types: (string | (() => string))[] | string | (() => string), message?: string): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
export interface DateMetadata extends DateValidatorOptions {
    types: string[];
}
/**
 * @summary Date Handler Decorator
 * @description Validators to validate a decorated property must use key {@link ValidationKeys#DATE}
 *
 * Will enforce serialization according to the selected format
 *
 * @param {string} format accepted format according to {@link formatDate}
 * @param {string} [message] the error message. Defaults to {@link DEFAULT_ERROR_MESSAGES#DATE}
 *
 * @function date
 *
 * @category Property Decorators
 */
export declare function date(format?: string, message?: string): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
/**
 * @summary Password Handler Decorator
 * @description Validators to validate a decorated property must use key {@link ValidationKeys#PASSWORD}
 *
 * @param {RegExp} [pattern] defaults to {@link DEFAULT_PATTERNS#CHAR8_ONE_OF_EACH}
 * @param {string} [message] the error message. Defaults to {@link DEFAULT_ERROR_MESSAGES#PASSWORD}
 *
 * @function password
 *
 * @category Property Decorators
 */
export declare function password(pattern?: RegExp, message?: string): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
export interface ListMetadata extends ListValidatorOptions {
    type: "Array" | "Set";
}
/**
 * @summary List Decorator
 * @description Also sets the {@link type} to the provided collection
 *
 * @param {ModelConstructor} clazz
 * @param {string} [collection] The collection being used. defaults to Array
 * @param {string} [message] defaults to {@link DEFAULT_ERROR_MESSAGES#LIST}
 *
 * @function list
 *
 * @category Property Decorators
 */
export declare function list(clazz: Constructor<any> | (() => Constructor<any>) | (Constructor<any> | (() => Constructor<any>))[], collection?: "Array" | "Set", message?: string): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
/**
 * @summary Set Decorator
 * @description Wrapper for {@link list} with the 'Set' Collection
 *
 * @param {ModelConstructor} clazz
 * @param {string} [message] defaults to {@link DEFAULT_ERROR_MESSAGES#LIST}
 *
 * @function set
 *
 * @category Property Decorators
 */
export declare function set(clazz: ModelConstructor<any>, message?: string): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
/**
 * @summary Declares that the decorated property must be equal to another specified property.
 * @description Applies the {@link ValidationKeys.EQUALS} validator to ensure the decorated value matches the value of the given property.
 *
 * @param {string} propertyToCompare - The name of the property to compare equality against.
 * @param {ComparisonValidatorOptions} options - Options for the validator.
 * @param {string} [options.label] - The label text displayed in the error message.
 * @param {string} [options.message=DEFAULT_ERROR_MESSAGES.EQUALS] - Custom error message to be returned if validation fails.
 *
 * @returns {PropertyDecorator} A property decorator used to register the equality validation metadata.
 *
 * @function eq
 * @category Property Decorators
 */
export declare function eq(propertyToCompare: string, options?: Omit<ComparisonValidatorOptions, "async" | "description">): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor) => void;
/**
 * @summary Declares that the decorated property must be different from another specified property.
 * @description Applies the {@link ValidationKeys.DIFF} validator to ensure the decorated value is different from the value of the given property.
 *
 * @param {string} propertyToCompare - The name of the property to compare difference against.
 * @param {ComparisonValidatorOptions} options - Options for the validator.
 * @param {string} [options.label] - The label text displayed in the error message.
 * @param {string} [options.message=DEFAULT_ERROR_MESSAGES.DIFF] - Custom error message to be returned if validation fails.
 *
 * @returns {PropertyDecorator} A property decorator used to register the difference validation metadata.
 *
 * @function diff
 * @category Property Decorators
 */
export declare function diff(propertyToCompare: string, options?: Omit<ComparisonValidatorOptions, "async" | "description">): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor) => void;
/**
 * @summary Declares that the decorated property must be less than another specified property.
 * @description Applies the {@link ValidationKeys.LESS_THAN} validator to ensure the decorated value is less than the value of the given property.
 *
 * @param {string} propertyToCompare - The name of the property to compare against.
 * @param {ComparisonValidatorOptions} options - Options for the validator.
 * @param {string} [options.label] - The label text displayed in the error message.
 * @param {string} [options.message=DEFAULT_ERROR_MESSAGES.LESS_THAN] - Custom error message to be returned if validation fails.
 *
 * @returns {PropertyDecorator} A property decorator used to register the less than validation metadata.
 *
 * @function lt
 * @category Property Decorators
 */
export declare function lt(propertyToCompare: string, options?: Omit<ComparisonValidatorOptions, "async" | "description">): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor) => void;
/**
 * @summary Declares that the decorated property must be equal or less than another specified property.
 * @description Applies the {@link ValidationKeys.LESS_THAN_OR_EQUAL} validator to ensure the decorated value is equal or less than the value of the given property.
 *
 * @param {string} propertyToCompare - The name of the property to compare against.
 * @param {ComparisonValidatorOptions} options - Options for the validator.
 * @param {string} [options.label] - The label text displayed in the error message.
 * @param {string} [options.message=DEFAULT_ERROR_MESSAGES.LESS_THAN_OR_EQUAL] - Custom error message to be returned if validation fails.
 *
 * @returns {PropertyDecorator} A property decorator used to register the less than or equal validation metadata.
 *
 * @function lte
 * @category Property Decorators
 */
export declare function lte(propertyToCompare: string, options?: Omit<ComparisonValidatorOptions, "async" | "description">): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor) => void;
/**
 * @summary Declares that the decorated property must be greater than another specified property.
 * @description Applies the {@link ValidationKeys.GREATER_THAN} validator to ensure the decorated value is greater than the value of the given property.
 *
 * @param {string} propertyToCompare - The name of the property to compare against.
 * @param {ComparisonValidatorOptions} options - Options for the validator.
 * @param {string} [options.label] - The label text displayed in the error message.
 * @param {string} [options.message=DEFAULT_ERROR_MESSAGES.GREATER_THAN] - Custom error message to be returned if validation fails.
 *
 * @returns {PropertyDecorator} A property decorator used to register the greater than validation metadata.
 *
 * @function gt
 * @category Property Decorators
 */
export declare function gt(propertyToCompare: string, options?: Omit<ComparisonValidatorOptions, "async" | "description">): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor) => void;
/**
 * @summary Declares that the decorated property must be equal or greater than another specified property.
 * @description Applies the {@link ValidationKeys.GREATER_THAN_OR_EQUAL} validator to ensure the decorated value is equal or greater than the value of the given property.
 *
 * @param {string} propertyToCompare - The name of the property to compare against.
 * @param {ComparisonValidatorOptions} options - Options for the validator.
 * @param {string} [options.label] - The label text displayed in the error message.
 * @param {string} [options.message=DEFAULT_ERROR_MESSAGES.GREATER_THAN_OR_EQUAL] - Custom error message to be returned if validation fails.
 *
 * @returns {PropertyDecorator} A property decorator used to register the greater than or equal validation metadata.
 *
 * @function gte
 * @category Property Decorators
 */
export declare function gte(propertyToCompare: string, options?: Omit<ComparisonValidatorOptions, "async" | "description">): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor) => void;