@noony-serverless/core
Version:
A Middy base framework compatible with Firebase and GCP Cloud Functions with TypeScript
228 lines • 7.07 kB
TypeScript
/**
* Memory Cache Adapter with LRU Eviction
*
* High-performance in-memory cache implementation using Least Recently Used (LRU)
* eviction strategy. Optimized for single-instance deployments where sub-millisecond
* cache lookups are critical for authentication performance.
*
* Features:
* - O(1) get/set operations using Map and doubly-linked list
* - TTL support with lazy expiration checking
* - Configurable size limits with automatic eviction
* - Pattern-based deletion for cache invalidation
* - Performance metrics for monitoring
* - Memory usage tracking
*
* @author Noony Framework Team
* @version 1.0.0
*/
import { CacheAdapter, CacheStats, CacheConfiguration } from './CacheAdapter';
/**
* Memory cache adapter with LRU eviction policy.
*
* Uses a combination of Map for O(1) key lookups and a doubly-linked list
* for O(1) LRU operations. TTL is implemented with lazy expiration checking
* to avoid timer overhead.
*
* @example
* Basic usage:
* ```typescript
* import { MemoryCacheAdapter } from '@noony/core';
*
* const cache = new MemoryCacheAdapter({
* maxSize: 10000, // Store up to 10,000 entries
* defaultTTL: 300000, // 5 minutes default TTL
* name: 'UserCache' // For debugging/monitoring
* });
*
* // Store user permissions
* await cache.set('user:123:permissions', ['read', 'write'], 600000);
*
* // Retrieve from cache
* const permissions = await cache.get<string[]>('user:123:permissions');
* if (permissions) {
* console.log('Found in cache:', permissions);
* }
* ```
*
* @example
* Performance monitoring:
* ```typescript
* // Get cache statistics
* const stats = await cache.getStats();
* console.log(`Cache performance:
* Hit rate: ${stats.hitRate}%
* Total entries: ${stats.totalEntries}
* Memory usage: ${(stats.memoryUsage || 0) / 1024 / 1024} MB`);
*
* // Monitor cache health
* if (stats.hitRate < 80) {
* console.warn('Cache hit rate is low - consider increasing TTL');
* }
* ```
*
* @example
* Cache invalidation patterns:
* ```typescript
* // Clear all cache entries for a specific user
* await cache.deletePattern('user:123:*');
*
* // Clear all permission caches
* await cache.deletePattern('permissions:*');
*
* // Clear everything (emergency invalidation)
* await cache.flush();
* ```
*/
export declare class MemoryCacheAdapter implements CacheAdapter {
private readonly cache;
private readonly maxSize;
private readonly defaultTTL;
private readonly name;
private head?;
private tail?;
private stats;
/**
* Creates a new memory cache adapter instance.
*
* @param config - Cache configuration with size, TTL, and name settings
* @throws Error if maxSize or defaultTTL are invalid
*
* @example
* ```typescript
* // Create cache for user authentication
* const authCache = new MemoryCacheAdapter({
* maxSize: 5000, // Store up to 5k user sessions
* defaultTTL: 900000, // 15 minutes default TTL
* name: 'AuthCache' // For monitoring and debugging
* });
* ```
*
* @example
* ```typescript
* // Create cache for permission data
* const permissionCache = new MemoryCacheAdapter({
* maxSize: 10000, // Higher capacity for permissions
* defaultTTL: 300000, // 5 minutes default TTL
* name: 'PermissionCache' // Descriptive name for logs
* });
* ```
*/
constructor(config: CacheConfiguration);
/**
* Retrieve a value from cache.
* Implements LRU behavior by moving accessed entries to the head of the list.
* Performs lazy expiration checking for better performance.
*
* @param key - Cache key to retrieve
* @returns Promise resolving to cached value or null if not found/expired
*
* @example
* ```typescript
* // Retrieve user permissions with type safety
* const permissions = await cache.get<string[]>('user:123:permissions');
* if (permissions) {
* console.log('Found permissions:', permissions);
* } else {
* console.log('Cache miss - loading from database');
* const dbPermissions = await loadFromDatabase('123');
* await cache.set('user:123:permissions', dbPermissions);
* }
* ```
*/
get<T>(key: string): Promise<T | null>;
/**
* Store a value in cache with optional TTL.
* If the key already exists, updates the value and moves to head.
* Triggers LRU eviction if cache size exceeds maxSize.
*
* @param key - Cache key to store under
* @param value - Value to cache (must be serializable)
* @param ttlMs - Time to live in milliseconds (defaults to defaultTTL)
*
* @example
* ```typescript
* // Store user data with custom TTL
* await cache.set('user:123:profile', {
* id: 123,
* name: 'John Doe',
* roles: ['admin', 'user']
* }, 1800000); // 30 minutes
*
* // Store with default TTL
* await cache.set('session:abc123', { userId: 123, active: true });
*
* // Store permission data
* await cache.set('user:123:permissions', ['read', 'write'], 600000);
* ```
*/
set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
/**
* Delete a specific cache entry
*
* @param key - Cache key to delete
*/
delete(key: string): Promise<void>;
/**
* Delete multiple cache entries matching a pattern
*
* Supports simple wildcard patterns:
* - "user:*" matches all keys starting with "user:"
* - "*:123" matches all keys ending with ":123"
* - "*pattern*" matches all keys containing "pattern"
*
* @param pattern - Pattern to match keys
*/
deletePattern(pattern: string): Promise<void>;
/**
* Clear all cache entries
*/
flush(): Promise<void>;
/**
* Get cache statistics for monitoring
*
* @returns Cache statistics including hit rate and memory usage
*/
getStats(): Promise<CacheStats>;
/**
* Get cache name for debugging
*/
getName(): string;
/**
* Get current cache size
*/
size(): number;
/**
* Check if cache is at maximum capacity
*/
isFull(): boolean;
/**
* Add entry to head of linked list (most recently used)
*/
private addToHead;
/**
* Move existing entry to head of linked list
*/
private moveToHead;
/**
* Remove entry from linked list (but not from cache)
*/
private removeFromList;
/**
* Remove entry from both cache and linked list
*/
private removeEntry;
/**
* Evict least recently used entry (tail)
*/
private evictTail;
/**
* Convert glob pattern to regular expression
*/
private patternToRegex;
/**
* Estimate memory usage of a cache entry (rough approximation)
*/
private estimateEntrySize;
}
//# sourceMappingURL=MemoryCacheAdapter.d.ts.map