@samline/formatter 1.0.1 → 1.1.0

package/dist/index.d.cts

@@ -111,7 +111,93 @@ declare const format: (value: unknown, formatType: FormatType, options?: FormatO
  */
 declare const formatPhone: (value: string, country?: string, delimiter?: string) => string;
 
-declare const regex: {
+/**
+ * # Regex Module
+ *
+ * Validation patterns exposed as public API for form consumers that pair
+ * formatting with validation. Each entry bundles the regex with a ready-to-use
+ * error message so consumers do not have to keep them in sync.
+ *
+ * ## Usage
+ *
+ * **Static (backward compatible):**
+ * ```ts
+ * regex.phone.pattern.test('5512345678')  // true
+ * regex.email.errorMessage                // 'Please enter a valid email address.'
+ * ```
+ *
+ * **Parametric (dynamic):**
+ * ```ts
+ * regex.digits(10).pattern.test('1234567890')  // true
+ * regex.digits(7).pattern.test('1234567')      // true
+ * regex.phone({ length: 10 }).pattern.test('1234567890')
+ * regex.phone({ length: 7 }).pattern.test('1234567')
+ * ```
+ *
+ * **Custom regex:**
+ * ```ts
+ * regex.custom(/^[A-Z]{5}$/, 'Must be 5 uppercase letters').pattern.test('HELLO')
+ * ```
+ *
+ * ## Available Patterns
+ *
+ * | Key | Static | Parametric | Description |
+ * | --- | --- | --- | --- |
+ * | `phone` | ✅ | ✅ `({ length })` | Phone numbers |
+ * | `email` | ✅ | — | Email addresses |
+ * | `rfc` | ✅ | — | Mexican RFC |
+ * | `curp` | ✅ | — | Mexican CURP |
+ * | `cp` | ✅ | — | Mexican postal code (5 digits) |
+ * | `numeral` | ✅ | — | Numbers with separators |
+ * | `onlyNumbers` | ✅ | ✅ `({ length })` | Digits only |
+ * | `digits` | — | ✅ `({ length, min, max })` | Variable digit count |
+ * | `creditCard` | ✅ | ✅ `({ min, max })` | Card numbers |
+ * | `expirationDate` | ✅ | — | MM/YY format |
+ * | `cardCvc` | ✅ | — | 3-4 digit CVC |
+ * | `onlyLetters` | ✅ | — | Letters only |
+ * | `onlyAlphanumeric` | ✅ | — | Letters and numbers |
+ * | `url` | ✅ | ✅ `({ protocol })` | URLs |
+ * | `ipv4` | ✅ | — | IPv4 addresses |
+ * | `ipv6` | ✅ | — | IPv6 addresses |
+ * | `uuid` | ✅ | — | UUID v4 |
+ * | `hexColor` | ✅ | — | Hex color codes |
+ * | `hashtag` | ✅ | — | Social media hashtags |
+ * | `mention` | ✅ | — | Social media mentions |
+ * | `password` | — | ✅ `({ min, max, rules })` | Password strength |
+ * | `custom` | — | ✅ `({ pattern, errorMessage })` | User-defined regex |
+ */
+interface RegexEntry {
+    pattern: RegExp;
+    errorMessage: string;
+}
+interface PhoneParams {
+    length?: number;
+}
+interface DigitsParams {
+    length?: number;
+    min?: number;
+    max?: number;
+}
+interface CreditCardParams {
+    min?: number;
+    max?: number;
+}
+interface UrlParams {
+    protocol?: 'http' | 'https' | 'ftp' | 'all';
+}
+interface PasswordParams {
+    min?: number;
+    max?: number;
+    uppercase?: boolean;
+    lowercase?: boolean;
+    numbers?: boolean;
+    special?: boolean;
+}
+interface CustomParams {
+    pattern: RegExp;
+    errorMessage: string;
+}
+declare const _regex: {
     readonly phone: {
         readonly pattern: RegExp;
         readonly errorMessage: "Please enter a valid 10-digit phone number.";
@@ -124,6 +210,14 @@ declare const regex: {
         readonly pattern: RegExp;
         readonly errorMessage: "Please enter a valid RFC.";
     };
+    readonly curp: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid CURP.";
+    };
+    readonly cp: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid 5-digit postal code.";
+    };
     readonly numeral: {
         readonly pattern: RegExp;
         readonly errorMessage: "Please enter a valid number.";
@@ -134,15 +228,174 @@ declare const regex: {
     };
     readonly creditCard: {
         readonly pattern: RegExp;
-        readonly errorMessage: "Please enter a valid card number.";
+        readonly errorMessage: "Please enter a valid card number (15-16 digits).";
+    };
+    readonly expirationDate: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid expiration date (MM/YY or MM/YYYY).";
+    };
+    readonly cardCvc: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid CVC (3-4 digits).";
+    };
+    readonly onlyLetters: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter only letters.";
+    };
+    readonly onlyAlphanumeric: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter only letters and numbers.";
+    };
+    readonly url: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid URL.";
+    };
+    readonly ipv4: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid IPv4 address.";
+    };
+    readonly ipv6: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid IPv6 address.";
+    };
+    readonly uuid: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid UUID.";
+    };
+    readonly hexColor: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid hex color code (e.g., #FFF or #FFFFFF).";
+    };
+    readonly hashtag: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid hashtag (e.g., #example).";
+    };
+    readonly mention: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid mention (e.g., @username).";
+    };
+    readonly postalCode: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid postal code (e.g., 90210 or 90210-1234).";
+    };
+    readonly time24: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid 24-hour time (HH:MM).";
+    };
+    readonly date: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid date (YYYY-MM-DD).";
+    };
+    readonly slug: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid slug (lowercase, hyphens, no spaces).";
+    };
+    readonly username: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid username (3-20 chars, letters, numbers, _ or -).";
+    };
+    readonly macAddress: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid MAC address (e.g., 00:1B:44:11:3A:B7).";
+    };
+    readonly semver: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid semantic version (e.g., 1.2.3).";
+    };
+    readonly base64: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid Base64 encoded string.";
+    };
+};
+/**
+ * Digits with configurable length.
+ * @example
+ * regex.digits(10).pattern.test('1234567890')     // true
+ * regex.digits({ length: 7 }).pattern.test('1234567') // true
+ * regex.digits({ min: 3, max: 10 }).pattern.test('12345') // true
+ */
+declare function digits(params?: number | DigitsParams): RegexEntry;
+/**
+ * Phone with configurable digit count.
+ *
+ * Also available as static entry: regex.phone.pattern (10 digits)
+ * @example
+ * regex.phone().pattern.test('5512345678')         // true (10 digits)
+ * regex.phone({ length: 7 }).pattern.test('1234567') // true (7 digits)
+ */
+declare function _phoneFn(params?: PhoneParams): RegexEntry;
+/**
+ * Credit card with configurable digit range.
+ *
+ * Also available as static entry: regex.creditCard.pattern (15-16 digits)
+ * @example
+ * regex.creditCard().pattern.test('4111111111111111')      // true (15-16)
+ * regex.creditCard({ min: 13, max: 19 }).pattern.test('1234567890123') // true
+ */
+declare function _creditCardFn(params?: CreditCardParams): RegexEntry;
+/**
+ * URL with configurable protocol.
+ *
+ * Also available as static entry: regex.url.pattern (any protocol)
+ * @example
+ * regex.url().pattern.test('https://example.com')   // true
+ * regex.url({ protocol: 'https' }).pattern.test('https://example.com') // true
+ * regex.url({ protocol: 'https' }).pattern.test('ftp://example.com')  // false
+ */
+declare function _urlFn(params?: UrlParams): RegexEntry;
+/**
+ * Password with configurable strength rules.
+ * @example
+ * regex.password().pattern.test('Passw0rd!')  // true (default: 8+ chars, upper, lower, number)
+ * regex.password({ min: 12, special: true }).pattern.test('MyP@ssw0rd!') // true
+ */
+declare function _passwordFn(params?: PasswordParams): RegexEntry;
+/**
+ * Custom regex provided by the user.
+ * @example
+ * regex.custom(/^[A-Z]{5}$/, 'Must be 5 uppercase letters').pattern.test('HELLO') // true
+ * regex.custom({ pattern: /^\d+$/, errorMessage: 'Numbers only' }).pattern.test('123') // true
+ */
+declare function _customFn(pattern: RegExp, errorMessage?: string): RegexEntry;
+declare function _customFn(params: CustomParams): RegexEntry;
+declare const regex: {
+    readonly digits: typeof digits & RegexEntry;
+    readonly phone: typeof _phoneFn & RegexEntry;
+    readonly creditCard: typeof _creditCardFn & RegexEntry;
+    readonly url: typeof _urlFn & RegexEntry;
+    readonly password: typeof _passwordFn & RegexEntry;
+    readonly custom: typeof _customFn & RegexEntry;
+    readonly email: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid email address.";
+    };
+    readonly rfc: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid RFC.";
+    };
+    readonly curp: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid CURP.";
+    };
+    readonly cp: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid 5-digit postal code.";
+    };
+    readonly numeral: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid number.";
+    };
+    readonly onlyNumbers: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter only numbers.";
     };
     readonly expirationDate: {
         readonly pattern: RegExp;
-        readonly errorMessage: "Please enter a valid expiration date.";
+        readonly errorMessage: "Please enter a valid expiration date (MM/YY or MM/YYYY).";
     };
     readonly cardCvc: {
         readonly pattern: RegExp;
-        readonly errorMessage: "Please enter a valid CVC.";
+        readonly errorMessage: "Please enter a valid CVC (3-4 digits).";
     };
     readonly onlyLetters: {
         readonly pattern: RegExp;
@@ -152,7 +405,64 @@ declare const regex: {
         readonly pattern: RegExp;
         readonly errorMessage: "Please enter only letters and numbers.";
     };
+    readonly ipv4: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid IPv4 address.";
+    };
+    readonly ipv6: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid IPv6 address.";
+    };
+    readonly uuid: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid UUID.";
+    };
+    readonly hexColor: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid hex color code (e.g., #FFF or #FFFFFF).";
+    };
+    readonly hashtag: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid hashtag (e.g., #example).";
+    };
+    readonly mention: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid mention (e.g., @username).";
+    };
+    readonly postalCode: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid postal code (e.g., 90210 or 90210-1234).";
+    };
+    readonly time24: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid 24-hour time (HH:MM).";
+    };
+    readonly date: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid date (YYYY-MM-DD).";
+    };
+    readonly slug: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid slug (lowercase, hyphens, no spaces).";
+    };
+    readonly username: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid username (3-20 chars, letters, numbers, _ or -).";
+    };
+    readonly macAddress: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid MAC address (e.g., 00:1B:44:11:3A:B7).";
+    };
+    readonly semver: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid semantic version (e.g., 1.2.3).";
+    };
+    readonly base64: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid Base64 encoded string.";
+    };
 };
-type RegexKey = keyof typeof regex;
+type RegexKey = keyof typeof _regex;
+type Regex = typeof regex;
 
-export { FORMAT_TYPES, type FormatOptions, type FormatType, type FormatterResult, type RegexKey, format, formatPhone, formatValue, getDateValueFromRaw, getRawValue, getTimeValueFromRaw, getValueForFormatting, isFormatType, regex, resolveRuntimeOptions, stripPrefixAndSuffix };
+export { FORMAT_TYPES, type FormatOptions, type FormatType, type FormatterResult, type Regex, type RegexEntry, type RegexKey, format, formatPhone, formatValue, getDateValueFromRaw, getRawValue, getTimeValueFromRaw, getValueForFormatting, isFormatType, regex, resolveRuntimeOptions, stripPrefixAndSuffix };