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

package/cache/providers/lrucache.provider.js

@@ -0,0 +1,226 @@
+"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 __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.LRUCacheProvider = void 0;
+const common_1 = require("@nestjs/common");
+const base_cache_provider_1 = require("./base-cache.provider");
+// Dynamic import to handle ESM/CommonJS interop
+const LRUCacheClass = require('lru-cache').LRUCache;
+/**
+ * LRU Memory Cache Provider
+ *
+ * High-performance in-memory LRU (Least Recently Used) cache provider.
+ * This is an L2 cache layer with fast access and automatic eviction.
+ *
+ * Features:
+ * - O(1) get/set operations
+ * - Automatic LRU eviction when cache is full
+ * - Optional TTL (Time To Live) support
+ * - Namespace isolation
+ * - Cache statistics (size, hit rate, usage percentage)
+ *
+ * Use Cases:
+ * - Session data caching
+ * - Frequently accessed configuration
+ * - API response caching
+ * - Temporary data storage
+ *
+ * @example
+ * ```typescript
+ * const provider = new LRUCacheProvider({
+ *   maxSize: 1000,
+ *   ttl: 60000, // optional TTL
+ *   namespace: 'my-cache',
+ * });
+ * ```
+ */
+let LRUCacheProvider = class LRUCacheProvider extends base_cache_provider_1.BaseCacheProvider {
+    constructor(options) {
+        super();
+        const { maxSize = 500, ttl, namespace = 'cache:lru' } = options || {};
+        this.namespace = namespace;
+        this.defaultTtl = ttl;
+        this.cache = new LRUCacheClass({
+            max: maxSize,
+            ttl: ttl,
+            updateAgeOnGet: true,
+            updateAgeOnHas: true,
+        });
+    }
+    getName() {
+        return 'LRUMemory';
+    }
+    get(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const fullKey = this.getFullKey(key);
+                const value = this.cache.get(fullKey);
+                return value !== undefined ? value : null;
+            }
+            catch (error) {
+                console.warn(`LRUCacheProvider: Failed to get key ${key}:`, error);
+                return null;
+            }
+        });
+    }
+    set(key, value, ttl) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const fullKey = this.getFullKey(key);
+                const effectiveTtl = ttl !== null && ttl !== void 0 ? ttl : this.defaultTtl;
+                this.cache.set(fullKey, value, { ttl: effectiveTtl });
+            }
+            catch (error) {
+                throw new Error(`LRUCacheProvider: Failed to set key ${key}: ${error}`);
+            }
+        });
+    }
+    delete(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                if (Array.isArray(key)) {
+                    key.forEach((k) => {
+                        const fullKey = this.getFullKey(k);
+                        this.cache.delete(fullKey);
+                    });
+                }
+                else {
+                    const fullKey = this.getFullKey(key);
+                    this.cache.delete(fullKey);
+                }
+            }
+            catch (error) {
+                throw new Error(`LRUCacheProvider: Failed to delete keys: ${error}`);
+            }
+        });
+    }
+    deletePattern(pattern) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const regex = this.patternToRegex(pattern);
+                const keys = Array.from(this.cache.keys());
+                let deleted = 0;
+                for (const key of keys) {
+                    if (regex.test(String(key))) {
+                        this.cache.delete(key);
+                        deleted++;
+                    }
+                }
+                return deleted;
+            }
+            catch (error) {
+                throw new Error(`LRUCacheProvider: Failed to delete pattern ${pattern}: ${error}`);
+            }
+        });
+    }
+    clear() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                this.cache.clear();
+            }
+            catch (error) {
+                throw new Error(`LRUCacheProvider: Failed to clear cache: ${error}`);
+            }
+        });
+    }
+    has(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const fullKey = this.getFullKey(key);
+                return this.cache.has(fullKey);
+            }
+            catch (error) {
+                return false;
+            }
+        });
+    }
+    mget(keys) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                return keys.map((key) => {
+                    const fullKey = this.getFullKey(key);
+                    const value = this.cache.get(fullKey);
+                    return value !== undefined ? value : null;
+                });
+            }
+            catch (error) {
+                console.warn(`LRUCacheProvider: Failed to mget:`, error);
+                return keys.map(() => null);
+            }
+        });
+    }
+    mset(items, ttl) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const effectiveTtl = ttl !== null && ttl !== void 0 ? ttl : this.defaultTtl;
+                items.forEach((item) => {
+                    const fullKey = this.getFullKey(item.key);
+                    this.cache.set(fullKey, item.value, { ttl: effectiveTtl });
+                });
+            }
+            catch (error) {
+                throw new Error(`LRUCacheProvider: Failed to mset: ${error}`);
+            }
+        });
+    }
+    /**
+     * Get cache size
+     */
+    getSize() {
+        return this.cache.size;
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        return {
+            provider: 'LRUMemory',
+            namespace: this.namespace,
+            size: this.cache.size,
+            maxSize: this.cache.max,
+            calculatedSize: this.cache.calculatedSize,
+            usagePercentage: this.cache.max
+                ? (this.cache.size / this.cache.max) * 100
+                : 0,
+        };
+    }
+    /**
+     * Clean up expired items
+     */
+    cleanup() {
+        const beforeSize = this.cache.size;
+        this.cache.purgeStale();
+        return beforeSize - this.cache.size;
+    }
+    /**
+     * Destroy the provider
+     */
+    onModuleDestroy() {
+        this.cache.clear();
+    }
+    getFullKey(key) {
+        return `${this.namespace}:${key}`;
+    }
+};
+exports.LRUCacheProvider = LRUCacheProvider;
+exports.LRUCacheProvider = LRUCacheProvider = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [Object])
+], LRUCacheProvider);

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/providers/typeorm-cache.provider.d.ts

@@ -0,0 +1,211 @@
+import { DataSource } from 'typeorm';
+import { BaseCacheProvider } from './base-cache.provider';
+/**
+ * Options for TypeormCacheProvider
+ */
+export interface TypeormCacheProviderOptions {
+    /**
+     * Default cache duration in milliseconds
+     * Default: 60000 (60 seconds)
+     */
+    duration?: number;
+    /**
+     * Enable or disable caching
+     * Default: true
+     */
+    enabled?: boolean;
+    /**
+     * Data source name to use for cache operations
+     * If not specified, uses the default data source
+     * Default: 'default'
+     */
+    dataSourceName?: string;
+    /**
+     * Namespace for cache isolation
+     * Default: 'cache'
+     */
+    namespace?: string;
+    /**
+     * Whether to automatically clean up expired entries
+     * Default: true
+     */
+    autoCleanup?: boolean;
+    /**
+     * Cleanup interval in milliseconds
+     * Default: 300000 (5 minutes)
+     */
+    cleanupInterval?: number;
+}
+/**
+ * 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
+ */
+export declare class TypeormCacheProvider extends BaseCacheProvider {
+    private readonly injectedDataSource?;
+    private defaultDuration;
+    private enabled;
+    private namespace;
+    private dataSourceName;
+    private autoCleanup;
+    private cleanupInterval;
+    private cleanupTimer?;
+    private dataSource?;
+    constructor(injectedDataSource?: DataSource, options?: TypeormCacheProviderOptions);
+    /**
+     * Get DataSource for cache operations
+     * Uses @nest-omni/transaction's getDataSource utility
+     */
+    private getDataSource;
+    /**
+     * Get repository for cache operations
+     */
+    private getRepository;
+    getName(): string;
+    /**
+     * Get cached value by key
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Set cache value with optional TTL
+     */
+    set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    /**
+     * Delete cache entry by key
+     */
+    delete(key: string | string[]): Promise<void>;
+    /**
+     * Delete cache entries matching a pattern
+     * Uses SQL LIKE for pattern matching
+     */
+    deletePattern(pattern: string): Promise<number>;
+    /**
+     * Clear all cache entries in namespace
+     */
+    clear(): Promise<void>;
+    /**
+     * Check if key exists and is not expired
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Get multiple values by keys
+     */
+    mget<T>(keys: string[]): Promise<(T | null)[]>;
+    /**
+     * Set multiple cache entries
+     */
+    mset(items: Array<{
+        key: string;
+        value: any;
+    }>, ttl?: number): Promise<void>;
+    /**
+     * Get cache configuration
+     */
+    getCacheConfig(): {
+        duration: number;
+        type: string;
+        enabled: boolean;
+        namespace: string;
+        dataSourceName: string;
+    };
+    /**
+     * Get statistics about cache entries
+     */
+    getStats(): Promise<{
+        totalEntries: number;
+        expiredEntries: number;
+        validEntries: number;
+        enabled: boolean;
+        defaultDuration: number;
+        type: string;
+        namespace: string;
+        dataSourceName: string;
+        error?: undefined;
+    } | {
+        totalEntries: number;
+        expiredEntries: number;
+        validEntries: number;
+        enabled: boolean;
+        defaultDuration: number;
+        type: string;
+        namespace: string;
+        dataSourceName: string;
+        error: string;
+    }>;
+    /**
+     * Clean up expired entries
+     */
+    cleanupExpired(): Promise<number>;
+    /**
+     * Enable or disable caching
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Set namespace
+     */
+    setNamespace(namespace: string): void;
+    /**
+     * Get full key with namespace
+     */
+    private getFullKey;
+    /**
+     * Start automatic cleanup of expired entries
+     */
+    private startAutoCleanup;
+    /**
+     * Stop automatic cleanup
+     */
+    private stopAutoCleanup;
+    onModuleDestroy(): Promise<void>;
+}