@indodev/toolkit 0.6.0 → 0.7.0

package/dist/email-validator/index.cjs

@@ -73,8 +73,18 @@ function normalizeEmail(email) {
   return email.trim().toLowerCase();
 }
 
+// src/email-validator/errors.ts
+var InvalidEmailError = class extends Error {
+  constructor(message = "Invalid email provided") {
+    super(message);
+    this.code = "INVALID_EMAIL";
+    this.name = "InvalidEmailError";
+  }
+};
+
 exports.DISPOSABLE_DOMAINS = DISPOSABLE_DOMAINS;
 exports.EMAIL_REGEX = EMAIL_REGEX;
+exports.InvalidEmailError = InvalidEmailError;
 exports.getEmailInfo = getEmailInfo;
 exports.maskEmail = maskEmail;
 exports.normalizeEmail = normalizeEmail;

package/dist/email-validator/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/email-validator/constants.ts","../../src/email-validator/email-validator.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Regular expression for standard email validation.\n * Optimized for RFC 5322 compliance.\n */\nexport const EMAIL_REGEX = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,253}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,253}[a-zA-Z0-9])?)*$/;\n\n/**\n * Common disposable email domains to block if needed.\n */\nexport const DISPOSABLE_DOMAINS = [\n  'mailinator.com',\n  '10minutemail.com',\n  'temp-mail.org',\n  'guerrillamail.com',\n];\n","import { EMAIL_REGEX, DISPOSABLE_DOMAINS } from './constants';\nimport type { EmailValidationOptions, EmailMaskOptions, EmailInfo } from './types';\n\n/**\n * List of common global email providers.\n */\nconst COMMON_PROVIDERS = ['gmail.com', 'yahoo.com', 'outlook.com', 'hotmail.com', 'icloud.com'];\n\n/**\n * The maximum length of an email address according to RFC 5321.\n */\nconst MAX_EMAIL_LENGTH = 254;\n\n/**\n * Validates if a string is a properly formatted email address based on RFC 5322.\n * \n * Performs checks for:\n * - Proper email format (regex).\n * - RFC specific rules (no double dots, username length < 64).\n * - Maximum total length (254 characters).\n * - Optional: disposable email detection.\n * \n * @param email - The email string to validate.\n * @param options - Optional validation configuration.\n * @returns `true` if valid, `false` otherwise.\n * \n * @example\n * ```typescript\n * import { validateEmail } from '@indodev/toolkit/email-validator';\n * \n * validateEmail('user@example.com'); // true\n * validateEmail('invalid-email'); // false\n * validateEmail('spam@mailinator.com', { blockDisposable: true }); // false\n * ```\n */\nexport function validateEmail(email: string, options?: EmailValidationOptions): boolean {\n  if (!email || typeof email !== 'string') {\n    return false;\n  }\n\n  const trimmedEmail = email.trim().toLowerCase();\n\n  if (trimmedEmail.length > MAX_EMAIL_LENGTH) {\n    return false;\n  }\n\n  const parts = trimmedEmail.split('@');\n  if (parts.length !== 2) {\n    return false;\n  }\n\n  const [username, domain] = parts;\n\n  if (!username || !domain) {\n    return false;\n  }\n\n  if (username.length > 64) {\n    return false;\n  }\n\n  if (\n    username.includes('..') ||\n    username.startsWith('.') ||\n    username.endsWith('.') ||\n    domain.startsWith('.') ||\n    domain.endsWith('.') ||\n    domain.includes('..')\n  ) {\n    return false;\n  }\n\n  if (!EMAIL_REGEX.test(trimmedEmail)) {\n    return false;\n  }\n\n  if (options?.blockDisposable) {\n    if (DISPOSABLE_DOMAINS.includes(domain)) {\n      return false;\n    }\n  }\n\n  return true;\n}\n\n/**\n * Parses an email address to extract useful metadata.\n * \n * @param email - The email address to parse.\n * @returns `EmailInfo` object containing details or `null` if the email is invalid.\n * \n * @example\n * ```typescript\n * import { getEmailInfo } from '@indodev/toolkit/email-validator';\n * \n * const info = getEmailInfo('adam@gmail.com');\n * // { username: 'adam', domain: 'gmail.com', isCommonProvider: true, isDisposable: false }\n * ```\n */\nexport function getEmailInfo(email: string): EmailInfo | null {\n  if (!validateEmail(email)) return null;\n\n  const [username, domain] = email.trim().toLowerCase().split('@');\n\n  return {\n    username,\n    domain,\n    isCommonProvider: COMMON_PROVIDERS.includes(domain),\n    isDisposable: DISPOSABLE_DOMAINS.includes(domain),\n  };\n}\n\n/**\n * Masks the username portion of an email for privacy protection.\n * \n * Falls back to a standard mask if the username is too short to respect visibleStart/visibleEnd.\n * \n * @param email - The email address to mask.\n * @param options - Optional masking configuration.\n * @returns Masked email string or original if invalid.\n * \n * @example\n * ```typescript\n * import { maskEmail } from '@indodev/toolkit/email-validator';\n * \n * maskEmail('user@example.com'); // 'u**r@example.com'\n * maskEmail('user@example.com', { maskChar: '#' }); // 'u##r@example.com'\n * ```\n */\nexport function maskEmail(email: string, options?: EmailMaskOptions): string {\n  if (!validateEmail(email)) return email;\n\n  const { visibleStart = 1, visibleEnd = 1, maskChar = '*' } = options || {};\n  const [username, domain] = email.split('@');\n\n  // Fallback for very short usernames\n  if (username.length <= 3) {\n    return `${username[0]}${maskChar.repeat(3)}@${domain}`;\n  }\n\n  // Calculate masked length\n  const maskedLength = username.length - (visibleStart + visibleEnd);\n\n  // If the result of masking would be empty or negative, use fallback\n  if (maskedLength <= 0) {\n    return `${username[0]}${maskChar.repeat(3)}@${domain}`;\n  }\n\n  const start = username.slice(0, visibleStart);\n  const end = username.slice(username.length - visibleEnd);\n\n  return `${start}${maskChar.repeat(maskedLength)}${end}@${domain}`;\n}\n\n/**\n * Normalizes an email address by trimming whitespace and converting to lowercase.\n * \n * @param email - The email to normalize.\n * @returns Normalized email string.\n * \n * @example\n * ```typescript\n * import { normalizeEmail } from '@indodev/toolkit/email-validator';\n * \n * normalizeEmail('  USER@Example.COM  '); // 'user@example.com'\n * ```\n */\nexport function normalizeEmail(email: string): string {\n  return email.trim().toLowerCase();\n}\n"]}
+{"version":3,"sources":["../../src/email-validator/constants.ts","../../src/email-validator/email-validator.ts","../../src/email-validator/errors.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Regular expression for standard email validation.\n * Optimized for RFC 5322 compliance.\n */\nexport const EMAIL_REGEX = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,253}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,253}[a-zA-Z0-9])?)*$/;\n\n/**\n * Common disposable email domains to block if needed.\n */\nexport const DISPOSABLE_DOMAINS = [\n  'mailinator.com',\n  '10minutemail.com',\n  'temp-mail.org',\n  'guerrillamail.com',\n];\n","import { EMAIL_REGEX, DISPOSABLE_DOMAINS } from './constants';\nimport type { EmailValidationOptions, EmailMaskOptions, EmailInfo } from './types';\n\n/**\n * List of common global email providers.\n */\nconst COMMON_PROVIDERS = ['gmail.com', 'yahoo.com', 'outlook.com', 'hotmail.com', 'icloud.com'];\n\n/**\n * The maximum length of an email address according to RFC 5321.\n */\nconst MAX_EMAIL_LENGTH = 254;\n\n/**\n * Validates if a string is a properly formatted email address based on RFC 5322.\n * \n * Performs checks for:\n * - Proper email format (regex).\n * - RFC specific rules (no double dots, username length < 64).\n * - Maximum total length (254 characters).\n * - Optional: disposable email detection.\n * \n * @param email - The email string to validate.\n * @param options - Optional validation configuration.\n * @returns `true` if valid, `false` otherwise.\n * \n * @example\n * ```typescript\n * import { validateEmail } from '@indodev/toolkit/email-validator';\n * \n * validateEmail('user@example.com'); // true\n * validateEmail('invalid-email'); // false\n * validateEmail('spam@mailinator.com', { blockDisposable: true }); // false\n * ```\n */\nexport function validateEmail(email: string, options?: EmailValidationOptions): boolean {\n  if (!email || typeof email !== 'string') {\n    return false;\n  }\n\n  const trimmedEmail = email.trim().toLowerCase();\n\n  if (trimmedEmail.length > MAX_EMAIL_LENGTH) {\n    return false;\n  }\n\n  const parts = trimmedEmail.split('@');\n  if (parts.length !== 2) {\n    return false;\n  }\n\n  const [username, domain] = parts;\n\n  if (!username || !domain) {\n    return false;\n  }\n\n  if (username.length > 64) {\n    return false;\n  }\n\n  if (\n    username.includes('..') ||\n    username.startsWith('.') ||\n    username.endsWith('.') ||\n    domain.startsWith('.') ||\n    domain.endsWith('.') ||\n    domain.includes('..')\n  ) {\n    return false;\n  }\n\n  if (!EMAIL_REGEX.test(trimmedEmail)) {\n    return false;\n  }\n\n  if (options?.blockDisposable) {\n    if (DISPOSABLE_DOMAINS.includes(domain)) {\n      return false;\n    }\n  }\n\n  return true;\n}\n\n/**\n * Parses an email address to extract useful metadata.\n * \n * @param email - The email address to parse.\n * @returns `EmailInfo` object containing details or `null` if the email is invalid.\n * \n * @example\n * ```typescript\n * import { getEmailInfo } from '@indodev/toolkit/email-validator';\n * \n * const info = getEmailInfo('adam@gmail.com');\n * // { username: 'adam', domain: 'gmail.com', isCommonProvider: true, isDisposable: false }\n * ```\n */\nexport function getEmailInfo(email: string): EmailInfo | null {\n  if (!validateEmail(email)) return null;\n\n  const [username, domain] = email.trim().toLowerCase().split('@');\n\n  return {\n    username,\n    domain,\n    isCommonProvider: COMMON_PROVIDERS.includes(domain),\n    isDisposable: DISPOSABLE_DOMAINS.includes(domain),\n  };\n}\n\n/**\n * Masks the username portion of an email for privacy protection.\n * \n * Falls back to a standard mask if the username is too short to respect visibleStart/visibleEnd.\n * \n * @param email - The email address to mask.\n * @param options - Optional masking configuration.\n * @returns Masked email string or original if invalid.\n * \n * @example\n * ```typescript\n * import { maskEmail } from '@indodev/toolkit/email-validator';\n * \n * maskEmail('user@example.com'); // 'u**r@example.com'\n * maskEmail('user@example.com', { maskChar: '#' }); // 'u##r@example.com'\n * ```\n */\nexport function maskEmail(email: string, options?: EmailMaskOptions): string {\n  if (!validateEmail(email)) return email;\n\n  const { visibleStart = 1, visibleEnd = 1, maskChar = '*' } = options || {};\n  const [username, domain] = email.split('@');\n\n  // Fallback for very short usernames\n  if (username.length <= 3) {\n    return `${username[0]}${maskChar.repeat(3)}@${domain}`;\n  }\n\n  // Calculate masked length\n  const maskedLength = username.length - (visibleStart + visibleEnd);\n\n  // If the result of masking would be empty or negative, use fallback\n  if (maskedLength <= 0) {\n    return `${username[0]}${maskChar.repeat(3)}@${domain}`;\n  }\n\n  const start = username.slice(0, visibleStart);\n  const end = username.slice(username.length - visibleEnd);\n\n  return `${start}${maskChar.repeat(maskedLength)}${end}@${domain}`;\n}\n\n/**\n * Normalizes an email address by trimming whitespace and converting to lowercase.\n * \n * @param email - The email to normalize.\n * @returns Normalized email string.\n * \n * @example\n * ```typescript\n * import { normalizeEmail } from '@indodev/toolkit/email-validator';\n * \n * normalizeEmail('  USER@Example.COM  '); // 'user@example.com'\n * ```\n */\nexport function normalizeEmail(email: string): string {\n  return email.trim().toLowerCase();\n}\n","/**\n * Error thrown when an invalid email is provided to a function.\n * Extends native Error with a `code` property for programmatic error handling.\n *\n * @example\n * ```typescript\n * try {\n *   requireEmail('invalid');\n * } catch (error) {\n *   if (error instanceof InvalidEmailError) {\n *     console.log(error.code); // 'INVALID_EMAIL'\n *   }\n * }\n * ```\n *\n * @public\n */\nexport class InvalidEmailError extends Error {\n  readonly code = 'INVALID_EMAIL' as const;\n\n  constructor(message: string = 'Invalid email provided') {\n    super(message);\n    this.name = 'InvalidEmailError';\n  }\n}\n"]}

package/dist/email-validator/index.d.cts

@@ -1,4 +1,4 @@
-export { c as EmailInfo, b as EmailMaskOptions, E as EmailValidationOptions, a as EmailValidationResult, g as getEmailInfo, m as maskEmail, n as normalizeEmail, v as validateEmail } from '../email-validator-R9L5unIw.cjs';
+export { c as EmailInfo, b as EmailMaskOptions, E as EmailValidationOptions, a as EmailValidationResult, I as InvalidEmailError, g as getEmailInfo, m as maskEmail, n as normalizeEmail, v as validateEmail } from '../errors-DdutHLae.cjs';
 
 /**
  * Regular expression for standard email validation.

package/dist/email-validator/index.d.ts

@@ -1,4 +1,4 @@
-export { c as EmailInfo, b as EmailMaskOptions, E as EmailValidationOptions, a as EmailValidationResult, g as getEmailInfo, m as maskEmail, n as normalizeEmail, v as validateEmail } from '../email-validator-R9L5unIw.js';
+export { c as EmailInfo, b as EmailMaskOptions, E as EmailValidationOptions, a as EmailValidationResult, I as InvalidEmailError, g as getEmailInfo, m as maskEmail, n as normalizeEmail, v as validateEmail } from '../errors-DdutHLae.js';
 
 /**
  * Regular expression for standard email validation.

package/dist/email-validator/index.js

@@ -71,6 +71,15 @@ function normalizeEmail(email) {
   return email.trim().toLowerCase();
 }
 
-export { DISPOSABLE_DOMAINS, EMAIL_REGEX, getEmailInfo, maskEmail, normalizeEmail, validateEmail };
+// src/email-validator/errors.ts
+var InvalidEmailError = class extends Error {
+  constructor(message = "Invalid email provided") {
+    super(message);
+    this.code = "INVALID_EMAIL";
+    this.name = "InvalidEmailError";
+  }
+};
+
+export { DISPOSABLE_DOMAINS, EMAIL_REGEX, InvalidEmailError, getEmailInfo, maskEmail, normalizeEmail, validateEmail };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/email-validator/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/email-validator/constants.ts","../../src/email-validator/email-validator.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Regular expression for standard email validation.\n * Optimized for RFC 5322 compliance.\n */\nexport const EMAIL_REGEX = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,253}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,253}[a-zA-Z0-9])?)*$/;\n\n/**\n * Common disposable email domains to block if needed.\n */\nexport const DISPOSABLE_DOMAINS = [\n  'mailinator.com',\n  '10minutemail.com',\n  'temp-mail.org',\n  'guerrillamail.com',\n];\n","import { EMAIL_REGEX, DISPOSABLE_DOMAINS } from './constants';\nimport type { EmailValidationOptions, EmailMaskOptions, EmailInfo } from './types';\n\n/**\n * List of common global email providers.\n */\nconst COMMON_PROVIDERS = ['gmail.com', 'yahoo.com', 'outlook.com', 'hotmail.com', 'icloud.com'];\n\n/**\n * The maximum length of an email address according to RFC 5321.\n */\nconst MAX_EMAIL_LENGTH = 254;\n\n/**\n * Validates if a string is a properly formatted email address based on RFC 5322.\n * \n * Performs checks for:\n * - Proper email format (regex).\n * - RFC specific rules (no double dots, username length < 64).\n * - Maximum total length (254 characters).\n * - Optional: disposable email detection.\n * \n * @param email - The email string to validate.\n * @param options - Optional validation configuration.\n * @returns `true` if valid, `false` otherwise.\n * \n * @example\n * ```typescript\n * import { validateEmail } from '@indodev/toolkit/email-validator';\n * \n * validateEmail('user@example.com'); // true\n * validateEmail('invalid-email'); // false\n * validateEmail('spam@mailinator.com', { blockDisposable: true }); // false\n * ```\n */\nexport function validateEmail(email: string, options?: EmailValidationOptions): boolean {\n  if (!email || typeof email !== 'string') {\n    return false;\n  }\n\n  const trimmedEmail = email.trim().toLowerCase();\n\n  if (trimmedEmail.length > MAX_EMAIL_LENGTH) {\n    return false;\n  }\n\n  const parts = trimmedEmail.split('@');\n  if (parts.length !== 2) {\n    return false;\n  }\n\n  const [username, domain] = parts;\n\n  if (!username || !domain) {\n    return false;\n  }\n\n  if (username.length > 64) {\n    return false;\n  }\n\n  if (\n    username.includes('..') ||\n    username.startsWith('.') ||\n    username.endsWith('.') ||\n    domain.startsWith('.') ||\n    domain.endsWith('.') ||\n    domain.includes('..')\n  ) {\n    return false;\n  }\n\n  if (!EMAIL_REGEX.test(trimmedEmail)) {\n    return false;\n  }\n\n  if (options?.blockDisposable) {\n    if (DISPOSABLE_DOMAINS.includes(domain)) {\n      return false;\n    }\n  }\n\n  return true;\n}\n\n/**\n * Parses an email address to extract useful metadata.\n * \n * @param email - The email address to parse.\n * @returns `EmailInfo` object containing details or `null` if the email is invalid.\n * \n * @example\n * ```typescript\n * import { getEmailInfo } from '@indodev/toolkit/email-validator';\n * \n * const info = getEmailInfo('adam@gmail.com');\n * // { username: 'adam', domain: 'gmail.com', isCommonProvider: true, isDisposable: false }\n * ```\n */\nexport function getEmailInfo(email: string): EmailInfo | null {\n  if (!validateEmail(email)) return null;\n\n  const [username, domain] = email.trim().toLowerCase().split('@');\n\n  return {\n    username,\n    domain,\n    isCommonProvider: COMMON_PROVIDERS.includes(domain),\n    isDisposable: DISPOSABLE_DOMAINS.includes(domain),\n  };\n}\n\n/**\n * Masks the username portion of an email for privacy protection.\n * \n * Falls back to a standard mask if the username is too short to respect visibleStart/visibleEnd.\n * \n * @param email - The email address to mask.\n * @param options - Optional masking configuration.\n * @returns Masked email string or original if invalid.\n * \n * @example\n * ```typescript\n * import { maskEmail } from '@indodev/toolkit/email-validator';\n * \n * maskEmail('user@example.com'); // 'u**r@example.com'\n * maskEmail('user@example.com', { maskChar: '#' }); // 'u##r@example.com'\n * ```\n */\nexport function maskEmail(email: string, options?: EmailMaskOptions): string {\n  if (!validateEmail(email)) return email;\n\n  const { visibleStart = 1, visibleEnd = 1, maskChar = '*' } = options || {};\n  const [username, domain] = email.split('@');\n\n  // Fallback for very short usernames\n  if (username.length <= 3) {\n    return `${username[0]}${maskChar.repeat(3)}@${domain}`;\n  }\n\n  // Calculate masked length\n  const maskedLength = username.length - (visibleStart + visibleEnd);\n\n  // If the result of masking would be empty or negative, use fallback\n  if (maskedLength <= 0) {\n    return `${username[0]}${maskChar.repeat(3)}@${domain}`;\n  }\n\n  const start = username.slice(0, visibleStart);\n  const end = username.slice(username.length - visibleEnd);\n\n  return `${start}${maskChar.repeat(maskedLength)}${end}@${domain}`;\n}\n\n/**\n * Normalizes an email address by trimming whitespace and converting to lowercase.\n * \n * @param email - The email to normalize.\n * @returns Normalized email string.\n * \n * @example\n * ```typescript\n * import { normalizeEmail } from '@indodev/toolkit/email-validator';\n * \n * normalizeEmail('  USER@Example.COM  '); // 'user@example.com'\n * ```\n */\nexport function normalizeEmail(email: string): string {\n  return email.trim().toLowerCase();\n}\n"]}
+{"version":3,"sources":["../../src/email-validator/constants.ts","../../src/email-validator/email-validator.ts","../../src/email-validator/errors.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Regular expression for standard email validation.\n * Optimized for RFC 5322 compliance.\n */\nexport const EMAIL_REGEX = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,253}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,253}[a-zA-Z0-9])?)*$/;\n\n/**\n * Common disposable email domains to block if needed.\n */\nexport const DISPOSABLE_DOMAINS = [\n  'mailinator.com',\n  '10minutemail.com',\n  'temp-mail.org',\n  'guerrillamail.com',\n];\n","import { EMAIL_REGEX, DISPOSABLE_DOMAINS } from './constants';\nimport type { EmailValidationOptions, EmailMaskOptions, EmailInfo } from './types';\n\n/**\n * List of common global email providers.\n */\nconst COMMON_PROVIDERS = ['gmail.com', 'yahoo.com', 'outlook.com', 'hotmail.com', 'icloud.com'];\n\n/**\n * The maximum length of an email address according to RFC 5321.\n */\nconst MAX_EMAIL_LENGTH = 254;\n\n/**\n * Validates if a string is a properly formatted email address based on RFC 5322.\n * \n * Performs checks for:\n * - Proper email format (regex).\n * - RFC specific rules (no double dots, username length < 64).\n * - Maximum total length (254 characters).\n * - Optional: disposable email detection.\n * \n * @param email - The email string to validate.\n * @param options - Optional validation configuration.\n * @returns `true` if valid, `false` otherwise.\n * \n * @example\n * ```typescript\n * import { validateEmail } from '@indodev/toolkit/email-validator';\n * \n * validateEmail('user@example.com'); // true\n * validateEmail('invalid-email'); // false\n * validateEmail('spam@mailinator.com', { blockDisposable: true }); // false\n * ```\n */\nexport function validateEmail(email: string, options?: EmailValidationOptions): boolean {\n  if (!email || typeof email !== 'string') {\n    return false;\n  }\n\n  const trimmedEmail = email.trim().toLowerCase();\n\n  if (trimmedEmail.length > MAX_EMAIL_LENGTH) {\n    return false;\n  }\n\n  const parts = trimmedEmail.split('@');\n  if (parts.length !== 2) {\n    return false;\n  }\n\n  const [username, domain] = parts;\n\n  if (!username || !domain) {\n    return false;\n  }\n\n  if (username.length > 64) {\n    return false;\n  }\n\n  if (\n    username.includes('..') ||\n    username.startsWith('.') ||\n    username.endsWith('.') ||\n    domain.startsWith('.') ||\n    domain.endsWith('.') ||\n    domain.includes('..')\n  ) {\n    return false;\n  }\n\n  if (!EMAIL_REGEX.test(trimmedEmail)) {\n    return false;\n  }\n\n  if (options?.blockDisposable) {\n    if (DISPOSABLE_DOMAINS.includes(domain)) {\n      return false;\n    }\n  }\n\n  return true;\n}\n\n/**\n * Parses an email address to extract useful metadata.\n * \n * @param email - The email address to parse.\n * @returns `EmailInfo` object containing details or `null` if the email is invalid.\n * \n * @example\n * ```typescript\n * import { getEmailInfo } from '@indodev/toolkit/email-validator';\n * \n * const info = getEmailInfo('adam@gmail.com');\n * // { username: 'adam', domain: 'gmail.com', isCommonProvider: true, isDisposable: false }\n * ```\n */\nexport function getEmailInfo(email: string): EmailInfo | null {\n  if (!validateEmail(email)) return null;\n\n  const [username, domain] = email.trim().toLowerCase().split('@');\n\n  return {\n    username,\n    domain,\n    isCommonProvider: COMMON_PROVIDERS.includes(domain),\n    isDisposable: DISPOSABLE_DOMAINS.includes(domain),\n  };\n}\n\n/**\n * Masks the username portion of an email for privacy protection.\n * \n * Falls back to a standard mask if the username is too short to respect visibleStart/visibleEnd.\n * \n * @param email - The email address to mask.\n * @param options - Optional masking configuration.\n * @returns Masked email string or original if invalid.\n * \n * @example\n * ```typescript\n * import { maskEmail } from '@indodev/toolkit/email-validator';\n * \n * maskEmail('user@example.com'); // 'u**r@example.com'\n * maskEmail('user@example.com', { maskChar: '#' }); // 'u##r@example.com'\n * ```\n */\nexport function maskEmail(email: string, options?: EmailMaskOptions): string {\n  if (!validateEmail(email)) return email;\n\n  const { visibleStart = 1, visibleEnd = 1, maskChar = '*' } = options || {};\n  const [username, domain] = email.split('@');\n\n  // Fallback for very short usernames\n  if (username.length <= 3) {\n    return `${username[0]}${maskChar.repeat(3)}@${domain}`;\n  }\n\n  // Calculate masked length\n  const maskedLength = username.length - (visibleStart + visibleEnd);\n\n  // If the result of masking would be empty or negative, use fallback\n  if (maskedLength <= 0) {\n    return `${username[0]}${maskChar.repeat(3)}@${domain}`;\n  }\n\n  const start = username.slice(0, visibleStart);\n  const end = username.slice(username.length - visibleEnd);\n\n  return `${start}${maskChar.repeat(maskedLength)}${end}@${domain}`;\n}\n\n/**\n * Normalizes an email address by trimming whitespace and converting to lowercase.\n * \n * @param email - The email to normalize.\n * @returns Normalized email string.\n * \n * @example\n * ```typescript\n * import { normalizeEmail } from '@indodev/toolkit/email-validator';\n * \n * normalizeEmail('  USER@Example.COM  '); // 'user@example.com'\n * ```\n */\nexport function normalizeEmail(email: string): string {\n  return email.trim().toLowerCase();\n}\n","/**\n * Error thrown when an invalid email is provided to a function.\n * Extends native Error with a `code` property for programmatic error handling.\n *\n * @example\n * ```typescript\n * try {\n *   requireEmail('invalid');\n * } catch (error) {\n *   if (error instanceof InvalidEmailError) {\n *     console.log(error.code); // 'INVALID_EMAIL'\n *   }\n * }\n * ```\n *\n * @public\n */\nexport class InvalidEmailError extends Error {\n  readonly code = 'INVALID_EMAIL' as const;\n\n  constructor(message: string = 'Invalid email provided') {\n    super(message);\n    this.name = 'InvalidEmailError';\n  }\n}\n"]}

package/dist/{parse-BmmsNlJt.d.cts → errors--47zprcf.d.cts}

@@ -194,14 +194,14 @@ interface PhoneInfo {
  * @example
  * Default masking:
  * ```typescript
- * { start: 4, end: 4, char: '*' }
+ * { visibleStart: 4, visibleEnd: 4, maskChar: '*' }
  * // '0812****7890'
  * ```
  *
  * @example
  * With separator:
  * ```typescript
- * { start: 4, end: 4, char: '*', separator: '-' }
+ * { visibleStart: 4, visibleEnd: 4, maskChar: '*', separator: '-' }
  * // '0812-****-7890'
  * ```
  *
@@ -213,25 +213,37 @@ interface MaskOptions {
      *
      * @defaultValue 4
      */
-    start?: number;
+    visibleStart?: number;
     /**
      * Number of digits to show at the end.
      *
      * @defaultValue 4
      */
-    end?: number;
+    visibleEnd?: number;
     /**
      * Character to use for masking hidden digits.
      *
      * @defaultValue '*'
      */
-    char?: string;
+    maskChar?: string;
     /**
      * Optional separator to add between groups of digits.
      *
      * @defaultValue undefined
      */
     separator?: string;
+    /**
+     * @deprecated Use `visibleStart` instead. Deprecated in v0.7.0.
+     */
+    start?: number;
+    /**
+     * @deprecated Use `visibleEnd` instead. Deprecated in v0.7.0.
+     */
+    end?: number;
+    /**
+     * @deprecated Use `maskChar` instead. Deprecated in v0.7.0.
+     */
+    char?: string;
 }
 
 /**
@@ -378,7 +390,7 @@ declare function cleanPhoneNumber(phone: string): string;
  * @example
  * Custom mask character:
  * ```typescript
- * maskPhoneNumber('081234567890', { char: 'X' });
+ * maskPhoneNumber('081234567890', { maskChar: 'X' });
  * // '0812XXXX7890'
  * ```
  *
@@ -555,4 +567,26 @@ declare function getOperator(phone: string): OperatorName | null;
  */
 declare function isProvider(phone: string, providerName: string): boolean;
 
-export { type MaskOptions as M, type OperatorName as O, type PhoneFormat as P, isLandlineNumber as a, toNational as b, toE164 as c, cleanPhoneNumber as d, generateWALink as e, formatPhoneNumber as f, getOperator as g, generateSmsLink as h, isMobileNumber as i, generateTelLink as j, isProvider as k, type PhoneInfo as l, maskPhoneNumber as m, parsePhoneNumber as p, toInternational as t, validatePhoneNumber as v };
+/**
+ * Error thrown when an invalid phone number is provided to a function.
+ * Extends native Error with a `code` property for programmatic error handling.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   requirePhone('invalid');
+ * } catch (error) {
+ *   if (error instanceof InvalidPhoneError) {
+ *     console.log(error.code); // 'INVALID_PHONE'
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+declare class InvalidPhoneError extends Error {
+    readonly code: "INVALID_PHONE";
+    constructor(message?: string);
+}
+
+export { InvalidPhoneError as I, type MaskOptions as M, type OperatorName as O, type PhoneFormat as P, isLandlineNumber as a, toNational as b, toE164 as c, cleanPhoneNumber as d, generateWALink as e, formatPhoneNumber as f, getOperator as g, generateSmsLink as h, isMobileNumber as i, generateTelLink as j, isProvider as k, type PhoneInfo as l, maskPhoneNumber as m, parsePhoneNumber as p, toInternational as t, validatePhoneNumber as v };

package/dist/{parse-BmmsNlJt.d.ts → errors--47zprcf.d.ts}

@@ -194,14 +194,14 @@ interface PhoneInfo {
  * @example
  * Default masking:
  * ```typescript
- * { start: 4, end: 4, char: '*' }
+ * { visibleStart: 4, visibleEnd: 4, maskChar: '*' }
  * // '0812****7890'
  * ```
  *
  * @example
  * With separator:
  * ```typescript
- * { start: 4, end: 4, char: '*', separator: '-' }
+ * { visibleStart: 4, visibleEnd: 4, maskChar: '*', separator: '-' }
  * // '0812-****-7890'
  * ```
  *
@@ -213,25 +213,37 @@ interface MaskOptions {
      *
      * @defaultValue 4
      */
-    start?: number;
+    visibleStart?: number;
     /**
      * Number of digits to show at the end.
      *
      * @defaultValue 4
      */
-    end?: number;
+    visibleEnd?: number;
     /**
      * Character to use for masking hidden digits.
      *
      * @defaultValue '*'
      */
-    char?: string;
+    maskChar?: string;
     /**
      * Optional separator to add between groups of digits.
      *
      * @defaultValue undefined
      */
     separator?: string;
+    /**
+     * @deprecated Use `visibleStart` instead. Deprecated in v0.7.0.
+     */
+    start?: number;
+    /**
+     * @deprecated Use `visibleEnd` instead. Deprecated in v0.7.0.
+     */
+    end?: number;
+    /**
+     * @deprecated Use `maskChar` instead. Deprecated in v0.7.0.
+     */
+    char?: string;
 }
 
 /**
@@ -378,7 +390,7 @@ declare function cleanPhoneNumber(phone: string): string;
  * @example
  * Custom mask character:
  * ```typescript
- * maskPhoneNumber('081234567890', { char: 'X' });
+ * maskPhoneNumber('081234567890', { maskChar: 'X' });
  * // '0812XXXX7890'
  * ```
  *
@@ -555,4 +567,26 @@ declare function getOperator(phone: string): OperatorName | null;
  */
 declare function isProvider(phone: string, providerName: string): boolean;
 
-export { type MaskOptions as M, type OperatorName as O, type PhoneFormat as P, isLandlineNumber as a, toNational as b, toE164 as c, cleanPhoneNumber as d, generateWALink as e, formatPhoneNumber as f, getOperator as g, generateSmsLink as h, isMobileNumber as i, generateTelLink as j, isProvider as k, type PhoneInfo as l, maskPhoneNumber as m, parsePhoneNumber as p, toInternational as t, validatePhoneNumber as v };
+/**
+ * Error thrown when an invalid phone number is provided to a function.
+ * Extends native Error with a `code` property for programmatic error handling.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   requirePhone('invalid');
+ * } catch (error) {
+ *   if (error instanceof InvalidPhoneError) {
+ *     console.log(error.code); // 'INVALID_PHONE'
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+declare class InvalidPhoneError extends Error {
+    readonly code: "INVALID_PHONE";
+    constructor(message?: string);
+}
+
+export { InvalidPhoneError as I, type MaskOptions as M, type OperatorName as O, type PhoneFormat as P, isLandlineNumber as a, toNational as b, toE164 as c, cleanPhoneNumber as d, generateWALink as e, formatPhoneNumber as f, getOperator as g, generateSmsLink as h, isMobileNumber as i, generateTelLink as j, isProvider as k, type PhoneInfo as l, maskPhoneNumber as m, parsePhoneNumber as p, toInternational as t, validatePhoneNumber as v };

package/dist/{email-validator-R9L5unIw.d.cts → errors-DdutHLae.d.cts}

@@ -117,4 +117,26 @@ declare function maskEmail(email: string, options?: EmailMaskOptions): string;
  */
 declare function normalizeEmail(email: string): string;
 
-export { type EmailValidationOptions as E, type EmailValidationResult as a, type EmailMaskOptions as b, type EmailInfo as c, getEmailInfo as g, maskEmail as m, normalizeEmail as n, validateEmail as v };
+/**
+ * Error thrown when an invalid email is provided to a function.
+ * Extends native Error with a `code` property for programmatic error handling.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   requireEmail('invalid');
+ * } catch (error) {
+ *   if (error instanceof InvalidEmailError) {
+ *     console.log(error.code); // 'INVALID_EMAIL'
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+declare class InvalidEmailError extends Error {
+    readonly code: "INVALID_EMAIL";
+    constructor(message?: string);
+}
+
+export { type EmailValidationOptions as E, InvalidEmailError as I, type EmailValidationResult as a, type EmailMaskOptions as b, type EmailInfo as c, getEmailInfo as g, maskEmail as m, normalizeEmail as n, validateEmail as v };

package/dist/{email-validator-R9L5unIw.d.ts → errors-DdutHLae.d.ts}

@@ -117,4 +117,26 @@ declare function maskEmail(email: string, options?: EmailMaskOptions): string;
  */
 declare function normalizeEmail(email: string): string;
 
-export { type EmailValidationOptions as E, type EmailValidationResult as a, type EmailMaskOptions as b, type EmailInfo as c, getEmailInfo as g, maskEmail as m, normalizeEmail as n, validateEmail as v };
+/**
+ * Error thrown when an invalid email is provided to a function.
+ * Extends native Error with a `code` property for programmatic error handling.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   requireEmail('invalid');
+ * } catch (error) {
+ *   if (error instanceof InvalidEmailError) {
+ *     console.log(error.code); // 'INVALID_EMAIL'
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+declare class InvalidEmailError extends Error {
+    readonly code: "INVALID_EMAIL";
+    constructor(message?: string);
+}
+
+export { type EmailValidationOptions as E, InvalidEmailError as I, type EmailValidationResult as a, type EmailMaskOptions as b, type EmailInfo as c, getEmailInfo as g, maskEmail as m, normalizeEmail as n, validateEmail as v };