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

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,59 +123,45 @@ 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
 });
 
-console.log(result.validFormat); // true
-console.log(result.validMx);     // true
-console.log(result.validSmtp);   // true or false
+console.log(result.valid);     // Overall validity
+console.log(result.format.valid); // true
+console.log(result.domain.valid); // true or false
+console.log(result.smtp.valid);   // true or false
 ```
 
 ## API Reference
 
 ### Core Functions
 
-#### `verifyEmail(params: IVerifyEmailParams): Promise<IVerifyEmailResult>`
+#### `verifyEmail(params: IVerifyEmailParams): Promise<DetailedVerificationResult>`
 
-Basic email verification with backward compatibility.
+Comprehensive email verification with detailed results and error codes.
 
 **Parameters:**
 - `emailAddress` (string, required): Email address to verify
 - `timeout` (number): Timeout in milliseconds (default: 4000)
-- `verifyMx` (boolean): Check MX records (default: false)
+- `verifyMx` (boolean): Check MX records (default: true)
 - `verifySmtp` (boolean): Verify SMTP connection (default: false)
 - `smtpPort` (number): Custom SMTP port
 - `debug` (boolean): Enable debug logging (default: false)
-- `detectName` (boolean): Detect names from email address (default: false)
-- `nameDetectionMethod` (function): Custom name detection method
-- `suggestDomain` (boolean): Enable domain typo suggestions (default: false)
-- `domainSuggestionMethod` (function): Custom domain suggestion method
-- `commonDomains` (string[]): Custom list of domains for suggestions
-
-**Returns:**
-```typescript
-{
-  validFormat: boolean;
-  validMx: boolean | null;
-  validSmtp: boolean | null;
-  detectedName?: DetectedName | null;
-  domainSuggestion?: DomainSuggestion | null;
-}
-```
-
-#### `verifyEmailDetailed(params: IVerifyEmailParams): Promise<DetailedVerificationResult>`
-
-Advanced verification with detailed results and error codes.
-
-**Additional Parameters:**
 - `checkDisposable` (boolean): Check for disposable emails (default: true)
 - `checkFree` (boolean): Check for free email providers (default: true)
 - `retryAttempts` (number): Retry attempts for failures (default: 1)
 - `detectName` (boolean): Detect names from email address (default: false)
-- `suggestDomain` (boolean): Enable domain typo suggestions (default: true in detailed mode)
+- `nameDetectionMethod` (function): Custom name detection method
+- `suggestDomain` (boolean): Enable domain typo suggestions (default: true)
+- `domainSuggestionMethod` (function): Custom domain suggestion method
+- `commonDomains` (string[]): Custom list of domains for suggestions
+- `checkDomainAge` (boolean): Check domain age (default: false)
+- `checkDomainRegistration` (boolean): Check domain registration status (default: false)
+- `whoisTimeout` (number): WHOIS lookup timeout (default: 5000)
+- `cache` (ICache): Optional custom cache instance
 
 **Returns:**
 ```typescript
@@ -237,7 +224,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 +257,7 @@ const customMethod = (email: string) => {
 };
 
 const name = detectNameFromEmail({
-  email: 'user@example.com',
+  email: 'user@mydomain.com',
   customMethod: customMethod
 });
 ```
@@ -349,10 +336,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 +348,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 +362,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 +417,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 +433,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
 ```
 
@@ -590,22 +577,23 @@ Number of retry attempts for transient failures. Default: `1`.
 ```typescript
 import { verifyEmail } from '@emailcheck/email-validator-js';
 
-const { validFormat, validSmtp, validMx } = await verifyEmail({ 
-  emailAddress: 'foo@email.com', 
-  verifyMx: true, 
-  verifySmtp: true, 
-  timeout: 3000 
+const result = await verifyEmail({
+  emailAddress: 'foo@email.com',
+  verifyMx: true,
+  verifySmtp: true,
+  timeout: 3000
 });
-// validFormat: true
-// validMx: true
-// validSmtp: true
+console.log(result.valid);       // true
+console.log(result.format.valid); // true
+console.log(result.domain.valid); // true
+console.log(result.smtp.valid);   // true
 ```
 
 ### Detailed Verification (NEW)
 ```typescript
-import { verifyEmailDetailed } from '@emailcheck/email-validator-js';
+import { verifyEmail } from '@emailcheck/email-validator-js';
 
-const result = await verifyEmailDetailed({
+const result = await verifyEmail({
   emailAddress: 'foo@email.com',
   verifyMx: true,
   verifySmtp: true,
@@ -623,7 +611,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,
@@ -638,26 +626,26 @@ const result = await verifyEmailBatch({
 
 ### Name Detection (ENHANCED)
 ```typescript
-import { detectName, verifyEmailDetailed } from '@emailcheck/email-validator-js';
+import { detectName, verifyEmail } 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',
+const result = await verifyEmail({
+  emailAddress: 'jane_smith@mydomain.com',
   detectName: true
 });
 // result.detectedName: { firstName: 'Jane', lastName: 'Smith', confidence: 0.8 }
@@ -669,7 +657,7 @@ const customMethod = (email: string) => {
 };
 
 const resultCustom = await verifyEmail({
-  emailAddress: 'user@example.com',
+  emailAddress: 'user@mydomain.com',
   detectName: true,
   nameDetectionMethod: customMethod
 });
@@ -677,14 +665,14 @@ const resultCustom = await verifyEmail({
 
 ### Domain Typo Detection (NEW)
 ```typescript
-import { suggestEmailDomain, verifyEmailDetailed } from '@emailcheck/email-validator-js';
+import { suggestEmailDomain, verifyEmail } from '@emailcheck/email-validator-js';
 
 // Standalone domain suggestion
 const suggestion = suggestEmailDomain('user@gmial.com');
 // suggestion: { original: 'user@gmial.com', suggested: 'user@gmail.com', confidence: 0.95 }
 
 // Integrated with email verification (enabled by default in detailed mode)
-const result = await verifyEmailDetailed({
+const result = await verifyEmail({
   emailAddress: 'john@yaho.com',
   suggestDomain: true  // Default: true for detailed verification
 });
@@ -704,20 +692,21 @@ const resultCustom = await verifyEmail({
 
 When a domain does not exist or has no MX records:
 ```typescript
-const result = await verifyEmail({ 
-  emailAddress: 'foo@bad-domain.com', 
-  verifyMx: true, 
-  verifySmtp: true 
+const result = await verifyEmail({
+  emailAddress: 'foo@bad-domain.com',
+  verifyMx: true,
+  verifySmtp: true
 });
-// validFormat: true
-// validMx: false
-// validSmtp: null (couldn't be performed)
+// result.valid: false (domain or SMTP failed)
+// result.format.valid: true
+// result.domain.valid: false
+// result.smtp.valid: null (couldn't be performed)
 ```
 
 ### Using Detailed Verification for Better Insights
 
 ```typescript
-const detailed = await verifyEmailDetailed({
+const detailed = await verifyEmail({
   emailAddress: 'user@suspicious-domain.com',
   verifyMx: true,
   verifySmtp: true,
@@ -776,16 +765,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,7 +782,271 @@ const second = await verifyEmail({
 clearAllCaches();
 ```
 
-**Note:** Yahoo, Hotmail, and some providers always return `validSmtp: true` as they don't allow mailbox verification.
+## 🚀 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 verifyEmail({
+  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 `result.smtp.valid: 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;
+};