@jdsalasc/solvejs-validators 1.0.2 → 1.1.0

package/README.md

@@ -11,9 +11,19 @@ npm i @jdsalasc/solvejs-validators
 ## Example
 
 ```ts
-import { isCellphoneNumber, isAddressDirection, isValidName } from "@jdsalasc/solvejs-validators";
+import { isCellphoneNumber, validateCellphoneNumber, validateName } from "@jdsalasc/solvejs-validators";
 
 isCellphoneNumber("+573001112233");
-isAddressDirection("NORTH");
-isValidName("Maria Fernanda");
+validateCellphoneNumber("+573001112233", { country: "CO" });
+validateName("Maria Fernanda");
+```
+
+Structured validators return:
+
+```ts
+type ValidationResult = {
+  ok: boolean;
+  code: string;
+  message: string;
+};
 ```

package/dist/cjs/index.cjs

@@ -1,129 +1,293 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateCellphoneNumber = validateCellphoneNumber;
 exports.isCellphoneNumber = isCellphoneNumber;
+exports.validateAddressDirection = validateAddressDirection;
 exports.isAddressDirection = isAddressDirection;
+exports.validateName = validateName;
 exports.isValidName = isValidName;
+exports.validateEmail = validateEmail;
 exports.isEmail = isEmail;
+exports.validateHttpUrl = validateHttpUrl;
 exports.isHttpUrl = isHttpUrl;
+exports.validatePostalCode = validatePostalCode;
 exports.isPostalCode = isPostalCode;
+exports.validateStrongPassword = validateStrongPassword;
 exports.isStrongPassword = isStrongPassword;
-const ADDRESS_DIRECTIONS = new Set([
-    "N",
-    "S",
-    "E",
-    "W",
-    "NE",
-    "NW",
-    "SE",
-    "SW",
-    "NORTH",
-    "SOUTH",
-    "EAST",
-    "WEST",
-    "NORTHEAST",
-    "NORTHWEST",
-    "SOUTHEAST",
-    "SOUTHWEST"
-]);
+const ADDRESS_DIRECTIONS = {
+    en: new Set([
+        "N",
+        "S",
+        "E",
+        "W",
+        "NE",
+        "NW",
+        "SE",
+        "SW",
+        "NORTH",
+        "SOUTH",
+        "EAST",
+        "WEST",
+        "NORTHEAST",
+        "NORTHWEST",
+        "SOUTHEAST",
+        "SOUTHWEST"
+    ]),
+    es: new Set([
+        "N",
+        "S",
+        "E",
+        "O",
+        "NE",
+        "NO",
+        "SE",
+        "SO",
+        "NORTE",
+        "SUR",
+        "ESTE",
+        "OESTE",
+        "NORESTE",
+        "NOROESTE",
+        "SURESTE",
+        "SUROESTE"
+    ])
+};
+const COUNTRY_RULES = {
+    US: { minDigits: 10, maxDigits: 11 },
+    CO: { minDigits: 10, maxDigits: 12 },
+    MX: { minDigits: 10, maxDigits: 13 },
+    ES: { minDigits: 9, maxDigits: 11 }
+};
+function ok(message = "Validation passed.") {
+    return { ok: true, code: "VALID", message };
+}
+function fail(code, message) {
+    return { ok: false, code, message };
+}
 /**
- * Checks whether a string is a valid international or local cellphone number.
+ * Validates cellphone numbers using regional presets.
  *
  * @param value - Input phone string.
  * @param options - Validation options.
  * @param options.allowInternational - Allows a leading `+`.
- * @param options.minDigits - Minimum number of digits.
- * @param options.maxDigits - Maximum number of digits.
- * @returns `true` when the input matches configured constraints.
+ * @param options.country - Country preset used for length constraints.
+ * @param options.minDigits - Override minimum digits.
+ * @param options.maxDigits - Override maximum digits.
+ * @returns Structured validation result.
  */
-function isCellphoneNumber(value, options = {}) {
+function validateCellphoneNumber(value, options = {}) {
     const allowInternational = options.allowInternational ?? true;
-    const minDigits = options.minDigits ?? 7;
-    const maxDigits = options.maxDigits ?? 15;
-    const normalized = value.trim().replace(/[\s().-]/g, "");
+    const country = options.country ?? "ANY";
+    if (!["ANY", "US", "CO", "MX", "ES"].includes(country)) {
+        return fail("UNSUPPORTED_COUNTRY", `Unsupported country preset: ${country}.`);
+    }
+    const normalized = value.trim();
+    if (normalized.length === 0) {
+        return fail("EMPTY", "Phone number cannot be empty.");
+    }
+    const compact = normalized.replace(/[\s().-]/g, "");
     const pattern = allowInternational ? /^\+?\d+$/ : /^\d+$/;
-    if (!pattern.test(normalized)) {
-        return false;
+    if (!pattern.test(compact)) {
+        return fail("INVALID_FORMAT", "Phone number contains invalid characters.");
+    }
+    const digits = compact.startsWith("+") ? compact.slice(1) : compact;
+    const preset = country === "ANY" ? { minDigits: 7, maxDigits: 15 } : COUNTRY_RULES[country];
+    const minDigits = options.minDigits ?? preset.minDigits;
+    const maxDigits = options.maxDigits ?? preset.maxDigits;
+    if (digits.length < minDigits) {
+        return fail("TOO_SHORT", `Phone number must have at least ${minDigits} digits.`);
+    }
+    if (digits.length > maxDigits) {
+        return fail("TOO_LONG", `Phone number must have at most ${maxDigits} digits.`);
+    }
+    return ok("Valid cellphone number.");
+}
+/**
+ * Boolean wrapper for `validateCellphoneNumber`.
+ *
+ * @param value - Input phone string.
+ * @param options - Validation options.
+ * @returns `true` when the value is valid.
+ */
+function isCellphoneNumber(value, options = {}) {
+    return validateCellphoneNumber(value, options).ok;
+}
+/**
+ * Validates address direction using localized dictionaries.
+ *
+ * @param value - Direction text.
+ * @param options - Validation options.
+ * @param options.locale - Locale dictionary (`en`, `es`).
+ * @returns Structured validation result.
+ */
+function validateAddressDirection(value, options = {}) {
+    const locale = options.locale ?? "en";
+    if (!ADDRESS_DIRECTIONS[locale]) {
+        return fail("UNSUPPORTED_LOCALE", `Unsupported direction locale: ${locale}.`);
     }
-    const digits = normalized.startsWith("+") ? normalized.slice(1) : normalized;
-    return digits.length >= minDigits && digits.length <= maxDigits;
+    const normalized = value.trim().toUpperCase();
+    if (!normalized) {
+        return fail("EMPTY", "Direction cannot be empty.");
+    }
+    return ADDRESS_DIRECTIONS[locale].has(normalized)
+        ? ok("Valid address direction.")
+        : fail("INVALID_FORMAT", "Direction does not match locale dictionary.");
 }
 /**
- * Validates common cardinal and intercardinal address directions.
+ * Boolean wrapper for `validateAddressDirection`.
  *
  * @param value - Direction text.
- * @returns `true` when the input matches known direction tokens.
+ * @param options - Validation options.
+ * @returns `true` when the value is valid.
  */
-function isAddressDirection(value) {
-    return ADDRESS_DIRECTIONS.has(value.trim().toUpperCase());
+function isAddressDirection(value, options = {}) {
+    return validateAddressDirection(value, options).ok;
 }
 /**
- * Validates names using practical rules for most user forms.
+ * Validates person names with practical production constraints.
  *
  * @param value - Name string.
  * @param options - Validation options.
  * @param options.minLength - Minimum total length.
  * @param options.maxLength - Maximum total length.
- * @returns `true` when the name is considered valid.
+ * @returns Structured validation result.
  */
-function isValidName(value, options = {}) {
+function validateName(value, options = {}) {
     const minLength = options.minLength ?? 2;
     const maxLength = options.maxLength ?? 80;
     const normalized = value.trim();
-    if (normalized.length < minLength || normalized.length > maxLength) {
-        return false;
+    if (!normalized) {
+        return fail("EMPTY", "Name cannot be empty.");
+    }
+    if (normalized.length < minLength) {
+        return fail("TOO_SHORT", `Name must have at least ${minLength} characters.`);
+    }
+    if (normalized.length > maxLength) {
+        return fail("TOO_LONG", `Name must have at most ${maxLength} characters.`);
+    }
+    if (!/^[A-Za-zÀ-ÖØ-öø-ÿ' -]+$/.test(normalized)) {
+        return fail("INVALID_CHARACTERS", "Name contains unsupported characters.");
+    }
+    return ok("Valid name.");
+}
+/**
+ * Boolean wrapper for `validateName`.
+ *
+ * @param value - Name string.
+ * @param options - Validation options.
+ * @returns `true` when the value is valid.
+ */
+function isValidName(value, options = {}) {
+    return validateName(value, options).ok;
+}
+/**
+ * Validates an email shape.
+ *
+ * @param value - Email string.
+ * @returns Structured validation result.
+ */
+function validateEmail(value) {
+    const normalized = value.trim();
+    if (!normalized) {
+        return fail("EMPTY", "Email cannot be empty.");
     }
-    return /^[A-Za-zÀ-ÖØ-öø-ÿ' -]+$/.test(normalized);
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(normalized)
+        ? ok("Valid email.")
+        : fail("INVALID_FORMAT", "Email does not match expected format.");
 }
 /**
- * Validates an email using practical constraints for application forms.
+ * Boolean wrapper for `validateEmail`.
  *
  * @param value - Email string.
- * @returns `true` when email shape is valid.
+ * @returns `true` when the value is valid.
  */
 function isEmail(value) {
-    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value.trim());
+    return validateEmail(value).ok;
 }
 /**
  * Validates an HTTP(S) URL.
  *
  * @param value - URL string.
- * @returns `true` when URL is valid and protocol is HTTP or HTTPS.
+ * @returns Structured validation result.
  */
-function isHttpUrl(value) {
+function validateHttpUrl(value) {
+    const normalized = value.trim();
+    if (!normalized) {
+        return fail("EMPTY", "URL cannot be empty.");
+    }
     try {
-        const parsed = new URL(value.trim());
-        return parsed.protocol === "http:" || parsed.protocol === "https:";
+        const parsed = new URL(normalized);
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            return fail("INVALID_FORMAT", "Only HTTP and HTTPS URLs are supported.");
+        }
+        return ok("Valid URL.");
     }
     catch {
-        return false;
+        return fail("INVALID_FORMAT", "URL does not match expected format.");
     }
 }
+/**
+ * Boolean wrapper for `validateHttpUrl`.
+ *
+ * @param value - URL string.
+ * @returns `true` when the value is valid.
+ */
+function isHttpUrl(value) {
+    return validateHttpUrl(value).ok;
+}
 /**
  * Validates US-style postal codes (`12345` or `12345-6789`).
  *
  * @param value - Postal code string.
- * @returns `true` when value matches supported postal formats.
+ * @returns Structured validation result.
+ */
+function validatePostalCode(value) {
+    const normalized = value.trim();
+    if (!normalized) {
+        return fail("EMPTY", "Postal code cannot be empty.");
+    }
+    return /^\d{5}(?:-\d{4})?$/.test(normalized)
+        ? ok("Valid postal code.")
+        : fail("INVALID_FORMAT", "Postal code does not match supported formats.");
+}
+/**
+ * Boolean wrapper for `validatePostalCode`.
+ *
+ * @param value - Postal code string.
+ * @returns `true` when the value is valid.
  */
 function isPostalCode(value) {
-    return /^\d{5}(?:-\d{4})?$/.test(value.trim());
+    return validatePostalCode(value).ok;
 }
 /**
- * Validates password strength with common security requirements.
+ * Validates password strength using default security checks.
  *
  * @param value - Password candidate.
  * @param options - Validation options.
  * @param options.minLength - Minimum required length.
- * @returns `true` when password meets complexity requirements.
+ * @returns Structured validation result.
  */
-function isStrongPassword(value, options = {}) {
+function validateStrongPassword(value, options = {}) {
     const minLength = options.minLength ?? 8;
+    if (!value) {
+        return fail("EMPTY", "Password cannot be empty.");
+    }
     if (value.length < minLength) {
-        return false;
+        return fail("TOO_SHORT", `Password must have at least ${minLength} characters.`);
     }
-    const hasUpper = /[A-Z]/.test(value);
-    const hasLower = /[a-z]/.test(value);
-    const hasDigit = /\d/.test(value);
-    const hasSymbol = /[^A-Za-z0-9]/.test(value);
-    return hasUpper && hasLower && hasDigit && hasSymbol;
+    if (!/[A-Z]/.test(value) || !/[a-z]/.test(value) || !/\d/.test(value) || !/[^A-Za-z0-9]/.test(value)) {
+        return fail("INVALID_FORMAT", "Password must include upper, lower, digit, and symbol characters.");
+    }
+    return ok("Strong password.");
+}
+/**
+ * Boolean wrapper for `validateStrongPassword`.
+ *
+ * @param value - Password candidate.
+ * @param options - Validation options.
+ * @returns `true` when the value is valid.
+ */
+function isStrongPassword(value, options = {}) {
+    return validateStrongPassword(value, options).ok;
 }
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.d.ts

@@ -1,66 +1,145 @@
+export type ValidationResultCode = "VALID" | "EMPTY" | "INVALID_FORMAT" | "TOO_SHORT" | "TOO_LONG" | "INVALID_CHARACTERS" | "UNSUPPORTED_LOCALE" | "UNSUPPORTED_COUNTRY";
+export type ValidationResult = {
+    ok: boolean;
+    code: ValidationResultCode;
+    message: string;
+};
+export type SupportedCountry = "ANY" | "US" | "CO" | "MX" | "ES";
+export type DirectionLocale = "en" | "es";
 /**
- * Checks whether a string is a valid international or local cellphone number.
+ * Validates cellphone numbers using regional presets.
  *
  * @param value - Input phone string.
  * @param options - Validation options.
  * @param options.allowInternational - Allows a leading `+`.
- * @param options.minDigits - Minimum number of digits.
- * @param options.maxDigits - Maximum number of digits.
- * @returns `true` when the input matches configured constraints.
+ * @param options.country - Country preset used for length constraints.
+ * @param options.minDigits - Override minimum digits.
+ * @param options.maxDigits - Override maximum digits.
+ * @returns Structured validation result.
+ */
+export declare function validateCellphoneNumber(value: string, options?: {
+    allowInternational?: boolean;
+    country?: SupportedCountry;
+    minDigits?: number;
+    maxDigits?: number;
+}): ValidationResult;
+/**
+ * Boolean wrapper for `validateCellphoneNumber`.
+ *
+ * @param value - Input phone string.
+ * @param options - Validation options.
+ * @returns `true` when the value is valid.
  */
 export declare function isCellphoneNumber(value: string, options?: {
     allowInternational?: boolean;
+    country?: SupportedCountry;
     minDigits?: number;
     maxDigits?: number;
 }): boolean;
 /**
- * Validates common cardinal and intercardinal address directions.
+ * Validates address direction using localized dictionaries.
+ *
+ * @param value - Direction text.
+ * @param options - Validation options.
+ * @param options.locale - Locale dictionary (`en`, `es`).
+ * @returns Structured validation result.
+ */
+export declare function validateAddressDirection(value: string, options?: {
+    locale?: DirectionLocale;
+}): ValidationResult;
+/**
+ * Boolean wrapper for `validateAddressDirection`.
  *
  * @param value - Direction text.
- * @returns `true` when the input matches known direction tokens.
+ * @param options - Validation options.
+ * @returns `true` when the value is valid.
  */
-export declare function isAddressDirection(value: string): boolean;
+export declare function isAddressDirection(value: string, options?: {
+    locale?: DirectionLocale;
+}): boolean;
 /**
- * Validates names using practical rules for most user forms.
+ * Validates person names with practical production constraints.
  *
  * @param value - Name string.
  * @param options - Validation options.
  * @param options.minLength - Minimum total length.
  * @param options.maxLength - Maximum total length.
- * @returns `true` when the name is considered valid.
+ * @returns Structured validation result.
+ */
+export declare function validateName(value: string, options?: {
+    minLength?: number;
+    maxLength?: number;
+}): ValidationResult;
+/**
+ * Boolean wrapper for `validateName`.
+ *
+ * @param value - Name string.
+ * @param options - Validation options.
+ * @returns `true` when the value is valid.
  */
 export declare function isValidName(value: string, options?: {
     minLength?: number;
     maxLength?: number;
 }): boolean;
 /**
- * Validates an email using practical constraints for application forms.
+ * Validates an email shape.
+ *
+ * @param value - Email string.
+ * @returns Structured validation result.
+ */
+export declare function validateEmail(value: string): ValidationResult;
+/**
+ * Boolean wrapper for `validateEmail`.
  *
  * @param value - Email string.
- * @returns `true` when email shape is valid.
+ * @returns `true` when the value is valid.
  */
 export declare function isEmail(value: string): boolean;
 /**
  * Validates an HTTP(S) URL.
  *
  * @param value - URL string.
- * @returns `true` when URL is valid and protocol is HTTP or HTTPS.
+ * @returns Structured validation result.
+ */
+export declare function validateHttpUrl(value: string): ValidationResult;
+/**
+ * Boolean wrapper for `validateHttpUrl`.
+ *
+ * @param value - URL string.
+ * @returns `true` when the value is valid.
  */
 export declare function isHttpUrl(value: string): boolean;
 /**
  * Validates US-style postal codes (`12345` or `12345-6789`).
  *
  * @param value - Postal code string.
- * @returns `true` when value matches supported postal formats.
+ * @returns Structured validation result.
+ */
+export declare function validatePostalCode(value: string): ValidationResult;
+/**
+ * Boolean wrapper for `validatePostalCode`.
+ *
+ * @param value - Postal code string.
+ * @returns `true` when the value is valid.
  */
 export declare function isPostalCode(value: string): boolean;
 /**
- * Validates password strength with common security requirements.
+ * Validates password strength using default security checks.
  *
  * @param value - Password candidate.
  * @param options - Validation options.
  * @param options.minLength - Minimum required length.
- * @returns `true` when password meets complexity requirements.
+ * @returns Structured validation result.
+ */
+export declare function validateStrongPassword(value: string, options?: {
+    minLength?: number;
+}): ValidationResult;
+/**
+ * Boolean wrapper for `validateStrongPassword`.
+ *
+ * @param value - Password candidate.
+ * @param options - Validation options.
+ * @returns `true` when the value is valid.
  */
 export declare function isStrongPassword(value: string, options?: {
     minLength?: number;

package/dist/esm/index.js

@@ -1,120 +1,277 @@
-const ADDRESS_DIRECTIONS = new Set([
-    "N",
-    "S",
-    "E",
-    "W",
-    "NE",
-    "NW",
-    "SE",
-    "SW",
-    "NORTH",
-    "SOUTH",
-    "EAST",
-    "WEST",
-    "NORTHEAST",
-    "NORTHWEST",
-    "SOUTHEAST",
-    "SOUTHWEST"
-]);
+const ADDRESS_DIRECTIONS = {
+    en: new Set([
+        "N",
+        "S",
+        "E",
+        "W",
+        "NE",
+        "NW",
+        "SE",
+        "SW",
+        "NORTH",
+        "SOUTH",
+        "EAST",
+        "WEST",
+        "NORTHEAST",
+        "NORTHWEST",
+        "SOUTHEAST",
+        "SOUTHWEST"
+    ]),
+    es: new Set([
+        "N",
+        "S",
+        "E",
+        "O",
+        "NE",
+        "NO",
+        "SE",
+        "SO",
+        "NORTE",
+        "SUR",
+        "ESTE",
+        "OESTE",
+        "NORESTE",
+        "NOROESTE",
+        "SURESTE",
+        "SUROESTE"
+    ])
+};
+const COUNTRY_RULES = {
+    US: { minDigits: 10, maxDigits: 11 },
+    CO: { minDigits: 10, maxDigits: 12 },
+    MX: { minDigits: 10, maxDigits: 13 },
+    ES: { minDigits: 9, maxDigits: 11 }
+};
+function ok(message = "Validation passed.") {
+    return { ok: true, code: "VALID", message };
+}
+function fail(code, message) {
+    return { ok: false, code, message };
+}
 /**
- * Checks whether a string is a valid international or local cellphone number.
+ * Validates cellphone numbers using regional presets.
  *
  * @param value - Input phone string.
  * @param options - Validation options.
  * @param options.allowInternational - Allows a leading `+`.
- * @param options.minDigits - Minimum number of digits.
- * @param options.maxDigits - Maximum number of digits.
- * @returns `true` when the input matches configured constraints.
+ * @param options.country - Country preset used for length constraints.
+ * @param options.minDigits - Override minimum digits.
+ * @param options.maxDigits - Override maximum digits.
+ * @returns Structured validation result.
  */
-export function isCellphoneNumber(value, options = {}) {
+export function validateCellphoneNumber(value, options = {}) {
     const allowInternational = options.allowInternational ?? true;
-    const minDigits = options.minDigits ?? 7;
-    const maxDigits = options.maxDigits ?? 15;
-    const normalized = value.trim().replace(/[\s().-]/g, "");
+    const country = options.country ?? "ANY";
+    if (!["ANY", "US", "CO", "MX", "ES"].includes(country)) {
+        return fail("UNSUPPORTED_COUNTRY", `Unsupported country preset: ${country}.`);
+    }
+    const normalized = value.trim();
+    if (normalized.length === 0) {
+        return fail("EMPTY", "Phone number cannot be empty.");
+    }
+    const compact = normalized.replace(/[\s().-]/g, "");
     const pattern = allowInternational ? /^\+?\d+$/ : /^\d+$/;
-    if (!pattern.test(normalized)) {
-        return false;
+    if (!pattern.test(compact)) {
+        return fail("INVALID_FORMAT", "Phone number contains invalid characters.");
+    }
+    const digits = compact.startsWith("+") ? compact.slice(1) : compact;
+    const preset = country === "ANY" ? { minDigits: 7, maxDigits: 15 } : COUNTRY_RULES[country];
+    const minDigits = options.minDigits ?? preset.minDigits;
+    const maxDigits = options.maxDigits ?? preset.maxDigits;
+    if (digits.length < minDigits) {
+        return fail("TOO_SHORT", `Phone number must have at least ${minDigits} digits.`);
+    }
+    if (digits.length > maxDigits) {
+        return fail("TOO_LONG", `Phone number must have at most ${maxDigits} digits.`);
+    }
+    return ok("Valid cellphone number.");
+}
+/**
+ * Boolean wrapper for `validateCellphoneNumber`.
+ *
+ * @param value - Input phone string.
+ * @param options - Validation options.
+ * @returns `true` when the value is valid.
+ */
+export function isCellphoneNumber(value, options = {}) {
+    return validateCellphoneNumber(value, options).ok;
+}
+/**
+ * Validates address direction using localized dictionaries.
+ *
+ * @param value - Direction text.
+ * @param options - Validation options.
+ * @param options.locale - Locale dictionary (`en`, `es`).
+ * @returns Structured validation result.
+ */
+export function validateAddressDirection(value, options = {}) {
+    const locale = options.locale ?? "en";
+    if (!ADDRESS_DIRECTIONS[locale]) {
+        return fail("UNSUPPORTED_LOCALE", `Unsupported direction locale: ${locale}.`);
     }
-    const digits = normalized.startsWith("+") ? normalized.slice(1) : normalized;
-    return digits.length >= minDigits && digits.length <= maxDigits;
+    const normalized = value.trim().toUpperCase();
+    if (!normalized) {
+        return fail("EMPTY", "Direction cannot be empty.");
+    }
+    return ADDRESS_DIRECTIONS[locale].has(normalized)
+        ? ok("Valid address direction.")
+        : fail("INVALID_FORMAT", "Direction does not match locale dictionary.");
 }
 /**
- * Validates common cardinal and intercardinal address directions.
+ * Boolean wrapper for `validateAddressDirection`.
  *
  * @param value - Direction text.
- * @returns `true` when the input matches known direction tokens.
+ * @param options - Validation options.
+ * @returns `true` when the value is valid.
  */
-export function isAddressDirection(value) {
-    return ADDRESS_DIRECTIONS.has(value.trim().toUpperCase());
+export function isAddressDirection(value, options = {}) {
+    return validateAddressDirection(value, options).ok;
 }
 /**
- * Validates names using practical rules for most user forms.
+ * Validates person names with practical production constraints.
  *
  * @param value - Name string.
  * @param options - Validation options.
  * @param options.minLength - Minimum total length.
  * @param options.maxLength - Maximum total length.
- * @returns `true` when the name is considered valid.
+ * @returns Structured validation result.
  */
-export function isValidName(value, options = {}) {
+export function validateName(value, options = {}) {
     const minLength = options.minLength ?? 2;
     const maxLength = options.maxLength ?? 80;
     const normalized = value.trim();
-    if (normalized.length < minLength || normalized.length > maxLength) {
-        return false;
+    if (!normalized) {
+        return fail("EMPTY", "Name cannot be empty.");
+    }
+    if (normalized.length < minLength) {
+        return fail("TOO_SHORT", `Name must have at least ${minLength} characters.`);
+    }
+    if (normalized.length > maxLength) {
+        return fail("TOO_LONG", `Name must have at most ${maxLength} characters.`);
+    }
+    if (!/^[A-Za-zÀ-ÖØ-öø-ÿ' -]+$/.test(normalized)) {
+        return fail("INVALID_CHARACTERS", "Name contains unsupported characters.");
+    }
+    return ok("Valid name.");
+}
+/**
+ * Boolean wrapper for `validateName`.
+ *
+ * @param value - Name string.
+ * @param options - Validation options.
+ * @returns `true` when the value is valid.
+ */
+export function isValidName(value, options = {}) {
+    return validateName(value, options).ok;
+}
+/**
+ * Validates an email shape.
+ *
+ * @param value - Email string.
+ * @returns Structured validation result.
+ */
+export function validateEmail(value) {
+    const normalized = value.trim();
+    if (!normalized) {
+        return fail("EMPTY", "Email cannot be empty.");
     }
-    return /^[A-Za-zÀ-ÖØ-öø-ÿ' -]+$/.test(normalized);
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(normalized)
+        ? ok("Valid email.")
+        : fail("INVALID_FORMAT", "Email does not match expected format.");
 }
 /**
- * Validates an email using practical constraints for application forms.
+ * Boolean wrapper for `validateEmail`.
  *
  * @param value - Email string.
- * @returns `true` when email shape is valid.
+ * @returns `true` when the value is valid.
  */
 export function isEmail(value) {
-    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value.trim());
+    return validateEmail(value).ok;
 }
 /**
  * Validates an HTTP(S) URL.
  *
  * @param value - URL string.
- * @returns `true` when URL is valid and protocol is HTTP or HTTPS.
+ * @returns Structured validation result.
  */
-export function isHttpUrl(value) {
+export function validateHttpUrl(value) {
+    const normalized = value.trim();
+    if (!normalized) {
+        return fail("EMPTY", "URL cannot be empty.");
+    }
     try {
-        const parsed = new URL(value.trim());
-        return parsed.protocol === "http:" || parsed.protocol === "https:";
+        const parsed = new URL(normalized);
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            return fail("INVALID_FORMAT", "Only HTTP and HTTPS URLs are supported.");
+        }
+        return ok("Valid URL.");
     }
     catch {
-        return false;
+        return fail("INVALID_FORMAT", "URL does not match expected format.");
     }
 }
+/**
+ * Boolean wrapper for `validateHttpUrl`.
+ *
+ * @param value - URL string.
+ * @returns `true` when the value is valid.
+ */
+export function isHttpUrl(value) {
+    return validateHttpUrl(value).ok;
+}
 /**
  * Validates US-style postal codes (`12345` or `12345-6789`).
  *
  * @param value - Postal code string.
- * @returns `true` when value matches supported postal formats.
+ * @returns Structured validation result.
+ */
+export function validatePostalCode(value) {
+    const normalized = value.trim();
+    if (!normalized) {
+        return fail("EMPTY", "Postal code cannot be empty.");
+    }
+    return /^\d{5}(?:-\d{4})?$/.test(normalized)
+        ? ok("Valid postal code.")
+        : fail("INVALID_FORMAT", "Postal code does not match supported formats.");
+}
+/**
+ * Boolean wrapper for `validatePostalCode`.
+ *
+ * @param value - Postal code string.
+ * @returns `true` when the value is valid.
  */
 export function isPostalCode(value) {
-    return /^\d{5}(?:-\d{4})?$/.test(value.trim());
+    return validatePostalCode(value).ok;
 }
 /**
- * Validates password strength with common security requirements.
+ * Validates password strength using default security checks.
  *
  * @param value - Password candidate.
  * @param options - Validation options.
  * @param options.minLength - Minimum required length.
- * @returns `true` when password meets complexity requirements.
+ * @returns Structured validation result.
  */
-export function isStrongPassword(value, options = {}) {
+export function validateStrongPassword(value, options = {}) {
     const minLength = options.minLength ?? 8;
+    if (!value) {
+        return fail("EMPTY", "Password cannot be empty.");
+    }
     if (value.length < minLength) {
-        return false;
+        return fail("TOO_SHORT", `Password must have at least ${minLength} characters.`);
     }
-    const hasUpper = /[A-Z]/.test(value);
-    const hasLower = /[a-z]/.test(value);
-    const hasDigit = /\d/.test(value);
-    const hasSymbol = /[^A-Za-z0-9]/.test(value);
-    return hasUpper && hasLower && hasDigit && hasSymbol;
+    if (!/[A-Z]/.test(value) || !/[a-z]/.test(value) || !/\d/.test(value) || !/[^A-Za-z0-9]/.test(value)) {
+        return fail("INVALID_FORMAT", "Password must include upper, lower, digit, and symbol characters.");
+    }
+    return ok("Strong password.");
+}
+/**
+ * Boolean wrapper for `validateStrongPassword`.
+ *
+ * @param value - Password candidate.
+ * @param options - Validation options.
+ * @returns `true` when the value is valid.
+ */
+export function isStrongPassword(value, options = {}) {
+    return validateStrongPassword(value, options).ok;
 }
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jdsalasc/solvejs-validators",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Practical validators for real JS/TS form pain points: cellphone, direction, name, password, email, and URL.",
   "license": "MIT",
   "type": "module",