@decaf-ts/decorator-validation 1.15.0 → 1.16.0

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

@@ -0,0 +1,157 @@
+/**
+ * @description Object-like set of keys used for comparison-based validations.
+ * @summary Provides canonical names for validators that compare two values (equality and ordering checks).
+ * @typedef {Object} ComparisonValidationKeysDef
+ * @property {"equals"} EQUALS Validates if two values are equal.
+ * @property {"different"} DIFF Validates if two values are different.
+ * @property {"lessThan"} LESS_THAN Validates if a value is less than another.
+ * @property {"lessThanOrEqual"} LESS_THAN_OR_EQUAL Validates if a value is less than or equal to another.
+ * @property {"greaterThan"} GREATER_THAN Validates if a value is greater than another.
+ * @property {"greaterThanOrEqual"} GREATER_THAN_OR_EQUAL Validates if a value is greater than or equal to another.
+ * @memberOf module:decorator-validation.Validation
+ */
+/**
+ * @description Keys used for comparison-based validations.
+ * @summary Canonical key names for comparison validators.
+ * @const ComparisonValidationKeys
+ * @memberOf module:decorator-validation.Validation
+ * @category Validation
+ * @type {ComparisonValidationKeysDef}
+ */
+export declare const ComparisonValidationKeys: {
+    readonly EQUALS: "equals";
+    readonly DIFF: "different";
+    readonly LESS_THAN: "lessThan";
+    readonly LESS_THAN_OR_EQUAL: "lessThanOrEqual";
+    readonly GREATER_THAN: "greaterThan";
+    readonly GREATER_THAN_OR_EQUAL: "greaterThanOrEqual";
+};
+/**
+ * @description Object-like set of keys used across all validators in the system.
+ * @summary Defines the canonical namespaced key prefix and the individual validation flags for rules such as required, min/max, length, patterns, types, lists and more.
+ * @typedef {Object} ValidationKeysDef
+ * @property {string} REFLECT prefixes others (namespace prefix)
+ * @property {"required"} REQUIRED sets as required
+ * @property {"min"} MIN defines min value
+ * @property {"max"} MAX defines max value
+ * @property {"step"} STEP defines step
+ * @property {"minlength"} MIN_LENGTH defines min length
+ * @property {"maxlength"} MAX_LENGTH defines max length
+ * @property {"pattern"} PATTERN defines pattern
+ * @property {"email"} EMAIL defines email
+ * @property {"url"} URL defines url
+ * @property {"date"} DATE defines date
+ * @property {"type"} TYPE defines type
+ * @property {"password"} PASSWORD defines password
+ * @property {"list"} LIST defines list
+ * @property {"unique"} UNIQUE flags uniqueness
+ * @property {"validator"} VALIDATOR custom validator id
+ * @memberOf module:decorator-validation.Validation
+ */
+/**
+ * @description The keys used for validation.
+ * @summary A namespaced collection of validation key strings used throughout the library.
+ * @const ValidationKeys
+ * @memberOf module:decorator-validation.Validation
+ * @category Validation
+ * @type {ValidationKeysDef}
+ */
+export declare const ValidationKeys: {
+    readonly EQUALS: "equals";
+    readonly DIFF: "different";
+    readonly LESS_THAN: "lessThan";
+    readonly LESS_THAN_OR_EQUAL: "lessThanOrEqual";
+    readonly GREATER_THAN: "greaterThan";
+    readonly GREATER_THAN_OR_EQUAL: "greaterThanOrEqual";
+    readonly REFLECT: "validation";
+    readonly DATE: "date";
+    readonly EMAIL: "email";
+    readonly FORMAT: "format";
+    readonly LIST: "list";
+    readonly MAX: "max";
+    readonly MAX_LENGTH: "maxlength";
+    readonly MIN: "min";
+    readonly MIN_LENGTH: "minlength";
+    readonly PASSWORD: "password";
+    readonly PATTERN: "pattern";
+    readonly REQUIRED: "required";
+    readonly STEP: "step";
+    readonly TYPE: "type";
+    readonly UNIQUE: "unique";
+    readonly URL: "url";
+    readonly VALIDATOR: "validator";
+    readonly ENUM: "enum";
+};
+/**
+ * @description list of month names
+ * @summary Stores month names. Can be changed for localization purposes
+ * @const MONTH_NAMES
+ * @memberOf module:decorator-validation.Validation
+ * @category Validation
+ */
+export declare const MONTH_NAMES: string[];
+/**
+ * @description list of names of days of the week
+ * @summary Stores names for days of the week. Can be changed for localization purposes
+ * @const DAYS_OF_WEEK_NAMES
+ * @memberOf module:decorator-validation.Validation
+ * @category Validation
+ */
+export declare const DAYS_OF_WEEK_NAMES: string[];
+/**
+ * @description Type definition for default error message strings keyed by validation type.
+ * @summary Enumerates the supported error message keys with their intended meaning; used to localize or override default messages.
+ * @typedef {Object} DefaultErrorMessages
+ * @property {string} REQUIRED default error message
+ * @property {string} MIN default error message
+ * @property {string} MAX default error message
+ * @property {string} MIN_LENGTH default error message
+ * @property {string} MAX_LENGTH default error message
+ * @property {string} PATTERN default error message
+ * @property {string} EMAIL default error message
+ * @property {string} URL default error message
+ * @property {string} TYPE default error message
+ * @property {string} STEP default error message
+ * @property {string} DATE default error message
+ * @property {string} DEFAULT default error message
+ * @property {string} PASSWORD default error message
+ * @property {string} LIST default error message
+ * @property {string} LIST_INSIDE default error message
+ * @property {string} MODEL_NOT_FOUND default error message
+ * @memberOf module:decorator-validation.Validation
+ */
+/**
+ * @description Defines the default error messages
+ * @summary Mapping between validation keys and their default human-readable error messages.
+ * @const DEFAULT_ERROR_MESSAGES
+ * @memberOf module:decorator-validation.Validation
+ * @category Validation
+ * @type {DefaultErrorMessages}
+ */
+export declare const DEFAULT_ERROR_MESSAGES: Record<string, string>;
+/**
+ * @description Type definition for default regular expression patterns used in validation.
+ * @summary Captures common regex patterns for email, URL, and password policies, including nested grouping for password-related rules.
+ * @typedef {Object} DefaultPatterns
+ * @property {RegExp} EMAIL Email address validation pattern
+ * @property {RegExp} URL URL validation pattern
+ * @property {Object} PASSWORD Password-related regex patterns
+ * @property {RegExp} PASSWORD.CHAR8_ONE_OF_EACH At least 8 chars with lower, upper, number, and special char
+ * @memberOf module:decorator-validation.Validation
+ */
+/**
+ * @description Defines the various default regexp patterns used
+ * @summary Collection of frequently used validation patterns grouped under semantic keys.
+ * @const DEFAULT_PATTERNS
+ * @memberOf module:decorator-validation.Validation
+ * @category Validation
+ * @type {DefaultPatterns}
+ */
+export declare const DEFAULT_PATTERNS: {
+    EMAIL: RegExp;
+    URL: RegExp;
+    PASSWORD: {
+        CHAR8_ONE_OF_EACH: RegExp;
+    };
+    asd: string;
+};

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

@@ -0,0 +1,12 @@
+import { Validator } from "./Validator.cjs";
+/**
+ * @summary Marks the class as a validator for a certain key.
+ * @description Registers the class in the {@link Validation} with the provided key
+ *
+ * @param {string} keys the validation key
+ *
+ * @function validator
+ *
+ * @category Class Decorators
+ */
+export declare function validator<T extends Validator>(...keys: string[]): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor | number) => void;

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

@@ -0,0 +1,12 @@
+import { Validator } from "./Validator.js";
+/**
+ * @summary Marks the class as a validator for a certain key.
+ * @description Registers the class in the {@link Validation} with the provided key
+ *
+ * @param {string} keys the validation key
+ *
+ * @function validator
+ *
+ * @category Class Decorators
+ */
+export declare function validator<T extends Validator>(...keys: string[]): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor | number) => void;

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

@@ -0,0 +1,26 @@
+export * from "./constants.cjs";
+export * from "./AsyncValidator.cjs";
+export * from "./DateValidator.cjs";
+export * from "./decorators.cjs";
+export * from "./DiffValidator.cjs";
+export * from "./EmailValidator.cjs";
+export * from "./EqualsValidator.cjs";
+export * from "./GreaterThanValidator.cjs";
+export * from "./GreaterThanOrEqualValidator.cjs";
+export * from "./LessThanValidator.cjs";
+export * from "./LessThanOrEqualValidator.cjs";
+export * from "./ListValidator.cjs";
+export * from "./MaxLengthValidator.cjs";
+export * from "./MaxValidator.cjs";
+export * from "./MinLengthValidator.cjs";
+export * from "./MinValidator.cjs";
+export * from "./OptionValidator.cjs";
+export * from "./PasswordValidator.cjs";
+export * from "./PatternValidator.cjs";
+export * from "./RequiredValidator.cjs";
+export * from "./StepValidator.cjs";
+export * from "./TypeValidator.cjs";
+export * from "./URLValidator.cjs";
+export * from "./Validator.cjs";
+export * from "./ValidatorRegistry.cjs";
+export * from "./utils.cjs";

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

@@ -0,0 +1,26 @@
+export * from "./constants.js";
+export * from "./AsyncValidator.js";
+export * from "./DateValidator.js";
+export * from "./decorators.js";
+export * from "./DiffValidator.js";
+export * from "./EmailValidator.js";
+export * from "./EqualsValidator.js";
+export * from "./GreaterThanValidator.js";
+export * from "./GreaterThanOrEqualValidator.js";
+export * from "./LessThanValidator.js";
+export * from "./LessThanOrEqualValidator.js";
+export * from "./ListValidator.js";
+export * from "./MaxLengthValidator.js";
+export * from "./MaxValidator.js";
+export * from "./MinLengthValidator.js";
+export * from "./MinValidator.js";
+export * from "./OptionValidator.js";
+export * from "./PasswordValidator.js";
+export * from "./PatternValidator.js";
+export * from "./RequiredValidator.js";
+export * from "./StepValidator.js";
+export * from "./TypeValidator.js";
+export * from "./URLValidator.js";
+export * from "./Validator.js";
+export * from "./ValidatorRegistry.js";
+export * from "./utils.js";

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

@@ -0,0 +1,75 @@
+/**
+ * Validates whether two values are eligible for comparison using >= or <= operators.
+ *
+ * Supported types: `undefined`, `number`, `bigint`, and `Date`.
+ *
+ * @param a - The first value to compare.
+ * @param b - The second value to compare.
+ *
+ * @returns {boolean} True if both values are of supported types.
+ *
+ * @throws {TypeError} If either value is of an unsupported type.
+ * @memberOf module:decorator-validation
+ */
+export declare function isValidForGteOrLteComparison(a: any, b: any): boolean;
+/**
+ * @summary Compares two values to determine if the first is less than the second.
+ * @description Supports numbers and dates. Throws an error for unsupported types.
+ *
+ * @param {any} a - The first value to compare.
+ * @param {any} b - The second value to compare against.
+ *
+ * @returns {boolean} True if `a` is less than `b`, false otherwise.
+ *
+ * @throws {Error} If either `a` or `b` is `null` or `undefined`.
+ * @throws {TypeError} If values are of mismatched or unsupported types.
+ * @memberOf module:decorator-validation
+ */
+export declare function isLessThan(a: any, b: any): boolean;
+/**
+ * Checks if `a` is greater than `b`.
+ * Supports comparison for numbers and Date objects.
+ *
+ * @param {any} a - The value to validate.
+ * @param {any} b - The value to compare against.
+ *
+ * @returns {boolean} True if `a` is greater than `b`, otherwise false.
+ *
+ * @throws {Error} If either `a` or `b` is `null` or `undefined`.
+ * @throws {TypeError} If values are of mismatched or unsupported types.
+ * @memberOf module:decorator-validation
+ */
+export declare function isGreaterThan(a: any, b: any): boolean;
+/**
+ * @description Checks if a value matches a specified type name
+ * @summary Utility function to verify if a value's type matches the provided type name
+ * @param {unknown} value - The value to check the type of
+ * @param {string} acceptedType - The type name to check against
+ * @return {boolean} Returns true if the value matches the accepted type, false otherwise
+ */
+export declare function checkType(value: unknown, acceptedType: string): boolean;
+/**
+ * @description Checks if a value matches any of the specified type names
+ * @summary Utility function to verify if a value's type matches any of the provided type names
+ * @param {unknown} value - The value to check the type of
+ * @param {string[]} acceptedTypes - Array of type names to check against
+ * @return {boolean} Returns true if the value matches any of the accepted types, false otherwise
+ */
+export declare function checkTypes(value: unknown, acceptedTypes: string[]): boolean;
+/**
+ * @description Evaluates if a value matches the specified type metadata
+ * @summary Compares a value against type metadata to determine if they match
+ * @param {unknown} value - The value to evaluate
+ * @param {string | string[] | {name: string}} types - Type metadata to check against, can be a string, array of strings, or an object with a name property
+ * @return {boolean} Returns true if the value matches the type metadata, false otherwise
+ */
+export declare function evaluateDesignTypes(value: unknown, types: string | string[] | {
+    name: string;
+}): boolean;
+/**
+ * @description Returns the length of a value
+ * @summary Returns the length of a value
+ * @param {string | Set<any> | any[] | Map<any, any>} value - The value to evaluate
+ * @return {number} Returns the length of a value
+ */
+export declare function valueLength(value: string | Set<any> | any[] | Map<any, any>): number;

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

@@ -0,0 +1,75 @@
+/**
+ * Validates whether two values are eligible for comparison using >= or <= operators.
+ *
+ * Supported types: `undefined`, `number`, `bigint`, and `Date`.
+ *
+ * @param a - The first value to compare.
+ * @param b - The second value to compare.
+ *
+ * @returns {boolean} True if both values are of supported types.
+ *
+ * @throws {TypeError} If either value is of an unsupported type.
+ * @memberOf module:decorator-validation
+ */
+export declare function isValidForGteOrLteComparison(a: any, b: any): boolean;
+/**
+ * @summary Compares two values to determine if the first is less than the second.
+ * @description Supports numbers and dates. Throws an error for unsupported types.
+ *
+ * @param {any} a - The first value to compare.
+ * @param {any} b - The second value to compare against.
+ *
+ * @returns {boolean} True if `a` is less than `b`, false otherwise.
+ *
+ * @throws {Error} If either `a` or `b` is `null` or `undefined`.
+ * @throws {TypeError} If values are of mismatched or unsupported types.
+ * @memberOf module:decorator-validation
+ */
+export declare function isLessThan(a: any, b: any): boolean;
+/**
+ * Checks if `a` is greater than `b`.
+ * Supports comparison for numbers and Date objects.
+ *
+ * @param {any} a - The value to validate.
+ * @param {any} b - The value to compare against.
+ *
+ * @returns {boolean} True if `a` is greater than `b`, otherwise false.
+ *
+ * @throws {Error} If either `a` or `b` is `null` or `undefined`.
+ * @throws {TypeError} If values are of mismatched or unsupported types.
+ * @memberOf module:decorator-validation
+ */
+export declare function isGreaterThan(a: any, b: any): boolean;
+/**
+ * @description Checks if a value matches a specified type name
+ * @summary Utility function to verify if a value's type matches the provided type name
+ * @param {unknown} value - The value to check the type of
+ * @param {string} acceptedType - The type name to check against
+ * @return {boolean} Returns true if the value matches the accepted type, false otherwise
+ */
+export declare function checkType(value: unknown, acceptedType: string): boolean;
+/**
+ * @description Checks if a value matches any of the specified type names
+ * @summary Utility function to verify if a value's type matches any of the provided type names
+ * @param {unknown} value - The value to check the type of
+ * @param {string[]} acceptedTypes - Array of type names to check against
+ * @return {boolean} Returns true if the value matches any of the accepted types, false otherwise
+ */
+export declare function checkTypes(value: unknown, acceptedTypes: string[]): boolean;
+/**
+ * @description Evaluates if a value matches the specified type metadata
+ * @summary Compares a value against type metadata to determine if they match
+ * @param {unknown} value - The value to evaluate
+ * @param {string | string[] | {name: string}} types - Type metadata to check against, can be a string, array of strings, or an object with a name property
+ * @return {boolean} Returns true if the value matches the type metadata, false otherwise
+ */
+export declare function evaluateDesignTypes(value: unknown, types: string | string[] | {
+    name: string;
+}): boolean;
+/**
+ * @description Returns the length of a value
+ * @summary Returns the length of a value
+ * @param {string | Set<any> | any[] | Map<any, any>} value - The value to evaluate
+ * @return {number} Returns the length of a value
+ */
+export declare function valueLength(value: string | Set<any> | any[] | Map<any, any>): number;