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

package/cache/cache-serialization.service.d.ts

@@ -1,22 +1,53 @@
+/**
+ * Cache serialization options
+ */
 export interface CacheSerializationOptions {
+    /** Whether to compress large values */
     compress?: boolean;
+    /** Compression threshold (bytes) */
     compressThreshold?: number;
 }
+/**
+ * Serialization result
+ */
 export interface SerializationResult {
     data: Buffer;
     compressed: boolean;
     originalSize: number;
     serializedSize: number;
 }
+/**
+ * Deserialization result
+ */
 export interface DeserializationResult<T> {
     data: T;
     wasCompressed: boolean;
 }
+/**
+ * Simple cache serialization service
+ *
+ * Handles basic data compression for cache values
+ */
 export declare class CacheSerializationService {
     private readonly logger;
+    /**
+     * Serialize and optionally compress cache value
+     */
     serialize<T>(value: T, options?: CacheSerializationOptions): Promise<SerializationResult>;
+    /**
+     * Deserialize and decompress cache value
+     */
     deserialize<T>(buffer: Buffer): Promise<DeserializationResult<T>>;
+    /**
+     * Serialize value with proper Date handling
+     */
     private serializeWithDates;
+    /**
+     * Pre-process object to convert Date objects to serializable format
+     */
     private preProcessDates;
+    /**
+     * Deserialize value with proper Date restoration
+     */
     private deserializeWithDates;
 }

package/cache/cache-serialization.service.js

@@ -22,18 +22,28 @@ const zlib_1 = require("zlib");
 const util_1 = require("util");
 const gzipAsync = (0, util_1.promisify)(zlib_1.gzip);
 const gunzipAsync = (0, util_1.promisify)(zlib_1.gunzip);
+/**
+ * Simple cache serialization service
+ *
+ * Handles basic data compression for cache values
+ */
 let CacheSerializationService = CacheSerializationService_1 = class CacheSerializationService {
     constructor() {
         this.logger = new common_1.Logger(CacheSerializationService_1.name);
     }
+    /**
+     * Serialize and optionally compress cache value
+     */
     serialize(value_1) {
         return __awaiter(this, arguments, void 0, function* (value, options = {}) {
             const { compress = false, compressThreshold = 1024 } = options;
             try {
+                // Serialize the value with date handling
                 const serialized = this.serializeWithDates(value);
                 const originalSize = Buffer.byteLength(serialized, 'utf8');
                 let data;
                 let wasCompressed = false;
+                // Compress if enabled and data is large enough
                 if (compress && originalSize >= compressThreshold) {
                     try {
                         data = yield gzipAsync(Buffer.from(serialized, 'utf8'));
@@ -60,12 +70,17 @@ let CacheSerializationService = CacheSerializationService_1 = class CacheSeriali
             }
         });
     }
+    /**
+     * Deserialize and decompress cache value
+     */
     deserialize(buffer) {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 let dataString;
                 let wasCompressed = false;
+                // Try to detect if data is compressed
                 if (buffer.length >= 2 && buffer[0] === 0x1f && buffer[1] === 0x8b) {
+                    // Gzip magic numbers
                     dataString = (yield gunzipAsync(buffer)).toString('utf8');
                     wasCompressed = true;
                 }
@@ -84,10 +99,17 @@ let CacheSerializationService = CacheSerializationService_1 = class CacheSeriali
             }
         });
     }
+    /**
+     * Serialize value with proper Date handling
+     */
     serializeWithDates(value) {
+        // Pre-process the value to handle Date objects
         const processed = this.preProcessDates(value);
         return JSON.stringify(processed);
     }
+    /**
+     * Pre-process object to convert Date objects to serializable format
+     */
     preProcessDates(obj) {
         if (obj === null || obj === undefined) {
             return obj;
@@ -107,6 +129,9 @@ let CacheSerializationService = CacheSerializationService_1 = class CacheSeriali
         }
         return obj;
     }
+    /**
+     * Deserialize value with proper Date restoration
+     */
     deserializeWithDates(dataString) {
         return JSON.parse(dataString, (key, val) => {
             if (val && typeof val === 'object' && val.__type === 'Date') {

package/cache/cache.constants.d.ts

@@ -1,2 +1,11 @@
+/**
+ * Cache constants and injection tokens
+ */
+/**
+ * Injection token for cache compression enabled flag
+ */
 export declare const CACHE_COMPRESSION_ENABLED: unique symbol;
+/**
+ * Injection token for cache compression threshold
+ */
 export declare const CACHE_COMPRESSION_THRESHOLD: unique symbol;

package/cache/cache.constants.js

@@ -1,5 +1,14 @@
 "use strict";
+/**
+ * Cache constants and injection tokens
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CACHE_COMPRESSION_THRESHOLD = exports.CACHE_COMPRESSION_ENABLED = void 0;
+/**
+ * Injection token for cache compression enabled flag
+ */
 exports.CACHE_COMPRESSION_ENABLED = Symbol('CACHE_COMPRESSION_ENABLED');
+/**
+ * Injection token for cache compression threshold
+ */
 exports.CACHE_COMPRESSION_THRESHOLD = Symbol('CACHE_COMPRESSION_THRESHOLD');

package/cache/cache.health.d.ts

@@ -1,4 +1,7 @@
 import { CacheService } from './cache.service';
+/**
+ * Cache health check result
+ */
 export interface CacheHealthResult {
     status: 'healthy' | 'degraded' | 'unhealthy';
     layers: {
@@ -22,14 +25,37 @@ export interface CacheHealthResult {
     timestamp: Date;
     overallLatency: number;
 }
+/**
+ * Cache health checker
+ *
+ * Provides health monitoring for all cache layers
+ */
 export declare class CacheHealthChecker {
     private readonly cacheService;
     private readonly logger;
     constructor(cacheService: CacheService);
+    /**
+     * Check health of all cache layers
+     */
     checkHealth(): Promise<CacheHealthResult>;
+    /**
+     * Get detailed cache statistics
+     */
     getDetailedStats(): Promise<any>;
+    /**
+     * Check CLS cache health
+     */
     private checkClsHealth;
+    /**
+     * Check Memory cache health
+     */
     private checkMemoryHealth;
+    /**
+     * Check Redis cache health
+     */
     private checkRedisHealth;
+    /**
+     * Generate recommendations based on health and stats
+     */
     private generateRecommendations;
 }

package/cache/cache.health.js

@@ -23,11 +23,19 @@ exports.CacheHealthChecker = void 0;
 const common_1 = require("@nestjs/common");
 const cache_service_1 = require("./cache.service");
 const cache_options_interface_1 = require("./interfaces/cache-options.interface");
+/**
+ * Cache health checker
+ *
+ * Provides health monitoring for all cache layers
+ */
 let CacheHealthChecker = CacheHealthChecker_1 = class CacheHealthChecker {
     constructor(cacheService) {
         this.cacheService = cacheService;
         this.logger = new common_1.Logger(CacheHealthChecker_1.name);
     }
+    /**
+     * Check health of all cache layers
+     */
     checkHealth() {
         return __awaiter(this, void 0, void 0, function* () {
             const startTime = Date.now();
@@ -37,6 +45,7 @@ let CacheHealthChecker = CacheHealthChecker_1 = class CacheHealthChecker {
                 redis: yield this.checkRedisHealth(),
             };
             const overallLatency = Date.now() - startTime;
+            // Determine overall status
             const layerStatuses = Object.values(results);
             const healthyCount = layerStatuses.filter((layer) => layer.available).length;
             const totalCount = layerStatuses.length;
@@ -58,6 +67,9 @@ let CacheHealthChecker = CacheHealthChecker_1 = class CacheHealthChecker {
             };
         });
     }
+    /**
+     * Get detailed cache statistics
+     */
     getDetailedStats() {
         return __awaiter(this, void 0, void 0, function* () {
             const stats = this.cacheService.getStats();
@@ -69,10 +81,14 @@ let CacheHealthChecker = CacheHealthChecker_1 = class CacheHealthChecker {
             };
         });
     }
+    /**
+     * Check CLS cache health
+     */
     checkClsHealth() {
         return __awaiter(this, void 0, void 0, function* () {
             const startTime = Date.now();
             try {
+                // Try to write and read a test value
                 yield this.cacheService.set('health:cls:test', 'test-value', {
                     layers: [cache_options_interface_1.CacheLayer.CLS],
                 });
@@ -101,10 +117,14 @@ let CacheHealthChecker = CacheHealthChecker_1 = class CacheHealthChecker {
             }
         });
     }
+    /**
+     * Check Memory cache health
+     */
     checkMemoryHealth() {
         return __awaiter(this, void 0, void 0, function* () {
             const startTime = Date.now();
             try {
+                // Try to write and read a test value
                 yield this.cacheService.set('health:memory:test', 'test-value', {
                     layers: [cache_options_interface_1.CacheLayer.MEMORY],
                 });
@@ -113,6 +133,7 @@ let CacheHealthChecker = CacheHealthChecker_1 = class CacheHealthChecker {
                 });
                 const latency = Date.now() - startTime;
                 if (result === 'test-value') {
+                    // Get memory cache size (if available)
                     const stats = this.cacheService.getStats();
                     return { available: true, latency, size: stats.totalSets };
                 }
@@ -134,10 +155,14 @@ let CacheHealthChecker = CacheHealthChecker_1 = class CacheHealthChecker {
             }
         });
     }
+    /**
+     * Check Redis cache health
+     */
     checkRedisHealth() {
         return __awaiter(this, void 0, void 0, function* () {
             const startTime = Date.now();
             try {
+                // Try to write and read a test value
                 yield this.cacheService.set('health:redis:test', 'test-value', {
                     layers: [cache_options_interface_1.CacheLayer.REDIS],
                 });
@@ -166,8 +191,12 @@ let CacheHealthChecker = CacheHealthChecker_1 = class CacheHealthChecker {
             }
         });
     }
+    /**
+     * Generate recommendations based on health and stats
+     */
     generateRecommendations(health, stats) {
         const recommendations = [];
+        // Health-based recommendations
         if (!health.layers.redis.available) {
             recommendations.push('Redis is unavailable. Check Redis connection and configuration.');
         }
@@ -177,6 +206,7 @@ let CacheHealthChecker = CacheHealthChecker_1 = class CacheHealthChecker {
         if (health.overallLatency > 100) {
             recommendations.push('Cache latency is high. Consider optimizing cache operations or increasing resources.');
         }
+        // Statistics-based recommendations
         if (stats.hitRate < 0.5) {
             recommendations.push('Cache hit rate is low. Review cache TTL and key patterns.');
         }

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