@catbee/utils/validation/index.d.ts

A modular, production-grade utility toolkit for Node.js and TypeScript, designed for robust, scalable applications (including Express-based services). All utilities are tree-shakable and can be imported independently.

/*
 * The MIT License
 * 
 * Copyright (c) 2026 Catbee Technologies. https://catbee.in/license
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

/**
 * Collection of common validation helpers for strings, numbers, email, UUID, etc.
 */
/**
 * Checks if a string is a valid port number.
 *
 * @param str - The input string or number.
 * @returns True if valid port number, else false.
 */
declare function isPort(value: string | number): boolean;
/**
 * Checks if a string is a valid email address.
 *
 * @param {string} str - The input string.
 * @returns {boolean} True if valid email, else false.
 */
declare function isEmail(str: string): boolean;
/**
 * Checks if a string is a valid UUID (versions 1-5).
 *
 * @param {string} str - The input string.
 * @returns {boolean} True if valid UUID, else false.
 */
declare function isUUID(str: string): boolean;
/**
 * Checks if a string is a valid URL.
 *
 * @param {string} str - The input string.
 * @param {string[]} [allowedProtocols=['http', 'https', 'ws', 'wss']] - Allowed URL protocols.
 * @returns {boolean} True if valid URL, else false.
 */
declare function isURL(str: string, allowedProtocols?: string[]): boolean;
/**
 * Checks if a string is a valid international phone number (E.164 or common patterns).
 *
 * @param {string} str - The input string.
 * @returns {boolean} True if looks like a phone number.
 */
declare function isPhone(str: string): boolean;
/**
 * Checks if a string is strictly alphanumeric (letters/numbers only).
 *
 * @param {string} str - The input string.
 * @returns {boolean} True if alphanumeric.
 */
declare function isAlphanumeric(str: string): boolean;
/**
 * Checks if a string or number can be safely parsed to a number.
 *
 * @param {string | number} value - The value to check.
 * @returns {boolean} True if the value is numeric.
 */
declare function isNumeric(value: string | number): boolean;
/**
 * Checks if a string is a valid hex color code (e.g. #FFF or #FFFFFF).
 *
 * @param {string} str - Input string.
 * @returns {boolean}
 */
declare function isHexColor(str: string): boolean;
/**
 * Checks if a string is a valid date string.
 *
 * @param {string} str - Input string.
 * @returns {boolean}
 */
declare function isISODate(str: string): boolean;
/**
 * Checks if a string matches a specified length range.
 *
 * @param {string} str - The input string.
 * @param {number} min - Minimum length (inclusive).
 * @param {number} max - Maximum length (inclusive).
 * @returns {boolean} True if string length is within range.
 */
declare function isLengthBetween(str: string, min: number, max: number): boolean;
/**
 * Validates that a number is between specified min and max values (inclusive).
 *
 * @param {number} value - The number to validate.
 * @param {number} min - Minimum value.
 * @param {number} max - Maximum value.
 * @returns {boolean} True if number is within range.
 */
declare function isNumberBetween(value: number, min: number, max: number): boolean;
/**
 * Checks if a string contains only alphabetic characters.
 *
 * @param {string} str - The input string.
 * @returns {boolean} True if alphabetic only.
 */
declare function isAlpha(str: string): boolean;
/**
 * Validates that a string contains at least one uppercase letter,
 * one lowercase letter, one number, and one special character.
 *
 * - Minimum length of 8 characters.
 * - At least one uppercase letter (A-Z).
 * - At least one lowercase letter (a-z).
 * - At least one digit (0-9).
 * - At least one special character e.g. !@#$%^&*()_+-=[]{};':"\\|,.<>?/
 *
 * @param {string} str - The input string.
 * @returns {boolean} True if string meets password complexity requirements.
 */
declare function isStrongPassword(str: string): boolean;
/**
 * Checks if a string is a valid IPv4 address.
 *
 * @param {string} str - The input string.
 * @returns {boolean} True if valid IPv4 address.
 */
declare function isIPv4(str: string): boolean;
/**
 * Checks if a string is a valid IPv6 address.
 *
 * @param {string} str - The input string.
 * @returns {boolean} True if valid IPv6 address.
 */
declare function isIPv6(str: string): boolean;
/**
 * Validates a credit card number using the Luhn algorithm.
 *
 * @param {string} str - The credit card number string.
 * @returns {boolean} True if valid credit card number.
 */
declare function isCreditCard(str: string): boolean;
/**
 * Checks if a string is a valid JSON.
 *
 * @param {string} str - The input string.
 * @returns {boolean} True if valid JSON.
 */
declare function isValidJSON(str: string): boolean;
/**
 * Type guard that checks if a value is an array.
 *
 * @template T Optional expected element type
 * @param {unknown} value - The value to check.
 * @param {(item: unknown) => boolean} [itemGuard] - Optional function to validate each item.
 * @returns {boolean} True if value is an array (with optional item validation).
 */
declare function isArray<T = unknown>(value: unknown, itemGuard?: (item: unknown) => item is T): value is T[];
/**
 * Checks if a string is a valid base64 encoded string.
 *
 * @param {string} str - The input string.
 * @returns {boolean} True if valid base64.
 */
declare function isBase64(str: string): boolean;
/**
 * Validates that an object has all required properties.
 *
 * @param {object} obj - The object to validate.
 * @param {string[]} requiredProps - Array of required property names.
 * @returns {boolean} True if all required properties exist.
 */
declare function hasRequiredProps(obj: Record<string, unknown>, requiredProps: string[]): boolean;
/**
 * Validates a date is within a specified range.
 *
 * @param {Date} date - The date to validate.
 * @param {Date} [minDate] - Optional minimum date (inclusive).
 * @param {Date} [maxDate] - Optional maximum date (inclusive).
 * @returns {boolean} True if date is within range.
 */
declare function isDateInRange(date: Date, minDate?: Date, maxDate?: Date): boolean;
/**
 * Validates a string matches a specific regular expression pattern.
 *
 * @param {string} str - The input string.
 * @param {RegExp} pattern - Regular expression to test against.
 * @returns {boolean} True if string matches pattern.
 */
declare function matchesPattern(str: string, pattern: RegExp): boolean;
/**
 * Validates data against multiple constraints.
 *
 * @param {unknown} value - The value to validate.
 * @param {Array<(value: unknown) => boolean>} validators - Array of validation functions.
 * @returns {boolean} True if value passes all validations.
 */
declare function validateAll(value: unknown, validators: Array<(value: unknown) => boolean>): boolean;

export { hasRequiredProps, isAlpha, isAlphanumeric, isArray, isBase64, isCreditCard, isDateInRange, isEmail, isHexColor, isIPv4, isIPv6, isISODate, isLengthBetween, isNumberBetween, isNumeric, isPhone, isPort, isStrongPassword, isURL, isUUID, isValidJSON, matchesPattern, validateAll };