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

package/cache/interfaces/cache-options.interface.d.ts

@@ -1,32 +1,121 @@
 import type { CacheDependency } from './cache-dependency.interface';
+/**
+ * Cache layer enum - defines the three-tier cache architecture
+ */
 export declare enum CacheLayer {
+    /** L1: Request-level cache (nestjs-cls) - fastest, scoped to request */
     CLS = "cls",
+    /** L2: Process-level cache (native Map) - fast, scoped to process */
     MEMORY = "memory",
+    /** L3: Distributed cache (Redis) - persistent, shared across processes */
     REDIS = "redis"
 }
+/**
+ * Cache configuration options
+ */
 export interface CacheOptions {
+    /**
+     * Time to live in milliseconds
+     * @example 300_000 // 5 minutes
+     */
     ttl?: number;
+    /**
+     * Cache layers to use
+     * @default [CacheLayer.MEMORY, CacheLayer.REDIS]
+     */
     layers?: CacheLayer[];
+    /**
+     * Key prefix for namespacing
+     * @example 'user:' will result in keys like 'user:123'
+     */
     prefix?: string;
+    /**
+     * Condition function to determine if value should be cached
+     * @param args - Method arguments
+     * @returns true to cache, false to skip
+     */
     condition?: (...args: any[]) => boolean | Promise<boolean>;
+    /**
+     * Unless condition - skip caching when this condition is true
+     * Can be a function (safe) or a string expression (use with caution)
+     * @param result - Method return value
+     * @param args - Method arguments
+     * @returns true to skip caching, false to cache normally
+     */
+    unless?: ((result: any, args: any[]) => boolean) | string;
+    /**
+     * Cache dependencies - cache will be invalidated when dependencies change
+     * Similar to Yii2 cache dependency system
+     */
     dependencies?: CacheDependency[];
+    /**
+     * Whether to backfill upper cache layers when value is found in lower layer
+     * @default true
+     */
     backfill?: boolean;
+    /**
+     * Namespace for grouping related cache keys
+     */
     namespace?: string;
 }
+/**
+ * Options for cache decorator key generation
+ */
 export interface CacheKeyOptions {
+    /**
+     * Static key or key generator function
+     */
     key?: string | ((...args: any[]) => string);
+    /**
+     * Key prefix
+     */
     prefix?: string;
+    /**
+     * Whether to include all method arguments in key generation
+     * @default false
+     */
     includeAllArgs?: boolean;
 }
+/**
+ * Options for @Cacheable decorator
+ */
 export interface CacheableOptions extends CacheOptions, CacheKeyOptions {
 }
+/**
+ * Options for @CacheEvict decorator
+ */
 export interface CacheEvictOptions {
+    /**
+     * Keys to evict (can be static strings or generator functions)
+     */
     keys?: Array<string | ((...args: any[]) => string)>;
+    /**
+     * Patterns to match for eviction (supports wildcards)
+     * @example ['user:*', 'posts:list:*']
+     */
     patterns?: string[];
+    /**
+     * Tags to invalidate
+     */
     tags?: string[];
+    /**
+     * Cache layers to evict from
+     */
     layers?: CacheLayer[];
+    /**
+     * Condition to determine if eviction should occur
+     * @param args - Method arguments
+     * @param result - Method return value
+     */
     condition?: (...args: any[]) => boolean | Promise<boolean>;
+    /**
+     * Whether to evict before or after method execution
+     * @default 'after'
+     */
     timing?: 'before' | 'after';
 }
+/**
+ * Options for @CachePut decorator
+ */
 export interface CachePutOptions extends CacheOptions, CacheKeyOptions {
 }

package/cache/interfaces/cache-options.interface.js

@@ -1,9 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CacheLayer = void 0;
+/**
+ * Cache layer enum - defines the three-tier cache architecture
+ */
 var CacheLayer;
 (function (CacheLayer) {
+    /** L1: Request-level cache (nestjs-cls) - fastest, scoped to request */
     CacheLayer["CLS"] = "cls";
+    /** L2: Process-level cache (native Map) - fast, scoped to process */
     CacheLayer["MEMORY"] = "memory";
+    /** L3: Distributed cache (Redis) - persistent, shared across processes */
     CacheLayer["REDIS"] = "redis";
 })(CacheLayer || (exports.CacheLayer = CacheLayer = {}));

package/cache/interfaces/cache-provider.interface.d.ts

@@ -1,28 +1,106 @@
+/**
+ * Base cache provider interface
+ * All cache providers (CLS, Memory, Redis) implement this interface
+ */
 export interface CacheProvider {
+    /**
+     * Get value from cache
+     *
+     * @param key - Cache key
+     * @returns Cached value or null if not found
+     */
     get<T>(key: string): Promise<T | null>;
+    /**
+     * Set value in cache
+     *
+     * @param key - Cache key
+     * @param value - Value to cache
+     * @param ttl - Time to live in milliseconds
+     */
     set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    /**
+     * Delete value from cache
+     *
+     * @param key - Cache key or array of keys
+     */
     delete(key: string | string[]): Promise<void>;
+    /**
+     * Delete keys matching a pattern (supports wildcards)
+     *
+     * @param pattern - Pattern to match (e.g., 'user:*')
+     * @returns Number of keys deleted
+     */
     deletePattern?(pattern: string): Promise<number>;
+    /**
+     * Clear all cache entries
+     */
     clear(): Promise<void>;
+    /**
+     * Check if a key exists in cache
+     *
+     * @param key - Cache key
+     */
     has(key: string): Promise<boolean>;
+    /**
+     * Get multiple values at once
+     *
+     * @param keys - Array of cache keys
+     * @returns Array of values (null for missing keys)
+     */
     mget<T>(keys: string[]): Promise<(T | null)[]>;
+    /**
+     * Set multiple values at once
+     *
+     * @param items - Array of key-value pairs
+     * @param ttl - Time to live in milliseconds
+     */
     mset(items: Array<{
         key: string;
         value: any;
     }>, ttl?: number): Promise<void>;
+    /**
+     * Get provider name
+     */
     getName(): string;
 }
+/**
+ * Cache statistics
+ */
 export interface CacheStats {
+    /**
+     * Total number of get operations
+     */
     totalGets: number;
+    /**
+     * Number of cache hits
+     */
     hits: number;
+    /**
+     * Number of cache misses
+     */
     misses: number;
+    /**
+     * Hit rate (hits / totalGets)
+     */
     hitRate: number;
+    /**
+     * Stats per layer
+     */
     byLayer: Record<string, {
         hits: number;
         misses: number;
         hitRate: number;
     }>;
+    /**
+     * Total number of set operations
+     */
     totalSets: number;
+    /**
+     * Total number of delete operations
+     */
     totalDeletes: number;
+    /**
+     * Total number of clear operations
+     */
     totalClears: number;
 }

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

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

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

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

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

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

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

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

package/cache/providers/index.d.ts

@@ -1,4 +1,5 @@
 export * from './base-cache.provider';
 export * from './cls-cache.provider';
-export * from './memory-cache.provider';
+export * from './lrucache.provider';
+export * from './typeorm-cache.provider';
 export { REDIS_CLIENT, RedisCacheProvider } from './redis-cache.provider';

package/cache/providers/index.js

@@ -17,7 +17,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RedisCacheProvider = exports.REDIS_CLIENT = void 0;
 __exportStar(require("./base-cache.provider"), exports);
 __exportStar(require("./cls-cache.provider"), exports);
-__exportStar(require("./memory-cache.provider"), exports);
+__exportStar(require("./lrucache.provider"), exports);
+__exportStar(require("./typeorm-cache.provider"), exports);
 var redis_cache_provider_1 = require("./redis-cache.provider");
 Object.defineProperty(exports, "REDIS_CLIENT", { enumerable: true, get: function () { return redis_cache_provider_1.REDIS_CLIENT; } });
 Object.defineProperty(exports, "RedisCacheProvider", { enumerable: true, get: function () { return redis_cache_provider_1.RedisCacheProvider; } });

package/cache/providers/lrucache.provider.d.ts

@@ -0,0 +1,76 @@
+import { OnModuleDestroy } from '@nestjs/common';
+import { BaseCacheProvider } from './base-cache.provider';
+/**
+ * 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',
+ * });
+ * ```
+ */
+export declare class LRUCacheProvider extends BaseCacheProvider implements OnModuleDestroy {
+    private cache;
+    private namespace;
+    private defaultTtl?;
+    constructor(options?: {
+        maxSize?: number;
+        ttl?: number;
+        namespace?: string;
+    });
+    getName(): string;
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    delete(key: string | string[]): Promise<void>;
+    deletePattern(pattern: string): Promise<number>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    mget<T>(keys: string[]): Promise<(T | null)[]>;
+    mset(items: Array<{
+        key: string;
+        value: any;
+    }>, ttl?: number): Promise<void>;
+    /**
+     * Get cache size
+     */
+    getSize(): number;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        provider: string;
+        namespace: string;
+        size: any;
+        maxSize: any;
+        calculatedSize: any;
+        usagePercentage: number;
+    };
+    /**
+     * Clean up expired items
+     */
+    cleanup(): number;
+    /**
+     * Destroy the provider
+     */
+    onModuleDestroy(): void;
+    private getFullKey;
+}