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

package/cache/dependencies/db.dependency.js

@@ -10,35 +10,105 @@ 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
+ *
+ * This dependency monitors database query results. When the query result changes,
+ * the cache becomes invalid.
+ *
+ * Common use case: Monitor MAX(updated_at) or COUNT(*) to detect data changes.
+ *
+ * @example
+ * ```typescript
+ * // Invalidate cache when user data changes
+ * @Cacheable({
+ *   key: (id) => `user:${id}:profile`,
+ *   dependencies: [
+ *     new DbDependency(
+ *       'SELECT updated_at FROM users WHERE id = ?',
+ *       (id) => [id]
+ *     )
+ *   ]
+ * })
+ * async getUserProfile(id: string) { }
+ *
+ * // Invalidate when any user in tenant changes
+ * @Cacheable({
+ *   key: (tenantId) => `users:list:${tenantId}`,
+ *   dependencies: [
+ *     new DbDependency(
+ *       'SELECT MAX(updated_at) FROM users WHERE tenant_id = ?',
+ *       (tenantId) => [tenantId]
+ *     )
+ *   ]
+ * })
+ * 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');
         }
     }
-    static setDataSource(dataSource) {
-        this.dataSource = dataSource;
-    }
-    static getDataSource() {
-        return this.dataSource;
+    /**
+     * Get DataSource for executing queries
+     * Priority: 1. Specific dataSourceName from options, 2. Default from getDataSourceByName, 3. Fallback
+     */
+    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);
             }
             catch (error) {
@@ -53,19 +123,24 @@ class DbDependency {
                 return oldData !== currentData;
             }
             catch (_a) {
+                // If query fails, consider it changed to be safe
                 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);
     }
 }
 exports.DbDependency = DbDependency;
-DbDependency.dataSource = null;
+DbDependency.fallbackDataSource = null;
+DbDependency.defaultDataSourceName = 'default';

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

@@ -1,4 +1,33 @@
 import type { CacheDependency } from '../interfaces/cache-dependency.interface';
+/**
+ * File-based cache dependency
+ *
+ * This dependency monitors file modification time. When the file is modified,
+ * the cache becomes invalid.
+ *
+ * Useful for configuration files, templates, or other file-based resources.
+ *
+ * @example
+ * ```typescript
+ * // Cache template, invalidate when template file changes
+ * @Cacheable({
+ *   key: (name) => `template:${name}`,
+ *   dependencies: [
+ *     new FileDependency((name) => `./templates/${name}.html`)
+ *   ]
+ * })
+ * async getTemplate(name: string) { }
+ *
+ * // Cache config, invalidate when config file changes
+ * @Cacheable({
+ *   key: 'app:config',
+ *   dependencies: [
+ *     new FileDependency('./config/app.json')
+ *   ]
+ * })
+ * async getConfig() { }
+ * ```
+ */
 export declare class FileDependency implements CacheDependency {
     private readonly filePath;
     constructor(filePath: string | ((...args: any[]) => string));
@@ -13,5 +42,8 @@ export declare class FileDependency implements CacheDependency {
         mtime: number;
         size: number;
     } | null): Promise<boolean>;
+    /**
+     * Resolve the file path (handle dynamic paths)
+     */
     private resolveFilePath;
 }

package/cache/dependencies/file.dependency.js

@@ -11,6 +11,35 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileDependency = void 0;
 const node_fs_1 = require("node:fs");
+/**
+ * File-based cache dependency
+ *
+ * This dependency monitors file modification time. When the file is modified,
+ * the cache becomes invalid.
+ *
+ * Useful for configuration files, templates, or other file-based resources.
+ *
+ * @example
+ * ```typescript
+ * // Cache template, invalidate when template file changes
+ * @Cacheable({
+ *   key: (name) => `template:${name}`,
+ *   dependencies: [
+ *     new FileDependency((name) => `./templates/${name}.html`)
+ *   ]
+ * })
+ * async getTemplate(name: string) { }
+ *
+ * // Cache config, invalidate when config file changes
+ * @Cacheable({
+ *   key: 'app:config',
+ *   dependencies: [
+ *     new FileDependency('./config/app.json')
+ *   ]
+ * })
+ * async getConfig() { }
+ * ```
+ */
 class FileDependency {
     constructor(filePath) {
         if (!filePath) {
@@ -42,15 +71,20 @@ class FileDependency {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 const currentData = yield this.getData();
+                // File path changed or mtime changed or size changed
                 return (currentData.path !== oldData.path ||
                     currentData.mtime !== oldData.mtime ||
                     currentData.size !== oldData.size);
             }
             catch (_a) {
+                // If we can't access file, consider it changed
                 return true;
             }
         });
     }
+    /**
+     * Resolve the file path (handle dynamic paths)
+     */
     resolveFilePath() {
         return __awaiter(this, void 0, void 0, function* () {
             if (typeof this.filePath === 'function') {

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

@@ -1,14 +1,85 @@
 import type { CacheDependency } from '../interfaces/cache-dependency.interface';
+import type Redis from 'ioredis';
+/**
+ * Tag-based cache dependency
+ *
+ * This dependency allows you to invalidate multiple cache entries by tags.
+ * When a tag is invalidated, all cache entries depending on that tag become invalid.
+ *
+ * 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
+ * @Cacheable({
+ *   key: (tenantId) => `users:list:${tenantId}`,
+ *   dependencies: [new TagDependency(['user-list', `tenant:${tenantId}`])]
+ * })
+ * async getUserList(tenantId: string) { }
+ *
+ * // When creating a new user, invalidate the tag
+ * await cacheService.invalidateTags(['user-list']);
+ * ```
+ */
 export declare class TagDependency implements CacheDependency {
     private readonly tags;
     private static readonly PREFIX;
+    private static readonly REDIS_KEY_PREFIX;
     private static tagVersions;
+    private static redis;
     constructor(tags: string[]);
-    static getTagVersion(tag: string): number;
-    static invalidateTag(tag: string): void;
-    static invalidateTags(tags: string[]): void;
-    static resetAllTags(): void;
+    /**
+     * 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): 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): Promise<void>;
+    /**
+     * Invalidate multiple tags
+     *
+     * @param tags - Array of tag names to invalidate
+     */
+    static invalidateTags(tags: string[]): Promise<void>;
+    /**
+     * Reset all tag versions (useful for testing)
+     * Clears both Redis and in-memory storage
+     */
+    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>;
+    /**
+     * Get tag version (synchronous version for backward compatibility)
+     * Only reads from in-memory storage
+     *
+     * @deprecated Use getTagVersion(tag) instead for distributed support
+     * @param tag - Tag name
+     * @returns Current tag version from memory
+     */
+    static getTagVersionSync(tag: string): number;
     getKey(): string;
     getData(): Promise<Record<string, number>>;
     isChanged(oldData: Record<string, number>): Promise<boolean>;

package/cache/dependencies/tag.dependency.js

@@ -10,6 +10,30 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TagDependency = void 0;
+/**
+ * Tag-based cache dependency
+ *
+ * This dependency allows you to invalidate multiple cache entries by tags.
+ * When a tag is invalidated, all cache entries depending on that tag become invalid.
+ *
+ * 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
+ * @Cacheable({
+ *   key: (tenantId) => `users:list:${tenantId}`,
+ *   dependencies: [new TagDependency(['user-list', `tenant:${tenantId}`])]
+ * })
+ * async getUserList(tenantId: string) { }
+ *
+ * // When creating a new user, invalidate the tag
+ * await cacheService.invalidateTags(['user-list']);
+ * ```
+ */
 class TagDependency {
     constructor(tags) {
         this.tags = tags;
@@ -17,23 +41,129 @@ 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
+                    console.warn(`[TagDependency] 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) {
+                    console.error(`[TagDependency] 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) {
+                    console.error(`[TagDependency] 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);
+    }
+    /**
+     * Get tag version (synchronous version for backward compatibility)
+     * Only reads from in-memory storage
+     *
+     * @deprecated Use getTagVersion(tag) instead for distributed support
+     * @param tag - Tag name
+     * @returns Current tag version from memory
+     */
+    static getTagVersionSync(tag) {
+        return TagDependency.tagVersions.get(tag) || 0;
     }
     getKey() {
         return `tag:${this.tags.sort().join(',')}`;
@@ -42,7 +172,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;
         });
@@ -53,7 +183,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;
@@ -65,11 +195,15 @@ 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';
+// 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/dependencies/time.dependency.d.ts

@@ -1,4 +1,38 @@
 import type { CacheDependency } from '../interfaces/cache-dependency.interface';
+/**
+ * Time-based cache dependency
+ *
+ * This dependency invalidates cache after a specific duration.
+ * Unlike TTL which is checked on read, this is checked as a dependency.
+ *
+ * Useful for implementing complex time-based invalidation logic.
+ *
+ * @example
+ * ```typescript
+ * // Cache for 5 minutes
+ * @Cacheable({
+ *   key: 'daily:report',
+ *   dependencies: [
+ *     new TimeDependency(5 * 60 * 1000) // 5 minutes
+ *   ]
+ * })
+ * async getDailyReport() { }
+ *
+ * // Cache until midnight
+ * @Cacheable({
+ *   key: 'today:stats',
+ *   dependencies: [
+ *     new TimeDependency(() => {
+ *       const now = new Date();
+ *       const midnight = new Date(now);
+ *       midnight.setHours(24, 0, 0, 0);
+ *       return midnight.getTime() - now.getTime();
+ *     })
+ *   ]
+ * })
+ * async getTodayStats() { }
+ * ```
+ */
 export declare class TimeDependency implements CacheDependency {
     private readonly duration;
     private createdAt;
@@ -13,7 +47,16 @@ export declare class TimeDependency implements CacheDependency {
         duration: number;
     }): Promise<boolean>;
     reset(): Promise<void>;
+    /**
+     * Get remaining time in milliseconds
+     */
     getRemainingTime(): number;
+    /**
+     * Check if dependency has expired
+     */
     isExpired(): boolean;
+    /**
+     * Resolve duration value (handle dynamic duration)
+     */
     private resolveDuration;
 }

package/cache/dependencies/time.dependency.js

@@ -10,6 +10,40 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TimeDependency = void 0;
+/**
+ * Time-based cache dependency
+ *
+ * This dependency invalidates cache after a specific duration.
+ * Unlike TTL which is checked on read, this is checked as a dependency.
+ *
+ * Useful for implementing complex time-based invalidation logic.
+ *
+ * @example
+ * ```typescript
+ * // Cache for 5 minutes
+ * @Cacheable({
+ *   key: 'daily:report',
+ *   dependencies: [
+ *     new TimeDependency(5 * 60 * 1000) // 5 minutes
+ *   ]
+ * })
+ * async getDailyReport() { }
+ *
+ * // Cache until midnight
+ * @Cacheable({
+ *   key: 'today:stats',
+ *   dependencies: [
+ *     new TimeDependency(() => {
+ *       const now = new Date();
+ *       const midnight = new Date(now);
+ *       midnight.setHours(24, 0, 0, 0);
+ *       return midnight.getTime() - now.getTime();
+ *     })
+ *   ]
+ * })
+ * async getTodayStats() { }
+ * ```
+ */
 class TimeDependency {
     constructor(duration) {
         if (typeof duration !== 'number' && typeof duration !== 'function') {
@@ -48,15 +82,24 @@ class TimeDependency {
             this.createdAt = Date.now();
         });
     }
+    /**
+     * Get remaining time in milliseconds
+     */
     getRemainingTime() {
         const duration = this.resolveDuration();
         const elapsed = Date.now() - this.createdAt;
         const remaining = duration - elapsed;
         return Math.max(0, remaining);
     }
+    /**
+     * Check if dependency has expired
+     */
     isExpired() {
         return this.getRemainingTime() === 0;
     }
+    /**
+     * Resolve duration value (handle dynamic duration)
+     */
     resolveDuration() {
         if (typeof this.duration === 'function') {
             const value = this.duration();

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