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

package/cache/providers/base-cache.provider.d.ts

@@ -1,4 +1,7 @@
 import type { CacheProvider } from '../interfaces/cache-provider.interface';
+/**
+ * Base cache provider with common utility methods
+ */
 export declare abstract class BaseCacheProvider implements CacheProvider {
     abstract get<T>(key: string): Promise<T | null>;
     abstract set<T>(key: string, value: T, ttl?: number): Promise<void>;
@@ -7,10 +10,21 @@ export declare abstract class BaseCacheProvider implements CacheProvider {
     abstract clear(): Promise<void>;
     abstract has(key: string): Promise<boolean>;
     abstract getName(): string;
+    /**
+     * Get multiple values at once
+     * Default implementation - can be overridden for better performance
+     */
     mget<T>(keys: string[]): Promise<(T | null)[]>;
+    /**
+     * Set multiple values at once
+     * Default implementation - can be overridden for better performance
+     */
     mset(items: Array<{
         key: string;
         value: any;
     }>, ttl?: number): Promise<void>;
+    /**
+     * Convert wildcard pattern to RegExp
+     */
     protected patternToRegex(pattern: string): RegExp;
 }

package/cache/providers/base-cache.provider.js

@@ -10,21 +10,37 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseCacheProvider = void 0;
+/**
+ * Base cache provider with common utility methods
+ */
 class BaseCacheProvider {
+    /**
+     * Get multiple values at once
+     * Default implementation - can be overridden for better performance
+     */
     mget(keys) {
         return __awaiter(this, void 0, void 0, function* () {
             const promises = keys.map((key) => this.get(key));
             return Promise.all(promises);
         });
     }
+    /**
+     * Set multiple values at once
+     * Default implementation - can be overridden for better performance
+     */
     mset(items, ttl) {
         return __awaiter(this, void 0, void 0, function* () {
             const promises = items.map((item) => this.set(item.key, item.value, ttl));
             yield Promise.all(promises);
         });
     }
+    /**
+     * Convert wildcard pattern to RegExp
+     */
     patternToRegex(pattern) {
+        // Escape special regex characters except *
         const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+        // Convert * to .*
         const regexPattern = escaped.replace(/\*/g, '.*');
         return new RegExp(`^${regexPattern}$`);
     }

package/cache/providers/cls-cache.provider.d.ts

@@ -1,4 +1,12 @@
 import { BaseCacheProvider } from './base-cache.provider';
+/**
+ * CLS (Continuation Local Storage) cache provider
+ *
+ * This is the L1 cache layer - request-scoped caching using nestjs-cls.
+ * Data stored here is only available within the same request context.
+ *
+ * Fastest cache layer but limited to single request lifecycle.
+ */
 export declare class ClsCacheProvider extends BaseCacheProvider {
     private static readonly CACHE_PREFIX;
     private static readonly KEYS_SET;
@@ -9,8 +17,20 @@ export declare class ClsCacheProvider extends BaseCacheProvider {
     deletePattern(pattern: string): Promise<number>;
     clear(): Promise<void>;
     has(key: string): Promise<boolean>;
+    /**
+     * Get full key with prefix
+     */
     private getFullKey;
+    /**
+     * Add key to tracked keys set
+     */
     private addKeyToSet;
+    /**
+     * Remove key from tracked keys set
+     */
     private removeKeyFromSet;
+    /**
+     * Get all tracked keys
+     */
     private getAllKeys;
 }

package/cache/providers/cls-cache.provider.js

@@ -12,6 +12,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClsCacheProvider = void 0;
 const nestjs_cls_1 = require("nestjs-cls");
 const base_cache_provider_1 = require("./base-cache.provider");
+/**
+ * CLS (Continuation Local Storage) cache provider
+ *
+ * This is the L1 cache layer - request-scoped caching using nestjs-cls.
+ * Data stored here is only available within the same request context.
+ *
+ * Fastest cache layer but limited to single request lifecycle.
+ */
 class ClsCacheProvider extends base_cache_provider_1.BaseCacheProvider {
     getName() {
         return 'CLS';
@@ -25,6 +33,7 @@ class ClsCacheProvider extends base_cache_provider_1.BaseCacheProvider {
                 if (!cached) {
                     return null;
                 }
+                // Check TTL
                 if (cached.expiresAt && Date.now() > cached.expiresAt) {
                     yield this.delete(key);
                     return null;
@@ -32,6 +41,7 @@ class ClsCacheProvider extends base_cache_provider_1.BaseCacheProvider {
                 return cached.value;
             }
             catch (_a) {
+                // CLS might not be available (e.g., outside request context)
                 return null;
             }
         });
@@ -46,9 +56,11 @@ class ClsCacheProvider extends base_cache_provider_1.BaseCacheProvider {
                     cached.expiresAt = Date.now() + ttl;
                 }
                 store.set(fullKey, cached);
+                // Track this key for cleanup
                 this.addKeyToSet(key);
             }
             catch (_a) {
+                // CLS might not be available, silently fail
             }
         });
     }
@@ -64,6 +76,7 @@ class ClsCacheProvider extends base_cache_provider_1.BaseCacheProvider {
                 }
             }
             catch (_a) {
+                // CLS might not be available, silently fail
             }
         });
     }
@@ -90,6 +103,7 @@ class ClsCacheProvider extends base_cache_provider_1.BaseCacheProvider {
                 yield this.delete(allKeys);
             }
             catch (_a) {
+                // CLS might not be available, silently fail
             }
         });
     }
@@ -99,9 +113,15 @@ class ClsCacheProvider extends base_cache_provider_1.BaseCacheProvider {
             return value !== null;
         });
     }
+    /**
+     * Get full key with prefix
+     */
     getFullKey(key) {
         return `${ClsCacheProvider.CACHE_PREFIX}${key}`;
     }
+    /**
+     * Add key to tracked keys set
+     */
     addKeyToSet(key) {
         try {
             const store = nestjs_cls_1.ClsServiceManager.getClsService();
@@ -110,8 +130,12 @@ class ClsCacheProvider extends base_cache_provider_1.BaseCacheProvider {
             store.set(ClsCacheProvider.KEYS_SET, keys);
         }
         catch (_a) {
+            // Ignore
         }
     }
+    /**
+     * Remove key from tracked keys set
+     */
     removeKeyFromSet(key) {
         try {
             const store = nestjs_cls_1.ClsServiceManager.getClsService();
@@ -122,8 +146,12 @@ class ClsCacheProvider extends base_cache_provider_1.BaseCacheProvider {
             }
         }
         catch (_a) {
+            // Ignore
         }
     }
+    /**
+     * Get all tracked keys
+     */
     getAllKeys() {
         try {
             const store = nestjs_cls_1.ClsServiceManager.getClsService();

package/cache/providers/memory-cache.provider.d.ts

@@ -1,13 +1,41 @@
 import { BaseCacheProvider } from './base-cache.provider';
+/**
+ * Memory cache provider using native Map with TTL support
+ *
+ * This is the L2 cache layer - process-level caching.
+ * Data is stored in memory and shared across all requests in the same process.
+ *
+ * Faster than Redis but not shared across multiple processes/servers.
+ *
+ * **Automatic Cleanup**: Includes periodic cleanup of expired items to prevent memory leaks.
+ */
 export declare class MemoryCacheProvider extends BaseCacheProvider {
     private cache;
     private keys;
     private defaultTtl?;
     private namespace;
+    private cleanupTimer?;
+    /**
+     * Cleanup interval in milliseconds
+     * @default 300000 (5 minutes)
+     */
+    private readonly CLEANUP_INTERVAL;
     constructor(options?: {
         ttl?: number;
         namespace?: string;
     });
+    /**
+     * Start periodic cleanup of expired items
+     */
+    private startCleanupTimer;
+    /**
+     * Stop automatic cleanup timer
+     */
+    private stopCleanupTimer;
+    /**
+     * Destroy the provider and cleanup resources
+     */
+    destroy(): void;
     getName(): string;
     get<T>(key: string): Promise<T | null>;
     set<T>(key: string, value: T, ttl?: number): Promise<void>;
@@ -15,10 +43,25 @@ export declare class MemoryCacheProvider extends BaseCacheProvider {
     deletePattern(pattern: string): Promise<number>;
     clear(): Promise<void>;
     has(key: string): Promise<boolean>;
+    /**
+     * Get all keys (for debugging/testing)
+     */
     getAllKeys(): string[];
+    /**
+     * Get cache size
+     */
     getSize(): number;
+    /**
+     * Clean up expired items (optional maintenance method)
+     */
     cleanup(): number;
+    /**
+     * Optimized mget with batch cleanup
+     */
     mget<T>(keys: string[]): Promise<(T | null)[]>;
+    /**
+     * Optimized mset
+     */
     mset(items: Array<{
         key: string;
         value: any;

package/cache/providers/memory-cache.provider.js

@@ -11,13 +11,61 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MemoryCacheProvider = void 0;
 const base_cache_provider_1 = require("./base-cache.provider");
+/**
+ * Memory cache provider using native Map with TTL support
+ *
+ * This is the L2 cache layer - process-level caching.
+ * Data is stored in memory and shared across all requests in the same process.
+ *
+ * Faster than Redis but not shared across multiple processes/servers.
+ *
+ * **Automatic Cleanup**: Includes periodic cleanup of expired items to prevent memory leaks.
+ */
 class MemoryCacheProvider extends base_cache_provider_1.BaseCacheProvider {
     constructor(options) {
         super();
         this.cache = new Map();
         this.keys = new Set();
+        /**
+         * Cleanup interval in milliseconds
+         * @default 300000 (5 minutes)
+         */
+        this.CLEANUP_INTERVAL = 5 * 60 * 1000;
         this.defaultTtl = options === null || options === void 0 ? void 0 : options.ttl;
         this.namespace = (options === null || options === void 0 ? void 0 : options.namespace) || 'cache:memory';
+        // Start automatic cleanup timer
+        this.startCleanupTimer();
+    }
+    /**
+     * Start periodic cleanup of expired items
+     */
+    startCleanupTimer() {
+        this.cleanupTimer = setInterval(() => {
+            const cleaned = this.cleanup();
+            if (cleaned > 0) {
+                console.debug(`[MemoryCache] Cleaned up ${cleaned} expired items from namespace: ${this.namespace}`);
+            }
+        }, this.CLEANUP_INTERVAL);
+        // Allow Node.js to exit if this is the only active timer
+        if (this.cleanupTimer.unref) {
+            this.cleanupTimer.unref();
+        }
+    }
+    /**
+     * Stop automatic cleanup timer
+     */
+    stopCleanupTimer() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = undefined;
+        }
+    }
+    /**
+     * Destroy the provider and cleanup resources
+     */
+    destroy() {
+        this.stopCleanupTimer();
+        this.clear();
     }
     getName() {
         return 'Memory';
@@ -29,6 +77,7 @@ class MemoryCacheProvider extends base_cache_provider_1.BaseCacheProvider {
                 if (!item) {
                     return null;
                 }
+                // Check if item has expired
                 if (item.expiresAt && Date.now() > item.expiresAt) {
                     this.cache.delete(key);
                     this.keys.delete(key);
@@ -110,6 +159,7 @@ class MemoryCacheProvider extends base_cache_provider_1.BaseCacheProvider {
                 if (!item) {
                     return false;
                 }
+                // Check if item has expired
                 if (item.expiresAt && Date.now() > item.expiresAt) {
                     this.cache.delete(key);
                     this.keys.delete(key);
@@ -122,12 +172,21 @@ class MemoryCacheProvider extends base_cache_provider_1.BaseCacheProvider {
             }
         });
     }
+    /**
+     * Get all keys (for debugging/testing)
+     */
     getAllKeys() {
         return Array.from(this.keys);
     }
+    /**
+     * Get cache size
+     */
     getSize() {
         return this.keys.size;
     }
+    /**
+     * Clean up expired items (optional maintenance method)
+     */
     cleanup() {
         let cleaned = 0;
         const now = Date.now();
@@ -140,6 +199,9 @@ class MemoryCacheProvider extends base_cache_provider_1.BaseCacheProvider {
         }
         return cleaned;
     }
+    /**
+     * Optimized mget with batch cleanup
+     */
     mget(keys) {
         return __awaiter(this, void 0, void 0, function* () {
             const results = [];
@@ -150,6 +212,7 @@ class MemoryCacheProvider extends base_cache_provider_1.BaseCacheProvider {
                     results.push(null);
                     continue;
                 }
+                // Check if item has expired
                 if (item.expiresAt && now > item.expiresAt) {
                     this.cache.delete(key);
                     this.keys.delete(key);
@@ -161,6 +224,9 @@ class MemoryCacheProvider extends base_cache_provider_1.BaseCacheProvider {
             return results;
         });
     }
+    /**
+     * Optimized mset
+     */
     mset(items, ttl) {
         return __awaiter(this, void 0, void 0, function* () {
             const promises = items.map((item) => this.set(item.key, item.value, ttl));

package/cache/providers/redis-cache.provider.d.ts

@@ -1,6 +1,17 @@
 import type Redis from 'ioredis';
 import { BaseCacheProvider } from './base-cache.provider';
+/**
+ * Token for injecting Redis client
+ */
 export declare const REDIS_CLIENT: unique symbol;
+/**
+ * Redis cache provider using ioredis
+ *
+ * This is the L3 cache layer - distributed caching using Redis.
+ * Data is persisted in Redis and shared across all processes/servers.
+ *
+ * Slowest but most persistent and widely shared cache layer.
+ */
 export declare class RedisCacheProvider extends BaseCacheProvider {
     private readonly redis?;
     private readonly keyPrefix;
@@ -12,12 +23,27 @@ export declare class RedisCacheProvider extends BaseCacheProvider {
     deletePattern(pattern: string): Promise<number>;
     clear(): Promise<void>;
     has(key: string): Promise<boolean>;
+    /**
+     * Batch get using Redis MGET
+     */
     mget<T>(keys: string[]): Promise<(T | null)[]>;
+    /**
+     * Batch set using Redis pipeline
+     */
     mset(items: Array<{
         key: string;
         value: any;
     }>, ttl?: number): Promise<void>;
+    /**
+     * Check if Redis client is available
+     */
     isAvailable(): boolean;
+    /**
+     * Get Redis client (for advanced usage)
+     */
     getClient(): Redis | undefined;
+    /**
+     * Get full key with prefix
+     */
     private getFullKey;
 }

package/cache/providers/redis-cache.provider.js

@@ -24,7 +24,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RedisCacheProvider = exports.REDIS_CLIENT = void 0;
 const common_1 = require("@nestjs/common");
 const base_cache_provider_1 = require("./base-cache.provider");
+/**
+ * Token for injecting Redis client
+ */
 exports.REDIS_CLIENT = Symbol('REDIS_CLIENT');
+/**
+ * Redis cache provider using ioredis
+ *
+ * This is the L3 cache layer - distributed caching using Redis.
+ * Data is persisted in Redis and shared across all processes/servers.
+ *
+ * Slowest but most persistent and widely shared cache layer.
+ */
 let RedisCacheProvider = class RedisCacheProvider extends base_cache_provider_1.BaseCacheProvider {
     constructor(redis) {
         super();
@@ -65,6 +76,7 @@ let RedisCacheProvider = class RedisCacheProvider extends base_cache_provider_1.
                 const fullKey = this.getFullKey(key);
                 const serialized = JSON.stringify(value);
                 if (ttl && ttl > 0) {
+                    // TTL in milliseconds, Redis expects seconds
                     yield this.redis.setex(fullKey, Math.ceil(ttl / 1000), serialized);
                 }
                 else {
@@ -102,6 +114,7 @@ let RedisCacheProvider = class RedisCacheProvider extends base_cache_provider_1.
                 const fullPattern = this.getFullKey(pattern);
                 let cursor = '0';
                 let deletedCount = 0;
+                // Use SCAN to find matching keys (more efficient than KEYS)
                 do {
                     const [nextCursor, keys] = yield this.redis.scan(cursor, 'MATCH', fullPattern, 'COUNT', 100);
                     cursor = nextCursor;
@@ -124,6 +137,7 @@ let RedisCacheProvider = class RedisCacheProvider extends base_cache_provider_1.
                 return;
             }
             try {
+                // Clear all keys with our prefix
                 yield this.deletePattern('*');
             }
             catch (error) {
@@ -146,6 +160,9 @@ let RedisCacheProvider = class RedisCacheProvider extends base_cache_provider_1.
             }
         });
     }
+    /**
+     * Batch get using Redis MGET
+     */
     mget(keys) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.redis || keys.length === 0) {
@@ -172,6 +189,9 @@ let RedisCacheProvider = class RedisCacheProvider extends base_cache_provider_1.
             }
         });
     }
+    /**
+     * Batch set using Redis pipeline
+     */
     mset(items, ttl) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.redis || items.length === 0) {
@@ -196,12 +216,21 @@ let RedisCacheProvider = class RedisCacheProvider extends base_cache_provider_1.
             }
         });
     }
+    /**
+     * Check if Redis client is available
+     */
     isAvailable() {
         return !!this.redis && this.redis.status === 'ready';
     }
+    /**
+     * Get Redis client (for advanced usage)
+     */
     getClient() {
         return this.redis;
     }
+    /**
+     * Get full key with prefix
+     */
     getFullKey(key) {
         return `${this.keyPrefix}${key}`;
     }

package/cache/utils/dependency-manager.util.d.ts

@@ -1,15 +1,67 @@
 import type { CacheDependency, DependencyData } from '../interfaces';
+/**
+ * Wrapper for cached value with dependency data
+ */
 export interface CachedValueWithDependencies<T> {
     value: T;
     dependencies?: DependencyData[];
     cachedAt: number;
 }
+/**
+ * Utility class for managing cache dependencies
+ */
 export declare class DependencyManager {
+    /**
+     * Wrap a value with its dependencies
+     *
+     * @param value - The value to cache
+     * @param dependencies - Array of dependencies
+     * @returns Wrapped value with dependency data
+     */
     static wrapWithDependencies<T>(value: T, dependencies?: CacheDependency[]): Promise<CachedValueWithDependencies<T>>;
+    /**
+     * Capture current state of all dependencies
+     *
+     * @param dependencies - Array of dependencies
+     * @returns Array of dependency data snapshots
+     */
     static captureDependencies(dependencies: CacheDependency[]): Promise<DependencyData[]>;
+    /**
+     * Check if any dependencies have changed
+     *
+     * @param dependencies - Current dependencies
+     * @param cachedDependencies - Previously captured dependency data
+     * @returns true if any dependency has changed
+     */
     static areDependenciesChanged(dependencies: CacheDependency[], cachedDependencies?: DependencyData[]): Promise<boolean>;
+    /**
+     * Unwrap cached value and validate dependencies
+     *
+     * @param wrapped - Wrapped cached value
+     * @param dependencies - Current dependencies to check
+     * @returns Unwrapped value if valid, null if dependencies changed
+     */
     static unwrapAndValidate<T>(wrapped: CachedValueWithDependencies<T> | null, dependencies?: CacheDependency[]): Promise<T | null>;
+    /**
+     * Get which dependencies have changed
+     *
+     * @param dependencies - Current dependencies
+     * @param cachedDependencies - Previously captured dependency data
+     * @returns Array of changed dependency keys
+     */
     static getChangedDependencies(dependencies: CacheDependency[], cachedDependencies?: DependencyData[]): Promise<string[]>;
+    /**
+     * Serialize dependencies for storage
+     *
+     * @param dependencies - Dependency data
+     * @returns Serialized string
+     */
     static serializeDependencies(dependencies: DependencyData[]): string;
+    /**
+     * Deserialize dependencies from storage
+     *
+     * @param serialized - Serialized string
+     * @returns Dependency data array
+     */
     static deserializeDependencies(serialized: string): DependencyData[];
 }