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

package/README.md

@@ -20,6 +20,7 @@
 - [API Reference](#api-reference)
 - [Configuration](#configuration-options)
 - [Examples](#examples)
+- [Custom Cache Injection](#-custom-cache-injection)
 - [Performance & Caching](#-performance--caching)
 - [Email Provider Databases](#️-email-provider-databases)
 - [Testing](#testing)
@@ -122,7 +123,7 @@ import { verifyEmail } from '@emailcheck/email-validator-js';
 
 // Basic usage
 const result = await verifyEmail({
-  emailAddress: 'user@example.com',
+  emailAddress: 'user@mydomain.com',
   verifyMx: true,
   verifySmtp: true,
   timeout: 3000
@@ -237,7 +238,7 @@ Verify multiple emails in parallel with concurrency control.
 Detect first and last name from email address.
 
 ```typescript
-const name = detectName('john.doe@example.com');
+const name = detectName('john.doe@mydomain.com');
 // Returns: { firstName: 'John', lastName: 'Doe', confidence: 0.9 }
 ```
 
@@ -270,7 +271,7 @@ const customMethod = (email: string) => {
 };
 
 const name = detectNameFromEmail({
-  email: 'user@example.com',
+  email: 'user@mydomain.com',
   customMethod: customMethod
 });
 ```
@@ -349,10 +350,10 @@ getDomainSimilarity('gmail.com', 'yahoo.com'); // 0.3
 Get domain age information via WHOIS lookup.
 
 ```typescript
-const ageInfo = await getDomainAge('example.com');
+const ageInfo = await getDomainAge('mydomain.com');
 // Returns:
 // {
-//   domain: 'example.com',
+//   domain: 'mydomain.com',
 //   creationDate: Date,
 //   ageInDays: 7890,
 //   ageInYears: 21.6,
@@ -361,8 +362,8 @@ const ageInfo = await getDomainAge('example.com');
 // }
 
 // Works with email addresses and URLs too
-await getDomainAge('user@example.com');
-await getDomainAge('https://example.com/path');
+await getDomainAge('user@mydomain.com');
+await getDomainAge('https://mydomain.com/path');
 ```
 
 **Parameters:**
@@ -375,15 +376,15 @@ await getDomainAge('https://example.com/path');
 Get detailed domain registration status via WHOIS.
 
 ```typescript
-const status = await getDomainRegistrationStatus('example.com');
+const status = await getDomainRegistrationStatus('mydomain.com');
 // Returns:
 // {
-//   domain: 'example.com',
+//   domain: 'mydomain.com',
 //   isRegistered: true,
 //   isAvailable: false,
 //   status: ['clientTransferProhibited'],
 //   registrar: 'Example Registrar',
-//   nameServers: ['ns1.example.com', 'ns2.example.com'],
+//   nameServers: ['ns1.mydomain.com', 'ns2.mydomain.com'],
 //   expirationDate: Date,
 //   isExpired: false,
 //   daysUntilExpiration: 365,
@@ -430,7 +431,7 @@ isFreeEmail('corporate.com'); // false
 Validate email format (RFC 5321 compliant).
 
 ```typescript
-isValidEmail('user@example.com'); // true
+isValidEmail('user@mydomain.com'); // true
 isValidEmail('invalid.email'); // false
 ```
 
@@ -446,7 +447,7 @@ isValidEmail('invalid.email'); // false
 Validate if a domain has a valid TLD.
 
 ```typescript
-isValidEmailDomain('example.com'); // true
+isValidEmailDomain('mydomain.com'); // true
 isValidEmailDomain('example.invalid'); // false
 ```
 
@@ -623,7 +624,7 @@ const result = await verifyEmailDetailed({
 ```typescript
 import { verifyEmailBatch } from '@emailcheck/email-validator-js';
 
-const emails = ['user1@gmail.com', 'user2@example.com', 'invalid@fake.com'];
+const emails = ['user1@gmail.com', 'user2@mydomain.com', 'invalid@fake.com'];
 
 const result = await verifyEmailBatch({
   emailAddresses: emails,
@@ -641,23 +642,23 @@ const result = await verifyEmailBatch({
 import { detectName, verifyEmailDetailed } from '@emailcheck/email-validator-js';
 
 // Standalone name detection - now with composite name support
-const name = detectName('john.doe@example.com');
+const name = detectName('john.doe@mydomain.com');
 // name: { firstName: 'John', lastName: 'Doe', confidence: 0.9 }
 
 // Handle alphanumeric composite names
-const composite = detectName('mo1.test2@example.com');
+const composite = detectName('mo1.test2@mydomain.com');
 // composite: { firstName: 'Mo1', lastName: 'Test2', confidence: 0.6 }
 
 // Smart handling of numbers and suffixes
-const withNumbers = detectName('john.doe123@example.com');
+const withNumbers = detectName('john.doe123@mydomain.com');
 // withNumbers: { firstName: 'John', lastName: 'Doe', confidence: 0.8 }
 
-const withSuffix = detectName('jane.smith.dev@example.com');
+const withSuffix = detectName('jane.smith.dev@mydomain.com');
 // withSuffix: { firstName: 'Jane', lastName: 'Smith', confidence: 0.7 }
 
 // Integrated with email verification
 const result = await verifyEmailDetailed({
-  emailAddress: 'jane_smith@example.com',
+  emailAddress: 'jane_smith@mydomain.com',
   detectName: true
 });
 // result.detectedName: { firstName: 'Jane', lastName: 'Smith', confidence: 0.8 }
@@ -669,7 +670,7 @@ const customMethod = (email: string) => {
 };
 
 const resultCustom = await verifyEmail({
-  emailAddress: 'user@example.com',
+  emailAddress: 'user@mydomain.com',
   detectName: true,
   nameDetectionMethod: customMethod
 });
@@ -776,16 +777,16 @@ for (const [email, result] of batch.results) {
 
 ```typescript
 // First verification - hits DNS and SMTP
-const first = await verifyEmail({ 
-  emailAddress: 'cached@example.com',
-  verifyMx: true 
+const first = await verifyEmail({
+  emailAddress: 'cached@mydomain.com',
+  verifyMx: true
 });
 // Takes ~500ms
 
 // Second verification - uses cache
-const second = await verifyEmail({ 
-  emailAddress: 'cached@example.com',
-  verifyMx: true 
+const second = await verifyEmail({
+  emailAddress: 'cached@mydomain.com',
+  verifyMx: true
 });
 // Takes ~1ms (cached)
 
@@ -793,6 +794,270 @@ const second = await verifyEmail({
 clearAllCaches();
 ```
 
+## 🚀 Custom Cache Injection
+
+The library supports parameter-based cache injection, allowing you to use custom cache backends like Redis, Memcached, or any LRU-compatible cache implementation.
+
+### Built-in Cache Adapters
+
+#### LRU Cache (Default)
+```typescript
+import { CacheFactory } from '@emailcheck/email-validator-js';
+
+// Create LRU cache with custom settings
+const lruCache = CacheFactory.createLRUCache({
+  mx: 1800000,        // 30 minutes for MX records
+  disposable: 86400000,  // 24 hours for disposable checks
+  free: 86400000,        // 24 hours for free email checks
+  smtp: 1800000,        // 30 minutes for SMTP verification
+});
+
+// Use with email verification
+const result = await verifyEmail({
+  emailAddress: 'user@mydomain.com',
+  verifyMx: true,
+  verifySmtp: true,
+  cache: lruCache  // Pass the cache instance
+});
+```
+
+#### Redis Cache
+```typescript
+import { CacheFactory } from '@emailcheck/email-validator-js';
+import Redis from 'ioredis';
+
+// Create Redis client
+const redis = new Redis({
+  host: 'localhost',
+  port: 6379,
+});
+
+// Create Redis cache adapter
+const redisCache = CacheFactory.createRedisCache(redis, {
+  keyPrefix: 'email_validator:',
+  defaultTtlMs: 3600000, // 1 hour default TTL
+  jsonSerializer: {
+    stringify: (value) => JSON.stringify(value),
+    parse: (value) => JSON.parse(value)
+  }
+});
+
+// Use with batch verification
+const batchResult = await verifyEmailBatch({
+  emailAddresses: ['user1@mydomain.com', 'user2@mydomain.com'],
+  verifyMx: true,
+  verifySmtp: true,
+  cache: redisCache,
+  concurrency: 10
+});
+```
+
+### Custom Cache Implementation
+
+Create your own cache adapter by implementing the `ICacheStore` interface:
+
+```typescript
+import { CacheFactory, type ICacheStore } from '@emailcheck/email-validator-js';
+
+class MyCustomCache<T> implements ICacheStore<T> {
+  private store = new Map<string, { value: T; expiry: number }>();
+
+  async get(key: string): Promise<T | null> {
+    const item = this.store.get(key);
+    if (!item) return null;
+
+    if (Date.now() > item.expiry) {
+      this.store.delete(key);
+      return null;
+    }
+
+    return item.value;
+  }
+
+  async set(key: string, value: T, ttlMs?: number): Promise<void> {
+    const expiry = Date.now() + (ttlMs || 3600000);
+    this.store.set(key, { value, expiry });
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return this.store.delete(key);
+  }
+
+  async has(key: string): Promise<boolean> {
+    return this.store.has(key);
+  }
+
+  async clear(): Promise<void> {
+    this.store.clear();
+  }
+
+  size(): number {
+    return this.store.size;
+  }
+}
+
+// Create custom cache
+const customCache = CacheFactory.createCustomCache(
+  (cacheType, defaultTtl, defaultSize) => new MyCustomCache(),
+  {
+    mx: 1800000,
+    disposable: 86400000,
+    free: 86400000
+  }
+);
+
+// Use with verification
+const result = await verifyEmailDetailed({
+  emailAddress: 'user@mydomain.com',
+  verifyMx: true,
+  verifySmtp: true,
+  checkDisposable: true,
+  cache: customCache
+});
+```
+
+### Mixed Cache Configuration
+
+Use different cache backends for different types of data:
+
+```typescript
+const mixedCache = CacheFactory.createMixedCache({
+  // Use Redis for frequently accessed data
+  mx: {
+    store: redisStore,  // Your Redis store implementation
+    ttlMs: 1800000
+  },
+  smtp: {
+    store: redisStore,
+    ttlMs: 900000
+  },
+
+  // Use LRU for less critical data
+  disposable: {
+    ttlMs: 86400000  // 24 hours
+  },
+  free: {
+    ttlMs: 86400000  // 24 hours
+  },
+  domainValid: {
+    ttlMs: 86400000  // 24 hours
+  }
+});
+
+// Verification will use appropriate cache for each operation
+await verifyEmail({
+  emailAddress: 'user@tempmail.com',
+  verifyMx: true,
+  verifySmtp: true,
+  checkDisposable: true,
+  checkFree: true,
+  cache: mixedCache
+});
+```
+
+### Cache Best Practices
+
+1. **Choose Appropriate TTL**:
+   - MX Records: 30-60 minutes (DNS changes infrequently)
+   - SMTP Results: 15-30 minutes (Mailbox status changes)
+   - Disposable/Free Lists: 12-24 hours (Provider lists update slowly)
+
+2. **Handle Cache Errors Gracefully**:
+```typescript
+const result = await verifyEmail({
+  emailAddress: 'user@mydomain.com',
+  cache: unreliableCache, // Cache might fail
+  verifyMx: true,
+  verifySmtp: true
+});
+// Library continues to work even if cache operations fail
+```
+
+3. **Monitor Cache Hit Rates**:
+```typescript
+import { CacheFactory } from '@emailcheck/email-validator-js';
+
+// Create cache with hit tracking
+const cache = CacheFactory.createLRUCache();
+let hits = 0;
+let misses = 0;
+
+// Wrap cache store to track metrics
+const trackingCache = {
+  get: async (key: string) => {
+    const result = await cache.mx.get(key);
+    if (result !== null && result !== undefined) {
+      hits++;
+    } else {
+      misses++;
+    }
+    return result;
+  },
+  set: cache.mx.set.bind(cache.mx),
+  delete: cache.mx.delete.bind(cache.mx),
+  has: cache.mx.has.bind(cache.mx),
+  clear: cache.mx.clear.bind(cache.mx),
+  size: () => cache.mx.size()
+};
+
+// Monitor performance
+console.log(`Cache hit rate: ${(hits / (hits + misses) * 100).toFixed(1)}%`);
+```
+
+### Cache Key Structure
+
+The library uses the following cache key patterns:
+
+- **MX Records**: Domain name (e.g., `mydomain.com`)
+- **SMTP Verification**: Full email with `:smtp` suffix (e.g., `user@mydomain.com:smtp`)
+- **Disposable Check**: Domain name (e.g., `tempmail.com`)
+- **Free Provider Check**: Domain name (e.g., `gmail.com`)
+- **Domain Validation**: Domain name (e.g., `mydomain.com`)
+
+### Redis Production Setup
+
+For production Redis deployment:
+
+```typescript
+import Redis from 'ioredis';
+import { CacheFactory } from '@emailcheck/email-validator-js';
+
+// Production Redis configuration
+const redis = new Redis({
+  host: process.env.REDIS_HOST || 'localhost',
+  port: parseInt(process.env.REDIS_PORT || '6379'),
+  password: process.env.REDIS_PASSWORD,
+  db: parseInt(process.env.REDIS_DB || '0'),
+  retryDelayOnFailover: 100,
+  maxRetriesPerRequest: 3,
+  lazyConnect: true,
+  keepAlive: 30000,
+  family: 4,
+});
+
+// Handle Redis connection errors
+redis.on('error', (err) => {
+  console.error('Redis connection error:', err);
+});
+
+// Production cache with appropriate settings
+const productionCache = CacheFactory.createRedisCache(redis, {
+  keyPrefix: 'prod:email:',
+  defaultTtlMs: 3600000,
+  // Configure for high availability
+  jsonSerializer: {
+    stringify: (value: any) => JSON.stringify(value),
+    parse: (value: string) => JSON.parse(value)
+  }
+});
+
+// Graceful shutdown
+process.on('SIGTERM', async () => {
+  await redis.quit();
+  process.exit(0);
+});
+```
+
 **Note:** Yahoo, Hotmail, and some providers always return `validSmtp: true` as they don't allow mailbox verification.
 
 ## 🌐 Serverless Deployment

package/dist/adapters/lru-adapter.d.ts

@@ -0,0 +1,19 @@
+import { type LRU } from 'tiny-lru';
+import type { ICacheStore } from '../cache-interface';
+/**
+ * Adapter to make tiny-lru compatible with our cache interface
+ */
+export declare class LRUAdapter<T> implements ICacheStore<T> {
+    private lru;
+    constructor(maxSize?: number, ttlMs?: number);
+    get(key: string): T | null | undefined;
+    set(key: string, value: T, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    has(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    size(): number;
+    /**
+     * Get the underlying LRU instance for advanced operations
+     */
+    getLRU(): LRU<T>;
+}

package/dist/adapters/redis-adapter.d.ts

@@ -0,0 +1,45 @@
+import type { ICacheStore } from '../cache-interface';
+/**
+ * Redis client interface to avoid direct dependency on redis package
+ */
+export interface IRedisClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, mode?: string, duration?: number): Promise<string | null>;
+    del(key: string): Promise<number>;
+    exists(key: string): Promise<number>;
+    flushdb(): Promise<string>;
+}
+/**
+ * Redis adapter for the cache interface
+ * Supports JSON serialization for complex objects
+ */
+export declare class RedisAdapter<T> implements ICacheStore<T> {
+    private redis;
+    private keyPrefix;
+    private defaultTtlMs;
+    private jsonSerializer;
+    constructor(redis: IRedisClient, options?: {
+        keyPrefix?: string;
+        defaultTtlMs?: number;
+        jsonSerializer?: {
+            stringify: (value: T) => string;
+            parse: (value: string) => T;
+        };
+    });
+    private getKey;
+    /**
+     * Recursively process an object to convert Date instances to a serializable format
+     */
+    private processDatesForSerialization;
+    get(key: string): Promise<T | null>;
+    set(key: string, value: T, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    has(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    size(): number | undefined;
+    /**
+     * Helper method to delete only keys with the configured prefix
+     * Requires Redis SCAN command which might not be available in all Redis clients
+     */
+    clearPrefixed(): Promise<void>;
+}

package/dist/cache-factory.d.ts

@@ -0,0 +1,39 @@
+import { type IRedisClient } from './adapters/redis-adapter';
+import type { CacheConfig, ICache, ICacheStore } from './cache-interface';
+import { DEFAULT_CACHE_TTL } from './cache-interface';
+/**
+ * Cache factory object to create cache instances with different backends
+ */
+export declare const CacheFactory: {
+    /**
+     * Create a cache with LRU (tiny-lru) backend
+     */
+    createLRUCache(customTtl?: Partial<typeof DEFAULT_CACHE_TTL>): ICache;
+    /**
+     * Create a cache with Redis backend
+     */
+    createRedisCache(redis: IRedisClient, options?: {
+        keyPrefix?: string;
+        customTtl?: Partial<typeof DEFAULT_CACHE_TTL>;
+        jsonSerializer?: {
+            stringify: (value: any) => string;
+            parse: (value: string) => any;
+        };
+    }): ICache;
+    /**
+     * Create a cache with custom backend
+     */
+    createCustomCache(storeFactory: (cacheType: keyof typeof DEFAULT_CACHE_TTL, defaultTtl: number, defaultSize: number) => ICacheStore, customTtl?: Partial<typeof DEFAULT_CACHE_TTL>): ICache;
+    /**
+     * Create a mixed cache with different backends for different cache types
+     */
+    createMixedCache(config: {
+        mx?: CacheConfig;
+        disposable?: CacheConfig;
+        free?: CacheConfig;
+        domainValid?: CacheConfig;
+        smtp?: CacheConfig;
+        domainSuggestion?: CacheConfig;
+        whois?: CacheConfig;
+    }): ICache;
+};

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[]>;