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

package/redis-lock/redis-lock.decorator.js

@@ -17,14 +17,47 @@ exports.UseRedisLockSmart = UseRedisLockSmart;
 exports.UseRedisLockOrSkipSmart = UseRedisLockOrSkipSmart;
 const common_1 = require("@nestjs/common");
 const redis_lock_service_1 = require("./redis-lock.service");
+/**
+ * Global LockService instance holder
+ * Will be set by RedisLockModule during initialization
+ */
 let globalLockService = null;
+/**
+ * Set global LockService instance
+ * Called by RedisLockModule during initialization
+ */
 function setLockService(lockService) {
     globalLockService = lockService;
+    // Also set the global instance in the service for backward compatibility
     redis_lock_service_1.RedisLockService.setGlobalInstance(lockService);
 }
+/**
+ * Get global LockService instance
+ */
 function getLockService() {
     return globalLockService;
 }
+/**
+ * Method decorator that wraps the method execution with a distributed Redis lock
+ *
+ * This decorator automatically acquires a lock before executing the method
+ * and releases it afterwards. If the lock cannot be acquired, the method
+ * execution is skipped and returns null (or the value specified in skipReturnValue).
+ *
+ * @param lockKey - The Redis lock key (required)
+ * @param options - Lock options
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * class MyService {
+ *   @UseRedisLock('my-task', { ttl: 60000 })
+ *   async processTask() {
+ *     // This will only execute if the lock is acquired
+ *   }
+ * }
+ * ```
+ */
 function UseRedisLock(lockKey, options = {}) {
     return function (target, propertyKey, descriptor) {
         const originalMethod = descriptor.value;
@@ -32,8 +65,11 @@ function UseRedisLock(lockKey, options = {}) {
         descriptor.value = function (...args) {
             return __awaiter(this, void 0, void 0, function* () {
                 var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
+                // Try to get the injected lock service first
                 let lockService = getLockService();
+                // If no injected service, fall back to global instance
                 if (!lockService) {
+                    // Import the service class to get global instance
                     const { RedisLockService } = yield Promise.resolve().then(() => require('./redis-lock.service'));
                     lockService = RedisLockService.getGlobalInstance();
                     if (!lockService) {
@@ -43,6 +79,7 @@ function UseRedisLock(lockKey, options = {}) {
                 }
                 const skipReturnValue = (_b = options.skipReturnValue) !== null && _b !== void 0 ? _b : null;
                 try {
+                    // Try to acquire the lock
                     const lockResult = yield lockService.acquireLock(lockKey, options);
                     if (!lockResult.acquired) {
                         logger.log(`Lock '${lockKey}' is already held, skipping execution of ${String(propertyKey)}`);
@@ -50,6 +87,7 @@ function UseRedisLock(lockKey, options = {}) {
                     }
                     logger.debug(`Lock '${lockKey}' acquired, executing ${String(propertyKey)}`);
                     try {
+                        // Execute the original method
                         return yield originalMethod.apply(this, args);
                     }
                     catch (error) {
@@ -57,19 +95,23 @@ function UseRedisLock(lockKey, options = {}) {
                         throw error;
                     }
                     finally {
+                        // Clear auto-extension timer if it exists
                         if (lockResult.autoExtendTimer) {
                             clearInterval(lockResult.autoExtendTimer);
                         }
+                        // Always release the lock
                         yield lockService.releaseLock(lockKey, lockResult.lockValue, options.keyPrefix);
                         logger.debug(`Lock '${lockKey}' released`);
                     }
                 }
                 catch (error) {
+                    // Handle Redis client not configured errors gracefully
                     if ((_c = error.message) === null || _c === void 0 ? void 0 : _c.includes('requires a Redis client to be set')) {
                         logger.error(`Redis client not configured for RedisLock in ${lockKey}: ${error.message}. ` +
                             `Skipping execution to prevent issues.`);
                         return skipReturnValue;
                     }
+                    // Handle Redis connection errors gracefully
                     if (((_d = error.message) === null || _d === void 0 ? void 0 : _d.includes('ECONNREFUSED')) ||
                         ((_e = error.message) === null || _e === void 0 ? void 0 : _e.includes('ECONNRESET')) ||
                         ((_f = error.message) === null || _f === void 0 ? void 0 : _f.includes('ETIMEDOUT')) ||
@@ -82,6 +124,7 @@ function UseRedisLock(lockKey, options = {}) {
                             `Skipping execution to prevent issues.`);
                         return skipReturnValue;
                     }
+                    // Handle Redis server errors (e.g., Redis crashed or restarted)
                     if (((_j = error.message) === null || _j === void 0 ? void 0 : _j.includes('READONLY')) ||
                         ((_k = error.message) === null || _k === void 0 ? void 0 : _k.includes('LOADING')) ||
                         ((_l = error.message) === null || _l === void 0 ? void 0 : _l.includes('MASTERDOWN')) ||
@@ -90,11 +133,13 @@ function UseRedisLock(lockKey, options = {}) {
                             `Skipping execution to prevent issues.`);
                         return skipReturnValue;
                     }
+                    // Handle network errors
                     if (((_o = error.message) === null || _o === void 0 ? void 0 : _o.includes('getaddrinfo')) || error.code === 'EAI_AGAIN') {
                         logger.error(`Network error connecting to Redis in ${lockKey}: ${error.message}. ` +
                             `Skipping execution to prevent issues.`);
                         return skipReturnValue;
                     }
+                    // For any other errors, log and rethrow
                     logger.error(`Unexpected error in RedisLock for ${lockKey}: ${error.message}`, error.stack);
                     throw error;
                 }
@@ -103,20 +148,95 @@ function UseRedisLock(lockKey, options = {}) {
         return descriptor;
     };
 }
+/**
+ * Simplified decorator for methods that should skip execution if lock cannot be acquired
+ * Returns false when skipped, true when executed successfully
+ *
+ * @param lockKey - The Redis lock key (required)
+ * @param ttl - Lock TTL in milliseconds (default: 300000 / 5 minutes)
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * class MyScheduler {
+ *   @Cron('0 * * * *')
+ *   @UseRedisLockOrSkip('hourly-task', 3600000)
+ *   async hourlyTask() {
+ *     // This will only execute on one instance
+ *   }
+ * }
+ * ```
+ */
 function UseRedisLockOrSkip(lockKey, ttl = 300000) {
     return UseRedisLock(lockKey, {
         ttl,
         skipReturnValue: false,
     });
 }
+/**
+ * Smart decorator that auto-generates lock key from class and method name
+ * Lock key format: ClassName:methodName
+ *
+ * This decorator is useful for simple cases where you don't need custom lock keys.
+ *
+ * @param options - Lock options
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * class MyService {
+ *   // Lock key will be auto-generated as "MyService:processData"
+ *   @UseRedisLockSmart({ ttl: 60000 })
+ *   async processData() {
+ *     // Business logic
+ *   }
+ *
+ *   // With strategy
+ *   @UseRedisLockSmart({
+ *     ttl: 120000,
+ *     strategy: LockStrategy.WAIT,
+ *     waitTimeout: 60000,
+ *   })
+ *   async generateReport() {
+ *     // Business logic
+ *   }
+ * }
+ * ```
+ */
 function UseRedisLockSmart(options = {}) {
     return function (target, propertyKey, descriptor) {
+        // Auto-generate lock key from class and method name
         const className = target.constructor.name;
         const methodName = String(propertyKey);
         const lockKey = `${className}:${methodName}`;
+        // Apply the original UseRedisLock decorator with auto-generated key
         return UseRedisLock(lockKey, options)(target, propertyKey, descriptor);
     };
 }
+/**
+ * Smart decorator for simple skip-on-busy scenarios with auto-generated lock key
+ * Lock key format: ClassName:methodName
+ *
+ * @param ttl - Lock TTL in milliseconds (default: 300000 / 5 minutes)
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * class MyScheduler {
+ *   @Cron('0 * * * *')
+ *   @UseRedisLockOrSkipSmart(3600000) // 1 hour TTL
+ *   async hourlyTask() {
+ *     // Lock key: "MyScheduler:hourlyTask"
+ *   }
+ *
+ *   @Cron('0 0 * * *')
+ *   @UseRedisLockOrSkipSmart() // Default 5 minutes TTL
+ *   async dailyTask() {
+ *     // Lock key: "MyScheduler:dailyTask"
+ *   }
+ * }
+ * ```
+ */
 function UseRedisLockOrSkipSmart(ttl = 300000) {
     return UseRedisLockSmart({
         ttl,

package/redis-lock/redis-lock.module.d.ts

@@ -1,18 +1,78 @@
 import { DynamicModule, OnModuleInit } from '@nestjs/common';
 import type { Redis } from 'ioredis';
+/**
+ * Injection token for Redis Lock Service
+ */
 export declare const REDIS_LOCK_SERVICE: unique symbol;
+/**
+ * Redis Lock module configuration options
+ */
 export interface RedisLockModuleOptions {
+    /**
+     * Whether to make the module global
+     * @default true
+     */
     isGlobal?: boolean;
+    /**
+     * Redis client instance (required)
+     * RedisLockService requires an external Redis client to function
+     */
     redisClient: Redis;
+    /**
+     * Default TTL for locks in milliseconds
+     */
     defaultTtl?: number;
+    /**
+     * Default key prefix for locks
+     */
     defaultKeyPrefix?: string;
+    /**
+     * Default retry count for lock acquisition
+     */
     defaultRetryCount?: number;
+    /**
+     * Default retry delay in milliseconds
+     */
     defaultRetryDelay?: number;
 }
+/**
+ * Redis Lock module with distributed locking support
+ *
+ * Provides RedisLockService and @UseRedisLock decorator for
+ * distributed locking mechanisms using Redis.
+ *
+ * Requires an external Redis client to function.
+ *
+ * @example
+ * ```typescript
+ * // With Redis client injection
+ * import { RedisModule } from '@songkeys/nestjs-redis';
+ *
+ * @Module({
+ *   imports: [
+ *     RedisModule.forRoot({ ... }),
+ *     RedisLockModule.forRootAsync({
+ *       imports: [RedisModule],
+ *       inject: [RedisService],
+ *       useFactory: (redisService: RedisService) => ({
+ *         redisClient: redisService.getClient()
+ *       })
+ *     })
+ *   ]
+ * })
+ * export class AppModule {}
+ * ```
+ */
 export declare class RedisLockModule implements OnModuleInit {
     private redisLockService;
     constructor();
+    /**
+     * Register Redis Lock module with options
+     */
     static forRoot(options: RedisLockModuleOptions): DynamicModule;
+    /**
+     * Register Redis Lock module asynchronously
+     */
     static forRootAsync(options: {
         imports?: any[];
         inject?: any[];

package/redis-lock/redis-lock.module.js

@@ -14,19 +14,55 @@ exports.RedisLockModule = exports.REDIS_LOCK_SERVICE = void 0;
 const common_1 = require("@nestjs/common");
 const redis_lock_service_1 = require("./redis-lock.service");
 const redis_lock_decorator_1 = require("./redis-lock.decorator");
+/**
+ * Injection token for Redis Lock Service
+ */
 exports.REDIS_LOCK_SERVICE = Symbol('REDIS_LOCK_SERVICE');
+/**
+ * Redis Lock module with distributed locking support
+ *
+ * Provides RedisLockService and @UseRedisLock decorator for
+ * distributed locking mechanisms using Redis.
+ *
+ * Requires an external Redis client to function.
+ *
+ * @example
+ * ```typescript
+ * // With Redis client injection
+ * import { RedisModule } from '@songkeys/nestjs-redis';
+ *
+ * @Module({
+ *   imports: [
+ *     RedisModule.forRoot({ ... }),
+ *     RedisLockModule.forRootAsync({
+ *       imports: [RedisModule],
+ *       inject: [RedisService],
+ *       useFactory: (redisService: RedisService) => ({
+ *         redisClient: redisService.getClient()
+ *       })
+ *     })
+ *   ]
+ * })
+ * export class AppModule {}
+ * ```
+ */
 let RedisLockModule = RedisLockModule_1 = class RedisLockModule {
     constructor() { }
+    /**
+     * Register Redis Lock module with options
+     */
     static forRoot(options) {
         const { isGlobal = true, redisClient, defaultTtl, defaultKeyPrefix, defaultRetryCount, defaultRetryDelay, } = options;
         return {
             module: RedisLockModule_1,
             global: isGlobal,
             providers: [
+                // Redis client provider
                 {
                     provide: 'REDIS_LOCK_CLIENT',
                     useValue: redisClient,
                 },
+                // Redis Lock Service
                 {
                     provide: exports.REDIS_LOCK_SERVICE,
                     useFactory: () => {
@@ -47,6 +83,7 @@ let RedisLockModule = RedisLockModule_1 = class RedisLockModule {
                         return service;
                     },
                 },
+                // Also provide the service class itself for direct injection
                 {
                     provide: redis_lock_service_1.RedisLockService,
                     useExisting: exports.REDIS_LOCK_SERVICE,
@@ -55,6 +92,9 @@ let RedisLockModule = RedisLockModule_1 = class RedisLockModule {
             exports: [exports.REDIS_LOCK_SERVICE, redis_lock_service_1.RedisLockService],
         };
     }
+    /**
+     * Register Redis Lock module asynchronously
+     */
     static forRootAsync(options) {
         var _a;
         return {
@@ -62,16 +102,19 @@ let RedisLockModule = RedisLockModule_1 = class RedisLockModule {
             global: (_a = options.isGlobal) !== null && _a !== void 0 ? _a : true,
             imports: options.imports || [],
             providers: [
+                // Async options provider
                 {
                     provide: 'REDIS_LOCK_MODULE_OPTIONS',
                     useFactory: options.useFactory,
                     inject: options.inject || [],
                 },
+                // Redis client provider
                 {
                     provide: 'REDIS_LOCK_CLIENT',
                     useFactory: (moduleOptions) => moduleOptions.redisClient,
                     inject: ['REDIS_LOCK_MODULE_OPTIONS'],
                 },
+                // Redis Lock Service
                 {
                     provide: exports.REDIS_LOCK_SERVICE,
                     useFactory: (moduleOptions) => {
@@ -93,6 +136,7 @@ let RedisLockModule = RedisLockModule_1 = class RedisLockModule {
                     },
                     inject: ['REDIS_LOCK_MODULE_OPTIONS'],
                 },
+                // Also provide the service class itself for direct injection
                 {
                     provide: redis_lock_service_1.RedisLockService,
                     useExisting: exports.REDIS_LOCK_SERVICE,
@@ -102,6 +146,8 @@ let RedisLockModule = RedisLockModule_1 = class RedisLockModule {
         };
     }
     onModuleInit() {
+        // Set global lock service for decorators
+        // Use the global instance that should have been created during module setup
         const globalInstance = redis_lock_service_1.RedisLockService.getGlobalInstance();
         if (globalInstance) {
             this.redisLockService = globalInstance;