@decaf-ts/decorator-validation 1.6.0 → 1.6.2

package/lib/esm/validation/Validators/RequiredValidator.js

@@ -11,13 +11,55 @@ import { Validator } from "./Validator";
 import { DEFAULT_ERROR_MESSAGES, ValidationKeys } from "./constants";
 import { validator } from "./decorators";
 /**
- * @summary Required Validator
+ * @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] defaults to {@link DEFAULT_ERROR_MESSAGES#REQUIRED}
+ * @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
  */
 let RequiredValidator = class RequiredValidator extends Validator {
@@ -25,12 +67,16 @@ let RequiredValidator = class RequiredValidator extends Validator {
         super(message);
     }
     /**
-     * @summary Validates a model
+     * @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 {string} value
-     * @param {ValidatorOptions} [options={}]
+     * @param {any} value - The value to validate
+     * @param {ValidatorOptions} [options={}] - Optional configuration options
      *
-     * @return {string | undefined}
+     * @return {string | undefined} Error message if validation fails, undefined if validation passes
      *
      * @override
      *
@@ -55,4 +101,4 @@ RequiredValidator = __decorate([
     __metadata("design:paramtypes", [String])
 ], RequiredValidator);
 export { RequiredValidator };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiUmVxdWlyZWRWYWxpZGF0b3IuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi9zcmMvdmFsaWRhdGlvbi9WYWxpZGF0b3JzL1JlcXVpcmVkVmFsaWRhdG9yLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7Ozs7Ozs7OztBQUFBLE9BQU8sRUFBRSxTQUFTLEVBQUUsTUFBTSxhQUFhLENBQUM7QUFDeEMsT0FBTyxFQUFFLHNCQUFzQixFQUFFLGNBQWMsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUNyRSxPQUFPLEVBQUUsU0FBUyxFQUFFLE1BQU0sY0FBYyxDQUFDO0FBR3pDOzs7Ozs7Ozs7R0FTRztBQUVJLElBQU0saUJBQWlCLEdBQXZCLE1BQU0saUJBQWtCLFNBQVEsU0FBUztJQUM5QyxZQUFZLFVBQWtCLHNCQUFzQixDQUFDLFFBQVE7UUFDM0QsS0FBSyxDQUFDLE9BQU8sQ0FBQyxDQUFDO0lBQ2pCLENBQUM7SUFFRDs7Ozs7Ozs7Ozs7T0FXRztJQUNJLFNBQVMsQ0FDZCxLQUFVLEVBQ1YsVUFBNEIsRUFBRTtRQUU5QixRQUFRLE9BQU8sS0FBSyxFQUFFLENBQUM7WUFDckIsS0FBSyxTQUFTLENBQUM7WUFDZixLQUFLLFFBQVE7Z0JBQ1gsT0FBTyxPQUFPLEtBQUssS0FBSyxXQUFXO29CQUNqQyxDQUFDLENBQUMsSUFBSSxDQUFDLFVBQVUsQ0FBQyxPQUFPLENBQUMsT0FBTyxJQUFJLElBQUksQ0FBQyxPQUFPLENBQUM7b0JBQ2xELENBQUMsQ0FBQyxTQUFTLENBQUM7WUFDaEI7Z0JBQ0UsT0FBTyxDQUFDLEtBQUs7b0JBQ1gsQ0FBQyxDQUFDLElBQUksQ0FBQyxVQUFVLENBQUMsT0FBTyxDQUFDLE9BQU8sSUFBSSxJQUFJLENBQUMsT0FBTyxDQUFDO29CQUNsRCxDQUFDLENBQUMsU0FBUyxDQUFDO1FBQ2xCLENBQUM7SUFDSCxDQUFDO0NBQ0YsQ0FBQTtBQWpDWSxpQkFBaUI7SUFEN0IsU0FBUyxDQUFDLGNBQWMsQ0FBQyxRQUFRLENBQUM7O0dBQ3RCLGlCQUFpQixDQWlDN0IiLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgeyBWYWxpZGF0b3IgfSBmcm9tIFwiLi9WYWxpZGF0b3JcIjtcbmltcG9ydCB7IERFRkFVTFRfRVJST1JfTUVTU0FHRVMsIFZhbGlkYXRpb25LZXlzIH0gZnJvbSBcIi4vY29uc3RhbnRzXCI7XG5pbXBvcnQgeyB2YWxpZGF0b3IgfSBmcm9tIFwiLi9kZWNvcmF0b3JzXCI7XG5pbXBvcnQgeyBWYWxpZGF0b3JPcHRpb25zIH0gZnJvbSBcIi4uL3R5cGVzXCI7XG5cbi8qKlxuICogQHN1bW1hcnkgUmVxdWlyZWQgVmFsaWRhdG9yXG4gKlxuICogQHBhcmFtIHtzdHJpbmd9IFttZXNzYWdlXSBkZWZhdWx0cyB0byB7QGxpbmsgREVGQVVMVF9FUlJPUl9NRVNTQUdFUyNSRVFVSVJFRH1cbiAqXG4gKiBAY2xhc3MgUmVxdWlyZWRWYWxpZGF0b3JcbiAqIEBleHRlbmRzIFZhbGlkYXRvclxuICpcbiAqIEBjYXRlZ29yeSBWYWxpZGF0b3JzXG4gKi9cbkB2YWxpZGF0b3IoVmFsaWRhdGlvbktleXMuUkVRVUlSRUQpXG5leHBvcnQgY2xhc3MgUmVxdWlyZWRWYWxpZGF0b3IgZXh0ZW5kcyBWYWxpZGF0b3Ige1xuICBjb25zdHJ1Y3RvcihtZXNzYWdlOiBzdHJpbmcgPSBERUZBVUxUX0VSUk9SX01FU1NBR0VTLlJFUVVJUkVEKSB7XG4gICAgc3VwZXIobWVzc2FnZSk7XG4gIH1cblxuICAvKipcbiAgICogQHN1bW1hcnkgVmFsaWRhdGVzIGEgbW9kZWxcbiAgICpcbiAgICogQHBhcmFtIHtzdHJpbmd9IHZhbHVlXG4gICAqIEBwYXJhbSB7VmFsaWRhdG9yT3B0aW9uc30gW29wdGlvbnM9e31dXG4gICAqXG4gICAqIEByZXR1cm4ge3N0cmluZyB8IHVuZGVmaW5lZH1cbiAgICpcbiAgICogQG92ZXJyaWRlXG4gICAqXG4gICAqIEBzZWUgVmFsaWRhdG9yI2hhc0Vycm9yc1xuICAgKi9cbiAgcHVibGljIGhhc0Vycm9ycyhcbiAgICB2YWx1ZTogYW55LFxuICAgIG9wdGlvbnM6IFZhbGlkYXRvck9wdGlvbnMgPSB7fVxuICApOiBzdHJpbmcgfCB1bmRlZmluZWQge1xuICAgIHN3aXRjaCAodHlwZW9mIHZhbHVlKSB7XG4gICAgICBjYXNlIFwiYm9vbGVhblwiOlxuICAgICAgY2FzZSBcIm51bWJlclwiOlxuICAgICAgICByZXR1cm4gdHlwZW9mIHZhbHVlID09PSBcInVuZGVmaW5lZFwiXG4gICAgICAgICAgPyB0aGlzLmdldE1lc3NhZ2Uob3B0aW9ucy5tZXNzYWdlIHx8IHRoaXMubWVzc2FnZSlcbiAgICAgICAgICA6IHVuZGVmaW5lZDtcbiAgICAgIGRlZmF1bHQ6XG4gICAgICAgIHJldHVybiAhdmFsdWVcbiAgICAgICAgICA/IHRoaXMuZ2V0TWVzc2FnZShvcHRpb25zLm1lc3NhZ2UgfHwgdGhpcy5tZXNzYWdlKVxuICAgICAgICAgIDogdW5kZWZpbmVkO1xuICAgIH1cbiAgfVxufVxuIl19
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiUmVxdWlyZWRWYWxpZGF0b3IuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi9zcmMvdmFsaWRhdGlvbi9WYWxpZGF0b3JzL1JlcXVpcmVkVmFsaWRhdG9yLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7Ozs7Ozs7OztBQUFBLE9BQU8sRUFBRSxTQUFTLEVBQUUsTUFBTSxhQUFhLENBQUM7QUFDeEMsT0FBTyxFQUFFLHNCQUFzQixFQUFFLGNBQWMsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUNyRSxPQUFPLEVBQUUsU0FBUyxFQUFFLE1BQU0sY0FBYyxDQUFDO0FBR3pDOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0FtREc7QUFFSSxJQUFNLGlCQUFpQixHQUF2QixNQUFNLGlCQUFrQixTQUFRLFNBQVM7SUFDOUMsWUFBWSxVQUFrQixzQkFBc0IsQ0FBQyxRQUFRO1FBQzNELEtBQUssQ0FBQyxPQUFPLENBQUMsQ0FBQztJQUNqQixDQUFDO0lBRUQ7Ozs7Ozs7Ozs7Ozs7OztPQWVHO0lBQ0ksU0FBUyxDQUNkLEtBQVUsRUFDVixVQUE0QixFQUFFO1FBRTlCLFFBQVEsT0FBTyxLQUFLLEVBQUUsQ0FBQztZQUNyQixLQUFLLFNBQVMsQ0FBQztZQUNmLEtBQUssUUFBUTtnQkFDWCxPQUFPLE9BQU8sS0FBSyxLQUFLLFdBQVc7b0JBQ2pDLENBQUMsQ0FBQyxJQUFJLENBQUMsVUFBVSxDQUFDLE9BQU8sQ0FBQyxPQUFPLElBQUksSUFBSSxDQUFDLE9BQU8sQ0FBQztvQkFDbEQsQ0FBQyxDQUFDLFNBQVMsQ0FBQztZQUNoQjtnQkFDRSxPQUFPLENBQUMsS0FBSztvQkFDWCxDQUFDLENBQUMsSUFBSSxDQUFDLFVBQVUsQ0FBQyxPQUFPLENBQUMsT0FBTyxJQUFJLElBQUksQ0FBQyxPQUFPLENBQUM7b0JBQ2xELENBQUMsQ0FBQyxTQUFTLENBQUM7UUFDbEIsQ0FBQztJQUNILENBQUM7Q0FDRixDQUFBO0FBckNZLGlCQUFpQjtJQUQ3QixTQUFTLENBQUMsY0FBYyxDQUFDLFFBQVEsQ0FBQzs7R0FDdEIsaUJBQWlCLENBcUM3QiIsInNvdXJjZXNDb250ZW50IjpbImltcG9ydCB7IFZhbGlkYXRvciB9IGZyb20gXCIuL1ZhbGlkYXRvclwiO1xuaW1wb3J0IHsgREVGQVVMVF9FUlJPUl9NRVNTQUdFUywgVmFsaWRhdGlvbktleXMgfSBmcm9tIFwiLi9jb25zdGFudHNcIjtcbmltcG9ydCB7IHZhbGlkYXRvciB9IGZyb20gXCIuL2RlY29yYXRvcnNcIjtcbmltcG9ydCB7IFZhbGlkYXRvck9wdGlvbnMgfSBmcm9tIFwiLi4vdHlwZXNcIjtcblxuLyoqXG4gKiBAZGVzY3JpcHRpb24gVmFsaWRhdG9yIGZvciBjaGVja2luZyBpZiBhIHZhbHVlIGlzIHByZXNlbnQgYW5kIG5vdCBlbXB0eVxuICogQHN1bW1hcnkgVGhlIFJlcXVpcmVkVmFsaWRhdG9yIGVuc3VyZXMgdGhhdCBhIHZhbHVlIGlzIHByb3ZpZGVkIGFuZCBub3QgZW1wdHkuXG4gKiBJdCBoYW5kbGVzIGRpZmZlcmVudCB0eXBlcyBvZiB2YWx1ZXMgYXBwcm9wcmlhdGVseTogZm9yIGJvb2xlYW5zIGFuZCBudW1iZXJzLFxuICogaXQgY2hlY2tzIGlmIHRoZXkncmUgdW5kZWZpbmVkOyBmb3Igb3RoZXIgdHlwZXMgKHN0cmluZ3MsIGFycmF5cywgb2JqZWN0cyksXG4gKiBpdCBjaGVja3MgaWYgdGhleSdyZSBmYWxzeS4gVGhpcyB2YWxpZGF0b3IgaXMgdHlwaWNhbGx5IHVzZWQgd2l0aCB0aGUgQHJlcXVpcmVkIGRlY29yYXRvclxuICogYW5kIGlzIG9mdGVuIHRoZSBmaXJzdCB2YWxpZGF0aW9uIGFwcGxpZWQgdG8gaW1wb3J0YW50IGZpZWxkcy5cbiAqIFxuICogQHBhcmFtIHtzdHJpbmd9IFttZXNzYWdlXSAtIEN1c3RvbSBlcnJvciBtZXNzYWdlIHRvIGRpc3BsYXkgd2hlbiB2YWxpZGF0aW9uIGZhaWxzLCBkZWZhdWx0cyB0byB7QGxpbmsgREVGQVVMVF9FUlJPUl9NRVNTQUdFUyNSRVFVSVJFRH1cbiAqIFxuICogQGNsYXNzIFJlcXVpcmVkVmFsaWRhdG9yXG4gKiBAZXh0ZW5kcyBWYWxpZGF0b3JcbiAqIFxuICogQGV4YW1wbGVcbiAqIGBgYHR5cGVzY3JpcHRcbiAqIC8vIENyZWF0ZSBhIHJlcXVpcmVkIHZhbGlkYXRvciB3aXRoIGRlZmF1bHQgZXJyb3IgbWVzc2FnZVxuICogY29uc3QgcmVxdWlyZWRWYWxpZGF0b3IgPSBuZXcgUmVxdWlyZWRWYWxpZGF0b3IoKTtcbiAqIFxuICogLy8gQ3JlYXRlIGEgcmVxdWlyZWQgdmFsaWRhdG9yIHdpdGggY3VzdG9tIGVycm9yIG1lc3NhZ2VcbiAqIGNvbnN0IGN1c3RvbVJlcXVpcmVkVmFsaWRhdG9yID0gbmV3IFJlcXVpcmVkVmFsaWRhdG9yKFwiVGhpcyBmaWVsZCBpcyBtYW5kYXRvcnlcIik7XG4gKiBcbiAqIC8vIFZhbGlkYXRlIGRpZmZlcmVudCB0eXBlcyBvZiB2YWx1ZXNcbiAqIHJlcXVpcmVkVmFsaWRhdG9yLmhhc0Vycm9ycyhcIkhlbGxvXCIpOyAvLyB1bmRlZmluZWQgKHZhbGlkKVxuICogcmVxdWlyZWRWYWxpZGF0b3IuaGFzRXJyb3JzKFwiXCIpOyAvLyBSZXR1cm5zIGVycm9yIG1lc3NhZ2UgKGludmFsaWQpXG4gKiByZXF1aXJlZFZhbGlkYXRvci5oYXNFcnJvcnMoMCk7IC8vIHVuZGVmaW5lZCAodmFsaWQgLSAwIGlzIGEgdmFsaWQgbnVtYmVyKVxuICogcmVxdWlyZWRWYWxpZGF0b3IuaGFzRXJyb3JzKG51bGwpOyAvLyBSZXR1cm5zIGVycm9yIG1lc3NhZ2UgKGludmFsaWQpXG4gKiByZXF1aXJlZFZhbGlkYXRvci5oYXNFcnJvcnMoW10pOyAvLyB1bmRlZmluZWQgKHZhbGlkIC0gZW1wdHkgYXJyYXkgaXMgc3RpbGwgYW4gYXJyYXkpXG4gKiBgYGBcbiAqIFxuICogQG1lcm1haWRcbiAqIHNlcXVlbmNlRGlhZ3JhbVxuICogICBwYXJ0aWNpcGFudCBDIGFzIENsaWVudFxuICogICBwYXJ0aWNpcGFudCBWIGFzIFJlcXVpcmVkVmFsaWRhdG9yXG4gKiAgIFxuICogICBDLT4+VjogbmV3IFJlcXVpcmVkVmFsaWRhdG9yKG1lc3NhZ2UpXG4gKiAgIEMtPj5WOiBoYXNFcnJvcnModmFsdWUsIG9wdGlvbnMpXG4gKiAgIGFsdCB0eXBlb2YgdmFsdWUgaXMgYm9vbGVhbiBvciBudW1iZXJcbiAqICAgICBhbHQgdmFsdWUgaXMgdW5kZWZpbmVkXG4gKiAgICAgICBWLS0+PkM6IEVycm9yIG1lc3NhZ2VcbiAqICAgICBlbHNlIHZhbHVlIGlzIGRlZmluZWRcbiAqICAgICAgIFYtLT4+QzogdW5kZWZpbmVkICh2YWxpZClcbiAqICAgICBlbmRcbiAqICAgZWxzZSBvdGhlciB0eXBlc1xuICogICAgIGFsdCB2YWx1ZSBpcyBmYWxzeSAobnVsbCwgdW5kZWZpbmVkLCBlbXB0eSBzdHJpbmcpXG4gKiAgICAgICBWLS0+PkM6IEVycm9yIG1lc3NhZ2VcbiAqICAgICBlbHNlIHZhbHVlIGlzIHRydXRoeVxuICogICAgICAgVi0tPj5DOiB1bmRlZmluZWQgKHZhbGlkKVxuICogICAgIGVuZFxuICogICBlbmRcbiAqIFxuICogQGNhdGVnb3J5IFZhbGlkYXRvcnNcbiAqL1xuQHZhbGlkYXRvcihWYWxpZGF0aW9uS2V5cy5SRVFVSVJFRClcbmV4cG9ydCBjbGFzcyBSZXF1aXJlZFZhbGlkYXRvciBleHRlbmRzIFZhbGlkYXRvciB7XG4gIGNvbnN0cnVjdG9yKG1lc3NhZ2U6IHN0cmluZyA9IERFRkFVTFRfRVJST1JfTUVTU0FHRVMuUkVRVUlSRUQpIHtcbiAgICBzdXBlcihtZXNzYWdlKTtcbiAgfVxuXG4gIC8qKlxuICAgKiBAZGVzY3JpcHRpb24gQ2hlY2tzIGlmIGEgdmFsdWUgaXMgcHJlc2VudCBhbmQgbm90IGVtcHR5XG4gICAqIEBzdW1tYXJ5IFZhbGlkYXRlcyB0aGF0IHRoZSBwcm92aWRlZCB2YWx1ZSBleGlzdHMgYW5kIGlzIG5vdCBlbXB0eS5cbiAgICogVGhlIHZhbGlkYXRpb24gbG9naWMgdmFyaWVzIGJ5IHR5cGU6XG4gICAqIC0gRm9yIGJvb2xlYW5zIGFuZCBudW1iZXJzOiBjaGVja3MgaWYgdGhlIHZhbHVlIGlzIHVuZGVmaW5lZFxuICAgKiAtIEZvciBvdGhlciB0eXBlcyAoc3RyaW5ncywgYXJyYXlzLCBvYmplY3RzKTogY2hlY2tzIGlmIHRoZSB2YWx1ZSBpcyBmYWxzeVxuICAgKlxuICAgKiBAcGFyYW0ge2FueX0gdmFsdWUgLSBUaGUgdmFsdWUgdG8gdmFsaWRhdGVcbiAgICogQHBhcmFtIHtWYWxpZGF0b3JPcHRpb25zfSBbb3B0aW9ucz17fV0gLSBPcHRpb25hbCBjb25maWd1cmF0aW9uIG9wdGlvbnNcbiAgICpcbiAgICogQHJldHVybiB7c3RyaW5nIHwgdW5kZWZpbmVkfSBFcnJvciBtZXNzYWdlIGlmIHZhbGlkYXRpb24gZmFpbHMsIHVuZGVmaW5lZCBpZiB2YWxpZGF0aW9uIHBhc3Nlc1xuICAgKlxuICAgKiBAb3ZlcnJpZGVcbiAgICpcbiAgICogQHNlZSBWYWxpZGF0b3IjaGFzRXJyb3JzXG4gICAqL1xuICBwdWJsaWMgaGFzRXJyb3JzKFxuICAgIHZhbHVlOiBhbnksXG4gICAgb3B0aW9uczogVmFsaWRhdG9yT3B0aW9ucyA9IHt9XG4gICk6IHN0cmluZyB8IHVuZGVmaW5lZCB7XG4gICAgc3dpdGNoICh0eXBlb2YgdmFsdWUpIHtcbiAgICAgIGNhc2UgXCJib29sZWFuXCI6XG4gICAgICBjYXNlIFwibnVtYmVyXCI6XG4gICAgICAgIHJldHVybiB0eXBlb2YgdmFsdWUgPT09IFwidW5kZWZpbmVkXCJcbiAgICAgICAgICA/IHRoaXMuZ2V0TWVzc2FnZShvcHRpb25zLm1lc3NhZ2UgfHwgdGhpcy5tZXNzYWdlKVxuICAgICAgICAgIDogdW5kZWZpbmVkO1xuICAgICAgZGVmYXVsdDpcbiAgICAgICAgcmV0dXJuICF2YWx1ZVxuICAgICAgICAgID8gdGhpcy5nZXRNZXNzYWdlKG9wdGlvbnMubWVzc2FnZSB8fCB0aGlzLm1lc3NhZ2UpXG4gICAgICAgICAgOiB1bmRlZmluZWQ7XG4gICAgfVxuICB9XG59XG4iXX0=

package/lib/esm/validation/Validators/TypeValidator.d.ts

@@ -1,21 +1,75 @@
 import { Validator } from "./Validator";
 import { TypeValidatorOptions } from "../types";
 /**
- * @summary Required Validator
+ * @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.
  *
- * @class RequiredValidator
+ * @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);
     /**
-     * @summary Validates a model
-     * @param {string} value
-     * @param {TypeValidatorOptions} options
+     * @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}
+     * @return {string | undefined} Error message if validation fails, undefined if validation passes
      *
      * @override
      *

package/lib/esm/validation/Validators/TypeValidator.js

@@ -14,11 +14,61 @@ import { Validation } from "../Validation";
 import { ModelKeys } from "../../utils/constants";
 import { Reflection } from "@decaf-ts/reflection";
 /**
- * @summary Required Validator
+ * @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.
  *
- * @class RequiredValidator
+ * @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
  */
 let TypeValidator = class TypeValidator extends Validator {
@@ -26,11 +76,15 @@ let TypeValidator = class TypeValidator extends Validator {
         super(message);
     }
     /**
-     * @summary Validates a model
-     * @param {string} value
-     * @param {TypeValidatorOptions} options
+     * @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}
+     * @return {string | undefined} Error message if validation fails, undefined if validation passes
      *
      * @override
      *
@@ -53,9 +107,17 @@ TypeValidator = __decorate([
     __metadata("design:paramtypes", [String])
 ], TypeValidator);
 export { TypeValidator };
+/**
+ * @description Register the TypeValidator with the Validation registry
+ * @summary This registration associates the TypeValidator with the ModelKeys.TYPE key,
+ * allowing it to be used for validating design types. The save flag is set to false
+ * to prevent the validator from being saved in the standard validator registry.
+ *
+ * @memberOf module:decorator-validation
+ */
 Validation.register({
     validator: TypeValidator,
     validationKey: ModelKeys.TYPE,
     save: false,
 });
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiVHlwZVZhbGlkYXRvci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uLy4uL3NyYy92YWxpZGF0aW9uL1ZhbGlkYXRvcnMvVHlwZVZhbGlkYXRvci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7Ozs7Ozs7QUFBQSxPQUFPLEVBQUUsU0FBUyxFQUFFLE1BQU0sYUFBYSxDQUFDO0FBQ3hDLE9BQU8sRUFBRSxzQkFBc0IsRUFBRSxjQUFjLEVBQUUsTUFBTSxhQUFhLENBQUM7QUFDckUsT0FBTyxFQUFFLFNBQVMsRUFBRSxNQUFNLGNBQWMsQ0FBQztBQUN6QyxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sZUFBZSxDQUFDO0FBRTNDLE9BQU8sRUFBRSxTQUFTLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUNsRCxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFFbEQ7Ozs7Ozs7R0FPRztBQUVJLElBQU0sYUFBYSxHQUFuQixNQUFNLGFBQWMsU0FBUSxTQUErQjtJQUNoRSxZQUFZLFVBQWtCLHNCQUFzQixDQUFDLElBQUk7UUFDdkQsS0FBSyxDQUFDLE9BQU8sQ0FBQyxDQUFDO0lBQ2pCLENBQUM7SUFFRDs7Ozs7Ozs7OztPQVVHO0lBQ0ksU0FBUyxDQUNkLEtBQVUsRUFDVixPQUE2QjtRQUU3QixJQUFJLEtBQUssS0FBSyxTQUFTO1lBQUUsT0FBTyxDQUFDLDBDQUEwQztRQUMzRSxNQUFNLEVBQUUsS0FBSyxFQUFFLE9BQU8sRUFBRSxHQUFHLE9BQU8sQ0FBQztRQUNuQyxJQUFJLENBQUMsVUFBVSxDQUFDLG1CQUFtQixDQUFDLEtBQUssRUFBRSxLQUFLLENBQUM7WUFDL0MsT0FBTyxJQUFJLENBQUMsVUFBVSxDQUNwQixPQUFPLElBQUksSUFBSSxDQUFDLE9BQU8sRUFDdkIsT0FBTyxLQUFLLEtBQUssUUFBUTtnQkFDdkIsQ0FBQyxDQUFDLEtBQUs7Z0JBQ1AsQ0FBQyxDQUFDLEtBQUssQ0FBQyxPQUFPLENBQUMsS0FBSyxDQUFDO29CQUNwQixDQUFDLENBQUMsS0FBSyxDQUFDLElBQUksQ0FBQyxJQUFJLENBQUM7b0JBQ2xCLENBQUMsQ0FBQyxLQUFLLENBQUMsSUFBSSxFQUNoQixPQUFPLEtBQUssQ0FDYixDQUFDO0lBQ04sQ0FBQztDQUNGLENBQUE7QUFqQ1ksYUFBYTtJQUR6QixTQUFTLENBQUMsY0FBYyxDQUFDLElBQUksQ0FBQzs7R0FDbEIsYUFBYSxDQWlDekI7O0FBRUQsVUFBVSxDQUFDLFFBQVEsQ0FBQztJQUNsQixTQUFTLEVBQUUsYUFBYTtJQUN4QixhQUFhLEVBQUUsU0FBUyxDQUFDLElBQUk7SUFDN0IsSUFBSSxFQUFFLEtBQUs7Q0FDVyxDQUFDLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgeyBWYWxpZGF0b3IgfSBmcm9tIFwiLi9WYWxpZGF0b3JcIjtcbmltcG9ydCB7IERFRkFVTFRfRVJST1JfTUVTU0FHRVMsIFZhbGlkYXRpb25LZXlzIH0gZnJvbSBcIi4vY29uc3RhbnRzXCI7XG5pbXBvcnQgeyB2YWxpZGF0b3IgfSBmcm9tIFwiLi9kZWNvcmF0b3JzXCI7XG5pbXBvcnQgeyBWYWxpZGF0aW9uIH0gZnJvbSBcIi4uL1ZhbGlkYXRpb25cIjtcbmltcG9ydCB7IFR5cGVWYWxpZGF0b3JPcHRpb25zLCBWYWxpZGF0b3JEZWZpbml0aW9uIH0gZnJvbSBcIi4uL3R5cGVzXCI7XG5pbXBvcnQgeyBNb2RlbEtleXMgfSBmcm9tIFwiLi4vLi4vdXRpbHMvY29uc3RhbnRzXCI7XG5pbXBvcnQgeyBSZWZsZWN0aW9uIH0gZnJvbSBcIkBkZWNhZi10cy9yZWZsZWN0aW9uXCI7XG5cbi8qKlxuICogQHN1bW1hcnkgUmVxdWlyZWQgVmFsaWRhdG9yXG4gKlxuICogQGNsYXNzIFJlcXVpcmVkVmFsaWRhdG9yXG4gKiBAZXh0ZW5kcyBWYWxpZGF0b3JcbiAqXG4gKiBAY2F0ZWdvcnkgVmFsaWRhdG9yc1xuICovXG5AdmFsaWRhdG9yKFZhbGlkYXRpb25LZXlzLlRZUEUpXG5leHBvcnQgY2xhc3MgVHlwZVZhbGlkYXRvciBleHRlbmRzIFZhbGlkYXRvcjxUeXBlVmFsaWRhdG9yT3B0aW9ucz4ge1xuICBjb25zdHJ1Y3RvcihtZXNzYWdlOiBzdHJpbmcgPSBERUZBVUxUX0VSUk9SX01FU1NBR0VTLlRZUEUpIHtcbiAgICBzdXBlcihtZXNzYWdlKTtcbiAgfVxuXG4gIC8qKlxuICAgKiBAc3VtbWFyeSBWYWxpZGF0ZXMgYSBtb2RlbFxuICAgKiBAcGFyYW0ge3N0cmluZ30gdmFsdWVcbiAgICogQHBhcmFtIHtUeXBlVmFsaWRhdG9yT3B0aW9uc30gb3B0aW9uc1xuICAgKlxuICAgKiBAcmV0dXJuIHtzdHJpbmcgfCB1bmRlZmluZWR9XG4gICAqXG4gICAqIEBvdmVycmlkZVxuICAgKlxuICAgKiBAc2VlIFZhbGlkYXRvciNoYXNFcnJvcnNcbiAgICovXG4gIHB1YmxpYyBoYXNFcnJvcnMoXG4gICAgdmFsdWU6IGFueSxcbiAgICBvcHRpb25zOiBUeXBlVmFsaWRhdG9yT3B0aW9uc1xuICApOiBzdHJpbmcgfCB1bmRlZmluZWQge1xuICAgIGlmICh2YWx1ZSA9PT0gdW5kZWZpbmVkKSByZXR1cm47IC8vIERvbid0IHRyeSBhbmQgZW5mb3JjZSB0eXBlIGlmIHVuZGVmaW5lZFxuICAgIGNvbnN0IHsgdHlwZXMsIG1lc3NhZ2UgfSA9IG9wdGlvbnM7XG4gICAgaWYgKCFSZWZsZWN0aW9uLmV2YWx1YXRlRGVzaWduVHlwZXModmFsdWUsIHR5cGVzKSlcbiAgICAgIHJldHVybiB0aGlzLmdldE1lc3NhZ2UoXG4gICAgICAgIG1lc3NhZ2UgfHwgdGhpcy5tZXNzYWdlLFxuICAgICAgICB0eXBlb2YgdHlwZXMgPT09IFwic3RyaW5nXCJcbiAgICAgICAgICA/IHR5cGVzXG4gICAgICAgICAgOiBBcnJheS5pc0FycmF5KHR5cGVzKVxuICAgICAgICAgICAgPyB0eXBlcy5qb2luKFwiLCBcIilcbiAgICAgICAgICAgIDogdHlwZXMubmFtZSxcbiAgICAgICAgdHlwZW9mIHZhbHVlXG4gICAgICApO1xuICB9XG59XG5cblZhbGlkYXRpb24ucmVnaXN0ZXIoe1xuICB2YWxpZGF0b3I6IFR5cGVWYWxpZGF0b3IsXG4gIHZhbGlkYXRpb25LZXk6IE1vZGVsS2V5cy5UWVBFLFxuICBzYXZlOiBmYWxzZSxcbn0gYXMgVmFsaWRhdG9yRGVmaW5pdGlvbik7XG4iXX0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiVHlwZVZhbGlkYXRvci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uLy4uL3NyYy92YWxpZGF0aW9uL1ZhbGlkYXRvcnMvVHlwZVZhbGlkYXRvci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7Ozs7Ozs7QUFBQSxPQUFPLEVBQUUsU0FBUyxFQUFFLE1BQU0sYUFBYSxDQUFDO0FBQ3hDLE9BQU8sRUFBRSxzQkFBc0IsRUFBRSxjQUFjLEVBQUUsTUFBTSxhQUFhLENBQUM7QUFDckUsT0FBTyxFQUFFLFNBQVMsRUFBRSxNQUFNLGNBQWMsQ0FBQztBQUN6QyxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sZUFBZSxDQUFDO0FBRTNDLE9BQU8sRUFBRSxTQUFTLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUNsRCxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFFbEQ7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQXlERztBQUVJLElBQU0sYUFBYSxHQUFuQixNQUFNLGFBQWMsU0FBUSxTQUErQjtJQUNoRSxZQUFZLFVBQWtCLHNCQUFzQixDQUFDLElBQUk7UUFDdkQsS0FBSyxDQUFDLE9BQU8sQ0FBQyxDQUFDO0lBQ2pCLENBQUM7SUFFRDs7Ozs7Ozs7Ozs7Ozs7T0FjRztJQUNJLFNBQVMsQ0FDZCxLQUFVLEVBQ1YsT0FBNkI7UUFFN0IsSUFBSSxLQUFLLEtBQUssU0FBUztZQUFFLE9BQU8sQ0FBQywwQ0FBMEM7UUFDM0UsTUFBTSxFQUFFLEtBQUssRUFBRSxPQUFPLEVBQUUsR0FBRyxPQUFPLENBQUM7UUFDbkMsSUFBSSxDQUFDLFVBQVUsQ0FBQyxtQkFBbUIsQ0FBQyxLQUFLLEVBQUUsS0FBSyxDQUFDO1lBQy9DLE9BQU8sSUFBSSxDQUFDLFVBQVUsQ0FDcEIsT0FBTyxJQUFJLElBQUksQ0FBQyxPQUFPLEVBQ3ZCLE9BQU8sS0FBSyxLQUFLLFFBQVE7Z0JBQ3ZCLENBQUMsQ0FBQyxLQUFLO2dCQUNQLENBQUMsQ0FBQyxLQUFLLENBQUMsT0FBTyxDQUFDLEtBQUssQ0FBQztvQkFDcEIsQ0FBQyxDQUFDLEtBQUssQ0FBQyxJQUFJLENBQUMsSUFBSSxDQUFDO29CQUNsQixDQUFDLENBQUMsS0FBSyxDQUFDLElBQUksRUFDaEIsT0FBTyxLQUFLLENBQ2IsQ0FBQztJQUNOLENBQUM7Q0FDRixDQUFBO0FBckNZLGFBQWE7SUFEekIsU0FBUyxDQUFDLGNBQWMsQ0FBQyxJQUFJLENBQUM7O0dBQ2xCLGFBQWEsQ0FxQ3pCOztBQUVEOzs7Ozs7O0dBT0c7QUFDSCxVQUFVLENBQUMsUUFBUSxDQUFDO0lBQ2xCLFNBQVMsRUFBRSxhQUFhO0lBQ3hCLGFBQWEsRUFBRSxTQUFTLENBQUMsSUFBSTtJQUM3QixJQUFJLEVBQUUsS0FBSztDQUNXLENBQUMsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbImltcG9ydCB7IFZhbGlkYXRvciB9IGZyb20gXCIuL1ZhbGlkYXRvclwiO1xuaW1wb3J0IHsgREVGQVVMVF9FUlJPUl9NRVNTQUdFUywgVmFsaWRhdGlvbktleXMgfSBmcm9tIFwiLi9jb25zdGFudHNcIjtcbmltcG9ydCB7IHZhbGlkYXRvciB9IGZyb20gXCIuL2RlY29yYXRvcnNcIjtcbmltcG9ydCB7IFZhbGlkYXRpb24gfSBmcm9tIFwiLi4vVmFsaWRhdGlvblwiO1xuaW1wb3J0IHsgVHlwZVZhbGlkYXRvck9wdGlvbnMsIFZhbGlkYXRvckRlZmluaXRpb24gfSBmcm9tIFwiLi4vdHlwZXNcIjtcbmltcG9ydCB7IE1vZGVsS2V5cyB9IGZyb20gXCIuLi8uLi91dGlscy9jb25zdGFudHNcIjtcbmltcG9ydCB7IFJlZmxlY3Rpb24gfSBmcm9tIFwiQGRlY2FmLXRzL3JlZmxlY3Rpb25cIjtcblxuLyoqXG4gKiBAZGVzY3JpcHRpb24gVmFsaWRhdG9yIGZvciBjaGVja2luZyBpZiBhIHZhbHVlIGlzIG9mIHRoZSBleHBlY3RlZCB0eXBlKHMpXG4gKiBAc3VtbWFyeSBUaGUgVHlwZVZhbGlkYXRvciBlbnN1cmVzIHRoYXQgYSB2YWx1ZSBtYXRjaGVzIG9uZSBvZiB0aGUgc3BlY2lmaWVkIHR5cGVzLlxuICogSXQgY2FuIHZhbGlkYXRlIGFnYWluc3QgYSBzaW5nbGUgdHlwZSwgbXVsdGlwbGUgdHlwZXMsIG9yIGEgdHlwZSB3aXRoIGEgc3BlY2lmaWMgbmFtZS5cbiAqIFRoaXMgdmFsaWRhdG9yIGlzIHR5cGljYWxseSB1c2VkIHdpdGggdGhlIEB0eXBlIGRlY29yYXRvciBhbmQgaXMgZnVuZGFtZW50YWwgZm9yXG4gKiBlbnN1cmluZyB0eXBlIHNhZmV0eSBpbiB2YWxpZGF0ZWQgbW9kZWxzLlxuICpcbiAqIEBwYXJhbSB7c3RyaW5nfSBbbWVzc2FnZV0gLSBDdXN0b20gZXJyb3IgbWVzc2FnZSB0byBkaXNwbGF5IHdoZW4gdmFsaWRhdGlvbiBmYWlscywgZGVmYXVsdHMgdG8ge0BsaW5rIERFRkFVTFRfRVJST1JfTUVTU0FHRVMjVFlQRX1cbiAqXG4gKiBAY2xhc3MgVHlwZVZhbGlkYXRvclxuICogQGV4dGVuZHMgVmFsaWRhdG9yXG4gKlxuICogQGV4YW1wbGVcbiAqIGBgYHR5cGVzY3JpcHRcbiAqIC8vIENyZWF0ZSBhIHR5cGUgdmFsaWRhdG9yIHdpdGggZGVmYXVsdCBlcnJvciBtZXNzYWdlXG4gKiBjb25zdCB0eXBlVmFsaWRhdG9yID0gbmV3IFR5cGVWYWxpZGF0b3IoKTtcbiAqXG4gKiAvLyBDcmVhdGUgYSB0eXBlIHZhbGlkYXRvciB3aXRoIGN1c3RvbSBlcnJvciBtZXNzYWdlXG4gKiBjb25zdCBjdXN0b21UeXBlVmFsaWRhdG9yID0gbmV3IFR5cGVWYWxpZGF0b3IoXCJWYWx1ZSBtdXN0IGJlIG9mIHR5cGUgezB9LCBidXQgZ290IHsxfVwiKTtcbiAqXG4gKiAvLyBWYWxpZGF0ZSBhZ2FpbnN0IGEgc2luZ2xlIHR5cGVcbiAqIGNvbnN0IHN0cmluZ09wdGlvbnMgPSB7IHR5cGVzOiBcInN0cmluZ1wiIH07XG4gKiB0eXBlVmFsaWRhdG9yLmhhc0Vycm9ycyhcImhlbGxvXCIsIHN0cmluZ09wdGlvbnMpOyAvLyB1bmRlZmluZWQgKHZhbGlkKVxuICogdHlwZVZhbGlkYXRvci5oYXNFcnJvcnMoMTIzLCBzdHJpbmdPcHRpb25zKTsgLy8gUmV0dXJucyBlcnJvciBtZXNzYWdlIChpbnZhbGlkKVxuICpcbiAqIC8vIFZhbGlkYXRlIGFnYWluc3QgbXVsdGlwbGUgdHlwZXNcbiAqIGNvbnN0IG11bHRpT3B0aW9ucyA9IHsgdHlwZXM6IFtcInN0cmluZ1wiLCBcIm51bWJlclwiXSB9O1xuICogdHlwZVZhbGlkYXRvci5oYXNFcnJvcnMoXCJoZWxsb1wiLCBtdWx0aU9wdGlvbnMpOyAvLyB1bmRlZmluZWQgKHZhbGlkKVxuICogdHlwZVZhbGlkYXRvci5oYXNFcnJvcnMoMTIzLCBtdWx0aU9wdGlvbnMpOyAvLyB1bmRlZmluZWQgKHZhbGlkKVxuICogdHlwZVZhbGlkYXRvci5oYXNFcnJvcnModHJ1ZSwgbXVsdGlPcHRpb25zKTsgLy8gUmV0dXJucyBlcnJvciBtZXNzYWdlIChpbnZhbGlkKVxuICpcbiAqIC8vIFZhbGlkYXRlIGFnYWluc3QgYSBjbGFzcyB0eXBlXG4gKiBjb25zdCBjbGFzc09wdGlvbnMgPSB7IHR5cGVzOiB7IG5hbWU6IFwiRGF0ZVwiIH0gfTtcbiAqIHR5cGVWYWxpZGF0b3IuaGFzRXJyb3JzKG5ldyBEYXRlKCksIGNsYXNzT3B0aW9ucyk7IC8vIHVuZGVmaW5lZCAodmFsaWQpXG4gKiBgYGBcbiAqXG4gKiBAbWVybWFpZFxuICogc2VxdWVuY2VEaWFncmFtXG4gKiAgIHBhcnRpY2lwYW50IEMgYXMgQ2xpZW50XG4gKiAgIHBhcnRpY2lwYW50IFYgYXMgVHlwZVZhbGlkYXRvclxuICogICBwYXJ0aWNpcGFudCBSIGFzIFJlZmxlY3Rpb25cbiAqXG4gKiAgIEMtPj5WOiBuZXcgVHlwZVZhbGlkYXRvcihtZXNzYWdlKVxuICogICBDLT4+VjogaGFzRXJyb3JzKHZhbHVlLCBvcHRpb25zKVxuICogICBhbHQgdmFsdWUgaXMgdW5kZWZpbmVkXG4gKiAgICAgVi0tPj5DOiB1bmRlZmluZWQgKHZhbGlkKVxuICogICBlbHNlIHZhbHVlIGlzIGRlZmluZWRcbiAqICAgICBWLT4+UjogZXZhbHVhdGVEZXNpZ25UeXBlcyh2YWx1ZSwgdHlwZXMpXG4gKiAgICAgYWx0IHR5cGUgZXZhbHVhdGlvbiBwYXNzZXNcbiAqICAgICAgIFYtLT4+QzogdW5kZWZpbmVkICh2YWxpZClcbiAqICAgICBlbHNlIHR5cGUgZXZhbHVhdGlvbiBmYWlsc1xuICogICAgICAgVi0+PlY6IEZvcm1hdCBlcnJvciBtZXNzYWdlIHdpdGggdHlwZSBpbmZvXG4gKiAgICAgICBWLS0+PkM6IEVycm9yIG1lc3NhZ2VcbiAqICAgICBlbmRcbiAqICAgZW5kXG4gKlxuICogQGNhdGVnb3J5IFZhbGlkYXRvcnNcbiAqL1xuQHZhbGlkYXRvcihWYWxpZGF0aW9uS2V5cy5UWVBFKVxuZXhwb3J0IGNsYXNzIFR5cGVWYWxpZGF0b3IgZXh0ZW5kcyBWYWxpZGF0b3I8VHlwZVZhbGlkYXRvck9wdGlvbnM+IHtcbiAgY29uc3RydWN0b3IobWVzc2FnZTogc3RyaW5nID0gREVGQVVMVF9FUlJPUl9NRVNTQUdFUy5UWVBFKSB7XG4gICAgc3VwZXIobWVzc2FnZSk7XG4gIH1cblxuICAvKipcbiAgICogQGRlc2NyaXB0aW9uIENoZWNrcyBpZiBhIHZhbHVlIGlzIG9mIHRoZSBleHBlY3RlZCB0eXBlKHMpXG4gICAqIEBzdW1tYXJ5IFZhbGlkYXRlcyB0aGF0IHRoZSBwcm92aWRlZCB2YWx1ZSBtYXRjaGVzIG9uZSBvZiB0aGUgc3BlY2lmaWVkIHR5cGVzLlxuICAgKiBJdCB1c2VzIHRoZSBSZWZsZWN0aW9uIHV0aWxpdHkgdG8gZXZhbHVhdGUgaWYgdGhlIHZhbHVlJ3MgdHlwZSBtYXRjaGVzIHRoZSBleHBlY3RlZCB0eXBlcy5cbiAgICogVGhlIG1ldGhvZCBza2lwcyB2YWxpZGF0aW9uIGZvciB1bmRlZmluZWQgdmFsdWVzIHRvIGF2b2lkIGNvbmZsaWN0cyB3aXRoIHRoZSBSZXF1aXJlZFZhbGlkYXRvci5cbiAgICpcbiAgICogQHBhcmFtIHthbnl9IHZhbHVlIC0gVGhlIHZhbHVlIHRvIHZhbGlkYXRlXG4gICAqIEBwYXJhbSB7VHlwZVZhbGlkYXRvck9wdGlvbnN9IG9wdGlvbnMgLSBDb25maWd1cmF0aW9uIG9wdGlvbnMgY29udGFpbmluZyB0aGUgZXhwZWN0ZWQgdHlwZXNcbiAgICpcbiAgICogQHJldHVybiB7c3RyaW5nIHwgdW5kZWZpbmVkfSBFcnJvciBtZXNzYWdlIGlmIHZhbGlkYXRpb24gZmFpbHMsIHVuZGVmaW5lZCBpZiB2YWxpZGF0aW9uIHBhc3Nlc1xuICAgKlxuICAgKiBAb3ZlcnJpZGVcbiAgICpcbiAgICogQHNlZSBWYWxpZGF0b3IjaGFzRXJyb3JzXG4gICAqL1xuICBwdWJsaWMgaGFzRXJyb3JzKFxuICAgIHZhbHVlOiBhbnksXG4gICAgb3B0aW9uczogVHlwZVZhbGlkYXRvck9wdGlvbnNcbiAgKTogc3RyaW5nIHwgdW5kZWZpbmVkIHtcbiAgICBpZiAodmFsdWUgPT09IHVuZGVmaW5lZCkgcmV0dXJuOyAvLyBEb24ndCB0cnkgYW5kIGVuZm9yY2UgdHlwZSBpZiB1bmRlZmluZWRcbiAgICBjb25zdCB7IHR5cGVzLCBtZXNzYWdlIH0gPSBvcHRpb25zO1xuICAgIGlmICghUmVmbGVjdGlvbi5ldmFsdWF0ZURlc2lnblR5cGVzKHZhbHVlLCB0eXBlcykpXG4gICAgICByZXR1cm4gdGhpcy5nZXRNZXNzYWdlKFxuICAgICAgICBtZXNzYWdlIHx8IHRoaXMubWVzc2FnZSxcbiAgICAgICAgdHlwZW9mIHR5cGVzID09PSBcInN0cmluZ1wiXG4gICAgICAgICAgPyB0eXBlc1xuICAgICAgICAgIDogQXJyYXkuaXNBcnJheSh0eXBlcylcbiAgICAgICAgICAgID8gdHlwZXMuam9pbihcIiwgXCIpXG4gICAgICAgICAgICA6IHR5cGVzLm5hbWUsXG4gICAgICAgIHR5cGVvZiB2YWx1ZVxuICAgICAgKTtcbiAgfVxufVxuXG4vKipcbiAqIEBkZXNjcmlwdGlvbiBSZWdpc3RlciB0aGUgVHlwZVZhbGlkYXRvciB3aXRoIHRoZSBWYWxpZGF0aW9uIHJlZ2lzdHJ5XG4gKiBAc3VtbWFyeSBUaGlzIHJlZ2lzdHJhdGlvbiBhc3NvY2lhdGVzIHRoZSBUeXBlVmFsaWRhdG9yIHdpdGggdGhlIE1vZGVsS2V5cy5UWVBFIGtleSxcbiAqIGFsbG93aW5nIGl0IHRvIGJlIHVzZWQgZm9yIHZhbGlkYXRpbmcgZGVzaWduIHR5cGVzLiBUaGUgc2F2ZSBmbGFnIGlzIHNldCB0byBmYWxzZVxuICogdG8gcHJldmVudCB0aGUgdmFsaWRhdG9yIGZyb20gYmVpbmcgc2F2ZWQgaW4gdGhlIHN0YW5kYXJkIHZhbGlkYXRvciByZWdpc3RyeS5cbiAqXG4gKiBAbWVtYmVyT2YgbW9kdWxlOmRlY29yYXRvci12YWxpZGF0aW9uXG4gKi9cblZhbGlkYXRpb24ucmVnaXN0ZXIoe1xuICB2YWxpZGF0b3I6IFR5cGVWYWxpZGF0b3IsXG4gIHZhbGlkYXRpb25LZXk6IE1vZGVsS2V5cy5UWVBFLFxuICBzYXZlOiBmYWxzZSxcbn0gYXMgVmFsaWRhdG9yRGVmaW5pdGlvbik7XG4iXX0=

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

@@ -1,27 +1,61 @@
 import { PatternValidator } from "./PatternValidator";
 import { PatternValidatorOptions } from "../types";
 /**
- * @summary URL Validator
- * @description Pattern from {@link https://gist.github.com/dperini/729294}
+ * @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);
     /**
-     * @summary Validates a model
+     * @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
-     * @param {PatternValidatorOptions} [options={}]
+     * @param {string} value - The string to validate as a URL
+     * @param {PatternValidatorOptions} [options={}] - Optional configuration options
      *
-     * @return {string | undefined}
+     * @return {string | undefined} Error message if validation fails, undefined if validation passes
      *
      * @override
      *
-     * @see Validator#hasErrors
+     * @see PatternValidator#hasErrors
      */
     hasErrors(value: string, options?: PatternValidatorOptions): string | undefined;
 }

package/lib/esm/validation/Validators/URLValidator.js

@@ -11,12 +11,43 @@ import { ValidationKeys, DEFAULT_ERROR_MESSAGES, DEFAULT_PATTERNS, } from "./con
 import { PatternValidator } from "./PatternValidator";
 import { validator } from "./decorators";
 /**
- * @summary URL Validator
- * @description Pattern from {@link https://gist.github.com/dperini/729294}
+ * @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
  */
 let URLValidator = class URLValidator extends PatternValidator {
@@ -24,16 +55,19 @@ let URLValidator = class URLValidator extends PatternValidator {
         super(message);
     }
     /**
-     * @summary Validates a model
+     * @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
-     * @param {PatternValidatorOptions} [options={}]
+     * @param {string} value - The string to validate as a URL
+     * @param {PatternValidatorOptions} [options={}] - Optional configuration options
      *
-     * @return {string | undefined}
+     * @return {string | undefined} Error message if validation fails, undefined if validation passes
      *
      * @override
      *
-     * @see Validator#hasErrors
+     * @see PatternValidator#hasErrors
      */
     hasErrors(value, options = {}) {
         return super.hasErrors(value, {
@@ -47,4 +81,4 @@ URLValidator = __decorate([
     __metadata("design:paramtypes", [String])
 ], URLValidator);
 export { URLValidator };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiVVJMVmFsaWRhdG9yLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vLi4vc3JjL3ZhbGlkYXRpb24vVmFsaWRhdG9ycy9VUkxWYWxpZGF0b3IudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7O0FBQUEsT0FBTyxFQUNMLGNBQWMsRUFDZCxzQkFBc0IsRUFDdEIsZ0JBQWdCLEdBQ2pCLE1BQU0sYUFBYSxDQUFDO0FBQ3JCLE9BQU8sRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLG9CQUFvQixDQUFDO0FBQ3RELE9BQU8sRUFBRSxTQUFTLEVBQUUsTUFBTSxjQUFjLENBQUM7QUFHekM7Ozs7Ozs7O0dBUUc7QUFFSSxJQUFNLFlBQVksR0FBbEIsTUFBTSxZQUFhLFNBQVEsZ0JBQWdCO0lBQ2hELFlBQVksVUFBa0Isc0JBQXNCLENBQUMsR0FBRztRQUN0RCxLQUFLLENBQUMsT0FBTyxDQUFDLENBQUM7SUFDakIsQ0FBQztJQUVEOzs7Ozs7Ozs7OztPQVdHO0lBQ0ksU0FBUyxDQUNkLEtBQWEsRUFDYixVQUFtQyxFQUFFO1FBRXJDLE9BQU8sS0FBSyxDQUFDLFNBQVMsQ0FBQyxLQUFLLEVBQUU7WUFDNUIsR0FBRyxPQUFPO1lBQ1YsT0FBTyxFQUFFLE9BQU8sQ0FBQyxPQUFPLElBQUksZ0JBQWdCLENBQUMsR0FBRztTQUNqRCxDQUFDLENBQUM7SUFDTCxDQUFDO0NBQ0YsQ0FBQTtBQTFCWSxZQUFZO0lBRHhCLFNBQVMsQ0FBQyxjQUFjLENBQUMsR0FBRyxDQUFDOztHQUNqQixZQUFZLENBMEJ4QiIsInNvdXJjZXNDb250ZW50IjpbImltcG9ydCB7XG4gIFZhbGlkYXRpb25LZXlzLFxuICBERUZBVUxUX0VSUk9SX01FU1NBR0VTLFxuICBERUZBVUxUX1BBVFRFUk5TLFxufSBmcm9tIFwiLi9jb25zdGFudHNcIjtcbmltcG9ydCB7IFBhdHRlcm5WYWxpZGF0b3IgfSBmcm9tIFwiLi9QYXR0ZXJuVmFsaWRhdG9yXCI7XG5pbXBvcnQgeyB2YWxpZGF0b3IgfSBmcm9tIFwiLi9kZWNvcmF0b3JzXCI7XG5pbXBvcnQgeyBQYXR0ZXJuVmFsaWRhdG9yT3B0aW9ucyB9IGZyb20gXCIuLi90eXBlc1wiO1xuXG4vKipcbiAqIEBzdW1tYXJ5IFVSTCBWYWxpZGF0b3JcbiAqIEBkZXNjcmlwdGlvbiBQYXR0ZXJuIGZyb20ge0BsaW5rIGh0dHBzOi8vZ2lzdC5naXRodWIuY29tL2RwZXJpbmkvNzI5Mjk0fVxuICpcbiAqIEBjbGFzcyBVUkxWYWxpZGF0b3JcbiAqIEBleHRlbmRzIFBhdHRlcm5WYWxpZGF0b3JcbiAqXG4gKiBAY2F0ZWdvcnkgVmFsaWRhdG9yc1xuICovXG5AdmFsaWRhdG9yKFZhbGlkYXRpb25LZXlzLlVSTClcbmV4cG9ydCBjbGFzcyBVUkxWYWxpZGF0b3IgZXh0ZW5kcyBQYXR0ZXJuVmFsaWRhdG9yIHtcbiAgY29uc3RydWN0b3IobWVzc2FnZTogc3RyaW5nID0gREVGQVVMVF9FUlJPUl9NRVNTQUdFUy5VUkwpIHtcbiAgICBzdXBlcihtZXNzYWdlKTtcbiAgfVxuXG4gIC8qKlxuICAgKiBAc3VtbWFyeSBWYWxpZGF0ZXMgYSBtb2RlbFxuICAgKlxuICAgKiBAcGFyYW0ge3N0cmluZ30gdmFsdWVcbiAgICogQHBhcmFtIHtQYXR0ZXJuVmFsaWRhdG9yT3B0aW9uc30gW29wdGlvbnM9e31dXG4gICAqXG4gICAqIEByZXR1cm4ge3N0cmluZyB8IHVuZGVmaW5lZH1cbiAgICpcbiAgICogQG92ZXJyaWRlXG4gICAqXG4gICAqIEBzZWUgVmFsaWRhdG9yI2hhc0Vycm9yc1xuICAgKi9cbiAgcHVibGljIGhhc0Vycm9ycyhcbiAgICB2YWx1ZTogc3RyaW5nLFxuICAgIG9wdGlvbnM6IFBhdHRlcm5WYWxpZGF0b3JPcHRpb25zID0ge31cbiAgKTogc3RyaW5nIHwgdW5kZWZpbmVkIHtcbiAgICByZXR1cm4gc3VwZXIuaGFzRXJyb3JzKHZhbHVlLCB7XG4gICAgICAuLi5vcHRpb25zLFxuICAgICAgcGF0dGVybjogb3B0aW9ucy5wYXR0ZXJuIHx8IERFRkFVTFRfUEFUVEVSTlMuVVJMLFxuICAgIH0pO1xuICB9XG59XG4iXX0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiVVJMVmFsaWRhdG9yLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vLi4vc3JjL3ZhbGlkYXRpb24vVmFsaWRhdG9ycy9VUkxWYWxpZGF0b3IudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7O0FBQUEsT0FBTyxFQUNMLGNBQWMsRUFDZCxzQkFBc0IsRUFDdEIsZ0JBQWdCLEdBQ2pCLE1BQU0sYUFBYSxDQUFDO0FBQ3JCLE9BQU8sRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLG9CQUFvQixDQUFDO0FBQ3RELE9BQU8sRUFBRSxTQUFTLEVBQUUsTUFBTSxjQUFjLENBQUM7QUFHekM7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQXVDRztBQUVJLElBQU0sWUFBWSxHQUFsQixNQUFNLFlBQWEsU0FBUSxnQkFBZ0I7SUFDaEQsWUFBWSxVQUFrQixzQkFBc0IsQ0FBQyxHQUFHO1FBQ3RELEtBQUssQ0FBQyxPQUFPLENBQUMsQ0FBQztJQUNqQixDQUFDO0lBRUQ7Ozs7Ozs7Ozs7Ozs7O09BY0c7SUFDSSxTQUFTLENBQ2QsS0FBYSxFQUNiLFVBQW1DLEVBQUU7UUFFckMsT0FBTyxLQUFLLENBQUMsU0FBUyxDQUFDLEtBQUssRUFBRTtZQUM1QixHQUFHLE9BQU87WUFDVixPQUFPLEVBQUUsT0FBTyxDQUFDLE9BQU8sSUFBSSxnQkFBZ0IsQ0FBQyxHQUFHO1NBQ2pELENBQUMsQ0FBQztJQUNMLENBQUM7Q0FDRixDQUFBO0FBN0JZLFlBQVk7SUFEeEIsU0FBUyxDQUFDLGNBQWMsQ0FBQyxHQUFHLENBQUM7O0dBQ2pCLFlBQVksQ0E2QnhCIiwic291cmNlc0NvbnRlbnQiOlsiaW1wb3J0IHtcbiAgVmFsaWRhdGlvbktleXMsXG4gIERFRkFVTFRfRVJST1JfTUVTU0FHRVMsXG4gIERFRkFVTFRfUEFUVEVSTlMsXG59IGZyb20gXCIuL2NvbnN0YW50c1wiO1xuaW1wb3J0IHsgUGF0dGVyblZhbGlkYXRvciB9IGZyb20gXCIuL1BhdHRlcm5WYWxpZGF0b3JcIjtcbmltcG9ydCB7IHZhbGlkYXRvciB9IGZyb20gXCIuL2RlY29yYXRvcnNcIjtcbmltcG9ydCB7IFBhdHRlcm5WYWxpZGF0b3JPcHRpb25zIH0gZnJvbSBcIi4uL3R5cGVzXCI7XG5cbi8qKlxuICogQGRlc2NyaXB0aW9uIFZhbGlkYXRvciBmb3IgY2hlY2tpbmcgaWYgYSBzdHJpbmcgaXMgYSB2YWxpZCBVUkxcbiAqIEBzdW1tYXJ5IFRoZSBVUkxWYWxpZGF0b3IgY2hlY2tzIGlmIGEgc3RyaW5nIG1hdGNoZXMgYSBzdGFuZGFyZCBVUkwgcGF0dGVybi5cbiAqIEl0IGV4dGVuZHMgdGhlIFBhdHRlcm5WYWxpZGF0b3IgYW5kIHVzZXMgYSByb2J1c3QgVVJMIHJlZ2V4IHBhdHRlcm4gdG8gdmFsaWRhdGUgd2ViIGFkZHJlc3Nlcy5cbiAqIFRoZSBwYXR0ZXJuIGlzIHNvdXJjZWQgZnJvbSB7QGxpbmsgaHR0cHM6Ly9naXN0LmdpdGh1Yi5jb20vZHBlcmluaS83MjkyOTR9IGFuZCBpcyB3aWRlbHlcbiAqIHJlY29nbml6ZWQgZm9yIGl0cyBhY2N1cmFjeSBpbiB2YWxpZGF0aW5nIFVSTHMuIFRoaXMgdmFsaWRhdG9yIGlzIHR5cGljYWxseSB1c2VkIHdpdGggdGhlIEB1cmwgZGVjb3JhdG9yLlxuICogXG4gKiBAcGFyYW0ge3N0cmluZ30gW21lc3NhZ2VdIC0gQ3VzdG9tIGVycm9yIG1lc3NhZ2UgdG8gZGlzcGxheSB3aGVuIHZhbGlkYXRpb24gZmFpbHMsIGRlZmF1bHRzIHRvIHtAbGluayBERUZBVUxUX0VSUk9SX01FU1NBR0VTI1VSTH1cbiAqIFxuICogQGNsYXNzIFVSTFZhbGlkYXRvclxuICogQGV4dGVuZHMgUGF0dGVyblZhbGlkYXRvclxuICogXG4gKiBAZXhhbXBsZVxuICogYGBgdHlwZXNjcmlwdFxuICogLy8gQ3JlYXRlIGEgVVJMIHZhbGlkYXRvciB3aXRoIGRlZmF1bHQgZXJyb3IgbWVzc2FnZVxuICogY29uc3QgdXJsVmFsaWRhdG9yID0gbmV3IFVSTFZhbGlkYXRvcigpO1xuICogXG4gKiAvLyBDcmVhdGUgYSBVUkwgdmFsaWRhdG9yIHdpdGggY3VzdG9tIGVycm9yIG1lc3NhZ2VcbiAqIGNvbnN0IGN1c3RvbVVybFZhbGlkYXRvciA9IG5ldyBVUkxWYWxpZGF0b3IoXCJQbGVhc2UgZW50ZXIgYSB2YWxpZCB3ZWIgYWRkcmVzc1wiKTtcbiAqIFxuICogLy8gVmFsaWRhdGUgYSBVUkxcbiAqIGNvbnN0IHJlc3VsdCA9IHVybFZhbGlkYXRvci5oYXNFcnJvcnMoXCJodHRwczovL2V4YW1wbGUuY29tXCIpOyAvLyB1bmRlZmluZWQgKHZhbGlkKVxuICogY29uc3QgaW52YWxpZFJlc3VsdCA9IHVybFZhbGlkYXRvci5oYXNFcnJvcnMoXCJub3QtYS11cmxcIik7IC8vIFJldHVybnMgZXJyb3IgbWVzc2FnZSAoaW52YWxpZClcbiAqIGBgYFxuICogXG4gKiBAbWVybWFpZFxuICogc2VxdWVuY2VEaWFncmFtXG4gKiAgIHBhcnRpY2lwYW50IEMgYXMgQ2xpZW50XG4gKiAgIHBhcnRpY2lwYW50IFUgYXMgVVJMVmFsaWRhdG9yXG4gKiAgIHBhcnRpY2lwYW50IFAgYXMgUGF0dGVyblZhbGlkYXRvclxuICogICBcbiAqICAgQy0+PlU6IG5ldyBVUkxWYWxpZGF0b3IobWVzc2FnZSlcbiAqICAgVS0+PlA6IHN1cGVyKG1lc3NhZ2UpXG4gKiAgIEMtPj5VOiBoYXNFcnJvcnModmFsdWUsIG9wdGlvbnMpXG4gKiAgIFUtPj5QOiBzdXBlci5oYXNFcnJvcnModmFsdWUsIG9wdGlvbnMgd2l0aCBVUkwgcGF0dGVybilcbiAqICAgUC0tPj5VOiB2YWxpZGF0aW9uIHJlc3VsdFxuICogICBVLS0+PkM6IHZhbGlkYXRpb24gcmVzdWx0XG4gKiBcbiAqIEBjYXRlZ29yeSBWYWxpZGF0b3JzXG4gKi9cbkB2YWxpZGF0b3IoVmFsaWRhdGlvbktleXMuVVJMKVxuZXhwb3J0IGNsYXNzIFVSTFZhbGlkYXRvciBleHRlbmRzIFBhdHRlcm5WYWxpZGF0b3Ige1xuICBjb25zdHJ1Y3RvcihtZXNzYWdlOiBzdHJpbmcgPSBERUZBVUxUX0VSUk9SX01FU1NBR0VTLlVSTCkge1xuICAgIHN1cGVyKG1lc3NhZ2UpO1xuICB9XG5cbiAgLyoqXG4gICAqIEBkZXNjcmlwdGlvbiBDaGVja3MgaWYgYSBzdHJpbmcgaXMgYSB2YWxpZCBVUkxcbiAgICogQHN1bW1hcnkgVmFsaWRhdGVzIHRoYXQgdGhlIHByb3ZpZGVkIHN0cmluZyBtYXRjaGVzIHRoZSBVUkwgcGF0dGVybi5cbiAgICogVGhpcyBtZXRob2QgZXh0ZW5kcyB0aGUgUGF0dGVyblZhbGlkYXRvcidzIGhhc0Vycm9ycyBtZXRob2QgYnkgZW5zdXJpbmdcbiAgICogdGhlIFVSTCBwYXR0ZXJuIGlzIHVzZWQsIGV2ZW4gaWYgbm90IGV4cGxpY2l0bHkgcHJvdmlkZWQgaW4gdGhlIG9wdGlvbnMuXG4gICAqXG4gICAqIEBwYXJhbSB7c3RyaW5nfSB2YWx1ZSAtIFRoZSBzdHJpbmcgdG8gdmFsaWRhdGUgYXMgYSBVUkxcbiAgICogQHBhcmFtIHtQYXR0ZXJuVmFsaWRhdG9yT3B0aW9uc30gW29wdGlvbnM9e31dIC0gT3B0aW9uYWwgY29uZmlndXJhdGlvbiBvcHRpb25zXG4gICAqXG4gICAqIEByZXR1cm4ge3N0cmluZyB8IHVuZGVmaW5lZH0gRXJyb3IgbWVzc2FnZSBpZiB2YWxpZGF0aW9uIGZhaWxzLCB1bmRlZmluZWQgaWYgdmFsaWRhdGlvbiBwYXNzZXNcbiAgICpcbiAgICogQG92ZXJyaWRlXG4gICAqXG4gICAqIEBzZWUgUGF0dGVyblZhbGlkYXRvciNoYXNFcnJvcnNcbiAgICovXG4gIHB1YmxpYyBoYXNFcnJvcnMoXG4gICAgdmFsdWU6IHN0cmluZyxcbiAgICBvcHRpb25zOiBQYXR0ZXJuVmFsaWRhdG9yT3B0aW9ucyA9IHt9XG4gICk6IHN0cmluZyB8IHVuZGVmaW5lZCB7XG4gICAgcmV0dXJuIHN1cGVyLmhhc0Vycm9ycyh2YWx1ZSwge1xuICAgICAgLi4ub3B0aW9ucyxcbiAgICAgIHBhdHRlcm46IG9wdGlvbnMucGF0dGVybiB8fCBERUZBVUxUX1BBVFRFUk5TLlVSTCxcbiAgICB9KTtcbiAgfVxufVxuIl19

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

@@ -1,14 +1,54 @@
 import { ValidatorOptions } from "../types";
 /**
- * @summary Base Implementation for Validators
- * @description Provides the underlying functionality for {@link Validator}s
+ * @description Abstract base class for all validators in the validation framework
+ * @summary The Validator class provides the foundation for all validator implementations.
+ * It handles type checking, error message formatting, and defines the common interface
+ * that all validators must implement. This class is designed to be extended by specific
+ * validator implementations that provide concrete validation logic.
  *
- * @param {string} validationKey the key to register the validator under
- * @param {string} [message] the error message. Defaults to {@link DEFAULT_ERROR_MESSAGES#DEFAULT}
- * @param {string[]} [acceptedTypes] defines the value types this validator can validate
+ * @param {string} message - Default error message to display when validation fails, defaults to {@link DEFAULT_ERROR_MESSAGES#DEFAULT}
+ * @param {string[]} acceptedTypes - Array of type names that this validator can validate
  *
  * @class Validator
  * @abstract
+ *
+ * @example
+ * ```typescript
+ * // Example of extending the Validator class to create a custom validator
+ * class CustomValidator extends Validator<CustomValidatorOptions> {
+ *   constructor(message: string = "Custom validation failed") {
+ *     // Specify that this validator accepts String and Number types
+ *     super(message, String.name, Number.name);
+ *   }
+ *
+ *   public hasErrors(value: any, options?: CustomValidatorOptions): string | undefined {
+ *     // Implement custom validation logic
+ *     if (someCondition) {
+ *       return this.getMessage(options?.message || this.message);
+ *     }
+ *     return undefined; // No errors
+ *   }
+ * }
+ * ```
+ *
+ * @mermaid
+ * sequenceDiagram
+ *   participant C as Client
+ *   participant V as Validator Subclass
+ *   participant B as Base Validator
+ *
+ *   C->>V: new CustomValidator(message)
+ *   V->>B: super(message, acceptedTypes)
+ *   B->>B: Store message and types
+ *   B->>B: 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 Validator<V extends ValidatorOptions = ValidatorOptions> {
@@ -16,26 +56,49 @@ export declare abstract class Validator<V extends ValidatorOptions = ValidatorOp
     readonly acceptedTypes?: string[];
     protected constructor(message?: string, ...acceptedTypes: string[]);
     /**
-     * @summary builds the error message
-     * @param {string} message
-     * @param {any[]} args
+     * @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;
     /**
-     * @summary Validates type
-     * @param {any} unbound
+     * @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;
     /**
-     * @summary Validates an attribute
-     * @param {any} value
-     * @param {ValidatorOptions} [options] Validate options for customizing the model validation behavior
+     * @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
+     *
+     * @return {string | undefined} Error message if validation fails, undefined if validation passes
      *
      * @abstract
      *
-     * @see Model#hasErrors
+     * @see Model#validate
      */
     abstract hasErrors(value: any, options?: V): string | undefined;
+    /**
+     * @summary Duck typing for Validators
+     * @param val
+     */
+    static isValidator(val: any): boolean;
 }