@nest-omni/core 4.1.3-3 → 4.1.3-30

package/cache/cache.service.d.ts

@@ -1,25 +1,27 @@
 import type { CacheOptions, CacheStats } from './interfaces';
 import { CacheLayer } from './interfaces';
-import { ClsCacheProvider, MemoryCacheProvider, RedisCacheProvider } from './providers';
+import { ClsCacheProvider, LRUCacheProvider, RedisCacheProvider } from './providers';
+import { CacheSerializationService } from './cache-serialization.service';
 /**
  * Unified cache service with three-tier architecture
  *
  * L1: CLS (request-level)
- * L2: Memory (process-level)
+ * L2: LRU (process-level with automatic eviction)
  * L3: Redis (distributed)
  *
  * Supports automatic fallback, backfill, and dependency-based invalidation.
  */
 export declare class CacheService {
     private readonly clsProvider;
-    private readonly memoryProvider;
+    private readonly lruProvider;
     private readonly redisProvider;
     private readonly enableCompression;
     private readonly compressionThreshold;
+    private readonly serializationService;
     private readonly logger;
     private readonly providers;
     private readonly stats;
-    constructor(clsProvider: ClsCacheProvider, memoryProvider: MemoryCacheProvider, redisProvider: RedisCacheProvider, enableCompression?: boolean, compressionThreshold?: number);
+    constructor(clsProvider: ClsCacheProvider, lruProvider: LRUCacheProvider, redisProvider: RedisCacheProvider, enableCompression?: boolean, compressionThreshold?: number, serializationService?: CacheSerializationService);
     /**
      * Get or set cache value with factory function
      *

package/cache/cache.service.js

@@ -34,18 +34,19 @@ const cache_constants_1 = require("./cache.constants");
  * Unified cache service with three-tier architecture
  *
  * L1: CLS (request-level)
- * L2: Memory (process-level)
+ * L2: LRU (process-level with automatic eviction)
  * 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) {
+    constructor(clsProvider, lruProvider, redisProvider, enableCompression = false, compressionThreshold = 1024, serializationService = new cache_serialization_service_1.CacheSerializationService()) {
         this.clsProvider = clsProvider;
-        this.memoryProvider = memoryProvider;
+        this.lruProvider = lruProvider;
         this.redisProvider = redisProvider;
         this.enableCompression = enableCompression;
         this.compressionThreshold = compressionThreshold;
+        this.serializationService = serializationService;
         this.logger = new common_1.Logger(CacheService_1.name);
         this.providers = new Map();
         this.stats = {
@@ -59,7 +60,7 @@ let CacheService = CacheService_1 = class CacheService {
             totalClears: 0,
         };
         this.providers.set(interfaces_1.CacheLayer.CLS, clsProvider);
-        this.providers.set(interfaces_1.CacheLayer.MEMORY, memoryProvider);
+        this.providers.set(interfaces_1.CacheLayer.MEMORY, lruProvider);
         this.providers.set(interfaces_1.CacheLayer.REDIS, redisProvider);
         this.initializeStats();
     }
@@ -125,8 +126,7 @@ let CacheService = CacheService_1 = class CacheService {
                         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);
+                                const decompressed = yield this.serializationService.deserialize(value);
                                 value = decompressed.data;
                             }
                             // Cache hit
@@ -206,14 +206,14 @@ let CacheService = CacheService_1 = class CacheService {
         return __awaiter(this, void 0, void 0, function* () {
             this.stats.totalDeletes++;
             const targetLayers = layers || this.getDefaultLayers();
-            const keys = Array.isArray(key) ? key : [key];
             const promises = targetLayers.map((layer) => __awaiter(this, void 0, void 0, function* () {
                 const provider = this.providers.get(layer);
                 if (!provider) {
                     return;
                 }
                 try {
-                    yield provider.delete(keys);
+                    // Pass the key directly (string or array) to the provider
+                    yield provider.delete(key);
                 }
                 catch (error) {
                     this.logger.warn(`Failed to delete from ${layer} cache: ${error instanceof Error ? error.message : String(error)}`);
@@ -333,6 +333,18 @@ let CacheService = CacheService_1 = class CacheService {
     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;
@@ -345,8 +357,7 @@ let CacheService = CacheService_1 = class CacheService {
                 value !== null &&
                 value !== undefined &&
                 JSON.stringify(value).length >= this.compressionThreshold) {
-                const serializationService = new cache_serialization_service_1.CacheSerializationService();
-                const compressed = yield serializationService.serialize(value, {
+                const compressed = yield this.serializationService.serialize(value, {
                     compress: true,
                     compressThreshold: this.compressionThreshold,
                 });
@@ -459,7 +470,8 @@ exports.CacheService = CacheService = CacheService_1 = __decorate([
     __param(3, (0, common_1.Inject)(cache_constants_1.CACHE_COMPRESSION_ENABLED)),
     __param(4, (0, common_1.Optional)()),
     __param(4, (0, common_1.Inject)(cache_constants_1.CACHE_COMPRESSION_THRESHOLD)),
+    __param(5, (0, common_1.Optional)()),
     __metadata("design:paramtypes", [providers_1.ClsCacheProvider,
-        providers_1.MemoryCacheProvider,
-        providers_1.RedisCacheProvider, Boolean, Number])
+        providers_1.LRUCacheProvider,
+        providers_1.RedisCacheProvider, Boolean, Number, cache_serialization_service_1.CacheSerializationService])
 ], CacheService);

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

@@ -71,13 +71,14 @@ function CachePut(options = {}) {
                     }
                     // Generate cache key
                     const key = utils_1.KeyGenerator.generate(options, args);
-                    // Update cache with result
-                    yield cacheService.set(key, result, options);
+                    // Update cache with result - don't await, let it happen in background
+                    cacheService.set(key, result, options).catch((error) => {
+                        logger.warn(`Failed to update cache for ${target.constructor.name}.${methodName}: ${error instanceof Error ? error.message : String(error)}`);
+                    });
                     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)
+                    // Method execution error - rethrow it
                     throw error;
                 }
             });

package/cache/dependencies/callback.dependency.js

@@ -65,6 +65,11 @@ class CallbackDependency {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 const currentData = yield this.getData();
+                // If oldData is null or undefined, consider it as changed
+                // (no previous valid data exists)
+                if (oldData === null || oldData === undefined) {
+                    return true;
+                }
                 return !this.isEqual(oldData, currentData);
             }
             catch (_a) {
@@ -86,6 +91,10 @@ class CallbackDependency {
         if (typeof a !== typeof b) {
             return false;
         }
+        // Handle Date objects
+        if (a instanceof Date && b instanceof Date) {
+            return a.getTime() === b.getTime();
+        }
         if (typeof a !== 'object') {
             return a === b;
         }

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

@@ -1,5 +1,19 @@
-import { DataSource } from 'typeorm';
-import type { CacheDependency } from '../interfaces/cache-dependency.interface';
+import type { CacheDependency } from '../interfaces';
+/**
+ * Options for DbDependency
+ */
+export interface DbDependencyOptions {
+    /**
+     * Name for this dependency (used in cache key generation)
+     * Default: 'db'
+     */
+    name?: string;
+    /**
+     * Data source name to use for querying
+     * If not specified, uses the default data source
+     */
+    dataSourceName?: string;
+}
 /**
  * Database-based cache dependency
  *
@@ -33,23 +47,40 @@ import type { CacheDependency } from '../interfaces/cache-dependency.interface';
  *   ]
  * })
  * async getUserList(tenantId: string) { }
+ *
+ * // Use specific data source
+ * @Cacheable({
+ *   key: (id) => `product:${id}:details`,
+ *   dependencies: [
+ *     new DbDependency(
+ *       'SELECT updated_at FROM products WHERE id = ?',
+ *       (id) => [id],
+ *       { dataSourceName: 'readReplicas' }
+ *     )
+ *   ]
+ * })
+ * async getProductDetails(id: string) { }
+ *
+ * // With custom name and data source
+ * new DbDependency(
+ *   'SELECT COUNT(*) FROM events',
+ *   [],
+ *   { name: 'eventCount', dataSourceName: 'analytics' }
+ * )
  * ```
  */
 export declare class DbDependency implements CacheDependency {
     private readonly sql;
     private readonly paramsFactory?;
-    private readonly name?;
-    private static dataSource;
-    constructor(sql: string, paramsFactory?: (...args: any[]) => any[], name?: string);
-    /**
-     * Set the TypeORM DataSource for database queries
-     * This should be called once during application initialization
-     */
-    static setDataSource(dataSource: DataSource): void;
+    private readonly options?;
+    private static fallbackDataSource;
+    private static defaultDataSourceName;
+    constructor(sql: string, paramsFactory?: (...args: any[]) => any[], options?: DbDependencyOptions);
     /**
-     * Get the current DataSource
+     * Get DataSource for executing queries
+     * Priority: 1. Specific dataSourceName from options, 2. Default from getDataSourceByName, 3. Fallback
      */
-    static getDataSource(): DataSource | null;
+    private getDataSource;
     getKey(): string;
     getData(): Promise<any>;
     isChanged(oldData: any): Promise<boolean>;

package/cache/dependencies/db.dependency.js

@@ -10,6 +10,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DbDependency = void 0;
+const transaction_1 = require("@nest-omni/transaction");
 /**
  * Database-based cache dependency
  *
@@ -43,44 +44,70 @@ exports.DbDependency = void 0;
  *   ]
  * })
  * async getUserList(tenantId: string) { }
+ *
+ * // Use specific data source
+ * @Cacheable({
+ *   key: (id) => `product:${id}:details`,
+ *   dependencies: [
+ *     new DbDependency(
+ *       'SELECT updated_at FROM products WHERE id = ?',
+ *       (id) => [id],
+ *       { dataSourceName: 'readReplicas' }
+ *     )
+ *   ]
+ * })
+ * async getProductDetails(id: string) { }
+ *
+ * // With custom name and data source
+ * new DbDependency(
+ *   'SELECT COUNT(*) FROM events',
+ *   [],
+ *   { name: 'eventCount', dataSourceName: 'analytics' }
+ * )
  * ```
  */
 class DbDependency {
-    constructor(sql, paramsFactory, name) {
+    constructor(sql, paramsFactory, options) {
         this.sql = sql;
         this.paramsFactory = paramsFactory;
-        this.name = name;
+        this.options = options;
         if (!sql || typeof sql !== 'string') {
             throw new Error('DbDependency requires a valid SQL query');
         }
     }
     /**
-     * Set the TypeORM DataSource for database queries
-     * This should be called once during application initialization
-     */
-    static setDataSource(dataSource) {
-        this.dataSource = dataSource;
-    }
-    /**
-     * Get the current DataSource
+     * Get DataSource for executing queries
+     * Priority: 1. Specific dataSourceName from options, 2. Default from getDataSourceByName, 3. Fallback
      */
-    static getDataSource() {
-        return this.dataSource;
+    getDataSource() {
+        var _a;
+        // Try to get from getDataSourceByName first
+        const dsName = ((_a = this.options) === null || _a === void 0 ? void 0 : _a.dataSourceName) || DbDependency.defaultDataSourceName;
+        const dataSource = (0, transaction_1.getDataSource)(dsName);
+        if (dataSource) {
+            return dataSource;
+        }
+        // Fallback to static dataSource for backward compatibility
+        if (DbDependency.fallbackDataSource) {
+            return DbDependency.fallbackDataSource;
+        }
+        throw new Error(`DbDependency requires DataSource '${dsName}' to be registered. ` +
+            `Use DataSourceUtil.registerDataSource('${dsName}', dataSource) ` +
+            `or DbDependency.setDataSource(dataSource) for fallback.`);
     }
     getKey() {
+        var _a;
         const queryHash = this.hashCode(this.sql);
-        const name = this.name || 'db';
+        const name = ((_a = this.options) === null || _a === void 0 ? void 0 : _a.name) || 'db';
         return `db:${name}:${queryHash}`;
     }
     getData() {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
-            if (!DbDependency.dataSource) {
-                throw new Error('DbDependency requires DataSource to be set. Call DbDependency.setDataSource(dataSource) during app initialization.');
-            }
             try {
+                const dataSource = this.getDataSource();
                 const params = ((_a = this.paramsFactory) === null || _a === void 0 ? void 0 : _a.call(this)) || [];
-                const result = yield DbDependency.dataSource.query(this.sql, params);
+                const result = yield dataSource.query(this.sql, params);
                 // Serialize result for comparison
                 return JSON.stringify(result);
             }
@@ -115,4 +142,5 @@ class DbDependency {
     }
 }
 exports.DbDependency = DbDependency;
-DbDependency.dataSource = null;
+DbDependency.fallbackDataSource = null;
+DbDependency.defaultDataSourceName = 'default';

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

@@ -1,4 +1,5 @@
 import type { CacheDependency } from '../interfaces/cache-dependency.interface';
+import type Redis from 'ioredis';
 /**
  * Tag-based cache dependency
  *
@@ -7,6 +8,9 @@ import type { CacheDependency } from '../interfaces/cache-dependency.interface';
  *
  * This is the most commonly used dependency type for managing related cache entries.
  *
+ * **Distributed Support**: Tag versions are stored in Redis for multi-instance deployments.
+ * Falls back to in-memory storage if Redis is not available.
+ *
  * @example
  * ```typescript
  * // Cache user list with tag dependency
@@ -23,26 +27,49 @@ import type { CacheDependency } from '../interfaces/cache-dependency.interface';
 export declare class TagDependency implements CacheDependency {
     private readonly tags;
     private static readonly PREFIX;
+    private static readonly REDIS_KEY_PREFIX;
+    private static readonly logger;
     private static tagVersions;
+    private static redis;
     constructor(tags: string[]);
+    /**
+     * Set Redis client for distributed tag version storage
+     * Called by CacheModule during initialization
+     *
+     * @param redis - Redis client instance
+     */
+    static setRedisClient(redis: Redis): void;
     /**
      * Get current version of a tag
+     * Prioritizes Redis, falls back to in-memory storage
+     *
+     * @param tag - Tag name
+     * @returns Current tag version
      */
-    static getTagVersion(tag: string): number;
+    static getTagVersion(tag: string): Promise<number>;
     /**
      * Invalidate a tag (increment its version)
+     * Updates both Redis and in-memory storage
+     *
+     * @param tag - Tag name to invalidate
      */
-    static invalidateTag(tag: string): void;
+    static invalidateTag(tag: string): Promise<void>;
     /**
      * Invalidate multiple tags
+     *
+     * @param tags - Array of tag names to invalidate
      */
-    static invalidateTags(tags: string[]): void;
+    static invalidateTags(tags: string[]): Promise<void>;
     /**
      * Reset all tag versions (useful for testing)
+     * Clears both Redis and in-memory storage
      */
-    static resetAllTags(): void;
+    static resetAllTags(): Promise<void>;
     /**
      * Get all tags and their versions
+     * Note: This only returns in-memory tags for backward compatibility
+     *
+     * @returns Map of tag names to versions
      */
     static getAllTags(): Map<string, number>;
     getKey(): string;

package/cache/dependencies/tag.dependency.js

@@ -10,6 +10,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TagDependency = void 0;
+const common_1 = require("@nestjs/common");
 /**
  * Tag-based cache dependency
  *
@@ -18,6 +19,9 @@ exports.TagDependency = void 0;
  *
  * This is the most commonly used dependency type for managing related cache entries.
  *
+ * **Distributed Support**: Tag versions are stored in Redis for multi-instance deployments.
+ * Falls back to in-memory storage if Redis is not available.
+ *
  * @example
  * ```typescript
  * // Cache user list with tag dependency
@@ -38,38 +42,118 @@ class TagDependency {
             throw new Error('TagDependency requires at least one tag');
         }
     }
+    /**
+     * Set Redis client for distributed tag version storage
+     * Called by CacheModule during initialization
+     *
+     * @param redis - Redis client instance
+     */
+    static setRedisClient(redis) {
+        TagDependency.redis = redis;
+    }
     /**
      * Get current version of a tag
+     * Prioritizes Redis, falls back to in-memory storage
+     *
+     * @param tag - Tag name
+     * @returns Current tag version
      */
     static getTagVersion(tag) {
-        return this.tagVersions.get(tag) || 0;
+        return __awaiter(this, void 0, void 0, function* () {
+            // Try to get from Redis first
+            if (TagDependency.redis) {
+                try {
+                    const key = `${TagDependency.REDIS_KEY_PREFIX}:${tag}`;
+                    const result = yield TagDependency.redis.get(key);
+                    if (result !== null) {
+                        const version = parseInt(result, 10);
+                        // Cache in memory for faster access
+                        TagDependency.tagVersions.set(tag, version);
+                        return version;
+                    }
+                }
+                catch (error) {
+                    // Log warning but don't throw - fall back to memory
+                    TagDependency.logger.warn(`Failed to get tag version from Redis: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            // Fall back to in-memory storage
+            return TagDependency.tagVersions.get(tag) || 0;
+        });
     }
     /**
      * Invalidate a tag (increment its version)
+     * Updates both Redis and in-memory storage
+     *
+     * @param tag - Tag name to invalidate
      */
     static invalidateTag(tag) {
-        const currentVersion = this.tagVersions.get(tag) || 0;
-        this.tagVersions.set(tag, currentVersion + 1);
+        return __awaiter(this, void 0, void 0, function* () {
+            const currentVersion = TagDependency.tagVersions.get(tag) || 0;
+            const newVersion = currentVersion + 1;
+            // Update in-memory storage
+            TagDependency.tagVersions.set(tag, newVersion);
+            // Update Redis if available
+            if (TagDependency.redis) {
+                try {
+                    const key = `${TagDependency.REDIS_KEY_PREFIX}:${tag}`;
+                    yield TagDependency.redis.set(key, newVersion.toString());
+                }
+                catch (error) {
+                    TagDependency.logger.error(`Failed to invalidate tag in Redis: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        });
     }
     /**
      * Invalidate multiple tags
+     *
+     * @param tags - Array of tag names to invalidate
      */
     static invalidateTags(tags) {
-        for (const tag of tags) {
-            this.invalidateTag(tag);
-        }
+        return __awaiter(this, void 0, void 0, function* () {
+            yield Promise.all(tags.map((tag) => TagDependency.invalidateTag(tag)));
+        });
     }
     /**
      * Reset all tag versions (useful for testing)
+     * Clears both Redis and in-memory storage
      */
     static resetAllTags() {
-        this.tagVersions.clear();
+        return __awaiter(this, void 0, void 0, function* () {
+            // Clear in-memory storage
+            TagDependency.tagVersions.clear();
+            // Clear Redis storage
+            if (TagDependency.redis) {
+                try {
+                    let cursor = '0';
+                    const pattern = `${TagDependency.REDIS_KEY_PREFIX}:*`;
+                    const keysToDelete = [];
+                    // Use SCAN to find all tag version keys
+                    do {
+                        const [nextCursor, keys] = yield TagDependency.redis.scan(cursor, 'MATCH', pattern, 'COUNT', 100);
+                        cursor = nextCursor;
+                        keysToDelete.push(...keys);
+                    } while (cursor !== '0');
+                    // Delete all found keys
+                    if (keysToDelete.length > 0) {
+                        yield TagDependency.redis.del(...keysToDelete);
+                    }
+                }
+                catch (error) {
+                    TagDependency.logger.error(`Failed to reset tags in Redis: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        });
     }
     /**
      * Get all tags and their versions
+     * Note: This only returns in-memory tags for backward compatibility
+     *
+     * @returns Map of tag names to versions
      */
     static getAllTags() {
-        return new Map(this.tagVersions);
+        return new Map(TagDependency.tagVersions);
     }
     getKey() {
         return `tag:${this.tags.sort().join(',')}`;
@@ -78,7 +162,7 @@ class TagDependency {
         return __awaiter(this, void 0, void 0, function* () {
             const data = {};
             for (const tag of this.tags) {
-                data[tag] = TagDependency.getTagVersion(tag);
+                data[tag] = yield TagDependency.getTagVersion(tag);
             }
             return data;
         });
@@ -89,7 +173,7 @@ class TagDependency {
                 return true;
             }
             for (const tag of this.tags) {
-                const currentVersion = TagDependency.getTagVersion(tag);
+                const currentVersion = yield TagDependency.getTagVersion(tag);
                 const oldVersion = oldData[tag];
                 if (currentVersion !== oldVersion) {
                     return true;
@@ -101,11 +185,16 @@ class TagDependency {
     reset() {
         return __awaiter(this, void 0, void 0, function* () {
             for (const tag of this.tags) {
-                TagDependency.invalidateTag(tag);
+                yield TagDependency.invalidateTag(tag);
             }
         });
     }
 }
 exports.TagDependency = TagDependency;
 TagDependency.PREFIX = 'cache:tag:';
+TagDependency.REDIS_KEY_PREFIX = 'cache:tag:versions';
+TagDependency.logger = new common_1.Logger(TagDependency.name);
+// In-memory fallback for when Redis is not available
 TagDependency.tagVersions = new Map();
+// Redis client for distributed tag version storage
+TagDependency.redis = null;

package/cache/entities/index.d.ts

@@ -0,0 +1 @@
+export * from './typeorm-cache.entity';

package/cache/entities/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./typeorm-cache.entity"), exports);