utilitify-core 1.0.0

package/dist/index-BXBmBHyL.d.ts

@@ -0,0 +1,718 @@
+import { B as BaseOptions, V as ValidationResult, I as IValidationError } from './common-CBDYNJeh.js';
+
+/**
+ * Name validation options
+ */
+interface NameOptions extends BaseOptions {
+    /** Minimum length (default: 2) */
+    minLength?: number;
+    /** Maximum length (default: 100) */
+    maxLength?: number;
+    /** Allow special characters (default: true) */
+    allowSpecialChars?: boolean;
+    /** Allow numbers (default: false) */
+    allowNumbers?: boolean;
+    /** Allowed scripts */
+    allowedScripts?: ('latin' | 'arabic' | 'cjk' | 'cyrillic' | 'devanagari')[];
+}
+/**
+ * Name validation result
+ */
+interface NameValidationResult extends ValidationResult {
+    sanitized: string;
+    detectedScript: 'latin' | 'arabic' | 'cjk' | 'cyrillic' | 'devanagari' | 'mixed' | 'unknown';
+}
+/**
+ * Email validation options
+ */
+interface EmailOptions extends BaseOptions {
+    /** Check for disposable email domains (default: true) */
+    checkDisposable?: boolean;
+    /** Check for corporate domains */
+    checkCorporate?: boolean;
+    /** Allowed domains whitelist */
+    allowedDomains?: string[];
+    /** Blocked domains blacklist */
+    blockedDomains?: string[];
+}
+/**
+ * Email validation result
+ */
+interface EmailValidationResult extends ValidationResult {
+    isDisposable: boolean;
+    isCorporate: boolean;
+    normalized: string;
+    domain: string;
+    localPart: string;
+}
+/**
+ * Phone validation options
+ */
+interface PhoneOptions extends BaseOptions {
+    /** Country code for validation (e.g., 'US', 'PK') */
+    countryCode?: string;
+    /** Strict mode - require exact format */
+    strict?: boolean;
+    /** Allow mobile only */
+    mobileOnly?: boolean;
+}
+/**
+ * Phone validation result
+ */
+interface PhoneValidationResult extends ValidationResult {
+    countryCode: string;
+    nationalNumber: string;
+    formatted: {
+        national: string;
+        international: string;
+        e164: string;
+    };
+    type: 'mobile' | 'landline' | 'toll_free' | 'premium' | 'unknown';
+    isValid: boolean;
+}
+/**
+ * Username validation options
+ */
+interface UsernameOptions extends BaseOptions {
+    /** Minimum length (default: 3) */
+    minLength?: number;
+    /** Maximum length (default: 30) */
+    maxLength?: number;
+    /** Allowed characters pattern */
+    allowedChars?: RegExp;
+    /** Reserved usernames list */
+    reserved?: string[];
+    /** Allow email format */
+    allowEmail?: boolean;
+}
+/**
+ * Username validation result
+ */
+interface UsernameValidationResult extends ValidationResult {
+    sanitized: string;
+    isReserved: boolean;
+}
+/**
+ * Combined user data for validateUser()
+ */
+interface UserData {
+    name?: string;
+    email?: string;
+    phone?: string;
+    country?: string;
+    username?: string;
+    password?: string;
+    dateOfBirth?: string | Date;
+}
+/**
+ * User validation options
+ */
+interface UserValidationOptions extends BaseOptions {
+    name?: NameOptions;
+    email?: EmailOptions;
+    phone?: PhoneOptions;
+    username?: UsernameOptions;
+    /** Required fields */
+    required?: (keyof UserData)[];
+}
+/**
+ * User validation result
+ */
+interface UserValidationResult extends ValidationResult {
+    data: {
+        name?: NameValidationResult;
+        email?: EmailValidationResult;
+        phone?: PhoneValidationResult;
+        username?: UsernameValidationResult;
+    };
+    sanitized: Partial<UserData>;
+}
+
+/**
+ * Validate an email address with comprehensive checks
+ *
+ * @param email - Email address to validate
+ * @param options - Validation options
+ * @returns Validation result with details
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const result = validateEmail('user@example.com');
+ * if (result.isValid) {
+ *   console.log('Email is valid:', result.normalized);
+ * }
+ * ```
+ */
+declare function validateEmail(email: string, options?: EmailOptions): EmailValidationResult;
+/**
+ * Simple email format validation
+ *
+ * @param email - Email to validate
+ * @returns true if email format is valid
+ * @since 1.0.0
+ */
+declare function isValidEmail(email: string): boolean;
+/**
+ * Check if email domain is disposable
+ *
+ * @param email - Email to check
+ * @returns true if domain is disposable
+ * @since 1.0.0
+ */
+declare function isDisposableEmail(email: string): boolean;
+/**
+ * Normalize email address
+ * - Lowercase
+ * - Remove dots from Gmail local part
+ * - Remove + aliases
+ *
+ * @param email - Email to normalize
+ * @returns Normalized email
+ * @since 1.0.0
+ */
+declare function normalizeEmail(email: string): string;
+/**
+ * Extract domain from email
+ *
+ * @param email - Email address
+ * @returns Domain part of email
+ * @since 1.0.0
+ */
+declare function getEmailDomain(email: string): string;
+
+/**
+ * Validate a name with multilingual support
+ *
+ * @param name - Name to validate
+ * @param options - Validation options
+ * @returns Validation result
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const result = validateName('John Doe');
+ * if (result.isValid) {
+ *   console.log('Name is valid:', result.sanitized);
+ * }
+ * ```
+ */
+declare function validateName(name: string, options?: NameOptions): NameValidationResult;
+/**
+ * Simple name validation check
+ *
+ * @param name - Name to validate
+ * @returns true if name is valid
+ * @since 1.0.0
+ */
+declare function isValidName(name: string): boolean;
+/**
+ * Sanitize a name string
+ * - Trim whitespace
+ * - Normalize unicode
+ * - Remove excessive spaces
+ * - Capitalize properly
+ *
+ * @param name - Name to sanitize
+ * @returns Sanitized name
+ * @since 1.0.0
+ */
+declare function sanitizeName(name: string): string;
+/**
+ * Detect the primary script used in a string
+ *
+ * @param text - Text to analyze
+ * @returns Detected script
+ * @since 1.0.0
+ */
+declare function detectScript(text: string): 'latin' | 'arabic' | 'cjk' | 'cyrillic' | 'devanagari' | 'mixed' | 'unknown';
+/**
+ * Format name to proper title case
+ *
+ * @param name - Name to format
+ * @returns Formatted name
+ * @since 1.0.0
+ */
+declare function formatName(name: string): string;
+/**
+ * Split full name into parts
+ *
+ * @param fullName - Full name string
+ * @returns Object with firstName, lastName, middleName
+ * @since 1.0.0
+ */
+declare function splitName(fullName: string): {
+    firstName: string;
+    lastName: string;
+    middleName?: string;
+};
+
+/**
+ * Validate a phone number
+ *
+ * @param phone - Phone number to validate
+ * @param options - Validation options
+ * @returns Validation result
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const result = validatePhone('+1 555-123-4567', { countryCode: 'US' });
+ * if (result.isValid) {
+ *   console.log('Phone:', result.formatted.international);
+ * }
+ * ```
+ */
+declare function validatePhone(phone: string, options?: PhoneOptions): PhoneValidationResult;
+/**
+ * Simple phone validation
+ *
+ * @param phone - Phone number to validate
+ * @param countryCode - Optional country code
+ * @returns true if phone is valid
+ * @since 1.0.0
+ */
+declare function isValidPhone(phone: string, countryCode?: string): boolean;
+/**
+ * Format phone number to specified format
+ *
+ * @param phone - Phone number
+ * @param format - Format type
+ * @param countryCode - Country code
+ * @returns Formatted phone number
+ * @since 1.0.0
+ */
+declare function formatPhone(phone: string, format?: 'national' | 'international' | 'e164', countryCode?: string): string;
+/**
+ * Parse phone number and extract components
+ *
+ * @param phone - Phone number
+ * @returns Parsed components
+ * @since 1.0.0
+ */
+declare function parsePhone(phone: string): {
+    countryCode: string;
+    dialCode: string;
+    nationalNumber: string;
+    isValid: boolean;
+};
+
+/**
+ * Validate a username
+ *
+ * @param username - Username to validate
+ * @param options - Validation options
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const result = validateUsername('john_doe');
+ * if (result.isValid) {
+ *   console.log('Username is valid');
+ * }
+ * ```
+ */
+declare function validateUsername(username: string, options?: UsernameOptions): UsernameValidationResult;
+/**
+ * Simple username validation
+ *
+ * @param username - Username to validate
+ * @returns true if username is valid
+ */
+declare function isValidUsername(username: string): boolean;
+/**
+ * Check if username is reserved
+ *
+ * @param username - Username to check
+ * @param additionalReserved - Additional reserved usernames
+ * @returns true if username is reserved
+ */
+declare function isReservedUsername(username: string, additionalReserved?: string[]): boolean;
+/**
+ * Sanitize username
+ *
+ * @param username - Username to sanitize
+ * @returns Sanitized username
+ */
+declare function sanitizeUsername(username: string): string;
+/**
+ * Generate username suggestions based on input
+ *
+ * @param base - Base string (e.g., name or email)
+ * @param count - Number of suggestions
+ * @returns Array of username suggestions
+ */
+declare function suggestUsernames(base: string, count?: number): string[];
+
+/**
+ * URL validation options
+ */
+interface UrlOptions {
+    /** Require HTTPS (default: false) */
+    requireHttps?: boolean;
+    /** Allow localhost (default: true) */
+    allowLocalhost?: boolean;
+    /** Allow IP addresses (default: true) */
+    allowIpAddress?: boolean;
+    /** Allowed protocols (default: ['http:', 'https:']) */
+    allowedProtocols?: string[];
+    /** Blocked domains */
+    blockedDomains?: string[];
+    /** Require specific TLDs */
+    allowedTlds?: string[];
+    /** Custom error messages */
+    messages?: {
+        required?: string;
+        invalidFormat?: string;
+        invalidProtocol?: string;
+        blockedDomain?: string;
+        invalidTld?: string;
+    };
+}
+/**
+ * URL validation result
+ */
+interface UrlValidationResult {
+    /** Whether URL is valid */
+    isValid: boolean;
+    /** Validation errors */
+    errors: IValidationError[];
+    /** Parsed URL components */
+    parsed?: {
+        protocol: string;
+        hostname: string;
+        port: string;
+        pathname: string;
+        search: string;
+        hash: string;
+    };
+    /** Normalized URL */
+    normalized: string;
+}
+/**
+ * Validate a URL
+ *
+ * @param url - URL to validate
+ * @param options - Validation options
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const result = validateUrl('https://example.com/path');
+ * if (result.isValid) {
+ *   console.log('Valid URL:', result.normalized);
+ * }
+ * ```
+ */
+declare function validateUrl(url: string, options?: UrlOptions): UrlValidationResult;
+/**
+ * Simple URL format validation
+ *
+ * @param url - URL to validate
+ * @returns true if URL format is valid
+ */
+declare function isValidUrl(url: string): boolean;
+/**
+ * Check if URL is HTTPS
+ *
+ * @param url - URL to check
+ * @returns true if URL uses HTTPS
+ */
+declare function isHttpsUrl(url: string): boolean;
+/**
+ * Extract domain from URL
+ *
+ * @param url - URL to extract from
+ * @returns Domain/hostname or empty string
+ */
+declare function getUrlDomain(url: string): string;
+/**
+ * Normalize URL (lowercase host, remove trailing slash, etc.)
+ *
+ * @param url - URL to normalize
+ * @returns Normalized URL or empty string
+ */
+declare function normalizeUrl(url: string): string;
+/**
+ * Check if URL is a data URL
+ *
+ * @param url - URL to check
+ * @returns true if data URL
+ */
+declare function isDataUrl(url: string): boolean;
+/**
+ * Check if URL contains potentially dangerous schemes
+ *
+ * @param url - URL to check
+ * @returns true if dangerous
+ */
+declare function isDangerousUrl(url: string): boolean;
+
+/**
+ * Credit card validation options
+ */
+interface CreditCardOptions {
+    /** Check Luhn algorithm (default: true) */
+    checkLuhn?: boolean;
+    /** Allowed card types */
+    allowedTypes?: CardType[];
+    /** Custom error messages */
+    messages?: {
+        required?: string;
+        invalidFormat?: string;
+        invalidLuhn?: string;
+        typeNotAllowed?: string;
+    };
+}
+/**
+ * Credit card validation result
+ */
+interface CreditCardValidationResult {
+    /** Whether card number is valid */
+    isValid: boolean;
+    /** Validation errors */
+    errors: IValidationError[];
+    /** Detected card type */
+    cardType: CardType | null;
+    /** Masked card number (last 4 digits visible) */
+    masked: string;
+    /** Cleaned card number (digits only) */
+    cleaned: string;
+}
+/**
+ * Supported card types
+ */
+type CardType = 'visa' | 'mastercard' | 'amex' | 'discover' | 'diners' | 'jcb' | 'unionpay' | 'maestro' | 'unknown';
+/**
+ * Validate a credit card number
+ *
+ * @param cardNumber - Credit card number to validate
+ * @param options - Validation options
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const result = validateCreditCard('4111111111111111');
+ * if (result.isValid) {
+ *   console.log('Card type:', result.cardType); // 'visa'
+ * }
+ * ```
+ */
+declare function validateCreditCard(cardNumber: string, options?: CreditCardOptions): CreditCardValidationResult;
+/**
+ * Simple credit card validation
+ *
+ * @param cardNumber - Card number to validate
+ * @returns true if valid
+ */
+declare function isValidCreditCard(cardNumber: string): boolean;
+/**
+ * Detect credit card type from number
+ *
+ * @param cardNumber - Card number
+ * @returns Detected card type
+ */
+declare function detectCardType(cardNumber: string): CardType;
+/**
+ * Get card type from prefix (for real-time typing)
+ *
+ * @param cardNumber - Partial card number
+ * @returns Detected card type or null
+ */
+declare function getCardTypeFromPrefix(cardNumber: string): CardType | null;
+/**
+ * Luhn algorithm check (mod 10)
+ *
+ * @param cardNumber - Card number (digits only)
+ * @returns true if passes Luhn check
+ */
+declare function luhnCheck(cardNumber: string): boolean;
+/**
+ * Mask credit card number (show last 4 digits)
+ *
+ * @param cardNumber - Card number to mask
+ * @param maskChar - Character to use for masking (default: '*')
+ * @returns Masked card number
+ */
+declare function maskCardNumber(cardNumber: string, maskChar?: string): string;
+/**
+ * Format credit card number with spaces
+ *
+ * @param cardNumber - Card number to format
+ * @returns Formatted card number
+ */
+declare function formatCardNumber(cardNumber: string): string;
+/**
+ * Validate CVV/CVC
+ *
+ * @param cvv - CVV code
+ * @param cardType - Card type (amex has 4-digit CVV)
+ * @returns true if valid
+ */
+declare function isValidCVV(cvv: string, cardType?: CardType): boolean;
+/**
+ * Validate expiry date
+ *
+ * @param month - Expiry month (1-12 or '01'-'12')
+ * @param year - Expiry year (2-digit or 4-digit)
+ * @returns true if not expired
+ */
+declare function isValidExpiry(month: string | number, year: string | number): boolean;
+
+/**
+ * IP validation options
+ */
+interface IpOptions {
+    /** Version to validate (default: both) */
+    version?: 4 | 6 | 'both';
+    /** Allow CIDR notation (default: false) */
+    allowCidr?: boolean;
+    /** Allow private/local IPs (default: true) */
+    allowPrivate?: boolean;
+    /** Custom error messages */
+    messages?: {
+        required?: string;
+        invalidFormat?: string;
+        versionNotAllowed?: string;
+        privateNotAllowed?: string;
+    };
+}
+/**
+ * IP validation result
+ */
+interface IpValidationResult {
+    /** Whether IP is valid */
+    isValid: boolean;
+    /** Validation errors */
+    errors: IValidationError[];
+    /** IP version (4 or 6) */
+    version: 4 | 6 | null;
+    /** Whether IP is private/local */
+    isPrivate: boolean;
+    /** Whether IP is loopback */
+    isLoopback: boolean;
+    /** CIDR prefix if present */
+    cidr: number | null;
+    /** Normalized IP */
+    normalized: string;
+}
+/**
+ * Validate an IP address
+ *
+ * @param ip - IP address to validate
+ * @param options - Validation options
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const result = validateIp('192.168.1.1');
+ * if (result.isValid) {
+ *   console.log('IP version:', result.version); // 4
+ *   console.log('Is private:', result.isPrivate); // true
+ * }
+ * ```
+ */
+declare function validateIp(ip: string, options?: IpOptions): IpValidationResult;
+/**
+ * Simple IPv4 validation
+ *
+ * @param ip - IP address to validate
+ * @returns true if valid IPv4
+ */
+declare function isValidIPv4(ip: string): boolean;
+/**
+ * Simple IPv6 validation
+ *
+ * @param ip - IP address to validate
+ * @returns true if valid IPv6
+ */
+declare function isValidIPv6(ip: string): boolean;
+/**
+ * Check if IP is valid (v4 or v6)
+ *
+ * @param ip - IP address to validate
+ * @returns true if valid
+ */
+declare function isValidIP(ip: string): boolean;
+/**
+ * Check if IP is private
+ *
+ * @param ip - IP address to check
+ * @param version - IP version (auto-detect if not provided)
+ * @returns true if private
+ */
+declare function isPrivateIp(ip: string, version?: 4 | 6): boolean;
+/**
+ * Check if IP is loopback
+ *
+ * @param ip - IP address to check
+ * @param version - IP version
+ * @returns true if loopback
+ */
+declare function isLoopbackIp(ip: string, version?: 4 | 6): boolean;
+/**
+ * Get IP version
+ *
+ * @param ip - IP address
+ * @returns 4, 6, or null
+ */
+declare function getIpVersion(ip: string): 4 | 6 | null;
+/**
+ * Validate CIDR notation
+ *
+ * @param cidr - CIDR string (e.g., "192.168.1.0/24")
+ * @returns true if valid CIDR
+ */
+declare function isValidCidr(cidr: string): boolean;
+
+/**
+ * Financial validation module
+ * Includes IBAN and VAT validation
+ *
+ * @packageDocumentation
+ * @since 1.0.0
+ */
+
+/**
+ * IBAN validation options
+ */
+interface IbanOptions {
+    /** Custom error messages */
+    messages?: {
+        invalidFormat?: string;
+        invalidLength?: string;
+        invalidChecksum?: string;
+    };
+}
+/**
+ * VAT validation options
+ */
+interface VatOptions {
+    /** Country code (e.g. 'GB', 'DE') */
+    countryCode?: string;
+}
+/**
+ * Validate International Bank Account Number (IBAN)
+ * Supports all SEPA and SWIFT IBAN formats
+ *
+ * @param iban - IBAN string
+ * @param options - Validation options
+ * @returns Validation result
+ */
+declare function validateIBAN(iban: string, options?: IbanOptions): {
+    isValid: boolean;
+    errors: IValidationError[];
+};
+/**
+ * Validate VAT number (Simplified regex-based check)
+ *
+ * @param vat - VAT number
+ * @param options - Validation options
+ * @returns Validation result
+ */
+declare function validateVAT(vat: string, options?: VatOptions): {
+    isValid: boolean;
+    errors: IValidationError[];
+};
+
+export { isValidIPv4 as $, suggestUsernames as A, validateUrl as B, isValidUrl as C, isHttpsUrl as D, type EmailOptions as E, getUrlDomain as F, normalizeUrl as G, isDataUrl as H, isDangerousUrl as I, type UrlOptions as J, type UrlValidationResult as K, validateCreditCard as L, isValidCreditCard as M, type NameOptions as N, detectCardType as O, type PhoneOptions as P, getCardTypeFromPrefix as Q, luhnCheck as R, maskCardNumber as S, formatCardNumber as T, type UserData as U, isValidCVV as V, isValidExpiry as W, type CreditCardOptions as X, type CreditCardValidationResult as Y, type CardType as Z, validateIp as _, type UserValidationOptions as a, isValidIPv6 as a0, isValidIP as a1, isPrivateIp as a2, isLoopbackIp as a3, getIpVersion as a4, isValidCidr as a5, type IpOptions as a6, type IpValidationResult as a7, validateIBAN as a8, validateVAT as a9, type IbanOptions as aa, type VatOptions as ab, type UserValidationResult as b, type NameValidationResult as c, type EmailValidationResult as d, type PhoneValidationResult as e, type UsernameOptions as f, type UsernameValidationResult as g, isDisposableEmail as h, isValidEmail as i, getEmailDomain as j, validateName as k, isValidName as l, detectScript as m, normalizeEmail as n, formatName as o, splitName as p, validatePhone as q, isValidPhone as r, sanitizeName as s, formatPhone as t, parsePhone as u, validateEmail as v, validateUsername as w, isValidUsername as x, isReservedUsername as y, sanitizeUsername as z };