@nest-omni/core 4.1.3-1 → 4.1.3-10

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;
                 }
             });

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

@@ -1,2 +1,36 @@
 import type { CachePutOptions } from '../interfaces';
+/**
+ * @CachePut decorator - Update cache with method result
+ *
+ * This decorator always executes the method and updates the cache with the result.
+ * Unlike @Cacheable which skips method execution if cache exists, @CachePut
+ * always runs the method and updates cache afterwards.
+ *
+ * Useful for update operations where you want to refresh the cache.
+ *
+ * @param options - Cache put options
+ *
+ * @example
+ * ```typescript
+ * class UserService {
+ *   @CachePut({
+ *     key: (id) => `user:${id}`,
+ *     ttl: 300_000
+ *   })
+ *   async updateUser(id: string, data: UpdateUserDto) {
+ *     await this.repo.update(id, data);
+ *     return await this.repo.findOne({ where: { id } });
+ *   }
+ *
+ *   // Conditional cache update
+ *   @CachePut({
+ *     key: (id) => `user:${id}`,
+ *     condition: (id, data) => data.important === true
+ *   })
+ *   async updateUserProfile(id: string, data: any) {
+ *     return await this.repo.update(id, data);
+ *   }
+ * }
+ * ```
+ */
 export declare function CachePut(options?: CachePutOptions): MethodDecorator;

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

@@ -13,6 +13,40 @@ exports.CachePut = CachePut;
 const common_1 = require("@nestjs/common");
 const utils_1 = require("../utils");
 const cacheable_decorator_1 = require("./cacheable.decorator");
+/**
+ * @CachePut decorator - Update cache with method result
+ *
+ * This decorator always executes the method and updates the cache with the result.
+ * Unlike @Cacheable which skips method execution if cache exists, @CachePut
+ * always runs the method and updates cache afterwards.
+ *
+ * Useful for update operations where you want to refresh the cache.
+ *
+ * @param options - Cache put options
+ *
+ * @example
+ * ```typescript
+ * class UserService {
+ *   @CachePut({
+ *     key: (id) => `user:${id}`,
+ *     ttl: 300_000
+ *   })
+ *   async updateUser(id: string, data: UpdateUserDto) {
+ *     await this.repo.update(id, data);
+ *     return await this.repo.findOne({ where: { id } });
+ *   }
+ *
+ *   // Conditional cache update
+ *   @CachePut({
+ *     key: (id) => `user:${id}`,
+ *     condition: (id, data) => data.important === true
+ *   })
+ *   async updateUserProfile(id: string, data: any) {
+ *     return await this.repo.update(id, data);
+ *   }
+ * }
+ * ```
+ */
 function CachePut(options = {}) {
     const logger = new common_1.Logger('CachePutDecorator');
     return function (target, propertyKey, descriptor) {
@@ -26,19 +60,24 @@ function CachePut(options = {}) {
                     return originalMethod.apply(this, args);
                 }
                 try {
+                    // Always execute the original method
                     const result = yield originalMethod.apply(this, args);
+                    // Check condition
                     if (options.condition) {
                         const shouldCache = yield Promise.resolve(options.condition(...args));
                         if (!shouldCache) {
                             return result;
                         }
                     }
+                    // Generate cache key
                     const key = utils_1.KeyGenerator.generate(options, args);
+                    // Update cache with result
                     yield cacheService.set(key, result, options);
                     return result;
                 }
                 catch (error) {
                     logger.error(`Cache put error in ${target.constructor.name}.${methodName}: ${error instanceof Error ? error.message : String(error)}`);
+                    // Re-throw the error (cache update failure shouldn't hide method errors)
                     throw error;
                 }
             });

package/cache/decorators/cacheable.decorator.d.ts

@@ -1,4 +1,44 @@
 import type { CacheableOptions } from '../interfaces';
+/**
+ * Set global CacheService instance
+ * Called by CacheModule during initialization
+ */
 export declare function setCacheService(cacheService: any): void;
+/**
+ * Get global CacheService instance
+ */
 export declare function getCacheService(): any;
+/**
+ * @Cacheable decorator - Cache method results
+ *
+ * This decorator automatically caches the return value of a method.
+ * On subsequent calls with the same arguments, the cached value is returned.
+ *
+ * @param options - Cacheable options
+ *
+ * @example
+ * ```typescript
+ * class UserService {
+ *   @Cacheable({
+ *     key: (id) => `user:${id}`,
+ *     ttl: 300_000, // 5 minutes
+ *     layers: [CacheLayer.MEMORY, CacheLayer.REDIS]
+ *   })
+ *   async getUserById(id: string) {
+ *     return await this.repo.findOne({ where: { id } });
+ *   }
+ *
+ *   // With dependencies
+ *   @Cacheable({
+ *     key: (id) => `user:${id}:profile`,
+ *     dependencies: [
+ *       new DbDependency('SELECT updated_at FROM users WHERE id = ?', (id) => [id])
+ *     ]
+ *   })
+ *   async getUserProfile(id: string) {
+ *     return await this.fetchProfile(id);
+ *   }
+ * }
+ * ```
+ */
 export declare function Cacheable(options?: CacheableOptions): MethodDecorator;

package/cache/decorators/cacheable.decorator.js

@@ -14,13 +14,57 @@ exports.getCacheService = getCacheService;
 exports.Cacheable = Cacheable;
 const common_1 = require("@nestjs/common");
 const utils_1 = require("../utils");
+/**
+ * Global CacheService instance holder
+ * Will be set by CacheModule during initialization
+ */
 let globalCacheService = null;
+/**
+ * Set global CacheService instance
+ * Called by CacheModule during initialization
+ */
 function setCacheService(cacheService) {
     globalCacheService = cacheService;
 }
+/**
+ * Get global CacheService instance
+ */
 function getCacheService() {
     return globalCacheService;
 }
+/**
+ * @Cacheable decorator - Cache method results
+ *
+ * This decorator automatically caches the return value of a method.
+ * On subsequent calls with the same arguments, the cached value is returned.
+ *
+ * @param options - Cacheable options
+ *
+ * @example
+ * ```typescript
+ * class UserService {
+ *   @Cacheable({
+ *     key: (id) => `user:${id}`,
+ *     ttl: 300_000, // 5 minutes
+ *     layers: [CacheLayer.MEMORY, CacheLayer.REDIS]
+ *   })
+ *   async getUserById(id: string) {
+ *     return await this.repo.findOne({ where: { id } });
+ *   }
+ *
+ *   // With dependencies
+ *   @Cacheable({
+ *     key: (id) => `user:${id}:profile`,
+ *     dependencies: [
+ *       new DbDependency('SELECT updated_at FROM users WHERE id = ?', (id) => [id])
+ *     ]
+ *   })
+ *   async getUserProfile(id: string) {
+ *     return await this.fetchProfile(id);
+ *   }
+ * }
+ * ```
+ */
 function Cacheable(options = {}) {
     const logger = new common_1.Logger('CacheableDecorator');
     return function (target, propertyKey, descriptor) {
@@ -34,20 +78,25 @@ function Cacheable(options = {}) {
                     return originalMethod.apply(this, args);
                 }
                 try {
+                    // Generate cache key
                     const key = utils_1.KeyGenerator.generate(options, args);
+                    // Check condition
                     if (options.condition) {
                         const shouldCache = yield Promise.resolve(options.condition(...args));
                         if (!shouldCache) {
                             return originalMethod.apply(this, args);
                         }
                     }
+                    // Resolve dependencies with context
                     const dependencies = options.dependencies
                         ? yield resolveDependenciesWithContext(options.dependencies, args)
                         : undefined;
+                    // Try to get from cache using getOrSet
                     return yield cacheService.getOrSet(key, () => originalMethod.apply(this, args), Object.assign(Object.assign({}, options), { dependencies }));
                 }
                 catch (error) {
                     logger.error(`Cache error in ${target.constructor.name}.${methodName}: ${error instanceof Error ? error.message : String(error)}`);
+                    // Fallback to original method on error
                     return originalMethod.apply(this, args);
                 }
             });
@@ -55,10 +104,16 @@ function Cacheable(options = {}) {
         return descriptor;
     };
 }
+/**
+ * Resolve dependencies that may need method arguments
+ * Some dependencies (like DbDependency) may use method args in their factory
+ */
 function resolveDependenciesWithContext(dependencies, args) {
     return __awaiter(this, void 0, void 0, function* () {
         return dependencies.map((dep) => {
+            // If dependency has a params factory, bind it to current args
             if (dep.paramsFactory && typeof dep.paramsFactory === 'function') {
+                // Create a new instance with resolved params
                 const params = dep.paramsFactory(...args);
                 return new dep.constructor(dep.sql, () => params, dep.name);
             }

package/cache/dependencies/callback.dependency.d.ts

@@ -1,4 +1,31 @@
 import type { CacheDependency } from '../interfaces/cache-dependency.interface';
+/**
+ * Callback-based cache dependency
+ *
+ * This dependency uses a callback function to determine if cache is still valid.
+ * When the callback's return value changes, the cache becomes invalid.
+ *
+ * @example
+ * ```typescript
+ * // Cache config, invalidate when version changes
+ * @Cacheable({
+ *   key: 'app:config',
+ *   dependencies: [
+ *     new CallbackDependency(() => ConfigService.get('app.version'))
+ *   ]
+ * })
+ * async getConfig() { }
+ *
+ * // Cache based on feature flag
+ * @Cacheable({
+ *   key: 'features',
+ *   dependencies: [
+ *     new CallbackDependency(() => FeatureService.getHash())
+ *   ]
+ * })
+ * async getFeatures() { }
+ * ```
+ */
 export declare class CallbackDependency implements CacheDependency {
     private readonly callback;
     private readonly name?;
@@ -6,6 +33,12 @@ export declare class CallbackDependency implements CacheDependency {
     getKey(): string;
     getData(): Promise<any>;
     isChanged(oldData: any): Promise<boolean>;
+    /**
+     * Deep equality check for primitive values, objects, and arrays
+     */
     private isEqual;
+    /**
+     * Simple hash code generation for strings
+     */
     private hashCode;
 }

package/cache/dependencies/callback.dependency.js

@@ -10,6 +10,33 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CallbackDependency = void 0;
+/**
+ * Callback-based cache dependency
+ *
+ * This dependency uses a callback function to determine if cache is still valid.
+ * When the callback's return value changes, the cache becomes invalid.
+ *
+ * @example
+ * ```typescript
+ * // Cache config, invalidate when version changes
+ * @Cacheable({
+ *   key: 'app:config',
+ *   dependencies: [
+ *     new CallbackDependency(() => ConfigService.get('app.version'))
+ *   ]
+ * })
+ * async getConfig() { }
+ *
+ * // Cache based on feature flag
+ * @Cacheable({
+ *   key: 'features',
+ *   dependencies: [
+ *     new CallbackDependency(() => FeatureService.getHash())
+ *   ]
+ * })
+ * async getFeatures() { }
+ * ```
+ */
 class CallbackDependency {
     constructor(callback, name) {
         this.callback = callback;
@@ -19,6 +46,7 @@ class CallbackDependency {
         }
     }
     getKey() {
+        // Use function name or provided name, fallback to hash
         const callbackName = this.name || this.callback.name || 'anonymous';
         return `callback:${callbackName}:${this.hashCode(this.callback.toString())}`;
     }
@@ -28,6 +56,7 @@ class CallbackDependency {
                 return yield Promise.resolve(this.callback());
             }
             catch (error) {
+                // If callback fails, consider it as changed to be safe
                 throw new Error(`CallbackDependency getData failed: ${error instanceof Error ? error.message : String(error)}`);
             }
         });
@@ -39,10 +68,14 @@ class CallbackDependency {
                 return !this.isEqual(oldData, currentData);
             }
             catch (_a) {
+                // If we can't get current data, consider it changed
                 return true;
             }
         });
     }
+    /**
+     * Deep equality check for primitive values, objects, and arrays
+     */
     isEqual(a, b) {
         if (a === b) {
             return true;
@@ -56,6 +89,7 @@ class CallbackDependency {
         if (typeof a !== 'object') {
             return a === b;
         }
+        // Handle arrays
         if (Array.isArray(a) && Array.isArray(b)) {
             if (a.length !== b.length) {
                 return false;
@@ -67,6 +101,7 @@ class CallbackDependency {
             }
             return true;
         }
+        // Handle objects
         const keysA = Object.keys(a);
         const keysB = Object.keys(b);
         if (keysA.length !== keysB.length) {
@@ -79,12 +114,15 @@ class CallbackDependency {
         }
         return true;
     }
+    /**
+     * Simple hash code generation for strings
+     */
     hashCode(str) {
         let hash = 0;
         for (let i = 0; i < str.length; i++) {
             const char = str.charCodeAt(i);
             hash = (hash << 5) - hash + char;
-            hash = hash & hash;
+            hash = hash & hash; // Convert to 32bit integer
         }
         return Math.abs(hash).toString(36);
     }

package/cache/dependencies/chain.dependency.d.ts

@@ -1,4 +1,26 @@
 import type { CacheDependency } from '../interfaces/cache-dependency.interface';
+/**
+ * Chain dependency - combines multiple dependencies
+ *
+ * The cache is invalidated when ANY of the dependencies change.
+ * This allows you to create complex invalidation logic by combining simpler dependencies.
+ *
+ * @example
+ * ```typescript
+ * // Invalidate when either user data changes OR config changes
+ * @Cacheable({
+ *   key: (id) => `user:${id}:view`,
+ *   dependencies: [
+ *     new ChainDependency([
+ *       new TagDependency(['user-data']),
+ *       new CallbackDependency(() => ConfigService.get('app.version')),
+ *       new DbDependency('SELECT updated_at FROM users WHERE id = ?', (id) => [id])
+ *     ])
+ *   ]
+ * })
+ * async getUserView(id: string) { }
+ * ```
+ */
 export declare class ChainDependency implements CacheDependency {
     private readonly dependencies;
     constructor(dependencies: CacheDependency[]);
@@ -12,7 +34,13 @@ export declare class ChainDependency implements CacheDependency {
         data: any;
     }>): Promise<boolean>;
     reset(): Promise<void>;
+    /**
+     * Get all dependencies in this chain
+     */
     getDependencies(): CacheDependency[];
+    /**
+     * Check which dependencies have changed
+     */
     getChangedDependencies(oldData: Array<{
         key: string;
         data: any;

package/cache/dependencies/chain.dependency.js

@@ -10,12 +10,35 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChainDependency = void 0;
+/**
+ * Chain dependency - combines multiple dependencies
+ *
+ * The cache is invalidated when ANY of the dependencies change.
+ * This allows you to create complex invalidation logic by combining simpler dependencies.
+ *
+ * @example
+ * ```typescript
+ * // Invalidate when either user data changes OR config changes
+ * @Cacheable({
+ *   key: (id) => `user:${id}:view`,
+ *   dependencies: [
+ *     new ChainDependency([
+ *       new TagDependency(['user-data']),
+ *       new CallbackDependency(() => ConfigService.get('app.version')),
+ *       new DbDependency('SELECT updated_at FROM users WHERE id = ?', (id) => [id])
+ *     ])
+ *   ]
+ * })
+ * async getUserView(id: string) { }
+ * ```
+ */
 class ChainDependency {
     constructor(dependencies) {
         this.dependencies = dependencies;
         if (!Array.isArray(dependencies) || dependencies.length === 0) {
             throw new Error('ChainDependency requires at least one dependency');
         }
+        // Validate all dependencies implement the interface
         for (const dep of dependencies) {
             if (!dep.getKey || !dep.getData || !dep.isChanged) {
                 throw new Error('All dependencies must implement CacheDependency interface');
@@ -38,6 +61,7 @@ class ChainDependency {
                     });
                 }
                 catch (error) {
+                    // If any dependency fails to get data, store the error
                     results.push({
                         key: dep.getKey(),
                         data: {
@@ -55,19 +79,23 @@ class ChainDependency {
                 oldData.length !== this.dependencies.length) {
                 return true;
             }
+            // Check each dependency
             for (let i = 0; i < this.dependencies.length; i++) {
                 const dep = this.dependencies[i];
                 const oldDepData = oldData[i];
+                // Key mismatch means dependencies changed
                 if (oldDepData.key !== dep.getKey()) {
                     return true;
                 }
                 try {
+                    // Check if this dependency has changed
                     const changed = yield dep.isChanged(oldDepData.data);
                     if (changed) {
                         return true;
                     }
                 }
                 catch (_a) {
+                    // If check fails, consider it changed
                     return true;
                 }
             }
@@ -83,9 +111,15 @@ class ChainDependency {
             }
         });
     }
+    /**
+     * Get all dependencies in this chain
+     */
     getDependencies() {
         return [...this.dependencies];
     }
+    /**
+     * Check which dependencies have changed
+     */
     getChangedDependencies(oldData) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!Array.isArray(oldData) ||