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

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

@@ -0,0 +1,483 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypeormCacheProvider = void 0;
+const common_1 = require("@nestjs/common");
+const typeorm_1 = require("typeorm");
+const base_cache_provider_1 = require("./base-cache.provider");
+const entities_1 = require("../entities");
+/**
+ * TypeORM Cache Provider
+ *
+ * Database-backed cache provider using TypeORM for persistent caching.
+ * This is an L3 cache layer that provides:
+ * - Persistent cache storage in database
+ * - Cross-instance cache sharing
+ * - Automatic expiration handling
+ * - Namespace isolation
+ *
+ * Unlike in-memory caches, this provider survives application restarts
+ * and can be shared across multiple application instances.
+ *
+ * @example
+ * ```typescript
+ * // In your module:
+ * @Module({
+ *   providers: [
+ *     {
+ *       provide: 'TYPEORM_CACHE',
+ *       useFactory: (dataSource: DataSource) => {
+ *         return new TypeormCacheProvider({
+ *           duration: 60000,
+ *           namespace: 'app:cache',
+ *           dataSourceName: 'default',
+ *         });
+ *       },
+ *       inject: [DataSource],
+ *     },
+ *   ],
+ * })
+ * export class AppModule {}
+ *
+ * // In your service:
+ * @Injectable()
+ * export class UserService {
+ *   constructor(@Inject('TYPEORM_CACHE') private cache: TypeormCacheProvider) {}
+ *
+ *   async getUser(id: string) {
+ *     // Try cache first
+ *     const cached = await this.cache.get(`user:${id}`);
+ *     if (cached) return cached;
+ *
+ *     // Cache miss - fetch from database
+ *     const user = await this.userRepository.findOne(id);
+ *
+ *     // Store in cache
+ *     await this.cache.set(`user:${id}`, user, 60000);
+ *
+ *     return user;
+ *   }
+ * }
+ * ```
+ *
+ * @see https://typeorm.io/#caching
+ */
+let TypeormCacheProvider = class TypeormCacheProvider extends base_cache_provider_1.BaseCacheProvider {
+    constructor(injectedDataSource, options) {
+        super();
+        this.injectedDataSource = injectedDataSource;
+        const { duration = 60000, enabled = true, dataSourceName = 'default', namespace = 'cache', autoCleanup = true, cleanupInterval = 300000, // 5 minutes
+         } = options || {};
+        this.defaultDuration = duration;
+        this.enabled = enabled;
+        this.namespace = namespace;
+        this.dataSourceName = dataSourceName;
+        this.autoCleanup = autoCleanup;
+        this.cleanupInterval = cleanupInterval;
+        if (this.injectedDataSource) {
+            this.dataSource = this.injectedDataSource;
+        }
+    }
+    /**
+     * Get DataSource for cache operations
+     * Uses @nest-omni/transaction's getDataSource utility
+     */
+    getDataSource() {
+        if (this.dataSource) {
+            return this.dataSource;
+        }
+        try {
+            // Try to use getDataSource from @nest-omni/transaction
+            const { getDataSource } = require('@nest-omni/transaction');
+            this.dataSource = getDataSource(this.dataSourceName);
+            if (!this.dataSource) {
+                throw new Error(`DataSource '${this.dataSourceName}' not found`);
+            }
+            return this.dataSource;
+        }
+        catch (error) {
+            throw new Error(`TypeormCacheProvider requires DataSource '${this.dataSourceName}' to be registered. ` +
+                `Use DataSourceUtil.registerDataSource('${this.dataSourceName}', dataSource) or inject it directly.`);
+        }
+    }
+    /**
+     * Get repository for cache operations
+     */
+    getRepository() {
+        const dataSource = this.getDataSource();
+        return dataSource.getRepository(entities_1.TypeormCacheEntity);
+    }
+    getName() {
+        return 'TypeORM';
+    }
+    /**
+     * Get cached value by key
+     */
+    get(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.enabled)
+                return null;
+            try {
+                const repository = this.getRepository();
+                const fullKey = this.getFullKey(key);
+                const cacheEntry = yield repository.findOne({
+                    where: { key: fullKey, namespace: this.namespace },
+                });
+                if (!cacheEntry) {
+                    return null;
+                }
+                // Check if expired
+                if (cacheEntry.isExpired()) {
+                    // Clean up expired entry
+                    yield repository.remove(cacheEntry);
+                    return null;
+                }
+                // Parse and return cached value
+                return JSON.parse(cacheEntry.value);
+            }
+            catch (error) {
+                console.error(`TypeormCacheProvider.get() failed for key '${key}':`, error);
+                return null;
+            }
+        });
+    }
+    /**
+     * Set cache value with optional TTL
+     */
+    set(key, value, ttl) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.enabled)
+                return;
+            try {
+                const repository = this.getRepository();
+                const fullKey = this.getFullKey(key);
+                const duration = ttl || this.defaultDuration;
+                const expiresAt = duration > 0 ? new Date(Date.now() + duration) : null;
+                // Check if entry already exists
+                const existing = yield repository.findOne({
+                    where: { key: fullKey, namespace: this.namespace },
+                });
+                if (existing) {
+                    // Update existing entry
+                    existing.updateValue(JSON.stringify(value), duration);
+                    yield repository.save(existing);
+                }
+                else {
+                    // Create new entry
+                    const cacheEntry = repository.create({
+                        key: fullKey,
+                        namespace: this.namespace,
+                        value: JSON.stringify(value),
+                        expires_at: expiresAt,
+                        ttl: duration > 0 ? Math.floor(duration / 1000) : null,
+                    });
+                    yield repository.save(cacheEntry);
+                }
+            }
+            catch (error) {
+                console.error(`TypeormCacheProvider.set() failed for key '${key}':`, error);
+            }
+        });
+    }
+    /**
+     * Delete cache entry by key
+     */
+    delete(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.enabled)
+                return;
+            try {
+                const repository = this.getRepository();
+                const keys = Array.isArray(key) ? key : [key];
+                const fullKeys = keys.map((k) => this.getFullKey(k));
+                yield repository.delete({
+                    key: (0, typeorm_1.In)(fullKeys),
+                    namespace: this.namespace,
+                });
+            }
+            catch (error) {
+                console.error('TypeormCacheProvider.delete() failed:', error);
+            }
+        });
+    }
+    /**
+     * Delete cache entries matching a pattern
+     * Uses SQL LIKE for pattern matching
+     */
+    deletePattern(pattern) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.enabled)
+                return 0;
+            try {
+                const repository = this.getRepository();
+                const fullPattern = this.getFullKey(pattern);
+                // Use LIKE for pattern matching
+                const result = yield repository
+                    .createQueryBuilder()
+                    .delete()
+                    .where('namespace = :namespace', { namespace: this.namespace })
+                    .andWhere('key LIKE :pattern', { pattern: fullPattern })
+                    .execute();
+                return result.affected || 0;
+            }
+            catch (error) {
+                console.error('TypeormCacheProvider.deletePattern() failed:', error);
+                return 0;
+            }
+        });
+    }
+    /**
+     * Clear all cache entries in namespace
+     */
+    clear() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.enabled)
+                return;
+            try {
+                const repository = this.getRepository();
+                yield repository.delete({
+                    namespace: this.namespace,
+                });
+            }
+            catch (error) {
+                console.error('TypeormCacheProvider.clear() failed:', error);
+            }
+        });
+    }
+    /**
+     * Check if key exists and is not expired
+     */
+    has(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.enabled)
+                return false;
+            try {
+                const value = yield this.get(key);
+                return value !== null;
+            }
+            catch (error) {
+                return false;
+            }
+        });
+    }
+    /**
+     * Get multiple values by keys
+     */
+    mget(keys) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.enabled || keys.length === 0) {
+                return keys.map(() => null);
+            }
+            try {
+                const repository = this.getRepository();
+                const fullKeys = keys.map((k) => this.getFullKey(k));
+                const cacheEntries = yield repository.find({
+                    where: {
+                        key: (0, typeorm_1.In)(fullKeys),
+                        namespace: this.namespace,
+                    },
+                });
+                // Create map for quick lookup
+                const entryMap = new Map();
+                for (const entry of cacheEntries) {
+                    if (entry.isValid()) {
+                        entryMap.set(entry.key, JSON.parse(entry.value));
+                    }
+                    else {
+                        // Clean up expired entry
+                        yield repository.remove(entry);
+                    }
+                }
+                // Return values in same order as input keys
+                return keys.map((key) => entryMap.get(this.getFullKey(key)) || null);
+            }
+            catch (error) {
+                console.error('TypeormCacheProvider.mget() failed:', error);
+                return keys.map(() => null);
+            }
+        });
+    }
+    /**
+     * Set multiple cache entries
+     */
+    mset(items, ttl) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.enabled || items.length === 0)
+                return;
+            try {
+                const repository = this.getRepository();
+                const duration = ttl || this.defaultDuration;
+                const expiresAt = duration > 0 ? new Date(Date.now() + duration) : null;
+                for (const item of items) {
+                    const fullKey = this.getFullKey(item.key);
+                    const existing = yield repository.findOne({
+                        where: { key: fullKey, namespace: this.namespace },
+                    });
+                    if (existing) {
+                        existing.updateValue(JSON.stringify(item.value), duration);
+                        yield repository.save(existing);
+                    }
+                    else {
+                        const cacheEntry = repository.create({
+                            key: fullKey,
+                            namespace: this.namespace,
+                            value: JSON.stringify(item.value),
+                            expires_at: expiresAt,
+                            ttl: duration > 0 ? Math.floor(duration / 1000) : null,
+                        });
+                        yield repository.save(cacheEntry);
+                    }
+                }
+            }
+            catch (error) {
+                console.error('TypeormCacheProvider.mset() failed:', error);
+            }
+        });
+    }
+    /**
+     * Get cache configuration
+     */
+    getCacheConfig() {
+        return {
+            duration: this.defaultDuration,
+            type: 'database',
+            enabled: this.enabled,
+            namespace: this.namespace,
+            dataSourceName: this.dataSourceName,
+        };
+    }
+    /**
+     * Get statistics about cache entries
+     */
+    getStats() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const repository = this.getRepository();
+                const [total, expired] = yield Promise.all([
+                    repository.count({
+                        where: { namespace: this.namespace },
+                    }),
+                    repository
+                        .createQueryBuilder('cache')
+                        .where('cache.namespace = :namespace', { namespace: this.namespace })
+                        .andWhere('cache.expires_at < :now', { now: new Date() })
+                        .getCount(),
+                ]);
+                return {
+                    totalEntries: total,
+                    expiredEntries: expired,
+                    validEntries: total - expired,
+                    enabled: this.enabled,
+                    defaultDuration: this.defaultDuration,
+                    type: 'database',
+                    namespace: this.namespace,
+                    dataSourceName: this.dataSourceName,
+                };
+            }
+            catch (error) {
+                return {
+                    totalEntries: 0,
+                    expiredEntries: 0,
+                    validEntries: 0,
+                    enabled: this.enabled,
+                    defaultDuration: this.defaultDuration,
+                    type: 'database',
+                    namespace: this.namespace,
+                    dataSourceName: this.dataSourceName,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        });
+    }
+    /**
+     * Clean up expired entries
+     */
+    cleanupExpired() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const repository = this.getRepository();
+                const result = yield repository
+                    .createQueryBuilder()
+                    .delete()
+                    .where('namespace = :namespace', { namespace: this.namespace })
+                    .andWhere('expires_at < :now', { now: new Date() })
+                    .execute();
+                return result.affected || 0;
+            }
+            catch (error) {
+                console.error('TypeormCacheProvider.cleanupExpired() failed:', error);
+                return 0;
+            }
+        });
+    }
+    /**
+     * Enable or disable caching
+     */
+    setEnabled(enabled) {
+        this.enabled = enabled;
+    }
+    /**
+     * Set namespace
+     */
+    setNamespace(namespace) {
+        this.namespace = namespace;
+    }
+    /**
+     * Get full key with namespace
+     */
+    getFullKey(key) {
+        return key;
+    }
+    /**
+     * Start automatic cleanup of expired entries
+     */
+    startAutoCleanup() {
+        if (!this.autoCleanup || this.cleanupTimer) {
+            return;
+        }
+        this.cleanupTimer = setInterval(() => __awaiter(this, void 0, void 0, function* () {
+            yield this.cleanupExpired();
+        }), this.cleanupInterval);
+    }
+    /**
+     * Stop automatic cleanup
+     */
+    stopAutoCleanup() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = undefined;
+        }
+    }
+    onModuleDestroy() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.stopAutoCleanup();
+        });
+    }
+};
+exports.TypeormCacheProvider = TypeormCacheProvider;
+exports.TypeormCacheProvider = TypeormCacheProvider = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Optional)()),
+    __param(0, (0, common_1.Inject)('TYPEORM_CACHE_DATASOURCE')),
+    __metadata("design:paramtypes", [typeorm_1.DataSource, Object])
+], TypeormCacheProvider);

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[];
 }

package/cache/utils/dependency-manager.util.js

@@ -10,7 +10,17 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DependencyManager = void 0;
+/**
+ * Utility class for managing cache dependencies
+ */
 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(value, dependencies) {
         return __awaiter(this, void 0, void 0, function* () {
             const wrapped = {
@@ -23,6 +33,12 @@ class DependencyManager {
             return wrapped;
         });
     }
+    /**
+     * Capture current state of all dependencies
+     *
+     * @param dependencies - Array of dependencies
+     * @returns Array of dependency data snapshots
+     */
     static captureDependencies(dependencies) {
         return __awaiter(this, void 0, void 0, function* () {
             const results = [];
@@ -36,6 +52,7 @@ class DependencyManager {
                     });
                 }
                 catch (error) {
+                    // Store error state
                     results.push({
                         key: dep.getKey(),
                         data: {
@@ -48,44 +65,67 @@ class DependencyManager {
             return results;
         });
     }
+    /**
+     * 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, cachedDependencies) {
         return __awaiter(this, void 0, void 0, function* () {
+            // No dependencies means never changed
             if (!dependencies || dependencies.length === 0) {
                 return false;
             }
+            // No cached dependency data means changed (first time)
             if (!cachedDependencies || cachedDependencies.length === 0) {
                 return true;
             }
+            // Different number of dependencies means changed
             if (dependencies.length !== cachedDependencies.length) {
                 return true;
             }
+            // Check each dependency
             for (let i = 0; i < dependencies.length; i++) {
                 const dep = dependencies[i];
                 const cached = cachedDependencies[i];
+                // Key mismatch means dependencies changed
                 if (dep.getKey() !== cached.key) {
                     return true;
                 }
                 try {
+                    // Check if this dependency has changed
                     const changed = yield dep.isChanged(cached.data);
                     if (changed) {
                         return true;
                     }
                 }
                 catch (_a) {
+                    // If check fails, consider it changed to be safe
                     return true;
                 }
             }
             return false;
         });
     }
+    /**
+     * 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(wrapped, dependencies) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!wrapped) {
                 return null;
             }
+            // No dependencies to check, return value
             if (!dependencies || dependencies.length === 0) {
                 return wrapped.value;
             }
+            // Check if dependencies have changed
             const changed = yield this.areDependenciesChanged(dependencies, wrapped.dependencies);
             if (changed) {
                 return null;
@@ -93,6 +133,13 @@ class DependencyManager {
             return wrapped.value;
         });
     }
+    /**
+     * Get which dependencies have changed
+     *
+     * @param dependencies - Current dependencies
+     * @param cachedDependencies - Previously captured dependency data
+     * @returns Array of changed dependency keys
+     */
     static getChangedDependencies(dependencies, cachedDependencies) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!dependencies || dependencies.length === 0) {
@@ -121,6 +168,12 @@ class DependencyManager {
             return changed;
         });
     }
+    /**
+     * Serialize dependencies for storage
+     *
+     * @param dependencies - Dependency data
+     * @returns Serialized string
+     */
     static serializeDependencies(dependencies) {
         try {
             return JSON.stringify(dependencies);
@@ -129,6 +182,12 @@ class DependencyManager {
             return '[]';
         }
     }
+    /**
+     * Deserialize dependencies from storage
+     *
+     * @param serialized - Serialized string
+     * @returns Dependency data array
+     */
     static deserializeDependencies(serialized) {
         try {
             return JSON.parse(serialized);