@nest-omni/core 4.1.3-1 → 4.1.3-11

package/cache/cache.module.d.ts

@@ -2,20 +2,106 @@ import { DynamicModule, OnModuleInit } from '@nestjs/common';
 import type { DataSource } from 'typeorm';
 import type { Redis } from 'ioredis';
 import { CacheService } from './cache.service';
+/**
+ * Injection token for CacheService
+ */
 export declare const CACHE_SERVICE: unique symbol;
+/**
+ * Cache module configuration options
+ */
 export interface CacheModuleOptions {
+    /**
+     * Whether to make the module global
+     * @default true
+     */
     isGlobal?: boolean;
+    /**
+     * Redis client instance (optional)
+     * If not provided, Redis caching will be disabled
+     */
     redisClient?: Redis;
+    /**
+     * TypeORM DataSource for DbDependency
+     * If not provided, DbDependency will throw error when used
+     */
     dataSource?: DataSource;
+    /**
+     * Default TTL for memory cache in milliseconds
+     */
     memoryTtl?: number;
+    /**
+     * Namespace for memory cache
+     */
     memoryNamespace?: string;
+    /**
+     * Enable compression for cache values
+     * @default false
+     */
     enableCompression?: boolean;
+    /**
+     * Compression threshold in bytes
+     * @default 1024
+     */
     compressionThreshold?: number;
 }
+/**
+ * Unified cache module with three-tier architecture
+ *
+ * Provides CacheService and cache decorators (@Cacheable, @CacheEvict, @CachePut)
+ *
+ * @example
+ * ```typescript
+ * // Basic usage (without Redis)
+ * @Module({
+ *   imports: [
+ *     CacheModule.forRoot()
+ *   ]
+ * })
+ * export class AppModule {}
+ *
+ * // With Redis
+ * import { RedisModule } from '@songkeys/nestjs-redis';
+ *
+ * @Module({
+ *   imports: [
+ *     RedisModule.forRoot({ ... }),
+ *     CacheModule.forRootAsync({
+ *       imports: [RedisModule],
+ *       inject: [RedisService],
+ *       useFactory: (redisService: RedisService) => ({
+ *         redisClient: redisService.getClient()
+ *       })
+ *     })
+ *   ]
+ * })
+ * export class AppModule {}
+ *
+ * // With TypeORM DataSource for DbDependency
+ * @Module({
+ *   imports: [
+ *     TypeOrmModule.forRoot({ ... }),
+ *     CacheModule.forRootAsync({
+ *       imports: [TypeOrmModule],
+ *       inject: [DataSource],
+ *       useFactory: (dataSource: DataSource) => ({
+ *         dataSource
+ *       })
+ *     })
+ *   ]
+ * })
+ * export class AppModule {}
+ * ```
+ */
 export declare class CacheModule implements OnModuleInit {
     private readonly cacheService;
     constructor(cacheService: CacheService);
+    /**
+     * Register cache module with options
+     */
     static forRoot(options?: CacheModuleOptions): DynamicModule;
+    /**
+     * Register cache module asynchronously
+     */
     static forRootAsync(options: {
         imports?: any[];
         inject?: any[];

package/cache/cache.module.js

@@ -20,13 +20,68 @@ const dependencies_1 = require("./dependencies");
 const decorators_1 = require("./decorators");
 const providers_1 = require("./providers");
 const cache_constants_1 = require("./cache.constants");
+/**
+ * Injection token for CacheService
+ */
 exports.CACHE_SERVICE = Symbol('CACHE_SERVICE');
+/**
+ * Unified cache module with three-tier architecture
+ *
+ * Provides CacheService and cache decorators (@Cacheable, @CacheEvict, @CachePut)
+ *
+ * @example
+ * ```typescript
+ * // Basic usage (without Redis)
+ * @Module({
+ *   imports: [
+ *     CacheModule.forRoot()
+ *   ]
+ * })
+ * export class AppModule {}
+ *
+ * // With Redis
+ * import { RedisModule } from '@songkeys/nestjs-redis';
+ *
+ * @Module({
+ *   imports: [
+ *     RedisModule.forRoot({ ... }),
+ *     CacheModule.forRootAsync({
+ *       imports: [RedisModule],
+ *       inject: [RedisService],
+ *       useFactory: (redisService: RedisService) => ({
+ *         redisClient: redisService.getClient()
+ *       })
+ *     })
+ *   ]
+ * })
+ * export class AppModule {}
+ *
+ * // With TypeORM DataSource for DbDependency
+ * @Module({
+ *   imports: [
+ *     TypeOrmModule.forRoot({ ... }),
+ *     CacheModule.forRootAsync({
+ *       imports: [TypeOrmModule],
+ *       inject: [DataSource],
+ *       useFactory: (dataSource: DataSource) => ({
+ *         dataSource
+ *       })
+ *     })
+ *   ]
+ * })
+ * export class AppModule {}
+ * ```
+ */
 let CacheModule = CacheModule_1 = class CacheModule {
     constructor(cacheService) {
         this.cacheService = cacheService;
     }
+    /**
+     * Register cache module with options
+     */
     static forRoot(options = {}) {
         const { isGlobal = true, redisClient, dataSource, memoryTtl, memoryNamespace, enableCompression = false, compressionThreshold = 1024, } = options;
+        // Set DataSource for DbDependency if provided
         if (dataSource) {
             dependencies_1.DbDependency.setDataSource(dataSource);
         }
@@ -34,6 +89,7 @@ let CacheModule = CacheModule_1 = class CacheModule {
             module: CacheModule_1,
             global: isGlobal,
             providers: [
+                // Providers
                 providers_1.ClsCacheProvider,
                 {
                     provide: providers_1.MemoryCacheProvider,
@@ -42,6 +98,7 @@ let CacheModule = CacheModule_1 = class CacheModule {
                         namespace: memoryNamespace,
                     }),
                 },
+                // Redis client provider (optional)
                 ...(redisClient
                     ? [
                         {
@@ -51,6 +108,7 @@ let CacheModule = CacheModule_1 = class CacheModule {
                     ]
                     : []),
                 providers_1.RedisCacheProvider,
+                // Compression configuration providers
                 {
                     provide: cache_constants_1.CACHE_COMPRESSION_ENABLED,
                     useValue: enableCompression,
@@ -59,12 +117,14 @@ let CacheModule = CacheModule_1 = class CacheModule {
                     provide: cache_constants_1.CACHE_COMPRESSION_THRESHOLD,
                     useValue: compressionThreshold,
                 },
+                // Additional services
                 cache_warmup_service_1.CacheWarmupService,
                 cache_metrics_service_1.CacheMetricsService,
                 {
                     provide: cache_serialization_service_1.CacheSerializationService,
                     useFactory: () => new cache_serialization_service_1.CacheSerializationService(),
                 },
+                // CacheService
                 {
                     provide: exports.CACHE_SERVICE,
                     useClass: cache_service_1.CacheService,
@@ -80,6 +140,9 @@ let CacheModule = CacheModule_1 = class CacheModule {
             ],
         };
     }
+    /**
+     * Register cache module asynchronously
+     */
     static forRootAsync(options) {
         var _a;
         return {
@@ -87,15 +150,18 @@ let CacheModule = CacheModule_1 = class CacheModule {
             global: (_a = options.isGlobal) !== null && _a !== void 0 ? _a : true,
             imports: options.imports || [],
             providers: [
+                // Async options provider
                 {
                     provide: 'CACHE_MODULE_OPTIONS',
                     useFactory: options.useFactory,
                     inject: options.inject || [],
                 },
+                // Providers
                 providers_1.ClsCacheProvider,
                 {
                     provide: providers_1.MemoryCacheProvider,
                     useFactory: (moduleOptions) => {
+                        // Set DataSource for DbDependency if provided
                         if (moduleOptions.dataSource) {
                             dependencies_1.DbDependency.setDataSource(moduleOptions.dataSource);
                         }
@@ -106,18 +172,21 @@ let CacheModule = CacheModule_1 = class CacheModule {
                     },
                     inject: ['CACHE_MODULE_OPTIONS'],
                 },
+                // Redis client provider (optional)
                 {
                     provide: providers_1.REDIS_CLIENT,
                     useFactory: (moduleOptions) => moduleOptions.redisClient,
                     inject: ['CACHE_MODULE_OPTIONS'],
                 },
                 providers_1.RedisCacheProvider,
+                // Additional services
                 cache_warmup_service_1.CacheWarmupService,
                 cache_metrics_service_1.CacheMetricsService,
                 {
                     provide: cache_serialization_service_1.CacheSerializationService,
                     useFactory: () => new cache_serialization_service_1.CacheSerializationService(),
                 },
+                // Compression configuration providers
                 {
                     provide: cache_constants_1.CACHE_COMPRESSION_ENABLED,
                     useFactory: (moduleOptions) => moduleOptions.enableCompression || false,
@@ -128,6 +197,7 @@ let CacheModule = CacheModule_1 = class CacheModule {
                     useFactory: (moduleOptions) => moduleOptions.compressionThreshold || 1024,
                     inject: ['CACHE_MODULE_OPTIONS'],
                 },
+                // CacheService
                 {
                     provide: exports.CACHE_SERVICE,
                     useClass: cache_service_1.CacheService,
@@ -144,6 +214,7 @@ let CacheModule = CacheModule_1 = class CacheModule {
         };
     }
     onModuleInit() {
+        // Set global cache service for decorators
         (0, decorators_1.setCacheService)(this.cacheService);
     }
 };

package/cache/cache.service.d.ts

@@ -1,6 +1,15 @@
 import type { CacheOptions, CacheStats } from './interfaces';
 import { CacheLayer } from './interfaces';
 import { ClsCacheProvider, MemoryCacheProvider, RedisCacheProvider } from './providers';
+/**
+ * Unified cache service with three-tier architecture
+ *
+ * L1: CLS (request-level)
+ * L2: Memory (process-level)
+ * L3: Redis (distributed)
+ *
+ * Supports automatic fallback, backfill, and dependency-based invalidation.
+ */
 export declare class CacheService {
     private readonly clsProvider;
     private readonly memoryProvider;
@@ -11,27 +20,158 @@ export declare class CacheService {
     private readonly providers;
     private readonly stats;
     constructor(clsProvider: ClsCacheProvider, memoryProvider: MemoryCacheProvider, redisProvider: RedisCacheProvider, enableCompression?: boolean, compressionThreshold?: number);
+    /**
+     * Get or set cache value with factory function
+     *
+     * @param key - Cache key
+     * @param factory - Function to generate value if not cached
+     * @param options - Cache options
+     * @returns Cached or generated value
+     */
     getOrSet<T>(key: string, factory: () => Promise<T>, options?: CacheOptions): Promise<T>;
+    /**
+     * Get value from cache with optional layer specification
+     *
+     * @param key - Cache key
+     * @param options - Cache options including layer preference
+     * @returns Cached value or null
+     *
+     * @example
+     * ```typescript
+     * // Try memory only
+     * const data = await this.cacheService.get('user:123', {
+     *   layers: [CacheLayer.MEMORY]
+     * });
+     *
+     * // Try all layers in order (CLS -> MEMORY -> REDIS)
+     * const data = await this.cacheService.get('config:app', {
+     *   layers: [CacheLayer.CLS, CacheLayer.MEMORY, CacheLayer.REDIS]
+     * });
+     * ```
+     */
     get<T>(key: string, options?: CacheOptions): Promise<T | null>;
+    /**
+     * Set value in cache with optional layer specification
+     *
+     * Supports both new API (CacheOptions) and legacy API (TTL number) for backward compatibility.
+     *
+     * @param key - Cache key
+     * @param value - Value to cache
+     * @param options - Cache options including layer selection OR TTL (number) for legacy compatibility
+     *
+     * @example
+     * ```typescript
+     * // New API - Cache in memory only
+     * await this.cacheService.set('user:123', userData, {
+     *   layers: [CacheLayer.MEMORY],
+     *   ttl: 300000
+     * });
+     *
+     * // Legacy API - TTL as third parameter (still works for backward compatibility)
+     * await this.cacheService.set('user:123', userData, 300000);
+     *
+     * // Cache in all layers (default behavior)
+     * await this.cacheService.set('config:app', configData, {
+     *   layers: [CacheLayer.CLS, CacheLayer.MEMORY, CacheLayer.REDIS],
+     *   ttl: 3600000
+     * });
+     *
+     * // Cache in Redis only (distributed)
+     * await this.cacheService.set('global:settings', settings, {
+     *   layers: [CacheLayer.REDIS],
+     *   ttl: 86400000
+     * });
+     * ```
+     */
     set<T>(key: string, value: T, options?: CacheOptions | number): Promise<void>;
+    /**
+     * Delete value from cache
+     *
+     * @param key - Cache key or array of keys
+     * @param layers - Specific layers to delete from (default: all)
+     */
     del(key: string | string[], layers?: CacheLayer[]): Promise<void>;
+    /**
+     * Delete keys matching pattern
+     *
+     * @param pattern - Pattern to match (e.g., 'user:*')
+     * @param layers - Specific layers to delete from (default: Memory and Redis only)
+     */
     deletePattern(pattern: string, layers?: CacheLayer[]): Promise<void>;
+    /**
+     * Clear all cache
+     *
+     * @param layers - Specific layers to clear (default: all)
+     */
     clear(layers?: CacheLayer[]): Promise<void>;
+    /**
+     * Invalidate tags (for TagDependency)
+     *
+     * @param tags - Tags to invalidate
+     */
     invalidateTags(tags: string[]): Promise<void>;
+    /**
+     * Get multiple values
+     *
+     * @param keys - Array of cache keys
+     * @param options - Cache options
+     * @returns Array of values (null for missing keys)
+     */
     mget<T>(keys: string[], options?: CacheOptions): Promise<(T | null)[]>;
+    /**
+     * Set multiple values
+     *
+     * @param items - Array of key-value pairs
+     * @param options - Cache options
+     */
     mset(items: Array<{
         key: string;
         value: any;
     }>, options?: CacheOptions): Promise<void>;
+    /**
+     * Get cache statistics
+     *
+     * @returns Cache statistics
+     */
     getStats(): CacheStats;
+    /**
+     * Reset statistics
+     */
     resetStats(): void;
+    /**
+     * Internal method to set cache value with options
+     */
     private setWithOptions;
+    /**
+     * Resolve cache layers from options
+     */
     private resolveLayers;
+    /**
+     * Get default cache layers
+     */
     private getDefaultLayers;
+    /**
+     * Build full cache key with namespace
+     */
     private buildKey;
+    /**
+     * Backfill upper cache layers
+     */
     private backfillUpperLayers;
+    /**
+     * Record cache hit
+     */
     private recordHit;
+    /**
+     * Record cache miss
+     */
     private recordMiss;
+    /**
+     * Update hit rate for a layer
+     */
     private updateLayerHitRate;
+    /**
+     * Initialize statistics for all layers
+     */
     private initializeStats;
 }