@decaf-ts/decorator-validation 1.19.0 → 1.21.0

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

@@ -1,72 +0,0 @@
-import type { ValidatorOptions } from "../types";
-import type { PathProxy } from "../../utils";
-import { BaseValidator } from "./BaseValidator";
-/**
- * @description
- * Abstract class for defining asynchronous validators.
- *
- * This class extends the base `Validator` and enforces that any implementation
- * of `hasErrors` must be asynchronous, always returning a Promise.
- *
- * Use this when the validation process involves asynchronous operations,
- * such as API calls, database lookups, or time-based checks (e.g., timeouts).
- *
- * @example
- * ```typescript
- * // Example of an asynchronous validator that compares value against a timeout
- * class TimeoutValidator extends AsyncValidator<{ timeout?: number }> {
- *   constructor(message: string = "Validation failed due to timeout") {
- *     super(message);
- *   }
- *
- *   async hasErrors(value: number, options?: { timeout?: number }) {
- *     const delay = options?.timeout ?? 100;
- *
- *     // async call
- *     await new Promise(res => setTimeout(res, delay));
- *
- *     if (value > delay) {
- *       // Rejects the validation after waiting the delay if value is greater
- *       return Promise.resolve(this.getMessage());
- *     }
- *
- *     // Passes the validation after waiting the delay
- *     return Promise.resolve(undefined);
- *   }
- * }
- *
- * // Example usage:
- * const validator = new TimeoutValidator();
- *
- * async function runValidation() {
- *  const error = await validator.hasErrors(50, { timeout: 100 });
- *  if (error) {
- *    return console.error('Validation error:', error);
- *  }
- *  console.log('Value is valid');
- * }
- *
- * await runValidation();
- * ```
- *
- * - If `value > timeout`, the validator waits for the delay and then rejects with an error.
- * - If `value <= timeout`, the validator waits for the delay and resolves successfully with `undefined`.
- *
- * @see {@link Validator} For the base synchronous validator.
- */
-export declare abstract class AsyncValidator<V extends ValidatorOptions> extends BaseValidator<V, true> {
-    protected constructor(message?: string, ...acceptedTypes: string[]);
-    /**
-     * @description
-     * Asynchronously validates a value.
-     *
-     * @template V - Type of the option 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 Promise<string | undefined> Error message if validation fails, undefined if validation passes
-     *
-     * @see {@link Validator}
-     */
-    abstract hasErrors(value: any, options?: V, proxy?: PathProxy<any>): Promise<string | undefined>;
-}

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

@@ -1,118 +0,0 @@
-import { ValidatorOptions } from "../types";
-import type { PathProxy } from "../../utils";
-import type { ConditionalAsync } from "../../types";
-/**
- * @description Abstract base class for all validators in the validation framework.
- * @summary The BaseValidator class provides the foundation for all synchronous and asynchronous validator implementations.
- * It handles type checking, error message formatting, and defines the interface that all validators must implement.
- * This class is designed to be extended by specific validator classes that define their own validation logic.
- *
- * @template V - Validator options type
- * @template IsAsync - Whether the validator is async (true) or sync (false). Default `false`.
- *
- * @param {boolean} async - Defines if the validator is async (must match the subclass signature)
- * @param {string} message - Default error message to display when validation fails (defaults to {@link DEFAULT_ERROR_MESSAGES#DEFAULT})
- * @param {string[]} acceptedTypes - Type names that this validator accepts (used for runtime type checking)
- *
- * @class BaseValidator
- * @abstract
- *
- * @example
- * // Example of a synchronous validator
- * class SyncValidator extends BaseValidator<SomeOptions, false> {
- *   constructor() {
- *     super(false, "Sync validation failed", String.name);
- *   }
- *
- *   public hasErrors(value: any, options?: SomeOptions): string | undefined {
- *     if (typeof value !== "string") return this.getMessage(this.message);
- *     return undefined;
- *   }
- * }
- *
- * @example
- * // Example of an asynchronous custom validator
- * class AsyncValidator extends BaseValidator<SomeOptions, true> {
- *   constructor() {
- *     super(true, "Async validation failed", String.name);
- *   }
- *
- *   public async hasErrors(value: any, options?: SomeOptions): Promise<string | undefined> {
- *     const result = await someAsyncCheck(value);
- *     if (!result) return this.getMessage(this.message);
- *     return undefined;
- *   }
- * }
- *
- * @mermaid
- * sequenceDiagram
- *   participant C as Client
- *   participant V as Validator Subclass
- *   participant B as BaseValidator
- *
- *   C->>V: new CustomValidator(async, message)
- *   V->>B: super(async, message, acceptedTypes)
- *   B->>B: Store message, async flag, and accepted types
- *   B->>B: Optionally wrap hasErrors with type checking
- *   C->>V: hasErrors(value, options)
- *   alt value type not in acceptedTypes
- *     B-->>C: Type error message
- *   else value type is accepted
- *     V->>V: Custom validation logic
- *     V-->>C: Validation result
- *   end
- *
- * @category Validators
- */
-export declare abstract class BaseValidator<V extends ValidatorOptions = ValidatorOptions, Async extends boolean = false> {
-    readonly message: string;
-    readonly acceptedTypes?: string[];
-    readonly async?: Async;
-    protected constructor(async: Async, message?: string, ...acceptedTypes: string[]);
-    /**
-     * @description Formats an error message with optional arguments
-     * @summary Creates a formatted error message by replacing placeholders with provided arguments.
-     * This method uses the string formatting utility to generate consistent error messages
-     * across all validators.
-     *
-     * @param {string} message - The message template with placeholders
-     * @param {...any} args - Values to insert into the message template
-     * @return {string} The formatted error message
-     * @protected
-     */
-    protected getMessage(message: string, ...args: any[]): string;
-    /**
-     * @description Creates a type-checking wrapper around the hasErrors method
-     * @summary Wraps the hasErrors method with type validation logic to ensure that
-     * the value being validated is of an accepted type before performing specific validation.
-     * This method is called during construction if acceptedTypes are provided.
-     *
-     * @param {Function} unbound - The original hasErrors method to be wrapped
-     * @return {Function} A new function that performs type checking before calling the original method
-     * @private
-     */
-    private checkTypeAndHasErrors;
-    /**
-     * @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>): ConditionalAsync<Async, string | undefined>;
-    /**
-     * @summary Duck typing for Validators
-     * @param val
-     */
-    static isValidator(val: any): boolean;
-}

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

@@ -1,60 +0,0 @@
-import { Validator } from "./Validator";
-import { DateValidatorOptions } from "../types";
-/**
- * @description Validator for checking if a value is a valid date
- * @summary The DateValidator checks if a value is a valid date object or a string that can be converted to a valid date.
- * It validates that the value represents a real date and not an invalid date like "2023-02-31".
- * @param {string} [message] - Custom error message to display when validation fails, defaults to {@link DEFAULT_ERROR_MESSAGES#DATE}
- * @class DateValidator
- * @extends Validator
- *
- * @category Validators
- * @example
- * ```typescript
- * // Create a date validator with default error message
- * const dateValidator = new DateValidator();
- *
- * // Create a date validator with custom error message
- * const customDateValidator = new DateValidator("Please enter a valid date");
- *
- * // Validate a date
- * const result = dateValidator.hasErrors(new Date()); // undefined (valid)
- * const invalidResult = dateValidator.hasErrors("not a date"); // Returns error message (invalid)
- * ```
- * @mermaid
- * sequenceDiagram
- *   participant C as Client
- *   participant V as DateValidator
- *
- *   C->>V: new DateValidator(message)
- *   C->>V: hasErrors(value, options)
- *   alt value is undefined
- *     V-->>C: undefined (valid)
- *   else value is string
- *     V->>V: Convert to Date
- *   end
- *   alt Date is invalid (NaN)
- *     V-->>C: Error message
- *   else Date is valid
- *     V-->>C: undefined (valid)
- *   end
- */
-export declare class DateValidator extends Validator<DateValidatorOptions> {
-    constructor(message?: string);
-    /**
-     * @description Checks if the provided value is a valid date
-     * @summary Validates that the given value is a valid date. If the value is a string,
-     * it attempts to convert it to a Date object. Returns an error message if the date is invalid,
-     * or undefined if the date is valid or if the value is undefined.
-     *
-     * @param {Date | string} value - The value to validate, can be a Date object or a string
-     * @param {DateValidatorOptions} [options={}] - Optional configuration options for the validator
-     *
-     * @return {string | undefined} Error message if validation fails, undefined if validation passes
-     *
-     * @override
-     *
-     * @see Validator#hasErrors
-     */
-    hasErrors(value: Date | string, options?: DateValidatorOptions): string | undefined;
-}

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

@@ -1,29 +0,0 @@
-import { Validator } from "./Validator";
-import { DiffValidatorOptions } from "../types";
-import type { PathProxy } from "../../utils";
-/**
- * @summary Diff Validator
- *
- * @param {string} [message] defaults to {@link DEFAULT_ERROR_MESSAGES#DiffValidator}
- *
- * @class DiffValidator
- * @extends Validator
- *
- * @category Validators
- */
-export declare class DiffValidator extends Validator<DiffValidatorOptions> {
-    constructor(message?: string);
-    /**
-     * @summary Validates a model
-     *
-     * @param {string} value
-     * @param {DiffValidatorOptions} options
-     * @param {PathProxy<any>} accessor - Proxy-like object used to resolve values from nested structures via path strings.
-     *
-     * @return {string | undefined}
-     *
-     * @override
-     * @see Validator#hasErrors
-     */
-    hasErrors(value: any, options: DiffValidatorOptions, accessor: PathProxy<any>): string | undefined;
-}

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

@@ -1,60 +0,0 @@
-import { PatternValidator } from "./PatternValidator";
-import { PatternValidatorOptions } from "../types";
-/**
- * @description Validator for checking if a string is a valid email address
- * @summary The EmailValidator checks if a string matches a standard email address pattern.
- * It extends the PatternValidator and uses a predefined email regex pattern to validate email addresses.
- * This validator is typically used with the @email decorator.
- *
- * @param {string} [message] - Custom error message to display when validation fails, defaults to {@link DEFAULT_ERROR_MESSAGES#EMAIL}
- *
- * @class EmailValidator
- * @extends PatternValidator
- *
- * @example
- * ```typescript
- * // Create an email validator with default error message
- * const emailValidator = new EmailValidator();
- *
- * // Create an email validator with custom error message
- * const customEmailValidator = new EmailValidator("Please enter a valid email address");
- *
- * // Validate an email
- * const result = emailValidator.hasErrors("user@example.com"); // undefined (valid)
- * const invalidResult = emailValidator.hasErrors("invalid-email"); // Returns error message (invalid)
- * ```
- *
- * @mermaid
- * sequenceDiagram
- *   participant C as Client
- *   participant E as EmailValidator
- *   participant P as PatternValidator
- *
- *   C->>E: new EmailValidator(message)
- *   E->>P: super(message)
- *   C->>E: hasErrors(value, options)
- *   E->>P: super.hasErrors(value, options with EMAIL pattern)
- *   P-->>E: validation result
- *   E-->>C: validation result
- *
- * @category Validators
- */
-export declare class EmailValidator extends PatternValidator {
-    constructor(message?: string);
-    /**
-     * @description Checks if a string is a valid email address
-     * @summary Validates that the provided string matches the email pattern.
-     * This method extends the PatternValidator's hasErrors method by ensuring
-     * the email pattern is used, even if not explicitly provided in the options.
-     *
-     * @param {string} value - The string to validate as an email address
-     * @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/EqualsValidator.d.ts

@@ -1,29 +0,0 @@
-import { Validator } from "./Validator";
-import { EqualsValidatorOptions } from "../types";
-import type { PathProxy } from "../../utils";
-/**
- * @summary Equals Validator
- *
- * @param {string} [message] defaults to {@link DEFAULT_ERROR_MESSAGES#EQUALS}
- *
- * @class EqualsValidator
- * @extends Validator
- *
- * @category Validators
- */
-export declare class EqualsValidator extends Validator<EqualsValidatorOptions> {
-    constructor(message?: string);
-    /**
-     * @summary Validates a model
-     *
-     * @param {string} value
-     * @param {EqualsValidatorOptions} options
-     * @param {PathProxy<any>} accessor - Proxy-like object used to resolve values from nested structures via path strings.
-     *
-     * @return {string | undefined}
-     *
-     * @override
-     * @see Validator#hasErrors
-     */
-    hasErrors(value: any, options: EqualsValidatorOptions, accessor: PathProxy<any>): string | undefined;
-}

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

@@ -1,29 +0,0 @@
-import { Validator } from "./Validator";
-import { GreaterThanOrEqualValidatorOptions } from "../types";
-import type { PathProxy } from "../../utils/PathProxy";
-/**
- * @summary Greater Than or Equal Validator
- *
- * @param {string} [message] defaults to {@link DEFAULT_ERROR_MESSAGES#GREATER_THAN_OR_EQUAL}
- *
- * @class GreaterThanOrEqualValidator
- * @extends Validator
- *
- * @category Validators
- */
-export declare class GreaterThanOrEqualValidator extends Validator<GreaterThanOrEqualValidatorOptions> {
-    constructor(message?: string);
-    /**
-     * @summary Validates a model
-     *
-     * @param {string} value
-     * @param {GreaterThanOrEqualValidatorOptions} options
-     * @param {PathProxy<any>} accessor - Proxy-like object used to resolve values from nested structures via path strings.
-     *
-     * @return {string | undefined}
-     *
-     * @override
-     * @see Validator#hasErrors
-     */
-    hasErrors(value: any, options: GreaterThanOrEqualValidatorOptions, accessor: PathProxy<any>): string | undefined;
-}

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

@@ -1,29 +0,0 @@
-import { Validator } from "./Validator";
-import { GreaterThanValidatorOptions } from "../types";
-import type { PathProxy } from "../../utils/PathProxy";
-/**
- * @summary Greater Than Validator
- *
- * @param {string} [message] defaults to {@link DEFAULT_ERROR_MESSAGES#GREATER_THAN}
- *
- * @class GreaterThanValidator
- * @extends Validator
- *
- * @category Validators
- */
-export declare class GreaterThanValidator extends Validator<GreaterThanValidatorOptions> {
-    constructor(message?: string);
-    /**
-     * @summary Validates a model
-     *
-     * @param {string} value
-     * @param {GreaterThanValidatorOptions} options
-     * @param {PathProxy<any>} accessor - Proxy-like object used to resolve values from nested structures via path strings.
-     *
-     * @return {string | undefined}
-     *
-     * @override
-     * @see Validator#hasErrors
-     */
-    hasErrors(value: any, options: GreaterThanValidatorOptions, accessor: PathProxy<any>): string | undefined;
-}

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

@@ -1,29 +0,0 @@
-import { Validator } from "./Validator";
-import type { LessThanOrEqualValidatorOptions } from "../types";
-import type { PathProxy } from "../../utils/PathProxy";
-/**
- * @summary Less Than or Equal Validator
- *
- * @param {string} [message] defaults to {@link DEFAULT_ERROR_MESSAGES#LESS_THAN_OR_EQUAL}
- *
- * @class LessThanOrEqualValidator
- * @extends Validator
- *
- * @category Validators
- */
-export declare class LessThanOrEqualValidator extends Validator<LessThanOrEqualValidatorOptions> {
-    constructor(message?: string);
-    /**
-     * @summary Validates a model
-     *
-     * @param {string} value
-     * @param {LessThanOrEqualValidatorOptions} options
-     * @param {PathProxy<any>} accessor - Proxy-like object used to resolve values from nested structures via path strings.
-     *
-     * @return {string | undefined}
-     *
-     * @override
-     * @see Validator#hasErrors
-     */
-    hasErrors(value: any, options: LessThanOrEqualValidatorOptions, accessor: PathProxy<any>): string | undefined;
-}

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

@@ -1,29 +0,0 @@
-import { Validator } from "./Validator";
-import { LessThanValidatorOptions } from "../types";
-import type { PathProxy } from "../../utils/PathProxy";
-/**
- * @summary Less Than Validator
- *
- * @param {string} [message] defaults to {@link DEFAULT_ERROR_MESSAGES#LESS_THAN}
- *
- * @class LessThanValidator
- * @extends Validator
- *
- * @category Validators
- */
-export declare class LessThanValidator extends Validator<LessThanValidatorOptions> {
-    constructor(message?: string);
-    /**
-     * @summary Validates a model
-     *
-     * @param {string} value
-     * @param {LessThanValidatorOptions} options
-     * @param {PathProxy<any>} accessor - Proxy-like object used to resolve values from nested structures via path strings.
-     *
-     * @return {string | undefined}
-     *
-     * @override
-     * @see Validator#hasErrors
-     */
-    hasErrors(value: any, options: LessThanValidatorOptions, accessor: PathProxy<any>): string | undefined;
-}

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

@@ -1,66 +0,0 @@
-import { Validator } from "./Validator";
-import { ListValidatorOptions } from "../types";
-/**
- * @description Validator for checking if elements in a list or set match expected types
- * @summary The ListValidator validates that all elements in an array or Set match the expected types.
- * It checks each element against a list of allowed class types and ensures type consistency.
- * This validator is typically used with the @list decorator.
- *
- * @param {string} [message] - Custom error message to display when validation fails, defaults to {@link DEFAULT_ERROR_MESSAGES#LIST}
- *
- * @class ListValidator
- * @extends Validator
- *
- * @example
- * ```typescript
- * // Create a list validator with default error message
- * const listValidator = new ListValidator();
- *
- * // Create a list validator with custom error message
- * const customListValidator = new ListValidator("All items must be of the specified type");
- *
- * // Validate a list
- * const options = { clazz: ["String", "Number"] };
- * const result = listValidator.hasErrors(["test", 123], options); // undefined (valid)
- * const invalidResult = listValidator.hasErrors([new Date()], options); // Returns error message (invalid)
- * ```
- *
- * @mermaid
- * sequenceDiagram
- *   participant C as Client
- *   participant V as ListValidator
- *
- *   C->>V: new ListValidator(message)
- *   C->>V: hasErrors(value, options)
- *   alt value is empty
- *     V-->>C: undefined (valid)
- *   else value has elements
- *     V->>V: Check each element's type
- *     alt All elements match allowed types
- *       V-->>C: undefined (valid)
- *     else Some elements don't match
- *       V-->>C: Error message
- *     end
- *   end
- *
- * @category Validators
- */
-export declare class ListValidator extends Validator<ListValidatorOptions> {
-    constructor(message?: string);
-    /**
-     * @description Checks if all elements in a list or set match the expected types
-     * @summary Validates that each element in the provided array or Set matches one of the
-     * class types specified in the options. For object types, it checks the constructor name,
-     * and for primitive types, it compares against the lowercase type name.
-     *
-     * @param {any[] | Set<any>} value - The array or Set to validate
-     * @param {ListValidatorOptions} options - Configuration options containing the allowed class types
-     *
-     * @return {string | undefined} Error message if validation fails, undefined if validation passes
-     *
-     * @override
-     *
-     * @see Validator#hasErrors
-     */
-    hasErrors(value: any[] | Set<any>, options: ListValidatorOptions): string | undefined;
-}

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

@@ -1,29 +0,0 @@
-import { Validator } from "./Validator";
-import { MaxLengthValidatorOptions } from "../types";
-/**
- * @summary Maximum Length Validator
- * @description Validates strings and Arrays on their maximum length
- *
- * @param {string} [message] defaults to {@link DEFAULT_ERROR_MESSAGES#MAX_LENGTH}
- *
- * @class MinLengthValidator
- * @extends Validator
- *
- * @category Validators
- */
-export declare class MaxLengthValidator extends Validator<MaxLengthValidatorOptions> {
-    constructor(message?: string);
-    /**
-     * @summary Validates a model
-     *
-     * @param {string} value
-     * @param {MaxLengthValidatorOptions} options
-     *
-     * @return {string | undefined}
-     *
-     * @override
-     *
-     * @see Validator#hasErrors
-     */
-    hasErrors(value: string | any[], options: MaxLengthValidatorOptions): string | undefined;
-}

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

@@ -1,74 +0,0 @@
-import { Validator } from "./Validator";
-import { MaxValidatorOptions } from "../types";
-/**
- * @description Validator for checking if a value is less than or equal to a maximum
- * @summary The MaxValidator checks if a numeric value, date, or string is less than or equal to
- * a specified maximum value. It supports comparing numbers directly, dates chronologically,
- * and strings lexicographically. This validator is typically used with the @max decorator.
- *
- * @param {string} [message] - Custom error message to display when validation fails, defaults to {@link DEFAULT_ERROR_MESSAGES#MAX}
- *
- * @class MaxValidator
- * @extends Validator
- *
- * @example
- * ```typescript
- * // Create a max validator with default error message
- * const maxValidator = new MaxValidator();
- *
- * // Create a max validator with custom error message
- * const customMaxValidator = new MaxValidator("Value must not exceed {0}");
- *
- * // Validate a number
- * const numOptions = { max: 100, message: "Number too large" };
- * const numResult = maxValidator.hasErrors(50, numOptions); // undefined (valid)
- * const invalidNumResult = maxValidator.hasErrors(150, numOptions); // Returns error message (invalid)
- *
- * // Validate a date
- * const dateOptions = { max: new Date(2023, 11, 31) };
- * const dateResult = maxValidator.hasErrors(new Date(2023, 5, 15), dateOptions); // undefined (valid)
- * ```
- *
- * @mermaid
- * sequenceDiagram
- *   participant C as Client
- *   participant V as MaxValidator
- *
- *   C->>V: new MaxValidator(message)
- *   C->>V: hasErrors(value, options)
- *   alt value is undefined
- *     V-->>C: undefined (valid)
- *   else value is Date and max is not Date
- *     V->>V: Convert max to Date
- *     alt conversion fails
- *       V-->>C: Error: Invalid Max param
- *     end
- *   end
- *   alt value > max
- *     V-->>C: Error message
- *   else value <= max
- *     V-->>C: undefined (valid)
- *   end
- *
- * @category Validators
- */
-export declare class MaxValidator extends Validator<MaxValidatorOptions> {
-    constructor(message?: string);
-    /**
-     * @description Checks if a value is less than or equal to a maximum
-     * @summary Validates that the provided value does not exceed the maximum 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 {MaxValidatorOptions} options - Configuration options containing the maximum value
-     *
-     * @return {string | undefined} Error message if validation fails, undefined if validation passes
-     *
-     * @override
-     *
-     * @see Validator#hasErrors
-     */
-    hasErrors(value: number | Date | string, options: MaxValidatorOptions): string | undefined;
-}