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

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,31 @@ 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++;
+            // Validate TTL if provided
+            if ((options === null || options === void 0 ? void 0 : options.ttl) !== undefined) {
+                if (typeof options.ttl !== 'number' || options.ttl < 0) {
+                    this.logger.warn(`Invalid TTL value: ${options.ttl}. TTL must be a non-negative number. Using default behavior.`);
+                    // Continue without TTL
+                    options.ttl = undefined;
+                }
+                else if (options.ttl === 0) {
+                    // TTL of 0 means no expiration
+                    options.ttl = undefined;
+                }
+            }
+            // 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 +364,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 +382,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 +426,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 +437,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 +453,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, {

package/cache/decorators/cache-evict.decorator.d.ts

@@ -1,2 +1,49 @@
 import type { CacheEvictOptions } from '../interfaces';
+/**
+ * @CacheEvict decorator - Evict/invalidate cache entries
+ *
+ * This decorator automatically removes cache entries when a method is executed.
+ * Useful for invalidating cache after update/delete operations.
+ *
+ * @param options - Cache evict options
+ *
+ * @example
+ * ```typescript
+ * class UserService {
+ *   // Evict single cache entry
+ *   @CacheEvict({
+ *     keys: [(id) => `user:${id}`]
+ *   })
+ *   async deleteUser(id: string) {
+ *     await this.repo.delete(id);
+ *   }
+ *
+ *   // Evict multiple entries with patterns
+ *   @CacheEvict({
+ *     patterns: ['user:*', 'users:list:*']
+ *   })
+ *   async updateAllUsers() {
+ *     await this.repo.update({}, { status: 'active' });
+ *   }
+ *
+ *   // Invalidate by tags
+ *   @CacheEvict({
+ *     tags: ['user-list', 'user-data']
+ *   })
+ *   async createUser(data: CreateUserDto) {
+ *     return await this.repo.save(data);
+ *   }
+ *
+ *   // Conditional eviction
+ *   @CacheEvict({
+ *     keys: [(id) => `user:${id}`],
+ *     condition: (id, result) => result.success
+ *   })
+ *   async updateUser(id: string, data: any) {
+ *     const result = await this.repo.update(id, data);
+ *     return { success: result.affected > 0 };
+ *   }
+ * }
+ * ```
+ */
 export declare function CacheEvict(options?: CacheEvictOptions): MethodDecorator;

package/cache/decorators/cache-evict.decorator.js

@@ -12,6 +12,53 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CacheEvict = CacheEvict;
 const common_1 = require("@nestjs/common");
 const cacheable_decorator_1 = require("./cacheable.decorator");
+/**
+ * @CacheEvict decorator - Evict/invalidate cache entries
+ *
+ * This decorator automatically removes cache entries when a method is executed.
+ * Useful for invalidating cache after update/delete operations.
+ *
+ * @param options - Cache evict options
+ *
+ * @example
+ * ```typescript
+ * class UserService {
+ *   // Evict single cache entry
+ *   @CacheEvict({
+ *     keys: [(id) => `user:${id}`]
+ *   })
+ *   async deleteUser(id: string) {
+ *     await this.repo.delete(id);
+ *   }
+ *
+ *   // Evict multiple entries with patterns
+ *   @CacheEvict({
+ *     patterns: ['user:*', 'users:list:*']
+ *   })
+ *   async updateAllUsers() {
+ *     await this.repo.update({}, { status: 'active' });
+ *   }
+ *
+ *   // Invalidate by tags
+ *   @CacheEvict({
+ *     tags: ['user-list', 'user-data']
+ *   })
+ *   async createUser(data: CreateUserDto) {
+ *     return await this.repo.save(data);
+ *   }
+ *
+ *   // Conditional eviction
+ *   @CacheEvict({
+ *     keys: [(id) => `user:${id}`],
+ *     condition: (id, result) => result.success
+ *   })
+ *   async updateUser(id: string, data: any) {
+ *     const result = await this.repo.update(id, data);
+ *     return { success: result.affected > 0 };
+ *   }
+ * }
+ * ```
+ */
 function CacheEvict(options = {}) {
     const logger = new common_1.Logger('CacheEvictDecorator');
     return function (target, propertyKey, descriptor) {
@@ -26,21 +73,25 @@ function CacheEvict(options = {}) {
                 }
                 const evictCache = (result) => __awaiter(this, void 0, void 0, function* () {
                     try {
+                        // Check condition
                         if (options.condition) {
                             const shouldEvict = yield Promise.resolve(options.condition(...args, result));
                             if (!shouldEvict) {
                                 return;
                             }
                         }
+                        // Evict by keys
                         if (options.keys && options.keys.length > 0) {
                             const resolvedKeys = options.keys.map((keyOrFn) => typeof keyOrFn === 'function' ? keyOrFn(...args) : keyOrFn);
                             yield cacheService.delete(resolvedKeys, options.layers);
                         }
+                        // Evict by patterns
                         if (options.patterns && options.patterns.length > 0) {
                             for (const pattern of options.patterns) {
                                 yield cacheService.deletePattern(pattern, options.layers);
                             }
                         }
+                        // Invalidate tags
                         if (options.tags && options.tags.length > 0) {
                             yield cacheService.invalidateTags(options.tags);
                         }
@@ -50,19 +101,24 @@ function CacheEvict(options = {}) {
                     }
                 });
                 try {
+                    // Evict before method execution
                     if (options.timing === 'before') {
                         yield evictCache();
                     }
+                    // Execute original method
                     const result = yield originalMethod.apply(this, args);
+                    // Evict after method execution (default)
                     if (options.timing !== 'before') {
                         yield evictCache(result);
                     }
                     return result;
                 }
                 catch (error) {
+                    // Still try to evict on error if timing is 'before'
                     if (options.timing === 'before') {
                         throw error;
                     }
+                    // For 'after' timing, don't evict on error
                     throw error;
                 }
             });