@xbg.solutions/utils-cache-connector 1.0.0

package/lib/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/providers/base-cache-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-cache-provider.d.ts","sourceRoot":"","sources":["../../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/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/providers/base-cache-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-cache-provider.js","sourceRoot":"","sources":["../../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"}

package/lib/providers/firestore-cache-provider.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Firestore Cache Provider
+ *
+ * Firestore-based cache provider for distributed caching across function instances.
+ *
+ * Features:
+ * - Shared cache across all function instances
+ * - Persistent across cold starts
+ * - TTL-based expiration using Firestore timestamps
+ * - Tag-based invalidation
+ * - Automatic cleanup of expired entries
+ *
+ * Best for:
+ * - Medium-traffic repositories
+ * - Data that needs to be shared across instances
+ * - Cache data that should survive cold starts
+ *
+ * Trade-offs:
+ * - Latency: ~50-100ms (vs memory ~1-5ms)
+ * - Cost: Firestore read/write operations
+ * - Size limit: 1MB per document
+ */
+import { BaseCacheProvider } from './base-cache-provider';
+import { CacheProviderType, CacheSetOptions, CacheEntry, FirestoreCacheProviderConfig } from '../types';
+export declare class FirestoreCacheProvider extends BaseCacheProvider {
+    private config;
+    private db;
+    private cleanupInterval;
+    constructor(config: FirestoreCacheProviderConfig);
+    getType(): CacheProviderType;
+    /**
+     * Get collection reference
+     */
+    private getCollection;
+    get<T>(key: string): Promise<T | null>;
+    getWithMetadata<T>(key: string): Promise<CacheEntry<T> | null>;
+    set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    has(key: string): Promise<boolean>;
+    invalidateByTags(tags: string[]): Promise<number>;
+    invalidateByPattern(pattern: string, mode?: 'prefix' | 'suffix' | 'contains'): Promise<number>;
+    clear(): Promise<void>;
+    cleanup(): Promise<number>;
+    getStats(): Promise<any>;
+    /**
+     * Start automatic cleanup of expired entries
+     */
+    private startCleanup;
+    /**
+     * Stop automatic cleanup
+     */
+    stopCleanup(): void;
+    /**
+     * Cleanup on provider destruction
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=firestore-cache-provider.d.ts.map

package/lib/providers/firestore-cache-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"firestore-cache-provider.d.ts","sourceRoot":"","sources":["../../src/providers/firestore-cache-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,UAAU,EACV,4BAA4B,EAC7B,MAAM,UAAU,CAAC;AAclB,qBAAa,sBAAuB,SAAQ,iBAAiB;IAI/C,OAAO,CAAC,MAAM;IAH1B,OAAO,CAAC,EAAE,CAA4B;IACtC,OAAO,CAAC,eAAe,CAA+B;gBAElC,MAAM,EAAE,4BAA4B;IAaxD,OAAO,IAAI,iBAAiB;IAI5B;;OAEG;IACH,OAAO,CAAC,aAAa;IAIf,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAkDtC,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAiD9D,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IA+B3E,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAoBrC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgClC,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IA+BjD,mBAAmB,CACvB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,QAAQ,GAAG,QAAQ,GAAG,UAAqB,GAChD,OAAO,CAAC,MAAM,CAAC;IA6CZ,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAwBtB,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IAiC1B,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC;IA2B9B;;OAEG;IACH,OAAO,CAAC,YAAY;IAapB;;OAEG;IACH,WAAW,IAAI,IAAI;IAOnB;;OAEG;IACH,OAAO,IAAI,IAAI;CAGhB"}