@xbg.solutions/backend-core 1.0.0

package/lib/utils-cache-connector/src/cache-connector.js

@@ -0,0 +1,277 @@
+"use strict";
+/**
+ * Cache Connector
+ *
+ * Main facade class for the caching system.
+ * Provides a unified API for all cache operations and manages multiple cache providers.
+ *
+ * Features:
+ * - Multi-provider support (memory, firestore, redis)
+ * - Lazy provider initialization
+ * - Global enable/disable switch
+ * - Provider-specific routing
+ * - Automatic fallback to no-op when disabled
+ *
+ * Usage:
+ * ```typescript
+ * const cache = getCacheConnector();
+ * await cache.set('key', value, { ttl: 300, provider: 'memory' });
+ * const cached = await cache.get<User>('key', { provider: 'memory' });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheConnector = void 0;
+const noop_cache_provider_1 = require("./providers/noop-cache-provider");
+const memory_cache_provider_1 = require("./providers/memory-cache-provider");
+const firestore_cache_provider_1 = require("./providers/firestore-cache-provider");
+const redis_cache_provider_1 = require("./providers/redis-cache-provider");
+const utils_logger_1 = require("@xbg/utils-logger");
+class CacheConnector {
+    constructor(config) {
+        this.config = config;
+        this.providers = new Map();
+        this.noopProvider = new noop_cache_provider_1.NoOpCacheProvider();
+        utils_logger_1.logger.info('CacheConnector initialized', {
+            operation: 'cache.init',
+            enabled: config.enabled,
+            defaultProvider: config.defaultProvider,
+        });
+    }
+    /**
+     * Check if caching is enabled globally
+     */
+    isEnabled() {
+        return this.config.enabled;
+    }
+    /**
+     * Get or create a provider instance
+     */
+    getProvider(type) {
+        // If global cache disabled, always return no-op
+        if (!this.config.enabled) {
+            return this.noopProvider;
+        }
+        // Check if provider already exists
+        if (this.providers.has(type)) {
+            return this.providers.get(type);
+        }
+        // Create new provider instance
+        try {
+            const provider = this.createProvider(type);
+            this.providers.set(type, provider);
+            utils_logger_1.logger.debug(`Cache provider created: ${type}`, {
+                operation: 'cache.createProvider',
+                provider: type,
+            });
+            return provider;
+        }
+        catch (error) {
+            utils_logger_1.logger.error(`Failed to create cache provider: ${type}`, error, {
+                operation: 'cache.createProvider',
+                provider: type,
+            });
+            // Fallback to no-op on error
+            return this.noopProvider;
+        }
+    }
+    /**
+     * Create a new provider instance based on type
+     */
+    createProvider(type) {
+        switch (type) {
+            case 'memory':
+                return new memory_cache_provider_1.MemoryCacheProvider(this.config.providers.memory);
+            case 'firestore':
+                return new firestore_cache_provider_1.FirestoreCacheProvider(this.config.providers.firestore);
+            case 'redis':
+                if (!this.config.providers.redis) {
+                    throw new Error('Redis provider configuration not found');
+                }
+                return new redis_cache_provider_1.RedisCacheProvider(this.config.providers.redis);
+            case 'noop':
+                return this.noopProvider;
+            default:
+                throw new Error(`Unknown cache provider type: ${type}`);
+        }
+    }
+    /**
+     * Resolve provider from options or use default
+     */
+    resolveProvider(providerType) {
+        const type = providerType || this.config.defaultProvider;
+        return this.getProvider(type);
+    }
+    /**
+     * Get a value from cache
+     *
+     * @param key - Cache key
+     * @param options - Get options (provider override, metadata, etc.)
+     * @returns Cached value or null if not found/expired
+     */
+    async get(key, options = {}) {
+        const provider = this.resolveProvider(options.provider);
+        return provider.get(key);
+    }
+    /**
+     * Get a value with metadata from cache
+     *
+     * @param key - Cache key
+     * @param options - Get options
+     * @returns Cache entry with metadata or null
+     */
+    async getWithMetadata(key, options = {}) {
+        const provider = this.resolveProvider(options.provider);
+        return provider.getWithMetadata(key);
+    }
+    /**
+     * Set a value in cache
+     *
+     * @param key - Cache key
+     * @param value - Value to cache
+     * @param options - Set options (TTL, tags, provider, etc.)
+     */
+    async set(key, value, options = {}) {
+        const provider = this.resolveProvider(options.provider);
+        const ttl = options.ttl || this.config.defaultTTL;
+        return provider.set(key, value, Object.assign(Object.assign({}, options), { ttl }));
+    }
+    /**
+     * Delete a specific cache entry
+     *
+     * @param key - Cache key to delete
+     * @param options - Invalidate options
+     * @returns True if entry was deleted
+     */
+    async delete(key, options = {}) {
+        const provider = this.resolveProvider(options.provider);
+        return provider.delete(key);
+    }
+    /**
+     * Check if a cache entry exists
+     *
+     * @param key - Cache key to check
+     * @param options - Get options
+     * @returns True if entry exists and is not expired
+     */
+    async has(key, options = {}) {
+        const provider = this.resolveProvider(options.provider);
+        return provider.has(key);
+    }
+    /**
+     * Invalidate cache entries by tags
+     *
+     * @param tags - Array of tags to invalidate
+     * @param options - Invalidate options
+     * @returns Number of entries invalidated
+     */
+    async invalidateByTags(tags, options = {}) {
+        const provider = this.resolveProvider(options.provider);
+        return provider.invalidateByTags(tags);
+    }
+    /**
+     * Invalidate cache entries by key pattern
+     *
+     * @param pattern - Pattern to match
+     * @param options - Invalidate options
+     * @returns Number of entries invalidated
+     */
+    async invalidateByPattern(pattern, options = {}) {
+        const provider = this.resolveProvider(options.provider);
+        const mode = (options.pattern === 'prefix' || options.pattern === 'suffix' || options.pattern === 'contains')
+            ? options.pattern
+            : 'prefix';
+        return provider.invalidateByPattern(pattern, mode);
+    }
+    /**
+     * Clear all cache entries
+     *
+     * @param options - Invalidate options
+     */
+    async clear(options = {}) {
+        const provider = this.resolveProvider(options.provider);
+        return provider.clear();
+    }
+    /**
+     * Clear all cache entries across all providers
+     */
+    async clearAll() {
+        const providers = Array.from(this.providers.values());
+        await Promise.all(providers.map(async (provider) => {
+            try {
+                await provider.clear();
+            }
+            catch (error) {
+                utils_logger_1.logger.error(`Failed to clear cache for provider: ${provider.getType()}`, error, {
+                    operation: 'cache.clearAll',
+                    provider: provider.getType(),
+                });
+            }
+        }));
+    }
+    /**
+     * Get cache statistics
+     *
+     * @param options - Get options
+     * @returns Cache statistics
+     */
+    async getStats(options = {}) {
+        const provider = this.resolveProvider(options.provider);
+        return provider.getStats();
+    }
+    /**
+     * Get statistics for all active providers
+     */
+    async getAllStats() {
+        const stats = {};
+        for (const [type, provider] of this.providers.entries()) {
+            try {
+                stats[type] = await provider.getStats();
+            }
+            catch (error) {
+                utils_logger_1.logger.error(`Failed to get stats for provider: ${type}`, error, {
+                    operation: 'cache.getAllStats',
+                    provider: type,
+                });
+            }
+        }
+        return stats;
+    }
+    /**
+     * Manually trigger cleanup of expired entries
+     *
+     * @param options - Get options
+     * @returns Number of entries cleaned up
+     */
+    async cleanup(options = {}) {
+        const provider = this.resolveProvider(options.provider);
+        if ('cleanup' in provider && typeof provider.cleanup === 'function') {
+            return provider.cleanup();
+        }
+        return 0;
+    }
+    /**
+     * Build a namespaced cache key
+     *
+     * @param parts - Key parts to join
+     * @returns Namespaced cache key
+     */
+    buildKey(...parts) {
+        return `${this.config.namespace}:${parts.join(':')}`;
+    }
+    /**
+     * Destroy all providers and cleanup resources
+     */
+    destroy() {
+        for (const provider of this.providers.values()) {
+            if ('destroy' in provider && typeof provider.destroy === 'function') {
+                provider.destroy();
+            }
+        }
+        this.providers.clear();
+        utils_logger_1.logger.info('CacheConnector destroyed', {
+            operation: 'cache.destroy',
+        });
+    }
+}
+exports.CacheConnector = CacheConnector;
+//# sourceMappingURL=cache-connector.js.map

package/lib/utils-cache-connector/src/cache-connector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-connector.js","sourceRoot":"","sources":["../../../../utils-cache-connector/src/cache-connector.ts"],"names":[],"mappings":"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"}

package/lib/utils-cache-connector/src/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Cache Connector
+ *
+ * Multi-level caching system with pluggable providers.
+ *
+ * Features:
+ * - Project-level control (global enable/disable)
+ * - Repository-level granularity (per-entity provider selection)
+ * - Multiple providers (memory, firestore, redis)
+ * - Tag-based invalidation
+ * - TTL-based expiration
+ * - Statistics and monitoring
+ *
+ * Usage:
+ * ```typescript
+ * // Get singleton instance
+ * const cache = getCacheConnector();
+ *
+ * // Set a value
+ * await cache.set('user:123', user, { ttl: 300, provider: 'memory' });
+ *
+ * // Get a value
+ * const user = await cache.get<User>('user:123', { provider: 'memory' });
+ *
+ * // Invalidate by tags
+ * await cache.invalidateByTags(['users', 'user:123']);
+ * ```
+ */
+import { CacheConnector } from './cache-connector';
+import { CacheConfig } from './types';
+/**
+ * Initialize the cache connector with configuration
+ * Call this once during app startup before using getCacheConnector()
+ */
+export declare function initializeCacheConnector(config: CacheConfig): CacheConnector;
+/**
+ * Get the singleton CacheConnector instance
+ * Throws if not initialized - call initializeCacheConnector() first
+ */
+export declare function getCacheConnector(): CacheConnector;
+/**
+ * Reset the cache connector instance (useful for testing)
+ */
+export declare function resetCacheConnector(): void;
+export { CacheConnector } from './cache-connector';
+export * from './types';
+export { BaseCacheProvider } from './providers/base-cache-provider';
+export { NoOpCacheProvider } from './providers/noop-cache-provider';
+export { MemoryCacheProvider } from './providers/memory-cache-provider';
+export { FirestoreCacheProvider } from './providers/firestore-cache-provider';
+export { RedisCacheProvider } from './providers/redis-cache-provider';
+//# sourceMappingURL=index.d.ts.map

package/lib/utils-cache-connector/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../utils-cache-connector/src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAKtC;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,WAAW,GAAG,cAAc,CAM5E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAYlD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAK1C;AAGD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AACxE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC"}

package/lib/utils-cache-connector/src/index.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * Cache Connector
+ *
+ * Multi-level caching system with pluggable providers.
+ *
+ * Features:
+ * - Project-level control (global enable/disable)
+ * - Repository-level granularity (per-entity provider selection)
+ * - Multiple providers (memory, firestore, redis)
+ * - Tag-based invalidation
+ * - TTL-based expiration
+ * - Statistics and monitoring
+ *
+ * Usage:
+ * ```typescript
+ * // Get singleton instance
+ * const cache = getCacheConnector();
+ *
+ * // Set a value
+ * await cache.set('user:123', user, { ttl: 300, provider: 'memory' });
+ *
+ * // Get a value
+ * const user = await cache.get<User>('user:123', { provider: 'memory' });
+ *
+ * // Invalidate by tags
+ * await cache.invalidateByTags(['users', 'user:123']);
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisCacheProvider = exports.FirestoreCacheProvider = exports.MemoryCacheProvider = exports.NoOpCacheProvider = exports.BaseCacheProvider = exports.CacheConnector = void 0;
+exports.initializeCacheConnector = initializeCacheConnector;
+exports.getCacheConnector = getCacheConnector;
+exports.resetCacheConnector = resetCacheConnector;
+const cache_connector_1 = require("./cache-connector");
+// Singleton instance
+let cacheConnectorInstance = null;
+/**
+ * Initialize the cache connector with configuration
+ * Call this once during app startup before using getCacheConnector()
+ */
+function initializeCacheConnector(config) {
+    if (cacheConnectorInstance) {
+        cacheConnectorInstance.destroy();
+    }
+    cacheConnectorInstance = new cache_connector_1.CacheConnector(config);
+    return cacheConnectorInstance;
+}
+/**
+ * Get the singleton CacheConnector instance
+ * Throws if not initialized - call initializeCacheConnector() first
+ */
+function getCacheConnector() {
+    if (!cacheConnectorInstance) {
+        // Create with defaults if not explicitly initialized
+        cacheConnectorInstance = new cache_connector_1.CacheConnector({
+            enabled: false,
+            defaultProvider: 'noop',
+            defaultTTL: 300,
+            namespace: 'app',
+            providers: {},
+        });
+    }
+    return cacheConnectorInstance;
+}
+/**
+ * Reset the cache connector instance (useful for testing)
+ */
+function resetCacheConnector() {
+    if (cacheConnectorInstance) {
+        cacheConnectorInstance.destroy();
+        cacheConnectorInstance = null;
+    }
+}
+// Export types and classes
+var cache_connector_2 = require("./cache-connector");
+Object.defineProperty(exports, "CacheConnector", { enumerable: true, get: function () { return cache_connector_2.CacheConnector; } });
+__exportStar(require("./types"), exports);
+var base_cache_provider_1 = require("./providers/base-cache-provider");
+Object.defineProperty(exports, "BaseCacheProvider", { enumerable: true, get: function () { return base_cache_provider_1.BaseCacheProvider; } });
+var noop_cache_provider_1 = require("./providers/noop-cache-provider");
+Object.defineProperty(exports, "NoOpCacheProvider", { enumerable: true, get: function () { return noop_cache_provider_1.NoOpCacheProvider; } });
+var memory_cache_provider_1 = require("./providers/memory-cache-provider");
+Object.defineProperty(exports, "MemoryCacheProvider", { enumerable: true, get: function () { return memory_cache_provider_1.MemoryCacheProvider; } });
+var firestore_cache_provider_1 = require("./providers/firestore-cache-provider");
+Object.defineProperty(exports, "FirestoreCacheProvider", { enumerable: true, get: function () { return firestore_cache_provider_1.FirestoreCacheProvider; } });
+var redis_cache_provider_1 = require("./providers/redis-cache-provider");
+Object.defineProperty(exports, "RedisCacheProvider", { enumerable: true, get: function () { return redis_cache_provider_1.RedisCacheProvider; } });
+//# sourceMappingURL=index.js.map

package/lib/utils-cache-connector/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../utils-cache-connector/src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;;;;;;;;;;;;;;;;;AAYH,4DAMC;AAMD,8CAYC;AAKD,kDAKC;AA5CD,uDAAmD;AAGnD,qBAAqB;AACrB,IAAI,sBAAsB,GAA0B,IAAI,CAAC;AAEzD;;;GAGG;AACH,SAAgB,wBAAwB,CAAC,MAAmB;IAC1D,IAAI,sBAAsB,EAAE,CAAC;QAC3B,sBAAsB,CAAC,OAAO,EAAE,CAAC;IACnC,CAAC;IACD,sBAAsB,GAAG,IAAI,gCAAc,CAAC,MAAM,CAAC,CAAC;IACpD,OAAO,sBAAsB,CAAC;AAChC,CAAC;AAED;;;GAGG;AACH,SAAgB,iBAAiB;IAC/B,IAAI,CAAC,sBAAsB,EAAE,CAAC;QAC5B,qDAAqD;QACrD,sBAAsB,GAAG,IAAI,gCAAc,CAAC;YAC1C,OAAO,EAAE,KAAK;YACd,eAAe,EAAE,MAAa;YAC9B,UAAU,EAAE,GAAG;YACf,SAAS,EAAE,KAAK;YAChB,SAAS,EAAE,EAAS;SACrB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,sBAAsB,CAAC;AAChC,CAAC;AAED;;GAEG;AACH,SAAgB,mBAAmB;IACjC,IAAI,sBAAsB,EAAE,CAAC;QAC3B,sBAAsB,CAAC,OAAO,EAAE,CAAC;QACjC,sBAAsB,GAAG,IAAI,CAAC;IAChC,CAAC;AACH,CAAC;AAED,2BAA2B;AAC3B,qDAAmD;AAA1C,iHAAA,cAAc,OAAA;AACvB,0CAAwB;AACxB,uEAAoE;AAA3D,wHAAA,iBAAiB,OAAA;AAC1B,uEAAoE;AAA3D,wHAAA,iBAAiB,OAAA;AAC1B,2EAAwE;AAA/D,4HAAA,mBAAmB,OAAA;AAC5B,iFAA8E;AAArE,kIAAA,sBAAsB,OAAA;AAC/B,yEAAsE;AAA7D,0HAAA,kBAAkB,OAAA"}

package/lib/utils-cache-connector/src/providers/base-cache-provider.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Base Cache Provider
+ *
+ * Abstract base class that all cache providers extend.
+ * Provides common functionality and enforces interface compliance.
+ */
+import { CacheProviderType, ICacheProvider, CacheSetOptions, CacheEntry, CacheStats, CacheEntryMetadata } from '../types';
+export declare abstract class BaseCacheProvider implements ICacheProvider {
+    protected stats: CacheStats;
+    /**
+     * Get the provider type
+     */
+    abstract getType(): CacheProviderType;
+    /**
+     * Get a value from cache
+     */
+    abstract get<T>(key: string): Promise<T | null>;
+    /**
+     * Get a value with metadata
+     */
+    abstract getWithMetadata<T>(key: string): Promise<CacheEntry<T> | null>;
+    /**
+     * Set a value in cache
+     */
+    abstract set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void>;
+    /**
+     * Delete a specific key
+     */
+    abstract delete(key: string): Promise<boolean>;
+    /**
+     * Check if a key exists
+     */
+    abstract has(key: string): Promise<boolean>;
+    /**
+     * Invalidate cache entries by tags
+     */
+    abstract invalidateByTags(tags: string[]): Promise<number>;
+    /**
+     * Invalidate cache entries by pattern
+     */
+    abstract invalidateByPattern(pattern: string, mode?: 'prefix' | 'suffix' | 'contains'): Promise<number>;
+    /**
+     * Clear all cache entries
+     */
+    abstract clear(): Promise<void>;
+    /**
+     * Get cache statistics
+     */
+    getStats(): Promise<CacheStats>;
+    /**
+     * Record a cache hit
+     */
+    protected recordHit(): void;
+    /**
+     * Record a cache miss
+     */
+    protected recordMiss(): void;
+    /**
+     * Record an eviction
+     */
+    protected recordEviction(): void;
+    /**
+     * Record an expiration
+     */
+    protected recordExpiration(): void;
+    /**
+     * Update entry count
+     */
+    protected updateEntryCount(count: number): void;
+    /**
+     * Update cache size
+     */
+    protected updateSize(size: number): void;
+    /**
+     * Check if an entry is expired
+     */
+    protected isExpired(expiresAt: Date): boolean;
+    /**
+     * Calculate TTL in milliseconds
+     */
+    protected calculateExpiresAt(ttl: number): Date;
+    /**
+     * Create cache entry metadata
+     */
+    protected createMetadata(ttl: number, tags?: string[]): CacheEntryMetadata;
+    /**
+     * Estimate size of a value in bytes
+     */
+    protected estimateSize(value: any): number;
+    /**
+     * Match key against pattern
+     */
+    protected matchPattern(key: string, pattern: string, mode: 'prefix' | 'suffix' | 'contains'): boolean;
+}
+//# sourceMappingURL=base-cache-provider.d.ts.map

package/lib/utils-cache-connector/src/providers/base-cache-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-cache-provider.d.ts","sourceRoot":"","sources":["../../../../../utils-cache-connector/src/providers/base-cache-provider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,UAAU,EACV,UAAU,EACV,kBAAkB,EACnB,MAAM,UAAU,CAAC;AAElB,8BAAsB,iBAAkB,YAAW,cAAc;IAC/D,SAAS,CAAC,KAAK,EAAE,UAAU,CAQzB;IAEF;;OAEG;IACH,QAAQ,CAAC,OAAO,IAAI,iBAAiB;IAErC;;OAEG;IACH,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAE/C;;OAEG;IACH,QAAQ,CAAC,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAEvE;;OAEG;IACH,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAEhF;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAE9C;;OAEG;IACH,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAE3C;;OAEG;IACH,QAAQ,CAAC,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAE1D;;OAEG;IACH,QAAQ,CAAC,mBAAmB,CAC1B,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,UAAU,GACtC,OAAO,CAAC,MAAM,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAE/B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC;IAQrC;;OAEG;IACH,SAAS,CAAC,SAAS,IAAI,IAAI;IAI3B;;OAEG;IACH,SAAS,CAAC,UAAU,IAAI,IAAI;IAI5B;;OAEG;IACH,SAAS,CAAC,cAAc,IAAI,IAAI;IAIhC;;OAEG;IACH,SAAS,CAAC,gBAAgB,IAAI,IAAI;IAIlC;;OAEG;IACH,SAAS,CAAC,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI/C;;OAEG;IACH,SAAS,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIxC;;OAEG;IACH,SAAS,CAAC,SAAS,CAAC,SAAS,EAAE,IAAI,GAAG,OAAO;IAI7C;;OAEG;IACH,SAAS,CAAC,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAI/C;;OAEG;IACH,SAAS,CAAC,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAO,GAAG,kBAAkB;IAW9E;;OAEG;IACH,SAAS,CAAC,YAAY,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM;IAQ1C;;OAEG;IACH,SAAS,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,OAAO;CAYtG"}

package/lib/utils-cache-connector/src/providers/base-cache-provider.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Base Cache Provider
+ *
+ * Abstract base class that all cache providers extend.
+ * Provides common functionality and enforces interface compliance.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseCacheProvider = void 0;
+class BaseCacheProvider {
+    constructor() {
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            hitRatio: 0,
+            entryCount: 0,
+            size: 0,
+            evictions: 0,
+            expirations: 0,
+        };
+    }
+    /**
+     * Get cache statistics
+     */
+    async getStats() {
+        // Calculate hit ratio
+        const total = this.stats.hits + this.stats.misses;
+        this.stats.hitRatio = total > 0 ? this.stats.hits / total : 0;
+        return Object.assign({}, this.stats);
+    }
+    /**
+     * Record a cache hit
+     */
+    recordHit() {
+        this.stats.hits++;
+    }
+    /**
+     * Record a cache miss
+     */
+    recordMiss() {
+        this.stats.misses++;
+    }
+    /**
+     * Record an eviction
+     */
+    recordEviction() {
+        this.stats.evictions++;
+    }
+    /**
+     * Record an expiration
+     */
+    recordExpiration() {
+        this.stats.expirations++;
+    }
+    /**
+     * Update entry count
+     */
+    updateEntryCount(count) {
+        this.stats.entryCount = count;
+    }
+    /**
+     * Update cache size
+     */
+    updateSize(size) {
+        this.stats.size = size;
+    }
+    /**
+     * Check if an entry is expired
+     */
+    isExpired(expiresAt) {
+        return expiresAt.getTime() < Date.now();
+    }
+    /**
+     * Calculate TTL in milliseconds
+     */
+    calculateExpiresAt(ttl) {
+        return new Date(Date.now() + ttl * 1000);
+    }
+    /**
+     * Create cache entry metadata
+     */
+    createMetadata(ttl, tags = []) {
+        const now = new Date();
+        return {
+            createdAt: now,
+            expiresAt: this.calculateExpiresAt(ttl),
+            hitCount: 0,
+            lastAccessedAt: now,
+            tags,
+        };
+    }
+    /**
+     * Estimate size of a value in bytes
+     */
+    estimateSize(value) {
+        try {
+            return JSON.stringify(value).length * 2; // Rough estimate (UTF-16)
+        }
+        catch (_a) {
+            return 0;
+        }
+    }
+    /**
+     * Match key against pattern
+     */
+    matchPattern(key, pattern, mode) {
+        switch (mode) {
+            case 'prefix':
+                return key.startsWith(pattern);
+            case 'suffix':
+                return key.endsWith(pattern);
+            case 'contains':
+                return key.includes(pattern);
+            default:
+                return false;
+        }
+    }
+}
+exports.BaseCacheProvider = BaseCacheProvider;
+//# sourceMappingURL=base-cache-provider.js.map

package/lib/utils-cache-connector/src/providers/base-cache-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-cache-provider.js","sourceRoot":"","sources":["../../../../../utils-cache-connector/src/providers/base-cache-provider.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAWH,MAAsB,iBAAiB;IAAvC;QACY,UAAK,GAAe;YAC5B,IAAI,EAAE,CAAC;YACP,MAAM,EAAE,CAAC;YACT,QAAQ,EAAE,CAAC;YACX,UAAU,EAAE,CAAC;YACb,IAAI,EAAE,CAAC;YACP,SAAS,EAAE,CAAC;YACZ,WAAW,EAAE,CAAC;SACf,CAAC;IA6JJ,CAAC;IA3GC;;OAEG;IACH,KAAK,CAAC,QAAQ;QACZ,sBAAsB;QACtB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;QAClD,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAE9D,yBAAY,IAAI,CAAC,KAAK,EAAG;IAC3B,CAAC;IAED;;OAEG;IACO,SAAS;QACjB,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IACpB,CAAC;IAED;;OAEG;IACO,UAAU;QAClB,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;IACtB,CAAC;IAED;;OAEG;IACO,cAAc;QACtB,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;IACzB,CAAC;IAED;;OAEG;IACO,gBAAgB;QACxB,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;IAC3B,CAAC;IAED;;OAEG;IACO,gBAAgB,CAAC,KAAa;QACtC,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC;IAChC,CAAC;IAED;;OAEG;IACO,UAAU,CAAC,IAAY;QAC/B,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;IACzB,CAAC;IAED;;OAEG;IACO,SAAS,CAAC,SAAe;QACjC,OAAO,SAAS,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC1C,CAAC;IAED;;OAEG;IACO,kBAAkB,CAAC,GAAW;QACtC,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC;IAC3C,CAAC;IAED;;OAEG;IACO,cAAc,CAAC,GAAW,EAAE,OAAiB,EAAE;QACvD,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,OAAO;YACL,SAAS,EAAE,GAAG;YACd,SAAS,EAAE,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC;YACvC,QAAQ,EAAE,CAAC;YACX,cAAc,EAAE,GAAG;YACnB,IAAI;SACL,CAAC;IACJ,CAAC;IAED;;OAEG;IACO,YAAY,CAAC,KAAU;QAC/B,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,0BAA0B;QACrE,CAAC;QAAC,WAAM,CAAC;YACP,OAAO,CAAC,CAAC;QACX,CAAC;IACH,CAAC;IAED;;OAEG;IACO,YAAY,CAAC,GAAW,EAAE,OAAe,EAAE,IAAsC;QACzF,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,QAAQ;gBACX,OAAO,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;YACjC,KAAK,QAAQ;gBACX,OAAO,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YAC/B,KAAK,UAAU;gBACb,OAAO,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YAC/B;gBACE,OAAO,KAAK,CAAC;QACjB,CAAC;IACH,CAAC;CACF;AAtKD,8CAsKC"}