@xbg.solutions/utils-cache-connector 1.0.0

package/lib/types.d.ts

@@ -0,0 +1,342 @@
+/**
+ * Cache Connector Type Definitions
+ *
+ * Defines the types and interfaces for the multi-level caching system.
+ */
+/**
+ * Supported cache provider types
+ */
+export type CacheProviderType = 'memory' | 'firestore' | 'redis' | 'noop';
+/**
+ * Cache strategies for advanced behavior
+ */
+export type CacheStrategy = 'write-through' | 'write-behind' | 'cache-aside' | 'refresh-ahead';
+/**
+ * Global cache configuration (project-level)
+ */
+export interface CacheConfig {
+    /**
+     * Master switch - if false, all caching is disabled
+     */
+    enabled: boolean;
+    /**
+     * Default provider for repositories that don't specify
+     */
+    defaultProvider: CacheProviderType;
+    /**
+     * Default TTL in seconds
+     */
+    defaultTTL: number;
+    /**
+     * Global cache namespace (for versioning)
+     * Change this to invalidate all cached data
+     */
+    namespace: string;
+    /**
+     * Provider-specific configurations
+     */
+    providers: {
+        memory: MemoryCacheProviderConfig;
+        firestore: FirestoreCacheProviderConfig;
+        redis?: RedisCacheProviderConfig;
+    };
+}
+/**
+ * Memory cache provider configuration
+ */
+export interface MemoryCacheProviderConfig {
+    /**
+     * Maximum cache size in bytes
+     */
+    maxSize: number;
+    /**
+     * Interval to check for expired entries (seconds)
+     */
+    checkPeriod: number;
+    /**
+     * Whether to use LRU eviction when max size is reached
+     */
+    useClones?: boolean;
+}
+/**
+ * Firestore cache provider configuration
+ */
+export interface FirestoreCacheProviderConfig {
+    /**
+     * Which database to use for cache storage
+     */
+    database: string;
+    /**
+     * Collection name for cache entries
+     */
+    collection: string;
+    /**
+     * Enable automatic cleanup of expired entries
+     */
+    enableCleanup: boolean;
+    /**
+     * Cleanup interval in seconds
+     */
+    cleanupInterval: number;
+}
+/**
+ * Redis cache provider configuration
+ */
+export interface RedisCacheProviderConfig {
+    /**
+     * Redis server host
+     */
+    host: string;
+    /**
+     * Redis server port
+     */
+    port: number;
+    /**
+     * Redis password (optional)
+     */
+    password?: string;
+    /**
+     * Redis database number
+     */
+    db: number;
+    /**
+     * Connection timeout in milliseconds
+     */
+    connectTimeout?: number;
+    /**
+     * Enable TLS
+     */
+    tls?: boolean;
+}
+/**
+ * Repository-level cache configuration
+ */
+export interface RepositoryCacheConfig {
+    /**
+     * Enable caching for this repository (only if global is enabled)
+     */
+    enabled: boolean;
+    /**
+     * Which provider to use (overrides global default)
+     */
+    provider?: CacheProviderType;
+    /**
+     * Default TTL for this repository (overrides global default)
+     */
+    ttl?: number;
+    /**
+     * Cache key prefix for this repository
+     */
+    keyPrefix?: string;
+    /**
+     * Invalidation tags (auto-applied to all cache entries)
+     */
+    tags?: string[];
+    /**
+     * Advanced: cache strategies
+     */
+    strategies?: CacheStrategy[];
+}
+/**
+ * Method-level cache options (runtime)
+ */
+export interface CacheOptions {
+    /**
+     * Time-to-live override in seconds
+     */
+    ttl?: number;
+    /**
+     * Tags for cache invalidation
+     */
+    tags?: string[];
+    /**
+     * Force refresh, skip cache lookup
+     */
+    forceRefresh?: boolean;
+    /**
+     * Additional metadata for debugging
+     */
+    metadata?: Record<string, any>;
+}
+/**
+ * Options for setting cache entries
+ */
+export interface CacheSetOptions extends CacheOptions {
+    /**
+     * Provider to use for this operation
+     */
+    provider?: CacheProviderType;
+}
+/**
+ * Options for getting cache entries
+ */
+export interface CacheGetOptions {
+    /**
+     * Provider to use for this operation
+     */
+    provider?: CacheProviderType;
+    /**
+     * Return metadata along with value
+     */
+    includeMetadata?: boolean;
+}
+/**
+ * Options for invalidation operations
+ */
+export interface CacheInvalidateOptions {
+    /**
+     * Provider to use for this operation
+     */
+    provider?: CacheProviderType;
+    /**
+     * Pattern matching mode
+     */
+    pattern?: 'exact' | 'prefix' | 'suffix' | 'contains';
+}
+/**
+ * Cache entry metadata
+ */
+export interface CacheEntryMetadata {
+    /**
+     * When the entry was created
+     */
+    createdAt: Date;
+    /**
+     * When the entry expires
+     */
+    expiresAt: Date;
+    /**
+     * Number of times this entry has been accessed
+     */
+    hitCount: number;
+    /**
+     * Last access timestamp
+     */
+    lastAccessedAt: Date;
+    /**
+     * Tags associated with this entry
+     */
+    tags: string[];
+    /**
+     * Size in bytes (approximate)
+     */
+    size?: number;
+}
+/**
+ * Cache entry with metadata
+ */
+export interface CacheEntry<T = any> {
+    /**
+     * Cache key
+     */
+    key: string;
+    /**
+     * Cached value
+     */
+    value: T;
+    /**
+     * Entry metadata
+     */
+    metadata: CacheEntryMetadata;
+}
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+    /**
+     * Total number of cache hits
+     */
+    hits: number;
+    /**
+     * Total number of cache misses
+     */
+    misses: number;
+    /**
+     * Hit ratio (hits / (hits + misses))
+     */
+    hitRatio: number;
+    /**
+     * Total number of entries in cache
+     */
+    entryCount: number;
+    /**
+     * Total size of cache in bytes
+     */
+    size: number;
+    /**
+     * Number of evictions (LRU or size-based)
+     */
+    evictions: number;
+    /**
+     * Number of expirations
+     */
+    expirations: number;
+}
+/**
+ * Cache operation result
+ */
+export interface CacheOperationResult {
+    /**
+     * Whether the operation succeeded
+     */
+    success: boolean;
+    /**
+     * Error message if operation failed
+     */
+    error?: string;
+    /**
+     * Operation duration in milliseconds
+     */
+    duration?: number;
+}
+/**
+ * Base cache provider interface
+ * All cache providers must implement this interface
+ */
+export interface ICacheProvider {
+    /**
+     * Get a value from cache
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Get a value with metadata
+     */
+    getWithMetadata<T>(key: string): Promise<CacheEntry<T> | null>;
+    /**
+     * Set a value in cache
+     */
+    set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void>;
+    /**
+     * Delete a specific key
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Check if a key exists
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Invalidate cache entries by tags
+     */
+    invalidateByTags(tags: string[]): Promise<number>;
+    /**
+     * Invalidate cache entries by pattern
+     */
+    invalidateByPattern(pattern: string, mode?: 'prefix' | 'suffix' | 'contains'): Promise<number>;
+    /**
+     * Clear all cache entries
+     */
+    clear(): Promise<void>;
+    /**
+     * Get cache statistics
+     */
+    getStats(): Promise<CacheStats>;
+    /**
+     * Get the provider type
+     */
+    getType(): CacheProviderType;
+    /**
+     * Cleanup expired entries (if supported)
+     */
+    cleanup?(): Promise<number>;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

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

package/lib/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Cache Connector Type Definitions
+ *
+ * Defines the types and interfaces for the multi-level caching system.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@xbg.solutions/utils-cache-connector",
+  "version": "1.0.0",
+  "description": "Multi-provider caching (memory, Firestore, Redis)",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "clean": "rm -rf lib",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@xbg/utils-logger": "^1.0.0",
+    "firebase-admin": "^12.0.0",
+    "ioredis": "^5.3.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": "22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}