@decaf-ts/decorator-validation 1.15.0 → 1.17.0

package/lib/types/validation/Validators/MinValidator.d.mts

@@ -0,0 +1,74 @@
+import { Validator } from "./Validator.js";
+import { MinValidatorOptions } from "../types.js";
+/**
+ * @description Validator for checking if a value is greater than or equal to a minimum
+ * @summary The MinValidator checks if a numeric value, date, or string is greater than or equal to
+ * a specified minimum value. It supports comparing numbers directly, dates chronologically,
+ * and strings lexicographically. This validator is typically used with the @min decorator.
+ *
+ * @param {string} [message] - Custom error message to display when validation fails, defaults to {@link DEFAULT_ERROR_MESSAGES#MIN}
+ *
+ * @class MinValidator
+ * @extends Validator
+ *
+ * @example
+ * ```typescript
+ * // Create a min validator with default error message
+ * const minValidator = new MinValidator();
+ *
+ * // Create a min validator with custom error message
+ * const customMinValidator = new MinValidator("Value must be at least {0}");
+ *
+ * // Validate a number
+ * const numOptions = { min: 10, message: "Number too small" };
+ * const numResult = minValidator.hasErrors(50, numOptions); // undefined (valid)
+ * const invalidNumResult = minValidator.hasErrors(5, numOptions); // Returns error message (invalid)
+ *
+ * // Validate a date
+ * const dateOptions = { min: new Date(2023, 0, 1) };
+ * const dateResult = minValidator.hasErrors(new Date(2023, 5, 15), dateOptions); // undefined (valid)
+ * ```
+ *
+ * @mermaid
+ * sequenceDiagram
+ *   participant C as Client
+ *   participant V as MinValidator
+ *
+ *   C->>V: new MinValidator(message)
+ *   C->>V: hasErrors(value, options)
+ *   alt value is undefined
+ *     V-->>C: undefined (valid)
+ *   else value is Date and min is not Date
+ *     V->>V: Convert min to Date
+ *     alt conversion fails
+ *       V-->>C: Error: Invalid Min param
+ *     end
+ *   end
+ *   alt value < min
+ *     V-->>C: Error message
+ *   else value >= min
+ *     V-->>C: undefined (valid)
+ *   end
+ *
+ * @category Validators
+ */
+export declare class MinValidator extends Validator<MinValidatorOptions> {
+    constructor(message?: string);
+    /**
+     * @description Checks if a value is greater than or equal to a minimum
+     * @summary Validates that the provided value is not less than the minimum value
+     * specified in the options. For dates, it performs chronological comparison,
+     * converting string representations to Date objects if necessary. For numbers
+     * and strings, it performs direct comparison.
+     *
+     * @param {number | Date | string} value - The value to validate
+     * @param {MinValidatorOptions} options - Configuration options containing the minimum value
+     *
+     * @return {string | undefined} Error message if validation fails, undefined if validation passes
+     *
+     * @override
+     *
+     * @see Validator#hasErrors
+     */
+    hasErrors(value: number | Date | string, options: MinValidatorOptions): string | undefined;
+}

package/lib/types/validation/Validators/OptionValidator.d.cts

@@ -0,0 +1,29 @@
+import { Validator } from "./Validator.cjs";
+import { EnumValidatorOptions } from "../types.cjs";
+/**
+ * @summary Option Validator
+ * @description Validates properties against an object or a list of accepted values
+ *
+ * @param {string} [message] defaults to {@link DEFAULT_ERROR_MESSAGES#ENUM}
+ *
+ * @class OptionValidator
+ * @extends Validator
+ *
+ * @category Validators
+ */
+export declare class OptionValidator extends Validator<EnumValidatorOptions> {
+    constructor(message?: string);
+    /**
+     *
+     * @param {any[] | Record<any, any>} value
+     * @param {EnumValidatorOptions} options
+     *
+     * @return {string | undefined}
+     *
+     * @memberOf module:decorator-validation
+     * @override
+     *
+     * @see Validator#hasErrors
+     */
+    hasErrors(value: any, options: EnumValidatorOptions): string | undefined;
+}

package/lib/types/validation/Validators/OptionValidator.d.mts

@@ -0,0 +1,29 @@
+import { Validator } from "./Validator.js";
+import { EnumValidatorOptions } from "../types.js";
+/**
+ * @summary Option Validator
+ * @description Validates properties against an object or a list of accepted values
+ *
+ * @param {string} [message] defaults to {@link DEFAULT_ERROR_MESSAGES#ENUM}
+ *
+ * @class OptionValidator
+ * @extends Validator
+ *
+ * @category Validators
+ */
+export declare class OptionValidator extends Validator<EnumValidatorOptions> {
+    constructor(message?: string);
+    /**
+     *
+     * @param {any[] | Record<any, any>} value
+     * @param {EnumValidatorOptions} options
+     *
+     * @return {string | undefined}
+     *
+     * @memberOf module:decorator-validation
+     * @override
+     *
+     * @see Validator#hasErrors
+     */
+    hasErrors(value: any, options: EnumValidatorOptions): string | undefined;
+}

package/lib/types/validation/Validators/PasswordValidator.d.cts

@@ -0,0 +1,28 @@
+import { PatternValidator } from "./PatternValidator.cjs";
+import { PatternValidatorOptions } from "../types.cjs";
+/**
+ * @summary Handles Password Validation
+ *
+ * @param {string} [errorMessage] defaults to {@link DEFAULT_ERROR_MESSAGES#PASSWORD}
+ *
+ * @class PasswordValidator
+ * @extends PatternValidator
+ *
+ * @category Validators
+ */
+export declare class PasswordValidator extends PatternValidator {
+    constructor(message?: string);
+    /**
+     * @summary Validates a model
+     *
+     * @param {string} value
+     * @param {PatternValidatorOptions} [options={}]
+     *
+     * @return {string | undefined}
+     *
+     * @override
+     *
+     * @see PatternValidator#hasErrors
+     */
+    hasErrors(value: string, options?: PatternValidatorOptions): string | undefined;
+}

package/lib/types/validation/Validators/PasswordValidator.d.mts

@@ -0,0 +1,28 @@
+import { PatternValidator } from "./PatternValidator.js";
+import { PatternValidatorOptions } from "../types.js";
+/**
+ * @summary Handles Password Validation
+ *
+ * @param {string} [errorMessage] defaults to {@link DEFAULT_ERROR_MESSAGES#PASSWORD}
+ *
+ * @class PasswordValidator
+ * @extends PatternValidator
+ *
+ * @category Validators
+ */
+export declare class PasswordValidator extends PatternValidator {
+    constructor(message?: string);
+    /**
+     * @summary Validates a model
+     *
+     * @param {string} value
+     * @param {PatternValidatorOptions} [options={}]
+     *
+     * @return {string | undefined}
+     *
+     * @override
+     *
+     * @see PatternValidator#hasErrors
+     */
+    hasErrors(value: string, options?: PatternValidatorOptions): string | undefined;
+}

package/lib/types/validation/Validators/PatternValidator.d.cts

@@ -0,0 +1,103 @@
+import { Validator } from "./Validator.cjs";
+import { PatternValidatorOptions } from "../types.cjs";
+/**
+ * @description Regular expression for parsing string patterns with flags
+ * @summary This regular expression is used to parse string patterns in the format "/pattern/flags".
+ * It captures the pattern and flags separately, allowing the creation of a RegExp object
+ * with the appropriate flags.
+ *
+ * @const {RegExp}
+ * @memberOf module:decorator-validation
+ * @category Validation
+ */
+export declare const regexpParser: RegExp;
+/**
+ * @description Validator for checking if a string matches a regular expression pattern
+ * @summary The PatternValidator checks if a string value matches a specified regular expression pattern.
+ * It supports both RegExp objects and string representations of patterns, including those with flags.
+ * This validator is the foundation for specialized validators like EmailValidator and URLValidator,
+ * and is typically used with the @pattern decorator.
+ *
+ * @param {string} [message] - Custom error message to display when validation fails, defaults to {@link DEFAULT_ERROR_MESSAGES#PATTERN}
+ *
+ * @class PatternValidator
+ * @extends Validator
+ *
+ * @example
+ * ```typescript
+ * // Create a pattern validator with default error message
+ * const patternValidator = new PatternValidator();
+ *
+ * // Create a pattern validator with custom error message
+ * const customPatternValidator = new PatternValidator("Value must match the required format");
+ *
+ * // Validate using a RegExp object
+ * const regexOptions = { pattern: /^[A-Z][a-z]+$/ };
+ * patternValidator.hasErrors("Hello", regexOptions); // undefined (valid)
+ * patternValidator.hasErrors("hello", regexOptions); // Returns error message (invalid)
+ *
+ * // Validate using a string pattern
+ * const stringOptions = { pattern: "^\\d{3}-\\d{2}-\\d{4}$" };
+ * patternValidator.hasErrors("123-45-6789", stringOptions); // undefined (valid)
+ *
+ * // Validate using a string pattern with flags
+ * const flagOptions = { pattern: "/^hello$/i" };
+ * patternValidator.hasErrors("Hello", flagOptions); // undefined (valid)
+ * ```
+ *
+ * @mermaid
+ * sequenceDiagram
+ *   participant C as Client
+ *   participant V as PatternValidator
+ *
+ *   C->>V: new PatternValidator(message)
+ *   C->>V: hasErrors(value, options)
+ *   alt value is empty
+ *     V-->>C: undefined (valid)
+ *   else pattern is missing
+ *     V-->>C: Error: Missing Pattern
+ *   else pattern is string
+ *     V->>V: getPattern(pattern)
+ *   end
+ *   V->>V: Reset pattern.lastIndex
+ *   V->>V: Test value against pattern
+ *   alt pattern test passes
+ *     V-->>C: undefined (valid)
+ *   else pattern test fails
+ *     V-->>C: Error message
+ *   end
+ *
+ * @category Validators
+ */
+export declare class PatternValidator extends Validator<PatternValidatorOptions> {
+    constructor(message?: string);
+    /**
+     * @description Converts a string pattern to a RegExp object
+     * @summary Parses a string representation of a regular expression and converts it to a RegExp object.
+     * It handles both simple string patterns and patterns with flags in the format "/pattern/flags".
+     *
+     * @param {string} pattern - The string pattern to convert
+     * @return {RegExp} A RegExp object created from the string pattern
+     * @private
+     */
+    private getPattern;
+    /**
+     * @description Checks if a string matches a regular expression pattern
+     * @summary Validates that the provided string matches the pattern specified in the options.
+     * If the pattern is provided as a string, it's converted to a RegExp object using the getPattern method.
+     * The method resets the pattern's lastIndex property to ensure consistent validation results
+     * for patterns with the global flag.
+     *
+     * @param {string} value - The string to validate against the pattern
+     * @param {PatternValidatorOptions} options - Configuration options containing the pattern
+     *
+     * @return {string | undefined} Error message if validation fails, undefined if validation passes
+     *
+     * @throws {Error} If no pattern is provided in the options
+     *
+     * @override
+     *
+     * @see Validator#hasErrors
+     */
+    hasErrors(value: string, options: PatternValidatorOptions): string | undefined;
+}

package/lib/types/validation/Validators/PatternValidator.d.mts

@@ -0,0 +1,103 @@
+import { Validator } from "./Validator.js";
+import { PatternValidatorOptions } from "../types.js";
+/**
+ * @description Regular expression for parsing string patterns with flags
+ * @summary This regular expression is used to parse string patterns in the format "/pattern/flags".
+ * It captures the pattern and flags separately, allowing the creation of a RegExp object
+ * with the appropriate flags.
+ *
+ * @const {RegExp}
+ * @memberOf module:decorator-validation
+ * @category Validation
+ */
+export declare const regexpParser: RegExp;
+/**
+ * @description Validator for checking if a string matches a regular expression pattern
+ * @summary The PatternValidator checks if a string value matches a specified regular expression pattern.
+ * It supports both RegExp objects and string representations of patterns, including those with flags.
+ * This validator is the foundation for specialized validators like EmailValidator and URLValidator,
+ * and is typically used with the @pattern decorator.
+ *
+ * @param {string} [message] - Custom error message to display when validation fails, defaults to {@link DEFAULT_ERROR_MESSAGES#PATTERN}
+ *
+ * @class PatternValidator
+ * @extends Validator
+ *
+ * @example
+ * ```typescript
+ * // Create a pattern validator with default error message
+ * const patternValidator = new PatternValidator();
+ *
+ * // Create a pattern validator with custom error message
+ * const customPatternValidator = new PatternValidator("Value must match the required format");
+ *
+ * // Validate using a RegExp object
+ * const regexOptions = { pattern: /^[A-Z][a-z]+$/ };
+ * patternValidator.hasErrors("Hello", regexOptions); // undefined (valid)
+ * patternValidator.hasErrors("hello", regexOptions); // Returns error message (invalid)
+ *
+ * // Validate using a string pattern
+ * const stringOptions = { pattern: "^\\d{3}-\\d{2}-\\d{4}$" };
+ * patternValidator.hasErrors("123-45-6789", stringOptions); // undefined (valid)
+ *
+ * // Validate using a string pattern with flags
+ * const flagOptions = { pattern: "/^hello$/i" };
+ * patternValidator.hasErrors("Hello", flagOptions); // undefined (valid)
+ * ```
+ *
+ * @mermaid
+ * sequenceDiagram
+ *   participant C as Client
+ *   participant V as PatternValidator
+ *
+ *   C->>V: new PatternValidator(message)
+ *   C->>V: hasErrors(value, options)
+ *   alt value is empty
+ *     V-->>C: undefined (valid)
+ *   else pattern is missing
+ *     V-->>C: Error: Missing Pattern
+ *   else pattern is string
+ *     V->>V: getPattern(pattern)
+ *   end
+ *   V->>V: Reset pattern.lastIndex
+ *   V->>V: Test value against pattern
+ *   alt pattern test passes
+ *     V-->>C: undefined (valid)
+ *   else pattern test fails
+ *     V-->>C: Error message
+ *   end
+ *
+ * @category Validators
+ */
+export declare class PatternValidator extends Validator<PatternValidatorOptions> {
+    constructor(message?: string);
+    /**
+     * @description Converts a string pattern to a RegExp object
+     * @summary Parses a string representation of a regular expression and converts it to a RegExp object.
+     * It handles both simple string patterns and patterns with flags in the format "/pattern/flags".
+     *
+     * @param {string} pattern - The string pattern to convert
+     * @return {RegExp} A RegExp object created from the string pattern
+     * @private
+     */
+    private getPattern;
+    /**
+     * @description Checks if a string matches a regular expression pattern
+     * @summary Validates that the provided string matches the pattern specified in the options.
+     * If the pattern is provided as a string, it's converted to a RegExp object using the getPattern method.
+     * The method resets the pattern's lastIndex property to ensure consistent validation results
+     * for patterns with the global flag.
+     *
+     * @param {string} value - The string to validate against the pattern
+     * @param {PatternValidatorOptions} options - Configuration options containing the pattern
+     *
+     * @return {string | undefined} Error message if validation fails, undefined if validation passes
+     *
+     * @throws {Error} If no pattern is provided in the options
+     *
+     * @override
+     *
+     * @see Validator#hasErrors
+     */
+    hasErrors(value: string, options: PatternValidatorOptions): string | undefined;
+}

package/lib/types/validation/Validators/RequiredValidator.d.cts

@@ -0,0 +1,74 @@
+import { Validator } from "./Validator.cjs";
+import { ValidatorOptions } from "../types.cjs";
+/**
+ * @description Validator for checking if a value is present and not empty
+ * @summary The RequiredValidator ensures that a value is provided and not empty.
+ * It handles different types of values appropriately: for booleans and numbers,
+ * it checks if they're undefined; for other types (strings, arrays, objects),
+ * it checks if they're falsy. This validator is typically used with the @required decorator
+ * and is often the first validation applied to important fields.
+ *
+ * @param {string} [message] - Custom error message to display when validation fails, defaults to {@link DEFAULT_ERROR_MESSAGES#REQUIRED}
+ *
+ * @class RequiredValidator
+ * @extends Validator
+ *
+ * @example
+ * ```typescript
+ * // Create a required validator with default error message
+ * const requiredValidator = new RequiredValidator();
+ *
+ * // Create a required validator with custom error message
+ * const customRequiredValidator = new RequiredValidator("This field is mandatory");
+ *
+ * // Validate different types of values
+ * requiredValidator.hasErrors("Hello"); // undefined (valid)
+ * requiredValidator.hasErrors(""); // Returns error message (invalid)
+ * requiredValidator.hasErrors(0); // undefined (valid - 0 is a valid number)
+ * requiredValidator.hasErrors(null); // Returns error message (invalid)
+ * requiredValidator.hasErrors([]); // undefined (valid - empty array is still an array)
+ * ```
+ *
+ * @mermaid
+ * sequenceDiagram
+ *   participant C as Client
+ *   participant V as RequiredValidator
+ *
+ *   C->>V: new RequiredValidator(message)
+ *   C->>V: hasErrors(value, options)
+ *   alt typeof value is boolean or number
+ *     alt value is undefined
+ *       V-->>C: Error message
+ *     else value is defined
+ *       V-->>C: undefined (valid)
+ *     end
+ *   else other types
+ *     alt value is falsy (null, undefined, empty string)
+ *       V-->>C: Error message
+ *     else value is truthy
+ *       V-->>C: undefined (valid)
+ *     end
+ *   end
+ *
+ * @category Validators
+ */
+export declare class RequiredValidator extends Validator {
+    constructor(message?: string);
+    /**
+     * @description Checks if a value is present and not empty
+     * @summary Validates that the provided value exists and is not empty.
+     * The validation logic varies by type:
+     * - For booleans and numbers: checks if the value is undefined
+     * - For other types (strings, arrays, objects): checks if the value is falsy
+     *
+     * @param {any} value - The value to validate
+     * @param {ValidatorOptions} [options={}] - Optional configuration options
+     *
+     * @return {string | undefined} Error message if validation fails, undefined if validation passes
+     *
+     * @override
+     *
+     * @see Validator#hasErrors
+     */
+    hasErrors(value: any, options?: ValidatorOptions): string | undefined;
+}

package/lib/types/validation/Validators/RequiredValidator.d.mts

@@ -0,0 +1,74 @@
+import { Validator } from "./Validator.js";
+import { ValidatorOptions } from "../types.js";
+/**
+ * @description Validator for checking if a value is present and not empty
+ * @summary The RequiredValidator ensures that a value is provided and not empty.
+ * It handles different types of values appropriately: for booleans and numbers,
+ * it checks if they're undefined; for other types (strings, arrays, objects),
+ * it checks if they're falsy. This validator is typically used with the @required decorator
+ * and is often the first validation applied to important fields.
+ *
+ * @param {string} [message] - Custom error message to display when validation fails, defaults to {@link DEFAULT_ERROR_MESSAGES#REQUIRED}
+ *
+ * @class RequiredValidator
+ * @extends Validator
+ *
+ * @example
+ * ```typescript
+ * // Create a required validator with default error message
+ * const requiredValidator = new RequiredValidator();
+ *
+ * // Create a required validator with custom error message
+ * const customRequiredValidator = new RequiredValidator("This field is mandatory");
+ *
+ * // Validate different types of values
+ * requiredValidator.hasErrors("Hello"); // undefined (valid)
+ * requiredValidator.hasErrors(""); // Returns error message (invalid)
+ * requiredValidator.hasErrors(0); // undefined (valid - 0 is a valid number)
+ * requiredValidator.hasErrors(null); // Returns error message (invalid)
+ * requiredValidator.hasErrors([]); // undefined (valid - empty array is still an array)
+ * ```
+ *
+ * @mermaid
+ * sequenceDiagram
+ *   participant C as Client
+ *   participant V as RequiredValidator
+ *
+ *   C->>V: new RequiredValidator(message)
+ *   C->>V: hasErrors(value, options)
+ *   alt typeof value is boolean or number
+ *     alt value is undefined
+ *       V-->>C: Error message
+ *     else value is defined
+ *       V-->>C: undefined (valid)
+ *     end
+ *   else other types
+ *     alt value is falsy (null, undefined, empty string)
+ *       V-->>C: Error message
+ *     else value is truthy
+ *       V-->>C: undefined (valid)
+ *     end
+ *   end
+ *
+ * @category Validators
+ */
+export declare class RequiredValidator extends Validator {
+    constructor(message?: string);
+    /**
+     * @description Checks if a value is present and not empty
+     * @summary Validates that the provided value exists and is not empty.
+     * The validation logic varies by type:
+     * - For booleans and numbers: checks if the value is undefined
+     * - For other types (strings, arrays, objects): checks if the value is falsy
+     *
+     * @param {any} value - The value to validate
+     * @param {ValidatorOptions} [options={}] - Optional configuration options
+     *
+     * @return {string | undefined} Error message if validation fails, undefined if validation passes
+     *
+     * @override
+     *
+     * @see Validator#hasErrors
+     */
+    hasErrors(value: any, options?: ValidatorOptions): string | undefined;
+}

package/lib/types/validation/Validators/StepValidator.d.cts

@@ -0,0 +1,29 @@
+import { Validator } from "./Validator.cjs";
+import { StepValidatorOptions } from "../types.cjs";
+/**
+ * @summary Step Validator
+ *
+ * @param {string} [message] defaults to {@link DEFAULT_ERROR_MESSAGES#STEP}
+ *
+ * @class StepValidator
+ * @extends Validator
+ *
+ * @category Validators
+ */
+export declare class StepValidator extends Validator<StepValidatorOptions> {
+    constructor(message?: string);
+    /**
+     * @summary Validates a model
+     *
+     * @param {string} value
+     * @param {number} step
+     * @param {StepValidatorOptions} options
+     *
+     * @return {string | undefined}
+     *
+     * @override
+     *
+     * @see Validator#hasErrors
+     */
+    hasErrors(value: number | string, options: StepValidatorOptions): string | undefined;
+}

package/lib/types/validation/Validators/StepValidator.d.mts

@@ -0,0 +1,29 @@
+import { Validator } from "./Validator.js";
+import { StepValidatorOptions } from "../types.js";
+/**
+ * @summary Step Validator
+ *
+ * @param {string} [message] defaults to {@link DEFAULT_ERROR_MESSAGES#STEP}
+ *
+ * @class StepValidator
+ * @extends Validator
+ *
+ * @category Validators
+ */
+export declare class StepValidator extends Validator<StepValidatorOptions> {
+    constructor(message?: string);
+    /**
+     * @summary Validates a model
+     *
+     * @param {string} value
+     * @param {number} step
+     * @param {StepValidatorOptions} options
+     *
+     * @return {string | undefined}
+     *
+     * @override
+     *
+     * @see Validator#hasErrors
+     */
+    hasErrors(value: number | string, options: StepValidatorOptions): string | undefined;
+}