@emailcheck/email-validator-js 2.13.1-beta.7 → 2.13.1-beta.9

package/README.md

@@ -442,11 +442,18 @@ isValidEmailDomain('mydomain.com'); // true
 isValidEmailDomain('example.invalid'); // false
 ```
 
-#### `clearAllCaches(): void`
-Clear all internal caches (including domain suggestions).
-
+#### Cache Management
 ```typescript
-clearAllCaches();
+import { getDefaultCache, clearDefaultCache, resetDefaultCache } from '@emailcheck/email-validator-js';
+
+// Get the default cache instance (singleton)
+const defaultCache = getDefaultCache();
+
+// Clear all entries from the default cache
+clearDefaultCache();
+
+// Reset to a fresh cache instance
+resetDefaultCache();
 ```
 
 ### Types and Interfaces
@@ -797,32 +804,65 @@ clearAllCaches();
 
 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
+### 📦 Performance & Caching
+
+The library includes a built-in LRU cache for all operations. By default, it uses a lazy-loaded singleton cache instance.
 
-#### LRU Cache (Default)
+#### Default Cache Usage
 ```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
+import { verifyEmail } from '@emailcheck/email-validator-js';
+
+// No cache setup needed - uses default LRU cache automatically
+const result = await verifyEmail({
+  emailAddress: 'user@example.com',
+  verifyMx: true,
+  verifySmtp: true
 });
 
+// Subsequent calls with the same email will use cached results
+const result2 = await verifyEmail({
+  emailAddress: 'user@example.com',
+  verifyMx: true,
+  verifySmtp: true
+});
+```
+
+#### Custom Cache Implementation
+
+Create your own cache by implementing the `ICache` interface:
+
+```typescript
+import { verifyEmail, type ICache, ICacheStore, DEFAULT_CACHE_OPTIONS } from '@emailcheck/email-validator-js';
+import { LRUAdapter } from '@emailcheck/email-validator-js';
+
+// Create custom cache with LRU adapters
+const customCache: ICache = {
+  mx: new LRUAdapter<string[]>(DEFAULT_CACHE_OPTIONS.maxSize.mx, DEFAULT_CACHE_OPTIONS.ttl.mx),
+  disposable: new LRUAdapter<boolean>(DEFAULT_CACHE_OPTIONS.maxSize.disposable, DEFAULT_CACHE_OPTIONS.ttl.disposable),
+  free: new LRUAdapter<boolean>(DEFAULT_CACHE_OPTIONS.maxSize.free, DEFAULT_CACHE_OPTIONS.ttl.free),
+  domainValid: new LRUAdapter<boolean>(DEFAULT_CACHE_OPTIONS.maxSize.domainValid, DEFAULT_CACHE_OPTIONS.ttl.domainValid),
+  smtp: new LRUAdapter<boolean | null>(DEFAULT_CACHE_OPTIONS.maxSize.smtp, DEFAULT_CACHE_OPTIONS.ttl.smtp),
+  domainSuggestion: new LRUAdapter<{ suggested: string; confidence: number } | null>(
+    DEFAULT_CACHE_OPTIONS.maxSize.domainSuggestion,
+    DEFAULT_CACHE_OPTIONS.ttl.domainSuggestion
+  ),
+  whois: new LRUAdapter<any>(DEFAULT_CACHE_OPTIONS.maxSize.whois, DEFAULT_CACHE_OPTIONS.ttl.whois),
+};
+
 // Use with email verification
 const result = await verifyEmail({
   emailAddress: 'user@mydomain.com',
   verifyMx: true,
   verifySmtp: true,
-  cache: lruCache  // Pass the cache instance
+  cache: customCache  // Pass the cache instance
 });
 ```
 
-#### Redis Cache
+#### Redis Cache Implementation
+
 ```typescript
-import { CacheFactory } from '@emailcheck/email-validator-js';
+import { verifyEmail, type ICache, ICacheStore } from '@emailcheck/email-validator-js';
+import { RedisAdapter } from '@emailcheck/email-validator-js';
 import Redis from 'ioredis';
 
 // Create Redis client
@@ -831,17 +871,41 @@ const redis = new Redis({
   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)
-  }
-});
+// Create Redis cache
+const redisCache: ICache = {
+  mx: new RedisAdapter(redis, {
+    keyPrefix: 'email:mx:',
+    ttl: 1800000, // 30 minutes
+  }),
+  disposable: new RedisAdapter(redis, {
+    keyPrefix: 'email:disposable:',
+    ttl: 86400000, // 24 hours
+  }),
+  free: new RedisAdapter(redis, {
+    keyPrefix: 'email:free:',
+    ttl: 86400000, // 24 hours
+  }),
+  domainValid: new RedisAdapter(redis, {
+    keyPrefix: 'email:domain:',
+    ttl: 86400000, // 24 hours
+  }),
+  smtp: new RedisAdapter(redis, {
+    keyPrefix: 'email:smtp:',
+    ttl: 1800000, // 30 minutes
+  }),
+  domainSuggestion: new RedisAdapter(redis, {
+    keyPrefix: 'email:suggest:',
+    ttl: 86400000, // 24 hours
+  }),
+  whois: new RedisAdapter(redis, {
+    keyPrefix: 'email:whois:',
+    ttl: 3600000, // 1 hour
+  }),
+};
 
 // Use with batch verification
+import { verifyEmailBatch } from '@emailcheck/email-validator-js';
+
 const batchResult = await verifyEmailBatch({
   emailAddresses: ['user1@mydomain.com', 'user2@mydomain.com'],
   verifyMx: true,
@@ -851,12 +915,12 @@ const batchResult = await verifyEmailBatch({
 });
 ```
 
-### Custom Cache Implementation
+#### Custom Cache Store Implementation
 
 Create your own cache adapter by implementing the `ICacheStore` interface:
 
 ```typescript
-import { CacheFactory, type ICacheStore } from '@emailcheck/email-validator-js';
+import { verifyEmail, type ICacheStore } from '@emailcheck/email-validator-js';
 
 class MyCustomCache<T> implements ICacheStore<T> {
   private store = new Map<string, { value: T; expiry: number }>();
@@ -883,7 +947,15 @@ class MyCustomCache<T> implements ICacheStore<T> {
   }
 
   async has(key: string): Promise<boolean> {
-    return this.store.has(key);
+    const item = this.store.get(key);
+    if (!item) return false;
+
+    if (Date.now() > item.expiry) {
+      this.store.delete(key);
+      return false;
+    }
+
+    return true;
   }
 
   async clear(): Promise<void> {
@@ -895,170 +967,52 @@ class MyCustomCache<T> implements ICacheStore<T> {
   }
 }
 
-// Create custom cache
-const customCache = CacheFactory.createCustomCache(
-  (cacheType, defaultTtl, defaultSize) => new MyCustomCache(),
-  {
-    mx: 1800000,
-    disposable: 86400000,
-    free: 86400000
-  }
-);
+// Use custom cache store
+const customCache = {
+  mx: new MyCustomCache<string[]>(),
+  disposable: new MyCustomCache<boolean>(),
+  free: new MyCustomCache<boolean>(),
+  domainValid: new MyCustomCache<boolean>(),
+  smtp: new MyCustomCache<boolean | null>(),
+  domainSuggestion: new MyCustomCache<{ suggested: string; confidence: number } | null>(),
+  whois: new MyCustomCache<any>(),
+};
 
-// Use with verification
 const result = await verifyEmail({
-  emailAddress: 'user@mydomain.com',
-  verifyMx: true,
-  verifySmtp: true,
-  checkDisposable: true,
+  emailAddress: 'user@example.com',
   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
+### Cache Options
 
-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)
+Default cache TTL and size settings:
 
-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()
+import { DEFAULT_CACHE_OPTIONS } from '@emailcheck/email-validator-js';
+
+// TTL (Time To Live) in milliseconds
+DEFAULT_CACHE_OPTIONS.ttl = {
+  mx: 3600000,              // 1 hour
+  disposable: 86400000,      // 24 hours
+  free: 86400000,           // 24 hours
+  domainValid: 86400000,    // 24 hours
+  smtp: 1800000,            // 30 minutes
+  domainSuggestion: 86400000, // 24 hours
+  whois: 3600000,           // 1 hour
 };
 
-// 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);
-});
+// Maximum number of entries per cache type
+DEFAULT_CACHE_OPTIONS.maxSize = {
+  mx: 500,
+  disposable: 1000,
+  free: 1000,
+  domainValid: 1000,
+  smtp: 500,
+  domainSuggestion: 1000,
+  whois: 200,
+};
 ```
-
-**Note:** Yahoo, Hotmail, and some providers always return `result.validSmtp: true` as they don't allow mailbox verification.
-
 ## 🌐 Serverless Deployment
 
 The package includes serverless adapters for major cloud platforms. The serverless implementation provides email validation without Node.js dependencies, making it suitable for edge computing environments.

package/dist/cache-interface.d.ts

@@ -1,6 +1,9 @@
+/**
+ * Simple cache interface for email validator
+ * Mirrors the logging pattern - pass as optional parameter
+ */
 /**
  * Generic cache interface that can be implemented by any cache store
- * including in-memory LRU cache, Redis, Memcached, etc.
  */
 export interface ICacheStore<T = any> {
     /**
@@ -13,7 +16,7 @@ export interface ICacheStore<T = any> {
      * 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
+     * @param ttlMs - Optional TTL in milliseconds
      */
     set(key: string, value: T, ttlMs?: number): Promise<void> | void;
     /**
@@ -37,54 +40,7 @@ export interface ICacheStore<T = any> {
     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
+ * Cache interface for different types of data
  */
 export interface ICache {
     mx: ICacheStore<string[]>;
@@ -98,27 +54,3 @@ export interface ICache {
     } | 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,40 +1,44 @@
 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>;
-export declare const freeCache: import("tiny-lru").LRU<boolean>;
-export declare const domainValidCache: import("tiny-lru").LRU<boolean>;
-export declare const smtpCache: import("tiny-lru").LRU<boolean | null>;
-export declare const domainSuggestionCache: import("tiny-lru").LRU<{
-    suggested: string;
-    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
+ * Default cache options
  */
-export declare function setCustomCache(cache: ICache): void;
+export declare const DEFAULT_CACHE_OPTIONS: {
+    ttl: {
+        mx: number;
+        disposable: number;
+        free: number;
+        domainValid: number;
+        smtp: number;
+        domainSuggestion: number;
+        whois: number;
+    };
+    maxSize: {
+        mx: number;
+        disposable: number;
+        free: number;
+        domainValid: number;
+        smtp: number;
+        domainSuggestion: number;
+        whois: number;
+    };
+};
 /**
- * Get the current global custom cache instance
+ * Get the default in-memory cache singleton using LRU
+ * This is created on first access and reused for all subsequent calls
  */
-export declare function getCustomCache(): ICache | null;
+export declare function getDefaultCache(): ICache;
 /**
- * Reset to use default LRU caches
+ * Helper function to get cache store from cache parameter
+ * Follows the same pattern as logging - use passed cache or default
  */
-export declare function resetToDefaultCache(): void;
+export declare function getCacheStore<T>(cache: ICache | null | undefined, key: keyof ICache): ICacheStore<T>;
 /**
- * Get cache adapter that works with passed cache, global cache, or default LRU
+ * Clear the default cache instance
+ * Useful for testing or when you want to reset cache state
  */
-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 declare function clearDefaultCache(): void;
+/**
+ * Reset the default cache instance to a fresh one
+ */
+export declare function resetDefaultCache(): void;
 export type { ICache, ICacheStore } from './cache-interface';

package/dist/domain-suggester.d.ts

@@ -1,3 +1,4 @@
+import type { ICache } from './cache-interface';
 import type { DomainSuggestion, ISuggestDomainParams } from './types';
 /**
  * List of common email domains for typo detection
@@ -11,7 +12,7 @@ export declare function defaultDomainSuggestionMethod(domain: string, commonDoma
 /**
  * Async version of default domain suggestion method
  */
-export declare function defaultDomainSuggestionMethodAsync(domain: string, commonDomains?: string[]): Promise<DomainSuggestion | null>;
+export declare function defaultDomainSuggestionMethodAsync(domain: string, commonDomains?: string[], cache?: ICache): Promise<DomainSuggestion | null>;
 /**
  * Suggest a corrected domain for a potentially misspelled email domain
  * @param params - Parameters including domain and optional custom method
@@ -22,9 +23,10 @@ export declare function suggestDomain(params: ISuggestDomainParams): DomainSugge
  * Convenience function to suggest domain from email address
  * @param email - Email address to check for domain typos
  * @param commonDomains - Optional list of common domains to check against
+ * @param cache - Optional cache instance
  * @returns Domain suggestion with confidence score, or null if no suggestion
  */
-export declare function suggestEmailDomain(email: string, commonDomains?: string[]): Promise<DomainSuggestion | null>;
+export declare function suggestEmailDomain(email: string, commonDomains?: string[], cache?: ICache): Promise<DomainSuggestion | null>;
 /**
  * Check if a domain is in the common domains list
  * @param domain - Domain to check

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { type IDisposableEmailParams, type IFreeEmailParams, type IVerifyEmailPa
 export * from './adapters/lru-adapter';
 export * from './adapters/redis-adapter';
 export { verifyEmailBatch } from './batch';
-export { clearAllCaches } from './cache';
+export * from './cache';
 export * from './cache-interface';
 export { COMMON_EMAIL_DOMAINS, defaultDomainSuggestionMethod, getDomainSimilarity, isCommonDomain, suggestDomain, suggestEmailDomain, } from './domain-suggester';
 export { defaultNameDetectionMethod, detectName, detectNameFromEmail } from './name-detector';