@nest-omni/core 4.1.3-2 → 4.1.3-4

package/cache/cache.service.d.ts

@@ -1,6 +1,15 @@
 import type { CacheOptions, CacheStats } from './interfaces';
 import { CacheLayer } from './interfaces';
 import { ClsCacheProvider, MemoryCacheProvider, RedisCacheProvider } from './providers';
+/**
+ * Unified cache service with three-tier architecture
+ *
+ * L1: CLS (request-level)
+ * L2: Memory (process-level)
+ * L3: Redis (distributed)
+ *
+ * Supports automatic fallback, backfill, and dependency-based invalidation.
+ */
 export declare class CacheService {
     private readonly clsProvider;
     private readonly memoryProvider;
@@ -11,27 +20,158 @@ export declare class CacheService {
     private readonly providers;
     private readonly stats;
     constructor(clsProvider: ClsCacheProvider, memoryProvider: MemoryCacheProvider, redisProvider: RedisCacheProvider, enableCompression?: boolean, compressionThreshold?: number);
+    /**
+     * Get or set cache value with factory function
+     *
+     * @param key - Cache key
+     * @param factory - Function to generate value if not cached
+     * @param options - Cache options
+     * @returns Cached or generated value
+     */
     getOrSet<T>(key: string, factory: () => Promise<T>, options?: CacheOptions): Promise<T>;
+    /**
+     * Get value from cache with optional layer specification
+     *
+     * @param key - Cache key
+     * @param options - Cache options including layer preference
+     * @returns Cached value or null
+     *
+     * @example
+     * ```typescript
+     * // Try memory only
+     * const data = await this.cacheService.get('user:123', {
+     *   layers: [CacheLayer.MEMORY]
+     * });
+     *
+     * // Try all layers in order (CLS -> MEMORY -> REDIS)
+     * const data = await this.cacheService.get('config:app', {
+     *   layers: [CacheLayer.CLS, CacheLayer.MEMORY, CacheLayer.REDIS]
+     * });
+     * ```
+     */
     get<T>(key: string, options?: CacheOptions): Promise<T | null>;
+    /**
+     * Set value in cache with optional layer specification
+     *
+     * Supports both new API (CacheOptions) and legacy API (TTL number) for backward compatibility.
+     *
+     * @param key - Cache key
+     * @param value - Value to cache
+     * @param options - Cache options including layer selection OR TTL (number) for legacy compatibility
+     *
+     * @example
+     * ```typescript
+     * // New API - Cache in memory only
+     * await this.cacheService.set('user:123', userData, {
+     *   layers: [CacheLayer.MEMORY],
+     *   ttl: 300000
+     * });
+     *
+     * // Legacy API - TTL as third parameter (still works for backward compatibility)
+     * await this.cacheService.set('user:123', userData, 300000);
+     *
+     * // Cache in all layers (default behavior)
+     * await this.cacheService.set('config:app', configData, {
+     *   layers: [CacheLayer.CLS, CacheLayer.MEMORY, CacheLayer.REDIS],
+     *   ttl: 3600000
+     * });
+     *
+     * // Cache in Redis only (distributed)
+     * await this.cacheService.set('global:settings', settings, {
+     *   layers: [CacheLayer.REDIS],
+     *   ttl: 86400000
+     * });
+     * ```
+     */
     set<T>(key: string, value: T, options?: CacheOptions | number): Promise<void>;
+    /**
+     * Delete value from cache
+     *
+     * @param key - Cache key or array of keys
+     * @param layers - Specific layers to delete from (default: all)
+     */
     del(key: string | string[], layers?: CacheLayer[]): Promise<void>;
+    /**
+     * Delete keys matching pattern
+     *
+     * @param pattern - Pattern to match (e.g., 'user:*')
+     * @param layers - Specific layers to delete from (default: Memory and Redis only)
+     */
     deletePattern(pattern: string, layers?: CacheLayer[]): Promise<void>;
+    /**
+     * Clear all cache
+     *
+     * @param layers - Specific layers to clear (default: all)
+     */
     clear(layers?: CacheLayer[]): Promise<void>;
+    /**
+     * Invalidate tags (for TagDependency)
+     *
+     * @param tags - Tags to invalidate
+     */
     invalidateTags(tags: string[]): Promise<void>;
+    /**
+     * Get multiple values
+     *
+     * @param keys - Array of cache keys
+     * @param options - Cache options
+     * @returns Array of values (null for missing keys)
+     */
     mget<T>(keys: string[], options?: CacheOptions): Promise<(T | null)[]>;
+    /**
+     * Set multiple values
+     *
+     * @param items - Array of key-value pairs
+     * @param options - Cache options
+     */
     mset(items: Array<{
         key: string;
         value: any;
     }>, options?: CacheOptions): Promise<void>;
+    /**
+     * Get cache statistics
+     *
+     * @returns Cache statistics
+     */
     getStats(): CacheStats;
+    /**
+     * Reset statistics
+     */
     resetStats(): void;
+    /**
+     * Internal method to set cache value with options
+     */
     private setWithOptions;
+    /**
+     * Resolve cache layers from options
+     */
     private resolveLayers;
+    /**
+     * Get default cache layers
+     */
     private getDefaultLayers;
+    /**
+     * Build full cache key with namespace
+     */
     private buildKey;
+    /**
+     * Backfill upper cache layers
+     */
     private backfillUpperLayers;
+    /**
+     * Record cache hit
+     */
     private recordHit;
+    /**
+     * Record cache miss
+     */
     private recordMiss;
+    /**
+     * Update hit rate for a layer
+     */
     private updateLayerHitRate;
+    /**
+     * Initialize statistics for all layers
+     */
     private initializeStats;
 }

package/cache/cache.service.js

@@ -30,6 +30,15 @@ const providers_1 = require("./providers");
 const utils_1 = require("./utils");
 const cache_serialization_service_1 = require("./cache-serialization.service");
 const cache_constants_1 = require("./cache.constants");
+/**
+ * Unified cache service with three-tier architecture
+ *
+ * L1: CLS (request-level)
+ * L2: Memory (process-level)
+ * L3: Redis (distributed)
+ *
+ * Supports automatic fallback, backfill, and dependency-based invalidation.
+ */
 let CacheService = CacheService_1 = class CacheService {
     constructor(clsProvider, memoryProvider, redisProvider, enableCompression = false, compressionThreshold = 1024) {
         this.clsProvider = clsProvider;
@@ -54,22 +63,54 @@ let CacheService = CacheService_1 = class CacheService {
         this.providers.set(interfaces_1.CacheLayer.REDIS, redisProvider);
         this.initializeStats();
     }
+    /**
+     * Get or set cache value with factory function
+     *
+     * @param key - Cache key
+     * @param factory - Function to generate value if not cached
+     * @param options - Cache options
+     * @returns Cached or generated value
+     */
     getOrSet(key, factory, options) {
         return __awaiter(this, void 0, void 0, function* () {
+            // Try to get from cache
             const cached = yield this.get(key, options);
             if (cached !== null) {
                 return cached;
             }
+            // Generate new value
             const value = yield factory();
+            // Cache the value
             yield this.set(key, value, options);
             return value;
         });
     }
+    /**
+     * Get value from cache with optional layer specification
+     *
+     * @param key - Cache key
+     * @param options - Cache options including layer preference
+     * @returns Cached value or null
+     *
+     * @example
+     * ```typescript
+     * // Try memory only
+     * const data = await this.cacheService.get('user:123', {
+     *   layers: [CacheLayer.MEMORY]
+     * });
+     *
+     * // Try all layers in order (CLS -> MEMORY -> REDIS)
+     * const data = await this.cacheService.get('config:app', {
+     *   layers: [CacheLayer.CLS, CacheLayer.MEMORY, CacheLayer.REDIS]
+     * });
+     * ```
+     */
     get(key, options) {
         return __awaiter(this, void 0, void 0, function* () {
             this.stats.totalGets++;
             const layers = this.resolveLayers(options === null || options === void 0 ? void 0 : options.layers);
             const fullKey = this.buildKey(key, options === null || options === void 0 ? void 0 : options.namespace);
+            // Try each layer in order
             for (let i = 0; i < layers.length; i++) {
                 const layer = layers[i];
                 const provider = this.providers.get(layer);
@@ -79,19 +120,24 @@ let CacheService = CacheService_1 = class CacheService {
                 try {
                     const wrapped = yield provider.get(fullKey);
                     if (wrapped !== null) {
+                        // Validate dependencies if present
                         let value = yield utils_1.DependencyManager.unwrapAndValidate(wrapped, options === null || options === void 0 ? void 0 : options.dependencies);
                         if (value !== null) {
+                            // Check if value is compressed and decompress if needed
                             if (this.enableCompression && Buffer.isBuffer(value)) {
                                 const serializationService = new cache_serialization_service_1.CacheSerializationService();
                                 const decompressed = yield serializationService.deserialize(value);
                                 value = decompressed.data;
                             }
+                            // Cache hit
                             this.recordHit(layer);
+                            // Backfill upper layers
                             if ((options === null || options === void 0 ? void 0 : options.backfill) !== false && i > 0) {
                                 yield this.backfillUpperLayers(fullKey, wrapped, layers.slice(0, i), options === null || options === void 0 ? void 0 : options.ttl);
                             }
                             return value;
                         }
+                        // Dependencies changed, delete from this layer
                         yield provider.delete(fullKey);
                     }
                 }
@@ -99,20 +145,63 @@ let CacheService = CacheService_1 = class CacheService {
                     this.logger.warn(`Failed to get from ${layer} cache: ${error instanceof Error ? error.message : String(error)}`);
                 }
             }
+            // Cache miss
             this.recordMiss();
             return null;
         });
     }
+    /**
+     * Set value in cache with optional layer specification
+     *
+     * Supports both new API (CacheOptions) and legacy API (TTL number) for backward compatibility.
+     *
+     * @param key - Cache key
+     * @param value - Value to cache
+     * @param options - Cache options including layer selection OR TTL (number) for legacy compatibility
+     *
+     * @example
+     * ```typescript
+     * // New API - Cache in memory only
+     * await this.cacheService.set('user:123', userData, {
+     *   layers: [CacheLayer.MEMORY],
+     *   ttl: 300000
+     * });
+     *
+     * // Legacy API - TTL as third parameter (still works for backward compatibility)
+     * await this.cacheService.set('user:123', userData, 300000);
+     *
+     * // Cache in all layers (default behavior)
+     * await this.cacheService.set('config:app', configData, {
+     *   layers: [CacheLayer.CLS, CacheLayer.MEMORY, CacheLayer.REDIS],
+     *   ttl: 3600000
+     * });
+     *
+     * // Cache in Redis only (distributed)
+     * await this.cacheService.set('global:settings', settings, {
+     *   layers: [CacheLayer.REDIS],
+     *   ttl: 86400000
+     * });
+     * ```
+     */
     set(key, value, options) {
         return __awaiter(this, void 0, void 0, function* () {
+            // Check if the third parameter is a number (old API) or CacheOptions (new API)
             if (typeof options === 'number') {
+                // Old cache-manager API: set(key, value, ttl)
                 return this.setWithOptions(key, value, { ttl: options });
             }
             else {
+                // New API: set(key, value, options)
                 return this.setWithOptions(key, value, options);
             }
         });
     }
+    /**
+     * Delete value from cache
+     *
+     * @param key - Cache key or array of keys
+     * @param layers - Specific layers to delete from (default: all)
+     */
     del(key, layers) {
         return __awaiter(this, void 0, void 0, function* () {
             this.stats.totalDeletes++;
@@ -133,6 +222,12 @@ let CacheService = CacheService_1 = class CacheService {
             yield Promise.all(promises);
         });
     }
+    /**
+     * Delete keys matching pattern
+     *
+     * @param pattern - Pattern to match (e.g., 'user:*')
+     * @param layers - Specific layers to delete from (default: Memory and Redis only)
+     */
     deletePattern(pattern, layers) {
         return __awaiter(this, void 0, void 0, function* () {
             const targetLayers = layers || [interfaces_1.CacheLayer.MEMORY, interfaces_1.CacheLayer.REDIS];
@@ -151,6 +246,11 @@ let CacheService = CacheService_1 = class CacheService {
             yield Promise.all(promises);
         });
     }
+    /**
+     * Clear all cache
+     *
+     * @param layers - Specific layers to clear (default: all)
+     */
     clear(layers) {
         return __awaiter(this, void 0, void 0, function* () {
             this.stats.totalClears++;
@@ -170,27 +270,53 @@ let CacheService = CacheService_1 = class CacheService {
             yield Promise.all(promises);
         });
     }
+    /**
+     * Invalidate tags (for TagDependency)
+     *
+     * @param tags - Tags to invalidate
+     */
     invalidateTags(tags) {
         return __awaiter(this, void 0, void 0, function* () {
             dependencies_1.TagDependency.invalidateTags(tags);
             this.logger.debug(`Invalidated tags: ${tags.join(', ')}`);
         });
     }
+    /**
+     * Get multiple values
+     *
+     * @param keys - Array of cache keys
+     * @param options - Cache options
+     * @returns Array of values (null for missing keys)
+     */
     mget(keys, options) {
         return __awaiter(this, void 0, void 0, function* () {
             const promises = keys.map((key) => this.get(key, options));
             return Promise.all(promises);
         });
     }
+    /**
+     * Set multiple values
+     *
+     * @param items - Array of key-value pairs
+     * @param options - Cache options
+     */
     mset(items, options) {
         return __awaiter(this, void 0, void 0, function* () {
             const promises = items.map((item) => this.set(item.key, item.value, options));
             yield Promise.all(promises);
         });
     }
+    /**
+     * Get cache statistics
+     *
+     * @returns Cache statistics
+     */
     getStats() {
         return Object.assign(Object.assign({}, this.stats), { hitRate: this.stats.totalGets > 0 ? this.stats.hits / this.stats.totalGets : 0 });
     }
+    /**
+     * Reset statistics
+     */
     resetStats() {
         this.stats.totalGets = 0;
         this.stats.hits = 0;
@@ -201,14 +327,19 @@ let CacheService = CacheService_1 = class CacheService {
         this.stats.totalClears = 0;
         this.initializeStats();
     }
+    /**
+     * Internal method to set cache value with options
+     */
     setWithOptions(key, value, options) {
         return __awaiter(this, void 0, void 0, function* () {
             this.stats.totalSets++;
+            // Check condition
             if ((options === null || options === void 0 ? void 0 : options.condition) && !(yield Promise.resolve(options.condition()))) {
                 return;
             }
             const layers = this.resolveLayers(options === null || options === void 0 ? void 0 : options.layers);
             const fullKey = this.buildKey(key, options === null || options === void 0 ? void 0 : options.namespace);
+            // Apply compression if enabled and value is large enough
             let processedValue = value;
             if (this.enableCompression &&
                 value !== null &&
@@ -221,7 +352,9 @@ let CacheService = CacheService_1 = class CacheService {
                 });
                 processedValue = compressed.data;
             }
+            // Wrap value with dependencies
             const wrapped = yield utils_1.DependencyManager.wrapWithDependencies(processedValue, options === null || options === void 0 ? void 0 : options.dependencies);
+            // Set in all layers
             const promises = layers.map((layer) => __awaiter(this, void 0, void 0, function* () {
                 const provider = this.providers.get(layer);
                 if (!provider) {
@@ -237,21 +370,33 @@ let CacheService = CacheService_1 = class CacheService {
             yield Promise.all(promises);
         });
     }
+    /**
+     * Resolve cache layers from options
+     */
     resolveLayers(layers) {
         if (layers && layers.length > 0) {
             return layers;
         }
         return this.getDefaultLayers();
     }
+    /**
+     * Get default cache layers
+     */
     getDefaultLayers() {
         return [interfaces_1.CacheLayer.CLS, interfaces_1.CacheLayer.MEMORY, interfaces_1.CacheLayer.REDIS];
     }
+    /**
+     * Build full cache key with namespace
+     */
     buildKey(key, namespace) {
         if (namespace) {
             return `${namespace}:${key}`;
         }
         return key;
     }
+    /**
+     * Backfill upper cache layers
+     */
     backfillUpperLayers(key, value, layers, ttl) {
         return __awaiter(this, void 0, void 0, function* () {
             const promises = layers.map((layer) => __awaiter(this, void 0, void 0, function* () {
@@ -269,6 +414,9 @@ let CacheService = CacheService_1 = class CacheService {
             yield Promise.all(promises);
         });
     }
+    /**
+     * Record cache hit
+     */
     recordHit(layer) {
         this.stats.hits++;
         if (!this.stats.byLayer[layer]) {
@@ -277,9 +425,15 @@ let CacheService = CacheService_1 = class CacheService {
         this.stats.byLayer[layer].hits++;
         this.updateLayerHitRate(layer);
     }
+    /**
+     * Record cache miss
+     */
     recordMiss() {
         this.stats.misses++;
     }
+    /**
+     * Update hit rate for a layer
+     */
     updateLayerHitRate(layer) {
         const layerStats = this.stats.byLayer[layer];
         if (layerStats) {
@@ -287,6 +441,9 @@ let CacheService = CacheService_1 = class CacheService {
             layerStats.hitRate = total > 0 ? layerStats.hits / total : 0;
         }
     }
+    /**
+     * Initialize statistics for all layers
+     */
     initializeStats() {
         for (const layer of [interfaces_1.CacheLayer.CLS, interfaces_1.CacheLayer.MEMORY, interfaces_1.CacheLayer.REDIS]) {
             if (!this.stats.byLayer[layer]) {

package/cache/cache.warmup.service.d.ts

@@ -1,13 +1,26 @@
 import { CacheService } from './cache.service';
+/**
+ * Cache warmup configuration
+ */
 export interface CacheWarmupConfig {
+    /** Warmup task name */
     name: string;
+    /** Function to generate cache data */
     dataProvider: () => Promise<any> | any;
+    /** Cache key or key generator */
     key: string | ((data: any) => string);
+    /** Cache TTL */
     ttl?: number;
+    /** Cache layers to use */
     layers?: string[];
+    /** Number of items to process in parallel */
     batchSize?: number;
+    /** Whether this warmup is critical (fail if it fails) */
     critical?: boolean;
 }
+/**
+ * Cache warmup result
+ */
 export interface CacheWarmupResult {
     name: string;
     success: boolean;
@@ -15,20 +28,46 @@ export interface CacheWarmupResult {
     duration: number;
     errors: string[];
 }
+/**
+ * Cache warmup service
+ *
+ * Provides functionality to warm up cache with data before serving requests
+ */
 export declare class CacheWarmupService {
     private readonly cacheService;
     private readonly logger;
     private warmupConfigs;
     constructor(cacheService: CacheService);
+    /**
+     * Register warmup configurations for a group
+     */
     registerWarmup(groupName: string, configs: CacheWarmupConfig[]): void;
+    /**
+     * Execute warmup for a specific group
+     */
     warmupGroup(groupName: string): Promise<CacheWarmupResult[]>;
+    /**
+     * Execute warmup for all registered groups
+     */
     warmupAll(): Promise<Map<string, CacheWarmupResult[]>>;
+    /**
+     * Get warmup statistics
+     */
     getWarmupStats(): {
         totalGroups: number;
         totalTasks: number;
         taskDetails: any[];
     };
+    /**
+     * Remove warmup configuration
+     */
     removeWarmupGroup(groupName: string): boolean;
+    /**
+     * Clear all warmup configurations
+     */
     clearWarmupConfigs(): void;
+    /**
+     * Execute a single warmup task
+     */
     private executeWarmupTask;
 }

package/cache/cache.warmup.service.js

@@ -22,16 +22,27 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CacheWarmupService = void 0;
 const common_1 = require("@nestjs/common");
 const cache_service_1 = require("./cache.service");
+/**
+ * Cache warmup service
+ *
+ * Provides functionality to warm up cache with data before serving requests
+ */
 let CacheWarmupService = CacheWarmupService_1 = class CacheWarmupService {
     constructor(cacheService) {
         this.cacheService = cacheService;
         this.logger = new common_1.Logger(CacheWarmupService_1.name);
         this.warmupConfigs = new Map();
     }
+    /**
+     * Register warmup configurations for a group
+     */
     registerWarmup(groupName, configs) {
         this.warmupConfigs.set(groupName, configs);
         this.logger.debug(`Registered ${configs.length} warmup tasks for group: ${groupName}`);
     }
+    /**
+     * Execute warmup for a specific group
+     */
     warmupGroup(groupName) {
         return __awaiter(this, void 0, void 0, function* () {
             const configs = this.warmupConfigs.get(groupName);
@@ -57,6 +68,9 @@ let CacheWarmupService = CacheWarmupService_1 = class CacheWarmupService {
             return results;
         });
     }
+    /**
+     * Execute warmup for all registered groups
+     */
     warmupAll() {
         return __awaiter(this, void 0, void 0, function* () {
             const results = new Map();
@@ -81,6 +95,9 @@ let CacheWarmupService = CacheWarmupService_1 = class CacheWarmupService {
             return results;
         });
     }
+    /**
+     * Get warmup statistics
+     */
     getWarmupStats() {
         const totalGroups = this.warmupConfigs.size;
         let totalTasks = 0;
@@ -98,13 +115,22 @@ let CacheWarmupService = CacheWarmupService_1 = class CacheWarmupService {
         }
         return { totalGroups, totalTasks, taskDetails };
     }
+    /**
+     * Remove warmup configuration
+     */
     removeWarmupGroup(groupName) {
         return this.warmupConfigs.delete(groupName);
     }
+    /**
+     * Clear all warmup configurations
+     */
     clearWarmupConfigs() {
         this.warmupConfigs.clear();
         this.logger.debug('All warmup configurations cleared');
     }
+    /**
+     * Execute a single warmup task
+     */
     executeWarmupTask(config) {
         return __awaiter(this, void 0, void 0, function* () {
             const startTime = Date.now();
@@ -113,8 +139,11 @@ let CacheWarmupService = CacheWarmupService_1 = class CacheWarmupService {
             let success = true;
             try {
                 this.logger.debug(`Executing warmup task: ${config.name}`);
+                // Get data from provider
                 const data = yield Promise.resolve(config.dataProvider());
+                // Handle different data types
                 if (Array.isArray(data)) {
+                    // Array of items - warm up each item
                     const batchSize = config.batchSize || 100;
                     itemCount = data.length;
                     for (let i = 0; i < data.length; i += batchSize) {
@@ -136,6 +165,7 @@ let CacheWarmupService = CacheWarmupService_1 = class CacheWarmupService {
                     }
                 }
                 else if (data && typeof data === 'object') {
+                    // Single object - could be a Map or key-value pairs
                     if (data instanceof Map) {
                         itemCount = data.size;
                         for (const [key, value] of data) {
@@ -151,6 +181,7 @@ let CacheWarmupService = CacheWarmupService_1 = class CacheWarmupService {
                         }
                     }
                     else {
+                        // Single object
                         itemCount = 1;
                         const key = typeof config.key === 'function' ? config.key(data) : config.key;
                         yield this.cacheService.set(key, data, {
@@ -160,6 +191,7 @@ let CacheWarmupService = CacheWarmupService_1 = class CacheWarmupService {
                     }
                 }
                 else if (data !== null && data !== undefined) {
+                    // Primitive value
                     itemCount = 1;
                     const key = typeof config.key === 'function' ? config.key(data) : config.key;
                     yield this.cacheService.set(key, data, {