shohan/dist/cache/index.d.ts

Production-grade utilities and tools by Shohan - Starting with Smart Cache System for Next.js applications

/**
 * 🔷 EZ Cache Types & Interfaces
 *
 * All TypeScript interfaces and types for the cache system
 */
interface MetricsData {
    hits: number;
    misses: number;
    errors: number;
    totalRequests: number;
    avgResponseTime: number;
    lastReset: number;
}
interface CacheItem {
    data: unknown;
    expires: number;
    lastAccess: number;
    hitCount: number;
    size: number;
    createdAt: number;
}
interface TrafficData {
    timestamps: number[];
    lastCleanup: number;
    totalRequests: number;
}
interface RedisStatus {
    available: boolean;
    connected: boolean;
    circuitOpen: boolean;
    failures: number;
    lastFailure: number;
    mode: 'unavailable' | 'connected' | 'disconnected' | 'circuit-open';
}
interface MemoryStats {
    size: number;
    maxSize: number;
    totalSizeKB: number;
    utilization: number;
    expiredItems: number;
    avgHitCount: number;
    oldestItem: number;
}
interface TrafficStats {
    endpoints: Record<string, unknown>;
    trackedEndpoints: number;
    trafficThreshold: number;
}
interface PerformanceStats extends MetricsData {
    hitRate: number;
    errorRate: number;
}
interface CacheOptions {
    /**
     * Time-to-live in seconds (optional, uses config default if not provided)
     * Memory will use this TTL, Redis will automatically use 10x this value
     * @example 300 // Memory: 5min, Redis: 50min
     */
    ttl?: number;
    /**
     * Minimum traffic count to activate caching for this specific item (optional, uses config default if not provided)
     * Lower values = more aggressive caching, Higher values = more conservative caching
     * @default 100 (production), 20 (test), 3 (development)
     * @example 5 // Cache after 5 requests (aggressive)
     * @example 50 // Cache after 50 requests (balanced)
     * @example 200 // Cache after 200 requests (conservative)
     */
    minTrafficCount?: number;
    /**
     * Force caching regardless of traffic (optional, defaults to false)
     * When true, ignores traffic patterns and always uses cache
     * @default false
     * @example true // Always cache (critical system data)
     * @example false // Respect traffic threshold (normal data)
     */
    forceCaching?: boolean;
}
interface SimpleCacheOptions {
    /**
     * Time-to-live in seconds (optional, uses config default if not provided)
     * Memory will use this TTL, Redis will automatically use 10x this value
     * @example 300 // Memory: 5min, Redis: 50min
     */
    ttl?: number;
    /**
     * Minimum traffic count to activate caching (optional, uses smart defaults)
     * @default Auto-calculated based on TTL: Short TTL = Lower threshold, Long TTL = Higher threshold
     * @example 5 // For hot data (TTL < 60s)
     * @example 25 // For warm data (TTL 60-600s)
     * @example 100 // For cold data (TTL > 600s)
     */
    minTrafficCount?: number;
    /**
     * Force caching regardless of traffic (optional)
     * @default false
     */
    forceCaching?: boolean;
}
interface CacheResult<T> {
    data: T;
    source: 'memory' | 'redis' | 'database';
    responseTime: number;
    isHighTraffic: boolean;
}
interface SystemStats {
    system: {
        environment: string;
        version: string;
        uptime: number;
        cacheStrategy: string;
    };
    memory: MemoryStats & {
        enabled: boolean;
    };
    redis: RedisStatus & {
        enabled: boolean;
        circuitBreakerEnabled: boolean;
    };
    traffic: TrafficStats;
    performance: PerformanceStats | null;
    config: {
        trafficThreshold: number;
        defaultTtl: number;
        memoryTtlMax: number;
        memorySize: number;
        maxValueSize: number;
    };
}

/**
 * 🚀 Production EZ Cache - Main Controller
 *
 * The main cache orchestrator that coordinates all components
 * Supports multiple cache modes: HYBRID, MEMORY_ONLY, REDIS_ONLY, DISABLED
 */

declare class ProductionEZCache {
    private memory;
    private traffic;
    private redis;
    private metrics;
    private cleanupInterval;
    constructor();
    /**
     * Initialize cache components based on configuration
     */
    private initializeComponents;
    /**
     * Helper function to calculate smart defaults based on TTL
     * Shorter TTL = More aggressive caching (lower traffic threshold)
     * Longer TTL = More conservative caching (higher traffic threshold)
     */
    private getSmartTrafficThreshold;
    /**
     * 🎯 Main cache method - TTL-focused with smart defaults
     *
     * Features intelligent defaults and flexible options:
     * - Pass just a number for TTL (gets smart traffic threshold)
     * - Pass an object for full control with TypeScript suggestions
     * - Smart traffic thresholds: Short TTL = aggressive, Long TTL = conservative
     * - Redis TTL automatically set to 10x memory TTL for optimal performance
     *
     * @param key - Cache key (auto-prefixed)
     * @param fetcher - Function to get data from database
     * @param optionsOrTtl - TTL number (simple) or options object (advanced) - optional
     * @returns Cached or fresh data
     *
     * @example
     * // Simple TTL (gets smart defaults)
     * await ezCache.fetch('products', fetcher, 300);
     *
     * @example
     * // Advanced with suggestions
     * await ezCache.fetch('products', fetcher, {
     *   ttl: 300,              // Memory: 5min, Redis: 50min
     *   minTrafficCount: 50,   // Cache after 50 requests
     *   forceCaching: false    // Respect traffic threshold
     * });
     */
    fetch<T>(key: string, fetcher: () => Promise<T>, optionsOrTtl?: number | SimpleCacheOptions): Promise<T>;
    /**
     * Fetch data from available cache layers with flexible TTL logic
     */
    private fetchFromCacheLayers;
    /**
     * Store data in available cache layers with optimal TTL strategy
     */
    private storeInCacheLayers;
    /**
     * 🗑️ Clear specific cache entry
     * @param key - Cache key to clear
     */
    clear(key: string): Promise<void>;
    /**
     * 🧹 Clear all cache
     */
    clearAll(): Promise<void>;
    /**
     * 🔄 Force refresh - get fresh data and update cache
     * @param key - Cache key
     * @param fetcher - Function to get fresh data
     * @param optionsOrTtl - TTL number or options object (optional)
     */
    forceRefresh<T>(key: string, fetcher: () => Promise<T>, optionsOrTtl?: number | SimpleCacheOptions): Promise<T>;
    /**
     * 📊 Get comprehensive system statistics
     */
    getStats(): SystemStats;
    /**
     * 🎯 Get simple cache status
     */
    getStatus(): {
        healthy: boolean;
        memoryUtilization: number;
        redisConnected: boolean;
        trackedEndpoints: number;
        efficiencyScore?: number;
    };
    /**
     * 🧪 Test cache functionality
     */
    test(): Promise<{
        memory: boolean;
        redis: boolean;
        traffic: boolean;
        overall: boolean;
    }>;
    /**
     * 🔧 Setup automatic cleanup processes
     */
    private setupCleanup;
    /**
     * 📝 Log current configuration
     */
    private logConfiguration;
    /**
     * 📝 Internal logging method
     */
    private log;
}

declare const CACHE_CONFIG: {
    readonly ENVIRONMENT: string;
    readonly IS_DEV: boolean;
    readonly IS_PROD: boolean;
    readonly IS_TEST: boolean;
    readonly ENABLE_MEMORY: boolean;
    readonly ENABLE_REDIS: boolean;
    readonly REDIS_URL: string;
    readonly REDIS_TOKEN: string;
    readonly REDIS_TIMEOUT: number;
    readonly REDIS_RETRY_ATTEMPTS: number;
    readonly ENABLE_CIRCUIT_BREAKER: boolean;
    readonly CIRCUIT_FAILURE_THRESHOLD: number;
    readonly CIRCUIT_RESET_TIMEOUT: number;
    readonly MEMORY_SIZE: number;
    readonly MEMORY_TTL_MAX: 180 | 300 | 120;
    readonly TRAFFIC_THRESHOLD: number;
    readonly DEFAULT_TTL: number;
    readonly CLEANUP_INTERVAL: number;
    readonly ENABLE_LOGGING: boolean;
    readonly ENABLE_METRICS: boolean;
    readonly ENABLE_TRAFFIC_DETECTION: boolean;
    readonly MAX_VALUE_SIZE: number;
    readonly WINDOW_MS: number;
    readonly TRACKER_CLEANUP_MS: number;
    readonly CACHE_STRATEGY: "aggressive" | "balanced" | "conservative" | "memory-only" | "custom";
    readonly CACHE_MODE: "HYBRID" | "MEMORY_ONLY" | "REDIS_ONLY" | "DISABLED";
};

/**
 * 🧠 Production Memory Cache
 *
 * LRU cache with smart eviction, size tracking, and automatic cleanup
 */

declare class ProductionMemoryCache {
    private cache;
    private totalSize;
    private lastCleanup;
    /**
     * Store data in memory cache
     * @param key - Cache key
     * @param data - Data to cache
     * @param ttlSeconds - Time to live in seconds
     * @returns Success status
     */
    set(key: string, data: unknown, ttlSeconds: number): boolean;
    /**
     * Get data from memory cache
     * @param key - Cache key
     * @returns Cached data or null
     */
    get<T>(key: string): T | null;
    /**
     * Delete specific cache entry
     * @param key - Cache key
     * @returns Success status
     */
    delete(key: string): boolean;
    /**
     * Clear all cache entries
     */
    clear(): void;
    /**
     * Get current cache size
     */
    size(): number;
    /**
     * Smart LRU eviction based on multiple factors
     * @returns Success status
     */
    private evictLRU;
    /**
     * Cleanup expired items
     */
    private cleanupExpired;
    /**
     * Estimate data size in bytes
     * @param data - Data to estimate
     * @returns Size in bytes
     */
    private estimateSize;
    /**
     * Get cache statistics
     */
    getStats(): MemoryStats;
}

/**
 * 📊 Production Traffic Tracker
 *
 * Tracks API request patterns with memory leak prevention and automatic cleanup
 */

declare class ProductionTrafficTracker {
    private requests;
    private lastGlobalCleanup;
    /**
     * Track a request and return current count
     * @param key - Endpoint identifier
     * @returns Current request count in window
     */
    track(key: string): number;
    /**
     * Check if endpoint has high traffic
     * @param key - Endpoint identifier
     * @param customThreshold - Custom traffic threshold (optional, uses config default)
     * @returns True if high traffic detected
     */
    isHighTraffic(key: string, customThreshold?: number): boolean;
    /**
     * Get current request count for endpoint
     * @param key - Endpoint identifier
     * @returns Current request count
     */
    getCurrentCount(key: string): number;
    /**
     * Clean up old timestamps for specific endpoint
     * @param key - Endpoint identifier
     * @param data - Traffic data to clean
     */
    private cleanupEndpoint;
    /**
     * Global cleanup of inactive endpoints
     */
    private globalCleanup;
    /**
     * Get comprehensive traffic statistics
     */
    getStats(): TrafficStats;
    /**
     * Clear all traffic data
     */
    clear(): void;
    /**
     * Get number of tracked endpoints
     */
    getTrackedEndpointsCount(): number;
}

/**
 * 💾 Resilient Redis Client - Production Grade
 *
 * Features:
 * - Graceful fallback when Redis is not available
 * - Circuit breaker pattern for fault tolerance
 * - Handles missing @upstash/redis package
 * - Safe for projects that don't use Redis
 * - Connection pooling and retry logic
 * - Health monitoring and metrics
 */

declare class ResilientRedis {
    private redis;
    private isConnected;
    private circuitOpen;
    private failureCount;
    private lastFailure;
    private connectionAttempts;
    private lastConnectionAttempt;
    private redisAvailable;
    private healthCheckInterval;
    private reconnectTimeout;
    private operationMetrics;
    private status;
    constructor();
    /**
     * Check if Redis package and configuration are available
     */
    private checkRedisAvailability;
    /**
     * Initialize Redis connection (only if available)
     */
    private initializeRedis;
    /**
     * Get value from Redis with enhanced error handling and metrics
     */
    get(key: string): Promise<unknown>;
    /**
     * Set value in Redis with expiration
     */
    setex(key: string, ttl: number, data: unknown): Promise<boolean>;
    /**
     * Delete key from Redis
     */
    del(key: string): Promise<boolean>;
    /**
     * Check if Redis is available for operations
     */
    private isAvailable;
    /**
     * Record a failure and potentially open circuit
     */
    private recordFailure;
    /**
     * Reset circuit breaker
     */
    private resetCircuit;
    /**
     * Get Redis connection status
     */
    getConnectionStatus(): RedisStatus;
    /**
     * Force retry connection (for admin/debugging)
     */
    forceReconnect(): Promise<boolean>;
    /**
     * Get Redis health info
     */
    getHealthInfo(): Promise<{
        available: boolean;
        connected: boolean;
        latency?: number;
        error?: string;
    }>;
    /**
     * Log messages (internal logging method)
     */
    private log;
    /**
     * Update internal status object
     */
    private updateStatus;
    /**
     * Schedule reconnection attempt
     */
    private scheduleReconnection;
    /**
     * Record successful operation for metrics
     */
    private recordSuccessfulOperation;
    /**
     * Record failed operation for metrics
     */
    private recordFailedOperation;
    /**
     * Start health monitoring (periodic health checks)
     */
    private startHealthMonitoring;
    /**
     * Cleanup resources
     */
    private cleanup;
    /**
     * Get operation metrics
     */
    getMetrics(): {
        totalOperations: number;
        successfulOperations: number;
        failedOperations: number;
        successRate: number;
        avgResponseTime: number;
        lastOperationTime: number;
    };
    /**
     * Additional Redis operations for completeness
     */
    exists(key: string): Promise<boolean>;
    ttl(key: string): Promise<number>;
    keys(pattern: string): Promise<string[]>;
}

/**
 * 📈 Performance Metrics Tracker
 *
 * Tracks cache performance metrics including hit rates and response times
 */

declare class PerformanceMetrics {
    private metrics;
    private responseTimes;
    /**
     * Record a cache hit
     * @param responseTime - Response time in milliseconds
     */
    recordHit(responseTime: number): void;
    /**
     * Record a cache miss
     * @param responseTime - Response time in milliseconds
     */
    recordMiss(responseTime: number): void;
    /**
     * Record an error
     */
    recordError(): void;
    /**
     * Record response time and update average
     * @param time - Response time in milliseconds
     */
    private recordResponseTime;
    /**
     * Get comprehensive performance statistics
     */
    getStats(): PerformanceStats;
    /**
     * Get detailed response time statistics
     */
    getResponseTimeStats(): {
        min: number;
        max: number;
        median: number;
        p95: number;
        p99: number;
    };
    /**
     * Reset all metrics
     */
    reset(): void;
    /**
     * Get cache efficiency score (0-100)
     */
    getEfficiencyScore(): number;
    /**
     * Check if metrics collection is enabled
     */
    isEnabled(): boolean;
}

/**
 * 🚀 Shohan Cache Module - Production-Grade Smart Cache System
 *
 * A sophisticated 3-layer cache architecture (Memory → Redis → Database) with:
 * - Intelligent traffic detection (caches only when beneficial)
 * - Smart TTL management (Redis gets 10x memory TTL)
 * - Zero-configuration setup with graceful fallbacks
 * - TypeScript-first API with intelligent defaults
 * - Circuit breaker for Redis failures
 * - Comprehensive metrics and monitoring
 *
 * @author Md Sabbir Roshid Shohan <shohan.dev.cse@gmail.com>
 * @version 1.0.0
 *
 * Usage:
 * ```typescript
 * import { cache } from 'shohan/cache';
 *
 * // Simple usage - Replace your DB calls with cache
 * const products = await cache.fetch('products', async () => {
 *   return [{ id: 1, name: 'Product 1' }]; // Your data fetching logic
 * });
 *
 * // With TTL
 * const users = await cache.fetch('users', async () => {
 *   return [{ id: 1, name: 'User 1' }];
 * }, 300);
 *
 * // Advanced configuration
 * const posts = await cache.fetch('posts', async () => {
 *   return [{ id: 1, title: 'Post 1' }];
 * }, {
 *   ttl: 300,
 *   minTrafficCount: 50,
 *   forceCaching: false
 * });
 * ```
 */

declare const cache: ProductionEZCache;

export { CACHE_CONFIG, type CacheItem, type CacheOptions, type CacheResult, type MemoryStats, type MetricsData, PerformanceMetrics, type PerformanceStats, ProductionEZCache, ProductionMemoryCache, ProductionTrafficTracker, type RedisStatus, ResilientRedis, type SimpleCacheOptions, type SystemStats, type TrafficData, type TrafficStats, cache, cache as default };