shohan/dist/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;

/**
 * 🚀 Shohan - Production-Grade Utilities & Tools
 *
 * A collection of production-ready utilities and tools for modern development.
 * Starting with the Smart Cache System, with more modules coming soon.
 *
 * @author Md Sabbir Roshid Shohan <shohan.dev.cse@gmail.com>
 * @version 1.0.0
 *
 * Available Modules:
 * - cache: Smart Cache System with 3-layer architecture
 *
 * Usage:
 * ```typescript
 * // Import specific module
 * import { cache } from 'shohan/cache';
 *
 * // Use the cache
 * const data = await cache.fetch('key', async () => {
 *   return { message: 'Hello from cache!' };
 * });
 * ```
 *
 * Coming Soon:
 * - auth: Authentication utilities
 * - db: Database helpers
 * - api: API utilities
 * - utils: General utilities
 */

declare const version = "1.0.0";
declare const author = "Md Sabbir Roshid Shohan";
declare const email = "shohan.dev.cse@gmail.com";
declare const modules: {
    cache: {
        description: string;
        version: string;
        status: string;
    };
};
declare const _default: {
    version: string;
    author: string;
    email: string;
    modules: {
        cache: {
            description: string;
            version: string;
            status: string;
        };
    };
};

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, author, cache, _default as default, email, modules, version };