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

package/redis-lock/examples/lock-strategy.examples.js

@@ -1,4 +1,9 @@
 "use strict";
+/**
+ * Lock Strategy Examples
+ *
+ * This file demonstrates the different lock acquisition strategies available in Redis Lock module.
+ */
 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);
@@ -23,18 +28,33 @@ exports.CombinedStrategiesExample = exports.WaitStrategyExample = exports.ThrowS
 const common_1 = require("@nestjs/common");
 const schedule_1 = require("@nestjs/schedule");
 const index_1 = require("../index");
+// ============================================================================
+// Strategy 1: SKIP (Default)
+// ============================================================================
+/**
+ * SKIP strategy - Skip execution if lock cannot be acquired
+ * This is the default behavior and is useful for scheduled tasks where you don't
+ * want to queue up requests if a previous execution is still running.
+ */
 let SkipStrategyExample = SkipStrategyExample_1 = class SkipStrategyExample {
     constructor(lockService) {
         this.lockService = lockService;
         this.logger = new common_1.Logger(SkipStrategyExample_1.name);
     }
+    /**
+     * Example 1: Using decorator with SKIP strategy (default)
+     */
     scheduledTask() {
         return __awaiter(this, void 0, void 0, function* () {
             this.logger.log('Executing scheduled task...');
+            // This will skip if another instance is already running
             yield this.simulateLongRunning();
             this.logger.log('Scheduled task completed');
         });
     }
+    /**
+     * Example 2: Using service directly with SKIP strategy
+     */
     processWithSkip() {
         return __awaiter(this, void 0, void 0, function* () {
             const lockResult = yield this.lockService.acquireLock('process-task', {
@@ -55,13 +75,16 @@ let SkipStrategyExample = SkipStrategyExample_1 = class SkipStrategyExample {
             }
         });
     }
+    /**
+     * Example 3: SKIP with retries
+     */
     processWithRetries() {
         return __awaiter(this, void 0, void 0, function* () {
             const lockResult = yield this.lockService.acquireLock('retry-task', {
                 strategy: index_1.LockStrategy.SKIP,
                 ttl: 30000,
-                retryCount: 3,
-                retryDelay: 500,
+                retryCount: 3, // Try 3 times
+                retryDelay: 500, // Wait 500ms between retries
             });
             if (!lockResult.acquired) {
                 this.logger.warn('Failed to acquire lock after 3 retries');
@@ -84,10 +107,11 @@ let SkipStrategyExample = SkipStrategyExample_1 = class SkipStrategyExample {
 };
 exports.SkipStrategyExample = SkipStrategyExample;
 __decorate([
-    (0, schedule_1.Cron)('* * * * *'),
+    (0, schedule_1.Cron)('* * * * *') // Every minute
+    ,
     (0, index_1.UseRedisLock)('scheduled-task', {
         ttl: 60000,
-        strategy: index_1.LockStrategy.SKIP,
+        strategy: index_1.LockStrategy.SKIP, // Can be omitted as it's the default
     }),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", []),
@@ -97,18 +121,33 @@ exports.SkipStrategyExample = SkipStrategyExample = SkipStrategyExample_1 = __de
     (0, common_1.Injectable)(),
     __metadata("design:paramtypes", [index_1.RedisLockService])
 ], SkipStrategyExample);
+// ============================================================================
+// Strategy 2: THROW
+// ============================================================================
+/**
+ * THROW strategy - Throw an error if lock cannot be acquired
+ * Use this for critical operations that must have exclusive access.
+ * If the lock cannot be acquired, an exception will be thrown.
+ */
 let ThrowStrategyExample = ThrowStrategyExample_1 = class ThrowStrategyExample {
     constructor(lockService) {
         this.lockService = lockService;
         this.logger = new common_1.Logger(ThrowStrategyExample_1.name);
     }
+    /**
+     * Example 1: Using decorator with THROW strategy
+     */
     criticalOperation() {
         return __awaiter(this, void 0, void 0, function* () {
             this.logger.log('Executing critical operation...');
+            // If lock cannot be acquired, an error will be thrown
             yield this.processData();
             this.logger.log('Critical operation completed');
         });
     }
+    /**
+     * Example 2: Using service with error handling
+     */
     processWithThrow() {
         return __awaiter(this, void 0, void 0, function* () {
             try {
@@ -127,20 +166,26 @@ let ThrowStrategyExample = ThrowStrategyExample_1 = class ThrowStrategyExample {
             }
             catch (error) {
                 this.logger.error(`Failed to acquire lock: ${error.message}`);
+                // Handle the error appropriately
                 throw new Error('Operation cannot proceed without exclusive access');
             }
         });
     }
+    /**
+     * Example 3: Critical payment processing
+     */
     processPayment(orderId, amount) {
         return __awaiter(this, void 0, void 0, function* () {
             const lockKey = `payment:${orderId}`;
             try {
+                // Must have exclusive access for payment processing
                 const lockResult = yield this.lockService.acquireLock(lockKey, {
                     strategy: index_1.LockStrategy.THROW,
                     ttl: 60000,
                 });
                 try {
                     this.logger.log(`Processing payment for order ${orderId}...`);
+                    // Payment logic here
                     yield this.chargePayment(orderId, amount);
                     yield this.updateOrderStatus(orderId, 'paid');
                     return { success: true };
@@ -162,11 +207,13 @@ let ThrowStrategyExample = ThrowStrategyExample_1 = class ThrowStrategyExample {
     }
     chargePayment(orderId, amount) {
         return __awaiter(this, void 0, void 0, function* () {
+            // Simulate payment processing
             yield new Promise((resolve) => setTimeout(resolve, 1000));
         });
     }
     updateOrderStatus(orderId, status) {
         return __awaiter(this, void 0, void 0, function* () {
+            // Update order status
             yield new Promise((resolve) => setTimeout(resolve, 500));
         });
     }
@@ -185,24 +232,39 @@ exports.ThrowStrategyExample = ThrowStrategyExample = ThrowStrategyExample_1 = _
     (0, common_1.Injectable)(),
     __metadata("design:paramtypes", [index_1.RedisLockService])
 ], ThrowStrategyExample);
+// ============================================================================
+// Strategy 3: WAIT
+// ============================================================================
+/**
+ * WAIT strategy - Block/wait until lock can be acquired
+ * Use this when you want to queue execution and ensure the operation eventually runs.
+ * The function will wait indefinitely (or until waitTimeout) for the lock to become available.
+ */
 let WaitStrategyExample = WaitStrategyExample_1 = class WaitStrategyExample {
     constructor(lockService) {
         this.lockService = lockService;
         this.logger = new common_1.Logger(WaitStrategyExample_1.name);
     }
+    /**
+     * Example 1: Using decorator with WAIT strategy
+     */
     sequentialTask() {
         return __awaiter(this, void 0, void 0, function* () {
             this.logger.log('Executing sequential task...');
+            // This will wait until lock is available
             yield this.processInOrder();
             this.logger.log('Sequential task completed');
         });
     }
+    /**
+     * Example 2: WAIT with timeout
+     */
     processWithWaitTimeout() {
         return __awaiter(this, void 0, void 0, function* () {
             const lockResult = yield this.lockService.acquireLock('wait-task', {
                 strategy: index_1.LockStrategy.WAIT,
-                waitTimeout: 30000,
-                retryDelay: 200,
+                waitTimeout: 30000, // Wait maximum 30 seconds
+                retryDelay: 200, // Check every 200ms
                 ttl: 60000,
             });
             if (!lockResult.acquired) {
@@ -219,16 +281,21 @@ let WaitStrategyExample = WaitStrategyExample_1 = class WaitStrategyExample {
             }
         });
     }
+    /**
+     * Example 3: Sequential data processing
+     * Perfect for operations that must be processed in order
+     */
     processDataSequentially(userId, data) {
         return __awaiter(this, void 0, void 0, function* () {
             const lockKey = `user-data:${userId}`;
             const lockResult = yield this.lockService.acquireLock(lockKey, {
                 strategy: index_1.LockStrategy.WAIT,
                 retryDelay: 50,
-                ttl: 120000,
+                ttl: 120000, // 2 minutes
             });
             try {
                 this.logger.log(`Processing data for user ${userId}...`);
+                // These operations will execute sequentially across all instances
                 yield this.validateData(data);
                 yield this.saveData(userId, data);
                 yield this.notifyUser(userId);
@@ -239,6 +306,10 @@ let WaitStrategyExample = WaitStrategyExample_1 = class WaitStrategyExample {
             }
         });
     }
+    /**
+     * Example 4: Queue-like behavior
+     * Multiple requests will queue and execute one by one
+     */
     processQueue(queueName, item) {
         return __awaiter(this, void 0, void 0, function* () {
             const lockKey = `queue:${queueName}`;
@@ -258,15 +329,19 @@ let WaitStrategyExample = WaitStrategyExample_1 = class WaitStrategyExample {
             }
         });
     }
+    /**
+     * Example 5: Database migration with WAIT
+     * Ensures migrations run sequentially across all instances
+     */
     runMigration(migrationName) {
         return __awaiter(this, void 0, void 0, function* () {
             const lockKey = `migration:${migrationName}`;
             this.logger.log(`Waiting to run migration ${migrationName}...`);
             const lockResult = yield this.lockService.acquireLock(lockKey, {
                 strategy: index_1.LockStrategy.WAIT,
-                waitTimeout: 300000,
-                retryDelay: 1000,
-                ttl: 600000,
+                waitTimeout: 300000, // Wait up to 5 minutes
+                retryDelay: 1000, // Check every second
+                ttl: 600000, // Hold lock for 10 minutes max
             });
             if (!lockResult.acquired) {
                 throw new Error(`Migration ${migrationName} timed out waiting for lock`);
@@ -318,7 +393,7 @@ __decorate([
     (0, index_1.UseRedisLock)('sequential-task', {
         ttl: 30000,
         strategy: index_1.LockStrategy.WAIT,
-        retryDelay: 100,
+        retryDelay: 100, // Check every 100ms
     }),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", []),
@@ -328,16 +403,50 @@ exports.WaitStrategyExample = WaitStrategyExample = WaitStrategyExample_1 = __de
     (0, common_1.Injectable)(),
     __metadata("design:paramtypes", [index_1.RedisLockService])
 ], WaitStrategyExample);
+// ============================================================================
+// Comparison: When to use each strategy
+// ============================================================================
+/**
+ * USE SKIP WHEN:
+ * - Running scheduled tasks where you don't want overlapping executions
+ * - Cron jobs that should skip if previous run is still in progress
+ * - Non-critical background tasks
+ * - Operations where it's okay to skip if busy
+ *
+ * USE THROW WHEN:
+ * - Critical operations that require exclusive access
+ * - Financial transactions
+ * - Operations where failure to acquire lock is an error
+ * - When you want to alert/fail fast if resource is busy
+ *
+ * USE WAIT WHEN:
+ * - Operations that must execute eventually
+ * - Sequential processing requirements
+ * - Queue-like behavior needed
+ * - Database migrations
+ * - Operations where order matters
+ * - When you want to ensure the operation runs (with optional timeout)
+ */
+/**
+ * Example: Combining strategies in a single service
+ */
 let CombinedStrategiesExample = CombinedStrategiesExample_1 = class CombinedStrategiesExample {
     constructor(lockService) {
         this.lockService = lockService;
         this.logger = new common_1.Logger(CombinedStrategiesExample_1.name);
     }
+    /**
+     * Background cleanup - SKIP if already running
+     */
     cleanupOldData() {
         return __awaiter(this, void 0, void 0, function* () {
             this.logger.log('Running cleanup...');
+            // Cleanup logic
         });
     }
+    /**
+     * Payment processing - THROW if cannot get exclusive access
+     */
     processPayment(orderId) {
         return __awaiter(this, void 0, void 0, function* () {
             const lockResult = yield this.lockService.acquireLock(`payment:${orderId}`, {
@@ -345,24 +454,29 @@ let CombinedStrategiesExample = CombinedStrategiesExample_1 = class CombinedStra
                 ttl: 60000,
             });
             try {
+                // Payment logic
             }
             finally {
                 yield this.lockService.releaseLock(`payment:${orderId}`, lockResult.lockValue);
             }
         });
     }
+    /**
+     * Report generation - WAIT to ensure it runs eventually
+     */
     generateReport(reportId) {
         return __awaiter(this, void 0, void 0, function* () {
             const lockResult = yield this.lockService.acquireLock(`report:${reportId}`, {
                 strategy: index_1.LockStrategy.WAIT,
-                waitTimeout: 180000,
+                waitTimeout: 180000, // Wait up to 3 minutes
                 retryDelay: 500,
-                ttl: 300000,
+                ttl: 300000, // 5 minutes
             });
             if (!lockResult.acquired) {
                 throw new Error('Report generation timed out');
             }
             try {
+                // Report generation logic
             }
             finally {
                 yield this.lockService.releaseLock(`report:${reportId}`, lockResult.lockValue);
@@ -372,10 +486,11 @@ let CombinedStrategiesExample = CombinedStrategiesExample_1 = class CombinedStra
 };
 exports.CombinedStrategiesExample = CombinedStrategiesExample;
 __decorate([
-    (0, schedule_1.Cron)('0 */6 * * *'),
+    (0, schedule_1.Cron)('0 */6 * * *') // Every 6 hours
+    ,
     (0, index_1.UseRedisLock)('cleanup-task', {
         strategy: index_1.LockStrategy.SKIP,
-        ttl: 3600000,
+        ttl: 3600000, // 1 hour
     }),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", []),

package/redis-lock/index.js

@@ -1,12 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getLockService = exports.setLockService = exports.UseRedisLockOrSkipSmart = exports.UseRedisLockSmart = exports.UseRedisLockOrSkip = exports.UseRedisLock = exports.LockStrategy = exports.RedisLockService = exports.REDIS_LOCK_SERVICE = exports.RedisLockModule = void 0;
+// Module
 var redis_lock_module_1 = require("./redis-lock.module");
 Object.defineProperty(exports, "RedisLockModule", { enumerable: true, get: function () { return redis_lock_module_1.RedisLockModule; } });
 Object.defineProperty(exports, "REDIS_LOCK_SERVICE", { enumerable: true, get: function () { return redis_lock_module_1.REDIS_LOCK_SERVICE; } });
+// Service
 var redis_lock_service_1 = require("./redis-lock.service");
 Object.defineProperty(exports, "RedisLockService", { enumerable: true, get: function () { return redis_lock_service_1.RedisLockService; } });
 Object.defineProperty(exports, "LockStrategy", { enumerable: true, get: function () { return redis_lock_service_1.LockStrategy; } });
+// Decorators
 var redis_lock_decorator_1 = require("./redis-lock.decorator");
 Object.defineProperty(exports, "UseRedisLock", { enumerable: true, get: function () { return redis_lock_decorator_1.UseRedisLock; } });
 Object.defineProperty(exports, "UseRedisLockOrSkip", { enumerable: true, get: function () { return redis_lock_decorator_1.UseRedisLockOrSkip; } });

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

@@ -1,12 +1,113 @@
 import type { LockOptions } from './redis-lock.service';
 import { RedisLockService } from './redis-lock.service';
+/**
+ * Set global LockService instance
+ * Called by RedisLockModule during initialization
+ */
 export declare function setLockService(lockService: RedisLockService): void;
+/**
+ * Get global LockService instance
+ */
 export declare function getLockService(): RedisLockService | null;
+/**
+ * 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
+ *   }
+ * }
+ * ```
+ */
 export declare function UseRedisLock(lockKey: string, options?: LockOptions & {
     skipReturnValue?: any;
 }): MethodDecorator;
+/**
+ * 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
+ *   }
+ * }
+ * ```
+ */
 export declare function UseRedisLockOrSkip(lockKey: string, ttl?: number): MethodDecorator;
+/**
+ * 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
+ *   }
+ * }
+ * ```
+ */
 export declare function UseRedisLockSmart(options?: LockOptions & {
     skipReturnValue?: any;
 }): MethodDecorator;
+/**
+ * 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"
+ *   }
+ * }
+ * ```
+ */
 export declare function UseRedisLockOrSkipSmart(ttl?: number): MethodDecorator;