@emailcheck/email-validator-js 2.12.0 → 2.13.1-beta.0

package/dist/domain-suggester.d.ts

@@ -5,9 +5,13 @@ import type { DomainSuggestion, ISuggestDomainParams } from './types';
  */
 export declare const COMMON_EMAIL_DOMAINS: string[];
 /**
- * Default domain suggestion method using string similarity
+ * Default domain suggestion method using string similarity (sync version)
  */
 export declare function defaultDomainSuggestionMethod(domain: string, commonDomains?: string[]): DomainSuggestion | null;
+/**
+ * Async version of default domain suggestion method
+ */
+export declare function defaultDomainSuggestionMethodAsync(domain: string, commonDomains?: string[]): Promise<DomainSuggestion | null>;
 /**
  * Suggest a corrected domain for a potentially misspelled email domain
  * @param params - Parameters including domain and optional custom method
@@ -20,7 +24,7 @@ export declare function suggestDomain(params: ISuggestDomainParams): DomainSugge
  * @param commonDomains - Optional list of common domains to check against
  * @returns Domain suggestion with confidence score, or null if no suggestion
  */
-export declare function suggestEmailDomain(email: string, commonDomains?: string[]): DomainSuggestion | null;
+export declare function suggestEmailDomain(email: string, commonDomains?: string[]): Promise<DomainSuggestion | null>;
 /**
  * Check if a domain is in the common domains list
  * @param domain - Domain to check

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import type { ICache } from './cache-interface';
 import { type DetailedVerificationResult, type IVerifyEmailParams, type IVerifyEmailResult } from './types';
 export { verifyEmailBatch } from './batch';
 export { clearAllCaches } from './cache';
@@ -6,8 +7,8 @@ export { defaultNameDetectionMethod, detectName, detectNameFromEmail } from './n
 export * from './types';
 export { isValidEmail, isValidEmailDomain } from './validator';
 export { getDomainAge, getDomainRegistrationStatus } from './whois';
-export declare function isDisposableEmail(emailOrDomain: string): boolean;
-export declare function isFreeEmail(emailOrDomain: string): boolean;
+export declare function isDisposableEmail(emailOrDomain: string, cache?: ICache | null): Promise<boolean>;
+export declare function isFreeEmail(emailOrDomain: string, cache?: ICache | null): Promise<boolean>;
 export declare const domainPorts: Record<string, number>;
 /**
  * Verify email address with basic result format (backward compatible)

package/dist/index.esm.js

@@ -4,6 +4,68 @@ import { promises } from 'node:dns';
 import { stringSimilarity } from 'string-similarity-js';
 import net from 'node:net';
 
+class LRUAdapter {
+  constructor(maxSize = 1e3, ttlMs = 36e5) {
+    this.lru = lru(maxSize, ttlMs);
+  }
+  get(key) {
+    const value = this.lru.get(key);
+    return value === void 0 ? null : value;
+  }
+  async set(key, value, ttlMs) {
+    if (ttlMs !== void 0) {
+      this.lru.set(key, value);
+    } else {
+      this.lru.set(key, value);
+    }
+  }
+  async delete(key) {
+    this.lru.delete(key);
+    return true;
+  }
+  async has(key) {
+    return this.lru.has(key);
+  }
+  async clear() {
+    this.lru.clear();
+  }
+  size() {
+    return this.lru.size;
+  }
+  /**
+   * Get the underlying LRU instance for advanced operations
+   */
+  getLRU() {
+    return this.lru;
+  }
+}
+
+const DEFAULT_CACHE_TTL = {
+  mx: 36e5,
+  // 1 hour
+  disposable: 864e5,
+  // 24 hours
+  free: 864e5,
+  // 24 hours
+  domainValid: 864e5,
+  // 24 hours
+  smtp: 18e5,
+  // 30 minutes
+  domainSuggestion: 864e5,
+  // 24 hours
+  whois: 36e5
+  // 1 hour
+};
+const DEFAULT_CACHE_SIZE = {
+  mx: 500,
+  disposable: 1e3,
+  free: 1e3,
+  domainValid: 1e3,
+  smtp: 500,
+  domainSuggestion: 1e3,
+  whois: 200
+};
+
 const mxCache = lru(500, 36e5);
 const disposableCache = lru(1e3, 864e5);
 const freeCache = lru(1e3, 864e5);
@@ -11,6 +73,19 @@ const domainValidCache = lru(1e3, 864e5);
 const smtpCache = lru(500, 18e5);
 const domainSuggestionCache = lru(1e3, 864e5);
 const whoisCache = lru(200, 36e5);
+function getCacheStore(defaultLru, cacheType, passedCache) {
+  if (passedCache && passedCache[cacheType]) {
+    return passedCache[cacheType];
+  }
+  return new LRUAdapter(DEFAULT_CACHE_SIZE[cacheType], DEFAULT_CACHE_TTL[cacheType]);
+}
+const mxCacheStore = (passedCache) => getCacheStore(mxCache, "mx", passedCache);
+const disposableCacheStore = (passedCache) => getCacheStore(disposableCache, "disposable", passedCache);
+const freeCacheStore = (passedCache) => getCacheStore(freeCache, "free", passedCache);
+const domainValidCacheStore = (passedCache) => getCacheStore(domainValidCache, "domainValid", passedCache);
+const smtpCacheStore = (passedCache) => getCacheStore(smtpCache, "smtp", passedCache);
+const domainSuggestionCacheStore = (passedCache) => getCacheStore(domainSuggestionCache, "domainSuggestion", passedCache);
+const whoisCacheStore = (passedCache) => getCacheStore(whoisCache, "whois", passedCache);
 function clearAllCaches() {
   mxCache.clear();
   disposableCache.clear();
@@ -21,9 +96,10 @@ function clearAllCaches() {
   whoisCache.clear();
 }
 
-async function resolveMxRecords(domain) {
-  const cached = mxCache.get(domain);
-  if (cached !== void 0) {
+async function resolveMxRecords(domain, cache) {
+  const cacheStore = mxCacheStore(cache);
+  const cached = await cacheStore.get(domain);
+  if (cached !== null && cached !== void 0) {
     return cached;
   }
   try {
@@ -38,10 +114,10 @@ async function resolveMxRecords(domain) {
       return 0;
     });
     const exchanges = records.map((record) => record.exchange);
-    mxCache.set(domain, exchanges);
+    await cacheStore.set(domain, exchanges);
     return exchanges;
   } catch (error) {
-    mxCache.set(domain, []);
+    await cacheStore.set(domain, []);
     throw error;
   }
 }
@@ -131,18 +207,73 @@ function getSimilarityThreshold(domain) {
   return 0.75;
 }
 function defaultDomainSuggestionMethod(domain, commonDomains) {
+  const domainsToCheck = commonDomains || COMMON_EMAIL_DOMAINS;
+  const lowerDomain = domain.toLowerCase();
+  if (domainsToCheck.includes(lowerDomain)) {
+    return null;
+  }
+  for (const [correctDomain, typos] of Object.entries(TYPO_PATTERNS)) {
+    if (typos.includes(lowerDomain)) {
+      return {
+        original: domain,
+        suggested: correctDomain,
+        confidence: 0.95
+        // High confidence for known typo patterns
+      };
+    }
+  }
+  let bestMatch = null;
+  const threshold = getSimilarityThreshold(lowerDomain);
+  for (const commonDomain of domainsToCheck) {
+    const similarity = stringSimilarity(lowerDomain, commonDomain.toLowerCase());
+    if (similarity >= threshold) {
+      if (!bestMatch || similarity > bestMatch.similarity) {
+        bestMatch = { domain: commonDomain, similarity };
+      }
+    }
+  }
+  if (!bestMatch) {
+    for (const commonDomain of domainsToCheck) {
+      if (Math.abs(lowerDomain.length - commonDomain.length) <= 2) {
+        const similarity = stringSimilarity(lowerDomain, commonDomain.toLowerCase());
+        if (similarity >= 0.7) {
+          if (!bestMatch || similarity > bestMatch.similarity) {
+            bestMatch = { domain: commonDomain, similarity };
+          }
+        }
+      }
+    }
+  }
+  if (bestMatch) {
+    if (bestMatch.domain.charAt(0) !== lowerDomain.charAt(0) && bestMatch.similarity < 0.9) {
+      return null;
+    }
+    return {
+      original: domain,
+      suggested: bestMatch.domain,
+      confidence: bestMatch.similarity
+    };
+  }
+  return null;
+}
+async function defaultDomainSuggestionMethodAsync(domain, commonDomains) {
+  return defaultDomainSuggestionMethodImpl(domain, commonDomains);
+}
+async function defaultDomainSuggestionMethodImpl(domain, commonDomains) {
   if (!domain || domain.length < 3) {
     return null;
   }
   const domainsToCheck = commonDomains || COMMON_EMAIL_DOMAINS;
   const lowerDomain = domain.toLowerCase();
   const cacheKey = `${lowerDomain}:${domainsToCheck.length}`;
-  const cached = domainSuggestionCache.get(cacheKey);
-  if (cached !== void 0) {
-    return cached ? { original: domain, ...cached } : null;
+  const cache = domainSuggestionCacheStore();
+  const cached = cache.get(cacheKey);
+  const resolved = cached && typeof cached === "object" && "then" in cached ? await cached : cached;
+  if (resolved !== null && resolved !== void 0) {
+    return resolved ? { original: domain, suggested: resolved.suggested, confidence: resolved.confidence } : null;
   }
   if (domainsToCheck.includes(lowerDomain)) {
-    domainSuggestionCache.set(cacheKey, null);
+    await cache.set(cacheKey, null);
     return null;
   }
   for (const [correctDomain, typos] of Object.entries(TYPO_PATTERNS)) {
@@ -153,7 +284,7 @@ function defaultDomainSuggestionMethod(domain, commonDomains) {
         confidence: 0.95
         // High confidence for known typo patterns
       };
-      domainSuggestionCache.set(cacheKey, { suggested: result.suggested, confidence: result.confidence });
+      await cache.set(cacheKey, { suggested: result.suggested, confidence: result.confidence });
       return result;
     }
   }
@@ -181,7 +312,7 @@ function defaultDomainSuggestionMethod(domain, commonDomains) {
   }
   if (bestMatch) {
     if (bestMatch.domain.charAt(0) !== lowerDomain.charAt(0) && bestMatch.similarity < 0.9) {
-      domainSuggestionCache.set(cacheKey, null);
+      await cache.set(cacheKey, null);
       return null;
     }
     const result = {
@@ -189,10 +320,10 @@ function defaultDomainSuggestionMethod(domain, commonDomains) {
       suggested: bestMatch.domain,
       confidence: bestMatch.similarity
     };
-    domainSuggestionCache.set(cacheKey, { suggested: result.suggested, confidence: result.confidence });
+    await cache.set(cacheKey, { suggested: result.suggested, confidence: result.confidence });
     return result;
   }
-  domainSuggestionCache.set(cacheKey, null);
+  await cache.set(cacheKey, null);
   return null;
 }
 function suggestDomain(params) {
@@ -209,7 +340,7 @@ function suggestDomain(params) {
   }
   return defaultDomainSuggestionMethod(domain, commonDomains);
 }
-function suggestEmailDomain(email, commonDomains) {
+async function suggestEmailDomain(email, commonDomains) {
   if (!email || !email.includes("@")) {
     return null;
   }
@@ -217,7 +348,7 @@ function suggestEmailDomain(email, commonDomains) {
   if (!domain || !localPart) {
     return null;
   }
-  const suggestion = suggestDomain({ domain, commonDomains });
+  const suggestion = await defaultDomainSuggestionMethodAsync(domain, commonDomains);
   if (suggestion) {
     return {
       original: email,
@@ -1089,7 +1220,7 @@ var VerificationErrorCode;
   VerificationErrorCode2["FREE_EMAIL_PROVIDER"] = "FREE_EMAIL_PROVIDER";
 })(VerificationErrorCode || (VerificationErrorCode = {}));
 
-function isValidEmailDomain(emailOrDomain) {
+async function isValidEmailDomain(emailOrDomain, cache) {
   let [_, emailDomain] = (emailOrDomain === null || emailOrDomain === void 0 ? void 0 : emailOrDomain.split("@")) || [];
   if (!emailDomain) {
     emailDomain = _;
@@ -1097,16 +1228,17 @@ function isValidEmailDomain(emailOrDomain) {
   if (!emailDomain) {
     return false;
   }
-  const cached = domainValidCache.get(emailDomain);
-  if (cached !== void 0) {
+  const cacheStore = domainValidCacheStore(cache);
+  const cached = await cacheStore.get(emailDomain);
+  if (cached !== null && cached !== void 0) {
     return cached;
   }
   try {
     const result = isValid(emailDomain) || false;
-    domainValidCache.set(emailDomain, result);
+    await cacheStore.set(emailDomain, result);
     return result;
   } catch (_e) {
-    domainValidCache.set(emailDomain, false);
+    await cacheStore.set(emailDomain, false);
     return false;
   }
 }
@@ -1628,8 +1760,9 @@ function queryWhoisServer(domain, server, timeout = 5e3) {
 async function getWhoisData(domain, timeout = 5e3) {
   var _a;
   const cacheKey = `whois:${domain}`;
-  const cached = whoisCache.get(cacheKey);
-  if (cached) {
+  const cache = whoisCacheStore();
+  const cached = await cache.get(cacheKey);
+  if (cached !== null && cached !== void 0) {
     return cached;
   }
   try {
@@ -1646,16 +1779,16 @@ async function getWhoisData(domain, timeout = 5e3) {
         const referredServer = referMatch[1];
         const whoisResponse2 = await queryWhoisServer(domain, referredServer, timeout);
         const whoisData3 = parseWhoisData({ rawData: whoisResponse2, domain });
-        whoisCache.set(cacheKey, whoisData3);
+        await cache.set(cacheKey, whoisData3);
         return whoisData3;
       }
       const whoisData2 = parseWhoisData({ rawData: ianaResponse, domain });
-      whoisCache.set(cacheKey, whoisData2);
+      await cache.set(cacheKey, whoisData2);
       return whoisData2;
     }
     const whoisResponse = await queryWhoisServer(domain, whoisServer, timeout);
     const whoisData = parseWhoisData({ rawData: whoisResponse, domain });
-    whoisCache.set(cacheKey, whoisData);
+    await cache.set(cacheKey, whoisData);
     return whoisData;
   } catch (_error) {
     return null;
@@ -1756,7 +1889,7 @@ async function getDomainRegistrationStatus(domain, timeout = 5e3) {
 }
 
 async function verifyEmailBatch(params) {
-  const { emailAddresses, concurrency = 5, timeout = 4e3, verifyMx = true, verifySmtp = false, checkDisposable = true, checkFree = true, detailed = false, detectName = false, nameDetectionMethod, suggestDomain = false, domainSuggestionMethod, commonDomains } = params;
+  const { emailAddresses, concurrency = 5, timeout = 4e3, verifyMx = true, verifySmtp = false, checkDisposable = true, checkFree = true, detectName = false, nameDetectionMethod, suggestDomain = false, domainSuggestionMethod, commonDomains, cache } = params;
   const startTime = Date.now();
   const results = /* @__PURE__ */ new Map();
   const batches = [];
@@ -1769,7 +1902,7 @@ async function verifyEmailBatch(params) {
   for (const batch of batches) {
     const batchPromises = batch.map(async (email) => {
       try {
-        const result = detailed ? await verifyEmailDetailed({
+        const result = await verifyEmailDetailed({
           emailAddress: email,
           timeout,
           verifyMx,
@@ -1780,39 +1913,20 @@ async function verifyEmailBatch(params) {
           nameDetectionMethod,
           suggestDomain,
           domainSuggestionMethod,
-          commonDomains
-        }) : await verifyEmail({
-          emailAddress: email,
-          timeout,
-          verifyMx,
-          verifySmtp,
-          detectName,
-          nameDetectionMethod,
-          suggestDomain,
-          domainSuggestionMethod,
-          commonDomains
+          commonDomains,
+          cache
         });
-        if (detailed) {
-          const detailedResult = result;
-          if (detailedResult.valid) {
-            totalValid++;
-          } else {
-            totalInvalid++;
-          }
+        if (result.valid) {
+          totalValid++;
         } else {
-          const basicResult = result;
-          if (basicResult.validFormat && basicResult.validMx !== false) {
-            totalValid++;
-          } else {
-            totalInvalid++;
-          }
+          totalInvalid++;
         }
         return { email, result };
       } catch (error) {
         totalErrors++;
         return {
           email,
-          result: detailed ? createErrorDetailedResult(email) : { validFormat: false, validMx: null, validSmtp: null, detectedName: null, domainSuggestion: null }
+          result: createErrorDetailedResult(email)
         };
       }
     });
@@ -1850,38 +1964,56 @@ function createErrorDetailedResult(email, _error) {
 
 let disposableEmailProviders;
 let freeEmailProviders;
-function isDisposableEmail(emailOrDomain) {
+async function isDisposableEmail(emailOrDomain, cache) {
   const parts = emailOrDomain.split("@");
   const emailDomain = parts.length > 1 ? parts[1] : parts[0];
   if (!emailDomain) {
     return false;
   }
-  const cached = disposableCache.get(emailDomain);
-  if (cached !== void 0) {
+  const cacheStore = disposableCacheStore(cache);
+  let cached;
+  try {
+    cached = await cacheStore.get(emailDomain);
+  } catch (_error) {
+    cached = null;
+  }
+  if (cached !== null && cached !== void 0) {
     return cached;
   }
   if (!disposableEmailProviders) {
     disposableEmailProviders = new Set(require("./disposable-email-providers.json"));
   }
   const result = disposableEmailProviders.has(emailDomain);
-  disposableCache.set(emailDomain, result);
+  try {
+    await cacheStore.set(emailDomain, result);
+  } catch (_error) {
+  }
   return result;
 }
-function isFreeEmail(emailOrDomain) {
+async function isFreeEmail(emailOrDomain, cache) {
   const parts = emailOrDomain.split("@");
   const emailDomain = parts.length > 1 ? parts[1] : parts[0];
   if (!emailDomain) {
     return false;
   }
-  const cached = freeCache.get(emailDomain);
-  if (cached !== void 0) {
+  const cacheStore = freeCacheStore(cache);
+  let cached;
+  try {
+    cached = await cacheStore.get(emailDomain);
+  } catch (_error) {
+    cached = null;
+  }
+  if (cached !== null && cached !== void 0) {
     return cached;
   }
   if (!freeEmailProviders) {
     freeEmailProviders = new Set(require("./free-email-providers.json"));
   }
   const result = freeEmailProviders.has(emailDomain);
-  freeCache.set(emailDomain, result);
+  try {
+    await cacheStore.set(emailDomain, result);
+  } catch (_error) {
+  }
   return result;
 }
 const domainPorts = {
@@ -1914,7 +2046,7 @@ async function verifyEmail(params) {
   if (suggestDomain2) {
     const [, emailDomain] = emailAddress.split("@");
     if (emailDomain) {
-      result.domainSuggestion = domainSuggestionMethod ? domainSuggestionMethod(emailDomain) : suggestEmailDomain(emailAddress, commonDomains);
+      result.domainSuggestion = domainSuggestionMethod ? domainSuggestionMethod(emailDomain) : await suggestEmailDomain(emailAddress, commonDomains);
     }
   }
   if (checkDomainAge) {
@@ -1936,7 +2068,7 @@ async function verifyEmail(params) {
   if (!verifyMx && !verifySmtp)
     return result;
   try {
-    mxRecords = await resolveMxRecords(domain);
+    mxRecords = await resolveMxRecords(domain, params.cache);
     log("[verifyEmail] Found MX records", mxRecords);
   } catch (err) {
     log("[verifyEmail] Failed to resolve MX records", err);
@@ -1950,8 +2082,9 @@ async function verifyEmail(params) {
   }
   if (verifySmtp && (mxRecords === null || mxRecords === void 0 ? void 0 : mxRecords.length) > 0) {
     const cacheKey = `${emailAddress}:smtp`;
-    const cachedSmtp = smtpCache.get(cacheKey);
-    if (cachedSmtp !== void 0) {
+    const smtpCacheInstance = smtpCacheStore(params.cache);
+    const cachedSmtp = await smtpCacheInstance.get(cacheKey);
+    if (cachedSmtp !== null && cachedSmtp !== void 0) {
       result.validSmtp = cachedSmtp;
       if (detectName2 && !result.detectedName) {
         result.detectedName = detectNameFromEmail({
@@ -1981,7 +2114,7 @@ async function verifyEmail(params) {
       port: domainPort,
       retryAttempts: params.retryAttempts
     });
-    smtpCache.set(cacheKey, smtpResult);
+    await smtpCacheInstance.set(cacheKey, smtpResult);
     result.validSmtp = smtpResult;
   }
   return result;
@@ -2021,7 +2154,7 @@ async function verifyEmailDetailed(params) {
   if (suggestDomain2) {
     const [, emailDomain] = emailAddress.split("@");
     if (emailDomain) {
-      result.domainSuggestion = domainSuggestionMethod ? domainSuggestionMethod(emailDomain) : suggestEmailDomain(emailAddress, commonDomains);
+      result.domainSuggestion = domainSuggestionMethod ? domainSuggestionMethod(emailDomain) : await suggestEmailDomain(emailAddress, commonDomains);
     }
   }
   const [local, domain] = emailAddress.split("@");
@@ -2032,7 +2165,7 @@ async function verifyEmailDetailed(params) {
     }
     return result;
   }
-  if (!isValidEmailDomain(domain)) {
+  if (!await isValidEmailDomain(domain, params.cache)) {
     result.domain.error = VerificationErrorCode.INVALID_DOMAIN;
     if (result.metadata) {
       result.metadata.verificationTime = Date.now() - startTime;
@@ -2040,14 +2173,14 @@ async function verifyEmailDetailed(params) {
     return result;
   }
   if (checkDisposable) {
-    result.disposable = isDisposableEmail(emailAddress);
+    result.disposable = await isDisposableEmail(emailAddress, params.cache);
     if (result.disposable) {
       result.valid = false;
       result.domain.error = VerificationErrorCode.DISPOSABLE_EMAIL;
     }
   }
   if (checkFree) {
-    result.freeProvider = isFreeEmail(emailAddress);
+    result.freeProvider = await isFreeEmail(emailAddress, params.cache);
   }
   if (checkDomainAge) {
     try {
@@ -2067,7 +2200,7 @@ async function verifyEmailDetailed(params) {
   }
   if (verifyMx || verifySmtp) {
     try {
-      const mxRecords = await resolveMxRecords(domain);
+      const mxRecords = await resolveMxRecords(domain, params.cache);
       result.domain.mxRecords = mxRecords;
       result.domain.valid = mxRecords.length > 0;
       if (!result.domain.valid) {
@@ -2075,8 +2208,9 @@ async function verifyEmailDetailed(params) {
       }
       if (verifySmtp && mxRecords.length > 0) {
         const cacheKey = `${emailAddress}:smtp`;
-        const cachedSmtp = smtpCache.get(cacheKey);
-        if (cachedSmtp !== void 0) {
+        const smtpCacheInstance = smtpCacheStore(params.cache);
+        const cachedSmtp = await smtpCacheInstance.get(cacheKey);
+        if (cachedSmtp !== null && cachedSmtp !== void 0) {
           result.smtp.valid = cachedSmtp;
           if (result.metadata) {
             result.metadata.cached = true;
@@ -2104,7 +2238,7 @@ async function verifyEmailDetailed(params) {
             port: domainPort,
             retryAttempts: params.retryAttempts
           });
-          smtpCache.set(cacheKey, smtpResult);
+          await smtpCacheInstance.set(cacheKey, smtpResult);
           result.smtp.valid = smtpResult;
         }
         if (result.smtp.valid === false) {