opticore-cache 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,597 @@
+import { ILoggerConfig } from 'opticore-logger';
+import { Request, Response, NextFunction } from 'opticore-express';
+
+/**
+ * Cache usage statistics
+ */
+interface CacheStatistics {
+    /** Number of successful cache reads */
+    hits: number;
+    /** Number of read failures (miss cache) */
+    misses: number;
+    /** Number of writes to the cache */
+    writes: number;
+    /** Number of entries currently in the cache */
+    size: number;
+    /** Maximum configured cache size */
+    maxSize: number;
+    /** Success rate (hits / (hits + misses)) */
+    hitRate: number;
+    /** Usage Percentage (size / maxSize) */
+    usagePercentage: number;
+}
+
+/**
+ * Interface defining the contract for a cache repository
+ * Follows the Repository pattern for persistence abstraction
+ */
+interface ICacheRepository {
+    /**
+     * Stores a value in the cache
+     *
+     * @param key - Unique key for the entry
+     * @param value - Value to store
+     * @param ttl - Time to live in milliseconds (optional)
+     * @returns Promise<void>
+     */
+    set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    /**
+     * Retrieves a value from the cache
+     *
+     * @param key - Key of the entry to retrieve
+     * @returns Promise<T | null> - The value or null if not found/expired
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Deletes an entry from the cache
+     *
+     * @param key - Key of the entry to delete
+     * @returns Promise<void>
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Checks if a key exists in the cache (not expired)
+     *
+     * @param key - Key to check
+     * @returns Promise<boolean>
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Deletes all entries from the cache
+     *
+     * @returns Promise<void>
+     */
+    clear(): Promise<void>;
+    /**
+     * Retrieves all valid keys from the cache
+     *
+     * @returns Promise<string[]> - List of keys
+     */
+    keys(): Promise<string[]>;
+    /**
+     * Retrieves cache usage statistics
+     *
+     * @returns Promise<CacheStatistics>
+     */
+    getStatistics(): Promise<CacheStatistics>;
+    /**
+     * Invalidates entries whose key matches the pattern
+     *
+     * @param pattern - Pattern of keys to invalidate
+     * @returns Promise<number> - Number of entries invalidated
+     */
+    invalidate(pattern: string): Promise<number>;
+}
+
+/**
+ * Factory pour créer des instances de cache selon la configuration
+ * Implémente le pattern Factory Method
+ */
+declare class CacheFactoryRepository {
+    /**
+     * Crée une instance de cache basée sur la configuration
+     *
+     * @param customConfig - Configuration personnalisée (optionnel)
+     * @returns CacheRepository | null - Instance de cache ou null si désactivé
+     */
+    static createCache(customConfig?: Partial<any>): ICacheRepository | null;
+    /**
+     * Crée un cache avec une configuration minimale
+     *
+     * @param enabled - Activer le cache
+     * @param maxSize - Taille maximale
+     * @returns CacheRepository | null
+     */
+    static createSimpleCache(enabled: boolean, maxSize?: number): ICacheRepository | null;
+}
+
+/**
+ * Application caching service that exposes a simple API to controllers
+ * Acts as a facade for domain use cases
+ */
+declare class CacheService {
+    private readonly cacheUseCase;
+    private readonly cacheRepository;
+    private readonly localLang;
+    private readonly configLogger;
+    /**
+     * Creates a CacheService instance
+     *
+     * @param cacheRepository - Cache repository (may be null if disabled)
+     * @param localLang
+     * @param configLogger
+     */
+    constructor(cacheRepository: ICacheRepository | null, localLang: string, configLogger?: Partial<ILoggerConfig>);
+    /**
+     * Retrieves a value or adds it if absent
+     *
+     * @param key - Input key
+     * @param fetcher - Function to retrieve the value if absent
+     * @param ttl - Specific time to live
+     * @returns Promise<T> - Cache value or fetch result
+     */
+    getOrSet<T>(key: string, fetcher: () => Promise<T>, ttl?: number): Promise<T>;
+    /**
+     * Stores a value directly in the cache
+     *
+     * @param key - Input key
+     * @param value - Value to store
+     * @param ttl - Time to live
+     * @returns Promise<void>
+     */
+    set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    /**
+     * Retrieves a value from the cache
+     *
+     * @param key - Input key
+     * @returns Promise<T | null>
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Removes an entry from the cache
+     *
+     * @param key - Entry key
+     * @returns Promise<void>
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Invalidates entries matching the pattern
+     *
+     * @param pattern - Pattern for selecting entries
+     * @returns Promise<number> - Number of invalidated entries
+     */
+    invalidate(pattern: string): Promise<number>;
+    /**
+     * Clear cache completely
+     *
+     * @returns Promise<void>
+     */
+    clear(): Promise<void>;
+    /**
+     * Get cache stats
+     *
+     * @returns Promise<CacheStatistics>
+     */
+    getStatistics(): Promise<CacheStatistics>;
+    /**
+     * Check the cache health status
+     *
+     * @returns Promise<{ healthy: boolean; message: string }>
+     */
+    healthCheck(): Promise<{
+        healthy: boolean;
+        message: string;
+    }>;
+    /**
+     * Check if the cache is enabled
+     * @returns boolean
+     */
+    isEnabled(): boolean;
+    /**
+     * Retrieves all keys from the cache
+     *
+     * @returns Promise<string[]> - List of keys
+     */
+    getKeys(): Promise<string[]>;
+    /**
+     * Checks if a key exists in the cache
+     *
+     * @param key - Key to check
+     * @returns Promise<boolean>
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Creates and configures a full cache service
+     *
+     * @param customConfig - Custom configuration (optional)
+     * @returns CacheService - Cache service configured
+     */
+    createCache(customConfig?: Partial<any>): CacheService;
+    /**
+     *
+     * @private
+     */
+    private translatorConfig;
+    private logger;
+}
+
+/**
+ * Options de configuration du middleware de cache
+ */
+interface ICacheMiddlewareOptions {
+    /** Durée de vie spécifique pour cette route */
+    timeToLive?: number;
+    /** Fonction pour générer la clé de cache */
+    keyGenerator?: (req: Request) => string;
+    /** Fonction pour déterminer si la requête doit être ignorée */
+    shouldSkip?: (req: Request) => boolean;
+    /** Fonction pour transformer la réponse avant stockage */
+    responseTransformer?: (body: any) => any;
+    /** Activer/désactiver le cache pour ce middleware */
+    enabled?: boolean;
+}
+
+type TCreateMiddlewareResponseType = (req: Request, res: Response, next: NextFunction) => Promise<void | Response<any, Record<string, any>>>;
+
+type TCreateStatsMiddlewareResponse = Promise<Response<any, Record<string, any>> | undefined>;
+
+/**
+ * Middleware Express pour la mise en cache automatique des réponses
+ */
+declare class CacheMiddleware {
+    private readonly routeValidator;
+    private readonly config;
+    /**
+     * Crée une instance de CacheMiddleware
+     */
+    constructor();
+    /**
+     * Crée un middleware Express configurable
+     * @param cacheRepository - Repository de cache à utiliser
+     * @param options - Options de configuration du middleware
+     * @returns Middleware Express
+     */
+    createMiddleware(cacheRepository: ICacheRepository | null, options?: ICacheMiddlewareOptions): TCreateMiddlewareResponseType;
+    /**
+     * Détermine si une requête doit être skipée
+     * @param req - Requête Express
+     * @param options - Options du middleware
+     * @returns boolean
+     * @private
+     */
+    private shouldSkipRequest;
+    /**
+     * Générateur de clé par défaut
+     * @param req - Requête Express
+     * @returns string - Clé de cache
+     * @private
+     */
+    private defaultKeyGenerator;
+    /**
+     * Normalizes a path for the cache
+     *
+     * @param path - Path to be standardized
+     * @returns string
+     * @private
+     */
+    private normalizePath;
+    /**
+     * Adds HTTP headers related to the cache
+     *
+     * @param res - Express Response
+     * @param status - Cache status (HIT/MISS)
+     * @param key - Cache key
+     * @param ttl - Lifespan (optional)
+     * @private
+     */
+    private addCacheHeaders;
+    /**
+     * Creates middleware to display cache statistics
+     * @param cacheRepository - Cache repository
+     * @returns Middleware Express
+     */
+    createStatsMiddleware(cacheRepository: ICacheRepository | null): (req: Request, res: Response, next: NextFunction) => TCreateStatsMiddlewareResponse;
+    /**
+     * Create a middleware to clear the cache
+     *
+     * @param cacheRepository - Cache repository
+     * @returns Middleware Express
+     */
+    createClearMiddleware(cacheRepository: ICacheRepository | null): (req: Request, res: Response, next: NextFunction) => Promise<Response<any, Record<string, any>> | undefined>;
+}
+
+/**
+ * Charge et valide la configuration depuis les variables d'environnement
+ * Implémente le pattern Singleton pour garantir une seule instance
+ */
+declare class EnvironmentLoader {
+    private static instance;
+    private configuration;
+    /**
+     * Constructeur privé pour forcer l'utilisation de getInstance()
+     */
+    private constructor();
+    /**
+     * Récupère l'instance unique du EnvironmentLoader
+     *
+     * @returns EnvironmentLoader
+     */
+    static getInstance(): EnvironmentLoader;
+    /**
+     * Charge et parse la configuration depuis process.env
+     *
+     * @private
+     */
+    private loadConfiguration;
+    /**
+     * Parse une valeur booléenne depuis les variables d'environnement
+     *
+     * @param key - Clé de la variable d'environnement
+     * @param defaultValue - Valeur par défaut si non définie
+     * @returns boolean
+     */
+    private parseBoolean;
+    /**
+     * Parse un nombre depuis les variables d'environnement
+     *
+     * @param key - Clé de la variable d'environnement
+     * @param defaultValue - Valeur par défaut si non définie ou invalide
+     * @returns number
+     */
+    private parseNumber;
+    /**
+     * Parse la stratégie d'éviction depuis les variables d'environnement
+     *
+     * @param key - Clé de la variable d'environnement
+     * @param defaultValue - Valeur par défaut
+     * @returns 'lru' | 'fifo' | 'lfu'
+     */
+    private parseEvictionStrategy;
+    /**
+     * Parse la liste des routes à ignorer depuis les variables d'environnement
+     *
+     * @param key - Clé de la variable d'environnement
+     * @returns string[] - Liste des routes à ignorer
+     */
+    private parseSkipRoutes;
+    /**
+     * Récupère la configuration complète
+     *
+     * @returns CacheConfiguration
+     */
+    getConfig(): any;
+    /**
+     * Met à jour la configuration (pour les tests)
+     *
+     * @param updates - Mises à jour partielles de configuration
+     */
+    updateConfig(updates: Partial<any>): void;
+}
+
+/**
+ * Pattern de route avec sa méthode HTTP associée
+ */
+interface IRoutePattern {
+    /** Méthode HTTP (undefined = toutes méthodes) */
+    method?: string;
+    /** Chemin de la route */
+    path: string;
+    /** Expression régulière compilée pour le matching */
+    regexPattern: RegExp;
+}
+
+/**
+ * Valide et match les routes contre des patterns configurés
+ * Gère les wildcards et les méthodes HTTP
+ */
+declare class RouteValidator {
+    private readonly skipRoutes;
+    private readonly enableWildcards;
+    private routePatterns;
+    /**
+     * Crée une instance de RouteValidator
+     *
+     * @param skipRoutes - Liste des routes à ignorer
+     * @param enableWildcards - Activer le support des wildcards
+     */
+    constructor(skipRoutes?: string[], enableWildcards?: boolean);
+    /**
+     * Compile les patterns de route en expressions régulières
+     *
+     * @private
+     */
+    private compileRoutePatterns;
+    /**
+     * Parse un pattern de route en méthode et chemin
+     *
+     * @param routePattern - Pattern à parser (format: "METHOD:path" ou "path")
+     * @returns {{ method?: string; path: string }}
+     */
+    private parseRoutePattern;
+    /**
+     * Compile un chemin en expression régulière
+     *
+     * @param path - Chemin à compiler
+     * @param enableWildcards - Activer le support des wildcards
+     * @returns RegExp
+     */
+    private compileToRegex;
+    /**
+     * Échappe les caractères spéciaux pour les expressions régulières
+     *
+     * @param string - Chaîne à échapper
+     * @returns string
+     */
+    private escapeRegex;
+    /**
+     * Vérifie si une requête correspond à un pattern de route ignorée
+     *
+     * @param request - Requête Express à vérifier
+     * @returns boolean - True si la route doit être ignorée
+     */
+    shouldSkipRoute(request: Request): boolean;
+    /**
+     * Normalise un chemin (supprime les slashes de fin)
+     *
+     * @param path - Chemin à normaliser
+     * @returns string - Chemin normalisé
+     */
+    private normalizePath;
+    /**
+     * Récupère la liste des patterns compilés (pour debug)
+     *
+     * @returns RoutePattern[]
+     */
+    getCompiledPatterns(): IRoutePattern[];
+}
+
+type CreateStatsMiddlewareResponseType = (req: Request, res: Response, next: NextFunction) => TCreateStatsMiddlewareResponse;
+
+type CreateClearMiddlewareResponseType = (req: Request, res: Response, next: NextFunction) => Promise<Response<any, Record<string, any>> | undefined>;
+
+/**
+ *
+ */
+declare class SCacheMiddleware {
+    /**
+     * Create and configure a complete caching service
+     *
+     * @param customConfig - Custom configuration (optional)
+     * @returns CacheService - Cache service configured
+     */
+    static cacheService(customConfig?: Partial<any>): CacheService;
+    /**
+     * Creates an Express middleware for automatic caching
+     *
+     * @param customConfig - Custom configuration (optional)
+     * @returns Express middleware configured
+     */
+    static cacheMiddleware(customConfig?: Partial<any>): TCreateMiddlewareResponseType;
+    /**
+     * Creates a middleware for cache statistics
+     *
+     * @returns Middleware Express
+     */
+    static createStatsMiddleware(): CreateStatsMiddlewareResponseType;
+    /**
+     * Create a middleware to clear the cache
+     *
+     * @returns Middleware Express
+     */
+    static createClearMiddleware(): CreateClearMiddlewareResponseType;
+}
+
+interface HttpCacheStats {
+    totalRequests: number;
+    cacheHits: number;
+    cacheMisses: number;
+    cacheSize: number;
+    hitRate: number;
+    cachedUrls: string[];
+    timestamp: string;
+    enabled: boolean;
+}
+
+/**
+ * Interface de base pour les options de cache
+ * Peut être étendue par différents types de cache
+ */
+interface BaseCacheOptions {
+    /** Durée de vie en millisecondes */
+    timeToLive?: number;
+    /** Activer/désactiver le cache */
+    enabled?: boolean;
+    /** Stratégie de cache */
+    strategy?: string;
+    /** Clé personnalisée */
+    customKey?: string;
+}
+
+interface HttpCacheOptions extends BaseCacheOptions {
+    bypassCache?: boolean;
+    customKey?: string;
+    namespace?: string;
+}
+
+interface IHttpCacheService {
+    /**
+     * Execute une requête GET avec cache
+     */
+    getWithCache<T>(url: string, options?: RequestInit, cacheOptions?: HttpCacheOptions): Promise<T & {
+        _metadata: any;
+    }>;
+    /**
+     * Execute une requête POST avec mise en cache optionnelle
+     */
+    postWithCache<T>(url: string, data: any, options?: RequestInit, cacheResponse?: boolean, cacheOptions?: HttpCacheOptions): Promise<T>;
+    /**
+     * Invalide le cache pour une URL spécifique ou un pattern
+     */
+    invalidateCache(urlOrPattern: string): Promise<number>;
+    /**
+     * Vide complètement le cache HTTP
+     */
+    clearHttpCache(): Promise<void>;
+    /**
+     * Récupère les statistiques du cache HTTP
+     */
+    getStats(): Promise<HttpCacheStats>;
+    /**
+     *
+     */
+    isEnabled(): boolean;
+}
+
+type HttpClientType = "fetch" | "node-http" | "axios" | "curl";
+
+declare class HttpCacheFactory {
+    private static instances;
+    static create(appName?: string, config?: {
+        namespace?: string;
+        localLang?: string;
+        storageType?: "memory" | "disk" | "hybrid";
+        diskDir?: string;
+        maxSize?: number;
+        defaultTTL?: number;
+        clientType?: HttpClientType;
+        clientOptions?: any;
+    }): IHttpCacheService;
+    static createFromExistingCache(cacheService: any, namespace?: string): IHttpCacheService;
+    static destroy(appName?: string, clientType?: HttpClientType): void;
+}
+
+/**
+ * Represents a cache entry with its metadata
+ * @template T - Type of the stored value
+ */
+interface CacheEntry<T = any> {
+    /** Unique key identifying the entry */
+    key: string;
+    /** Value stored in the cache */
+    value: T;
+    /** Time to live in milliseconds */
+    timeToLive: number;
+    /** Creation timestamp in milliseconds */
+    createdAt: number;
+    /** Expiration timestamp in milliseconds */
+    expiresAt: number;
+    /** Number of accesses to this entry (for LFU) */
+    accessCount: number;
+    /** Last access timestamp (for LRU) */
+    lastAccessedAt: number;
+}
+
+/**
+ * Default export object with all features
+ */
+declare const _default: {
+    SCacheMiddleware: typeof SCacheMiddleware;
+    CacheService: typeof CacheService;
+    CacheMiddleware: typeof CacheMiddleware;
+    CacheFactoryRepository: typeof CacheFactoryRepository;
+    RouteValidator: typeof RouteValidator;
+    EnvironmentLoader: typeof EnvironmentLoader;
+    HttpCacheFactory: typeof HttpCacheFactory;
+};
+
+export { type CacheEntry, type ICacheRepository, type IHttpCacheService, _default as default };