@decaf-ts/decorator-validation 1.6.4 → 1.7.0

package/lib/esm/validation/decorators.d.ts

@@ -1,28 +1,54 @@
 import "reflect-metadata";
 import { ModelConstructor } from "../model/types";
 /**
- * @summary Marks the property as required.
- * @description Validators to validate a decorated property must use key {@link ValidationKeys#REQUIRED}
+ * @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. Defaults to {@link DEFAULT_ERROR_MESSAGES#REQUIRED}
+ * @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 Decorators
+ *
+ * @example
+ * ```typescript
+ * class User {
+ *   @required()
+ *   username: string;
+ *
+ *   @required("Email address is mandatory")
+ *   email: string;
+ * }
+ * ```
  */
-export declare function required(message?: string): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor) => void;
+export declare function required(message?: string): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
 /**
- * @summary Defines a minimum value for the property
- * @description Validators to validate a decorated property must use key {@link ValidationKeys#MIN}
+ * @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} value
- * @param {string} [message] the error message. Defaults to {@link DEFAULT_ERROR_MESSAGES#MIN}
+ * @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
- * @memberOf module:decorator-validation.Decorators.Validation
  * @category 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: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor) => void;
+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}
@@ -31,10 +57,9 @@ export declare function min(value: number | Date | string, message?: string): (t
  * @param {string} [message] the error message. Defaults to {@link DEFAULT_ERROR_MESSAGES#MAX}
  *
  * @function max
- * @memberOf module:decorator-validation.Decorators.Validation
  * @category Decorators
  */
-export declare function max(value: number | Date | string, message?: string): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor) => void;
+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}
@@ -43,10 +68,9 @@ export declare function max(value: number | Date | string, message?: string): (t
  * @param {string} [message] the error message. Defaults to {@link DEFAULT_ERROR_MESSAGES#STEP}
  *
  * @function step
- * @memberOf module:decorator-validation.Decorators.Validation
  * @category Decorators
  */
-export declare function step(value: number, message?: string): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor) => void;
+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}
@@ -55,10 +79,9 @@ export declare function step(value: number, message?: string): (target: object,
  * @param {string} [message] the error message. Defaults to {@link DEFAULT_ERROR_MESSAGES#MIN_LENGTH}
  *
  * @function minlength
- * @memberOf module:decorator-validation.Decorators.Validation
  * @category Decorators
  */
-export declare function minlength(value: number, message?: string): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor) => void;
+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}
@@ -67,10 +90,9 @@ export declare function minlength(value: number, message?: string): (target: obj
  * @param {string} [message] the error message. Defaults to {@link DEFAULT_ERROR_MESSAGES#MAX_LENGTH}
  *
  * @function maxlength
- * @memberOf module:decorator-validation.Decorators.Validation
  * @category Decorators
  */
-export declare function maxlength(value: number, message?: string): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor) => void;
+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}
@@ -79,10 +101,9 @@ export declare function maxlength(value: number, message?: string): (target: obj
  * @param {string} [message] the error message. Defaults to {@link DEFAULT_ERROR_MESSAGES#PATTERN}
  *
  * @function pattern
- * @memberOf module:decorator-validation.Decorators.Validation
  * @category Decorators
  */
-export declare function pattern(value: RegExp | string, message?: string): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor) => void;
+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}
@@ -90,10 +111,9 @@ export declare function pattern(value: RegExp | string, message?: string): (targ
  * @param {string} [message] the error message. Defaults to {@link DEFAULT_ERROR_MESSAGES#EMAIL}
  *
  * @function email
- * @memberOf module:decorator-validation.Decorators.Validation
  * @category Decorators
  */
-export declare function email(message?: string): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor) => void;
+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}
@@ -101,10 +121,9 @@ export declare function email(message?: string): (target: object, propertyKey?:
  * @param {string} [message] the error message. Defaults to {@link DEFAULT_ERROR_MESSAGES#URL}
  *
  * @function url
- * @memberOf module:decorator-validation.Decorators.Validation
  * @category Decorators
  */
-export declare function url(message?: string): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor) => void;
+export declare function url(message?: string): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
 /**
  * @summary Enforces type verification
  * @description Validators to validate a decorated property must use key {@link ValidationKeys#TYPE}
@@ -113,10 +132,9 @@ export declare function url(message?: string): (target: object, propertyKey?: st
  * @param {string} [message] the error message. Defaults to {@link DEFAULT_ERROR_MESSAGES#TYPE}
  *
  * @function type
- * @memberOf module:decorator-validation.Decorators.Validation
  * @category Decorators
  */
-export declare function type(types: string[] | string, message?: string): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor) => void;
+export declare function type(types: string[] | string, message?: string): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
 /**
  * @summary Date Handler Decorator
  * @description Validators to validate a decorated property must use key {@link ValidationKeys#DATE}
@@ -125,28 +143,24 @@ export declare function type(types: string[] | string, message?: string): (targe
  *
  * @param {string} format accepted format according to {@link formatDate}
  * @param {string} [message] the error message. Defaults to {@link DEFAULT_ERROR_MESSAGES#DATE}
- * @param {Constructor<Validator>} [validator] the Validator to be used. Defaults to {@link DateValidator}
  *
  * @function date
  *
- * @memberOf module:decorator-validation.Decorators.Validation
  * @category Decorators
  */
-export declare function date(format?: string, message?: string): (target: Record<string, any>, propertyKey?: any) => any;
+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 PasswordPatterns#CHAR8_ONE_OF_EACH}
+ * @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}
- * @param {Constructor<Validator>} [validator] Defaults to {@link PasswordValidator}
  *
  * @function password
  *
- * @memberOf module:decorator-validation.Decorators.Validation
  * @category Decorators
  */
-export declare function password(pattern?: RegExp, message?: string): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor) => void;
+export declare function password(pattern?: RegExp, message?: string): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
 /**
  * @summary List Decorator
  * @description Also sets the {@link type} to the provided collection
@@ -154,28 +168,24 @@ export declare function password(pattern?: RegExp, message?: string): (target: o
  * @param {ModelConstructor} clazz
  * @param {string} [collection] The collection being used. defaults to Array
  * @param {string} [message] defaults to {@link DEFAULT_ERROR_MESSAGES#LIST}
- * @param {Constructor<Validator>} [validator] defaults to {@link ListValidator}
  *
  * @function list
  *
- * @memberOf module:decorator-validation.Decorators.Validation
  * @category Decorators
  */
-export declare function list(clazz: ModelConstructor<any> | ModelConstructor<any>[], collection?: "Array" | "Set", message?: string): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor) => void;
+export declare function list(clazz: ModelConstructor<any> | ModelConstructor<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}
- * @param {Constructor<Validator>} [validator]
  *
  * @function set
  *
- * @memberOf module:decorator-validation.Decorators.Validation
  * @category Decorators
  */
-export declare function set(clazz: ModelConstructor<any>, message?: string): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor) => void;
+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.