Cache

Caching system implementations for geocoding results with hybrid LRU/LFU eviction and factory pattern for multiple cache types.

Cache Adapters (adapters/cache/)

Caching system implementations for geocoding results with hybrid LRU/LFU eviction and factory pattern for multiple cache types.

Implementations

in-memory-cache.ts

High-performance in-memory cache with hybrid LRU/LFU eviction strategy.

Features:

• Hybrid LRU/LFU eviction algorithm
• Automatic TTL expiration
• Thread-safe operations
• Hit/miss statistics
• Configurable size limits

Eviction Strategy:

• Tracks both recency (LRU) and frequency (LFU)
• Protected entries (high frequency) are harder to evict
• Logarithmic frequency counters prevent overflow
• Efficient O(1) lookups and updates

Configuration:

cache: {
  maxEntries: 16384,        // Maximum cache size
  ttlDays: 7,               // Time to live in days
  lruFrequencyThreshold: 3, // Threshold for LRU vs LFU
  protectedFrequencyThreshold: 5  // High-frequency protection
}

cache-factory.ts

Factory for creating cache instances based on configuration.

Cache Types:

• "in-memory" - In-memory cache (default)
• "redis" - Redis cache (placeholder for future implementation)
• "none" - No-op cache (always returns miss)

Usage:

const cache = createCache({
  type: "in-memory",
  config: cacheConfig,
});

Cache Interface

Implements CacheServicePort:

interface CacheServicePort {
  get<T>(key: string): Promise<T | undefined>;
  set<T>(key: string, value: T, ttlDays?: number): Promise<CacheEntry<T>>;
  delete(key: string): Promise<boolean>;
  clear(): Promise<number>;
  getStats(): Promise<CacheStats>;
}

Performance Characteristics

• Get: O(1) average case
• Set: O(1) average case (O(log n) worst case with eviction)
• Delete: O(1)
• Clear: O(n)
• Memory: ~200 bytes per entry overhead

Statistics Tracking

const stats = await cache.getStats();
console.log(`Hit rate: ${stats.hitRate.toFixed(2)}%`);
console.log(`Evictions: ${stats.evictions}`);

Testing

• Unit tests: Verify eviction, expiration, statistics
• Integration tests: Test with real geocoding results
• Performance tests: Measure throughput and memory usage