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

package/dist/cache-interface.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Generic cache interface that can be implemented by any cache store
+ * including in-memory LRU cache, Redis, Memcached, etc.
+ */
+export interface ICacheStore<T = any> {
+    /**
+     * Get a value from the cache
+     * @param key - The cache key
+     * @returns The cached value or null/undefined if not found or expired
+     */
+    get(key: string): Promise<T | null | undefined> | T | null | undefined;
+    /**
+     * Set a value in the cache with optional TTL
+     * @param key - The cache key
+     * @param value - The value to cache
+     * @param ttlMs - Optional TTL in milliseconds. If not provided, use default TTL
+     */
+    set(key: string, value: T, ttlMs?: number): Promise<void> | void;
+    /**
+     * Delete a value from the cache
+     * @param key - The cache key
+     */
+    delete(key: string): Promise<boolean> | boolean;
+    /**
+     * Check if a key exists in the cache
+     * @param key - The cache key
+     */
+    has(key: string): Promise<boolean> | boolean;
+    /**
+     * Clear all values from the cache
+     */
+    clear(): Promise<void> | void;
+    /**
+     * Get the current size of the cache (number of entries)
+     * Returns undefined if size is not applicable (e.g., Redis)
+     */
+    size?(): number | undefined;
+}
+/**
+ * Synchronous cache interface for in-memory caches
+ */
+export interface ISyncCacheStore<T = any> {
+    /**
+     * Get a value from the cache
+     * @param key - The cache key
+     * @returns The cached value or null/undefined if not found or expired
+     */
+    get(key: string): T | null | undefined;
+    /**
+     * Set a value in the cache with optional TTL
+     * @param key - The cache key
+     * @param value - The value to cache
+     * @param ttlMs - Optional TTL in milliseconds. If not provided, use default TTL
+     */
+    set(key: string, value: T, ttlMs?: number): void;
+    /**
+     * Delete a value from the cache
+     * @param key - The cache key
+     */
+    delete(key: string): boolean;
+    /**
+     * Check if a key exists in the cache
+     * @param key - The cache key
+     */
+    has(key: string): boolean;
+    /**
+     * Clear all values from the cache
+     */
+    clear(): void;
+    /**
+     * Get the current size of the cache (number of entries)
+     */
+    size?(): number;
+}
+/**
+ * Cache configuration for different cache types
+ */
+export interface CacheConfig {
+    /** Maximum number of entries (for LRU caches) */
+    maxSize?: number;
+    /** Default TTL in milliseconds */
+    ttlMs?: number;
+    /** Custom cache store implementation */
+    store?: ICacheStore;
+}
+/**
+ * Cache holder interface for typed caches
+ */
+export interface ICache {
+    mx: ICacheStore<string[]>;
+    disposable: ICacheStore<boolean>;
+    free: ICacheStore<boolean>;
+    domainValid: ICacheStore<boolean>;
+    smtp: ICacheStore<boolean | null>;
+    domainSuggestion: ICacheStore<{
+        suggested: string;
+        confidence: number;
+    } | null>;
+    whois: ICacheStore<any>;
+}
+/**
+ * Default TTL values in milliseconds
+ */
+export declare const DEFAULT_CACHE_TTL: {
+    mx: number;
+    disposable: number;
+    free: number;
+    domainValid: number;
+    smtp: number;
+    domainSuggestion: number;
+    whois: number;
+};
+/**
+ * Default cache sizes
+ */
+export declare const DEFAULT_CACHE_SIZE: {
+    mx: number;
+    disposable: number;
+    free: number;
+    domainValid: number;
+    smtp: number;
+    domainSuggestion: number;
+    whois: number;
+};

package/dist/cache.d.ts

@@ -1,3 +1,4 @@
+import type { ICache, ICacheStore } from './cache-interface';
 import type { ParsedWhoisResult } from './whois-parser';
 export declare const mxCache: import("tiny-lru").LRU<string[]>;
 export declare const disposableCache: import("tiny-lru").LRU<boolean>;
@@ -9,4 +10,31 @@ export declare const domainSuggestionCache: import("tiny-lru").LRU<{
     confidence: number;
 } | null>;
 export declare const whoisCache: import("tiny-lru").LRU<ParsedWhoisResult>;
+/**
+ * Set a global custom cache instance to use instead of the default LRU caches
+ */
+export declare function setCustomCache(cache: ICache): void;
+/**
+ * Get the current global custom cache instance
+ */
+export declare function getCustomCache(): ICache | null;
+/**
+ * Reset to use default LRU caches
+ */
+export declare function resetToDefaultCache(): void;
+/**
+ * Get cache adapter that works with passed cache, global cache, or default LRU
+ */
+export declare function getCacheStore<T>(defaultLru: any, cacheType: keyof ICache, passedCache?: ICache | null): ICacheStore<T>;
+export declare const mxCacheStore: (passedCache?: ICache | null) => ICacheStore<string[]>;
+export declare const disposableCacheStore: (passedCache?: ICache | null) => ICacheStore<boolean>;
+export declare const freeCacheStore: (passedCache?: ICache | null) => ICacheStore<boolean>;
+export declare const domainValidCacheStore: (passedCache?: ICache | null) => ICacheStore<boolean>;
+export declare const smtpCacheStore: (passedCache?: ICache | null) => ICacheStore<boolean | null>;
+export declare const domainSuggestionCacheStore: (passedCache?: ICache | null) => ICacheStore<{
+    suggested: string;
+    confidence: number;
+} | null>;
+export declare const whoisCacheStore: (passedCache?: ICache | null) => ICacheStore<ParsedWhoisResult>;
 export declare function clearAllCaches(): void;
+export type { ICache, ICacheStore } from './cache-interface';

package/dist/dns.d.ts

@@ -1 +1,2 @@
-export declare function resolveMxRecords(domain: string): Promise<string[]>;
+import type { ICache } from './cache-interface';
+export declare function resolveMxRecords(domain: string, cache?: ICache | null): Promise<string[]>;

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,4 +1,5 @@
-import { type DetailedVerificationResult, type IVerifyEmailParams, type IVerifyEmailResult } from './types';
+import type { ICache } from './cache-interface';
+import { type DetailedVerificationResult, type IVerifyEmailParams } from './types';
 export { verifyEmailBatch } from './batch';
 export { clearAllCaches } from './cache';
 export { COMMON_EMAIL_DOMAINS, defaultDomainSuggestionMethod, getDomainSimilarity, isCommonDomain, suggestDomain, suggestEmailDomain, } from './domain-suggester';
@@ -6,14 +7,10 @@ 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)
+ * Verify email address
  */
-export declare function verifyEmail(params: IVerifyEmailParams): Promise<IVerifyEmailResult>;
-/**
- * Verify email address with detailed result format
- */
-export declare function verifyEmailDetailed(params: IVerifyEmailParams): Promise<DetailedVerificationResult>;
+export declare function verifyEmail(params: IVerifyEmailParams): Promise<DetailedVerificationResult>;