@decaf-ts/decorator-validation 1.20.0 → 1.21.0

package/lib/types/validation/Validators/MinLengthValidator.d.ts

@@ -1,29 +0,0 @@
-import { Validator } from "./Validator";
-import { MinLengthValidatorOptions } from "../types";
-/**
- * @summary Minimum Length Validator
- * @description Validates strings and Arrays on their minimum length
- *
- * @param {string} [message] defaults to {@link DEFAULT_ERROR_MESSAGES#MIN_LENGTH}
- *
- * @class MinLengthValidator
- * @extends Validator
- *
- * @category Validators
- */
-export declare class MinLengthValidator extends Validator<MinLengthValidatorOptions> {
-    constructor(message?: string);
-    /**
-     *
-     * @param {string | Array} value
-     * @param {MinLengthValidatorOptions} options
-     *
-     * @return {string | undefined}
-     *
-     * @memberOf module:decorator-validation
-     * @override
-     *
-     * @see Validator#hasErrors
-     */
-    hasErrors(value: string | any[], options: MinLengthValidatorOptions): string | undefined;
-}

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

@@ -1,74 +0,0 @@
-import { Validator } from "./Validator";
-import { MinValidatorOptions } from "../types";
-/**
- * @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.ts

@@ -1,29 +0,0 @@
-import { Validator } from "./Validator";
-import { EnumValidatorOptions } from "../types";
-/**
- * @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.ts

@@ -1,28 +0,0 @@
-import { PatternValidator } from "./PatternValidator";
-import { PatternValidatorOptions } from "../types";
-/**
- * @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.ts

@@ -1,103 +0,0 @@
-import { Validator } from "./Validator";
-import { PatternValidatorOptions } from "../types";
-/**
- * @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.ts

@@ -1,74 +0,0 @@
-import { Validator } from "./Validator";
-import { ValidatorOptions } from "../types";
-/**
- * @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.ts

@@ -1,29 +0,0 @@
-import { Validator } from "./Validator";
-import { StepValidatorOptions } from "../types";
-/**
- * @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/TypeValidator.d.ts

@@ -1,79 +0,0 @@
-import { Validator } from "./Validator";
-import { TypeValidatorOptions } from "../types";
-/**
- * @description Validator for checking if a value is of the expected type(s)
- * @summary The TypeValidator ensures that a value matches one of the specified types.
- * It can validate against a single type, multiple types, or a type with a specific name.
- * This validator is typically used with the @type decorator and is fundamental for
- * ensuring type safety in validated models.
- *
- * @param {string} [message] - Custom error message to display when validation fails, defaults to {@link DEFAULT_ERROR_MESSAGES#TYPE}
- *
- * @class TypeValidator
- * @extends Validator
- *
- * @example
- * ```typescript
- * // Create a type validator with default error message
- * const typeValidator = new TypeValidator();
- *
- * // Create a type validator with custom error message
- * const customTypeValidator = new TypeValidator("Value must be of type {0}, but got {1}");
- *
- * // Validate against a single type
- * const stringOptions = { types: "string" };
- * typeValidator.hasErrors("hello", stringOptions); // undefined (valid)
- * typeValidator.hasErrors(123, stringOptions); // Returns error message (invalid)
- *
- * // Validate against multiple types
- * const multiOptions = { types: ["string", "number"] };
- * typeValidator.hasErrors("hello", multiOptions); // undefined (valid)
- * typeValidator.hasErrors(123, multiOptions); // undefined (valid)
- * typeValidator.hasErrors(true, multiOptions); // Returns error message (invalid)
- *
- * // Validate against a class type
- * const classOptions = { types: { name: "Date" } };
- * typeValidator.hasErrors(new Date(), classOptions); // undefined (valid)
- * ```
- *
- * @mermaid
- * sequenceDiagram
- *   participant C as Client
- *   participant V as TypeValidator
- *   participant R as Reflection
- *
- *   C->>V: new TypeValidator(message)
- *   C->>V: hasErrors(value, options)
- *   alt value is undefined
- *     V-->>C: undefined (valid)
- *   else value is defined
- *     V->>R: evaluateDesignTypes(value, types)
- *     alt type evaluation passes
- *       V-->>C: undefined (valid)
- *     else type evaluation fails
- *       V->>V: Format error message with type info
- *       V-->>C: Error message
- *     end
- *   end
- *
- * @category Validators
- */
-export declare class TypeValidator extends Validator<TypeValidatorOptions> {
-    constructor(message?: string);
-    /**
-     * @description Checks if a value is of the expected type(s)
-     * @summary Validates that the provided value matches one of the specified types.
-     * It uses the Reflection utility to evaluate if the value's type matches the expected types.
-     * The method skips validation for undefined values to avoid conflicts with the RequiredValidator.
-     *
-     * @param {any} value - The value to validate
-     * @param {TypeValidatorOptions} options - Configuration options containing the expected types
-     *
-     * @return {string | undefined} Error message if validation fails, undefined if validation passes
-     *
-     * @override
-     *
-     * @see Validator#hasErrors
-     */
-    hasErrors(value: any, options: TypeValidatorOptions): string | undefined;
-}

package/lib/types/validation/Validators/URLValidator.d.ts

@@ -1,61 +0,0 @@
-import { PatternValidator } from "./PatternValidator";
-import { PatternValidatorOptions } from "../types";
-/**
- * @description Validator for checking if a string is a valid URL
- * @summary The URLValidator checks if a string matches a standard URL pattern.
- * It extends the PatternValidator and uses a robust URL regex pattern to validate web addresses.
- * The pattern is sourced from {@link https://gist.github.com/dperini/729294} and is widely
- * recognized for its accuracy in validating URLs. This validator is typically used with the @url decorator.
- *
- * @param {string} [message] - Custom error message to display when validation fails, defaults to {@link DEFAULT_ERROR_MESSAGES#URL}
- *
- * @class URLValidator
- * @extends PatternValidator
- *
- * @example
- * ```typescript
- * // Create a URL validator with default error message
- * const urlValidator = new URLValidator();
- *
- * // Create a URL validator with custom error message
- * const customUrlValidator = new URLValidator("Please enter a valid web address");
- *
- * // Validate a URL
- * const result = urlValidator.hasErrors("https://example.com"); // undefined (valid)
- * const invalidResult = urlValidator.hasErrors("not-a-url"); // Returns error message (invalid)
- * ```
- *
- * @mermaid
- * sequenceDiagram
- *   participant C as Client
- *   participant U as URLValidator
- *   participant P as PatternValidator
- *
- *   C->>U: new URLValidator(message)
- *   U->>P: super(message)
- *   C->>U: hasErrors(value, options)
- *   U->>P: super.hasErrors(value, options with URL pattern)
- *   P-->>U: validation result
- *   U-->>C: validation result
- *
- * @category Validators
- */
-export declare class URLValidator extends PatternValidator {
-    constructor(message?: string);
-    /**
-     * @description Checks if a string is a valid URL
-     * @summary Validates that the provided string matches the URL pattern.
-     * This method extends the PatternValidator's hasErrors method by ensuring
-     * the URL pattern is used, even if not explicitly provided in the options.
-     *
-     * @param {string} value - The string to validate as a URL
-     * @param {PatternValidatorOptions} [options={}] - Optional configuration options
-     *
-     * @return {string | undefined} Error message if validation fails, undefined if validation passes
-     *
-     * @override
-     *
-     * @see PatternValidator#hasErrors
-     */
-    hasErrors(value: string, options?: PatternValidatorOptions): string | undefined;
-}

package/lib/types/validation/Validators/Validator.d.ts

@@ -1,65 +0,0 @@
-import { ValidatorOptions } from "../types";
-import type { PathProxy } from "../../utils";
-import { BaseValidator } from "./BaseValidator";
-/**
- * @description
- * Abstract class for defining synchronous validators.
- *
- * This class extends the base {@link BaseValidator} and enforces that any implementation of `hasErrors` must be synchronous.
- *
- * Use this when the validation process is immediate and does not require asynchronous operations.
- *
- * @example
- * ```typescript
- * // Example of a synchronous validator that checks if a number is greater than
- * class GreaterThanValidator extends Validator<{ gt?: number }> {
- *   constructor(message: string = "Value must be greater than {0}") {
- *     super(message);
- *   }
- *
- *   hasErrors(value: number, options?: { gt?: number }) {
- *     const minValue = options?.gt ?? 0;
- *     if (value <= minValue) {
- *       return this.getMessage();
- *     }
- *     return undefined;
- *   }
- * }
- *
- * // Example usage:
- * const validator = new GreaterThanValidator();
- * const error = validator.hasErrors(10, { gt: 15 });
- * if (error) {
- *   console.log('Value must be greater than 15')
- * } else {
- *   console.log('Value is valid');
- * }
- * ```
- *
- * - If `value` is less than or equal to `gt`, returns the error message.
- * - Otherwise, returns `undefined` indicating validation success.
- *
- * @see {@link BaseValidator} For the base validator.
- * @see {@link ValidatorOptions} For the base validator options.
- */
-export declare abstract class Validator<V extends ValidatorOptions = ValidatorOptions> extends BaseValidator<V, false> {
-    protected constructor(message?: string, ...acceptedTypes: string[]);
-    /**
-     * @description Validates a value against specific validation rules
-     * @summary Abstract method that must be implemented by all validator subclasses.
-     * This method contains the core validation logic that determines whether a value
-     * is valid according to the specific rules of the validator. If the value is valid,
-     * the method returns undefined; otherwise, it returns an error message.
-     *
-     * @template V - Type of the options object that can be passed to the validator
-     * @param {any} value - The value to validate
-     * @param {V} [options] - Optional configuration options for customizing validation behavior
-     * @param {PathProxy<any>} proxy -
-     * @return {string | undefined} Error message if validation fails, undefined if validation passes
-     *
-     * @abstract
-     *
-     * @see Model#validate
-     */
-    abstract hasErrors(value: any, options?: V, proxy?: PathProxy<any>): string | undefined;
-}

package/lib/types/validation/Validators/ValidatorRegistry.d.ts

@@ -1,41 +0,0 @@
-import { ValidatorDefinition } from "../types";
-import { IValidatorRegistry } from "../types";
-import { Validator } from "./Validator";
-/**
- * @summary Base Implementation of a Validator Registry
- *
- * @prop {Validator[]} [validators] the initial validators to register
- *
- * @class ValidatorRegistry
- * @implements IValidatorRegistry<T>
- *
- * @category Validation
- */
-export declare class ValidatorRegistry<T extends Validator> implements IValidatorRegistry<T> {
-    private cache;
-    private customKeyCache;
-    constructor(...validators: (ValidatorDefinition | Validator)[]);
-    /**
-     * @summary retrieves the custom keys
-     */
-    getCustomKeys(): {
-        [indexer: string]: string;
-    };
-    /**
-     * @summary retrieves the registered validators keys
-     */
-    getKeys(): string[];
-    /**
-     * @summary Retrieves a validator
-     *
-     * @param {string} validatorKey one of the {@link ValidationKeys}
-     * @return {Validator | undefined} the registered Validator or undefined if there is nono matching the provided key
-     */
-    get<T extends Validator>(validatorKey: string): T | undefined;
-    /**
-     * @summary Registers the provided validators onto the registry
-     *
-     * @param {T[] | ValidatorDefinition[]} validator
-     */
-    register<T extends Validator>(...validator: (ValidatorDefinition | T)[]): void;
-}