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

package/redis-lock/lock-heartbeat.service.js

@@ -0,0 +1,232 @@
+"use strict";
+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);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var LockHeartbeatService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LockHeartbeatService = void 0;
+const common_1 = require("@nestjs/common");
+/**
+ * Lock heartbeat service
+ *
+ * Provides heartbeat mechanism for distributed lock instances.
+ * Each instance sends periodic heartbeats to Redis to indicate it's alive.
+ * Dead instances can be detected by checking if their heartbeat has expired.
+ *
+ * @example
+ * ```typescript
+ * constructor(private heartbeatService: LockHeartbeatService) {}
+ *
+ * async isInstanceAlive(instanceId: string): Promise<boolean> {
+ *   return this.heartbeatService.isInstanceAlive(instanceId);
+ * }
+ * ```
+ */
+let LockHeartbeatService = LockHeartbeatService_1 = class LockHeartbeatService {
+    constructor() {
+        this.logger = new common_1.Logger(LockHeartbeatService_1.name);
+        this.redis = null;
+        this.heartbeatTimer = null;
+        /**
+         * Heartbeat interval in milliseconds
+         * @default 5000 (5 seconds) - reduced for faster failure detection
+         */
+        this.heartbeatInterval = 5000;
+        /**
+         * Heartbeat TTL in seconds (3x interval for safety)
+         * @default 15 (15 seconds) - adjusted to match new interval
+         */
+        this.heartbeatTtl = 15;
+        this.instanceId = this.getInstanceId();
+    }
+    onModuleInit() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.redis) {
+                this.logger.warn('LockHeartbeatService initialized but no Redis client provided. Heartbeat functionality will not work.');
+                return;
+            }
+            // Send initial heartbeat
+            yield this.sendHeartbeat();
+            // Start periodic heartbeat
+            this.heartbeatTimer = setInterval(() => {
+                this.sendHeartbeat().catch((error) => {
+                    this.logger.error('Failed to send heartbeat:', error);
+                });
+            }, this.heartbeatInterval);
+            this.logger.log(`Heartbeat started for instance: ${this.instanceId}`);
+        });
+    }
+    onModuleDestroy() {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Stop heartbeat timer
+            if (this.heartbeatTimer) {
+                clearInterval(this.heartbeatTimer);
+                this.heartbeatTimer = null;
+            }
+            // Remove heartbeat record
+            yield this.removeHeartbeat();
+            this.logger.log('Heartbeat stopped');
+        });
+    }
+    /**
+     * Set Redis client (required for dependency injection)
+     */
+    setRedisClient(redis) {
+        this.redis = redis;
+        this.logger.log('Redis client set for LockHeartbeatService');
+    }
+    /**
+     * Send heartbeat to Redis
+     * Stores instance information with TTL
+     */
+    sendHeartbeat() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.redis) {
+                return;
+            }
+            const key = `heartbeat:${this.instanceId}`;
+            const data = {
+                instanceId: this.instanceId,
+                timestamp: Date.now(),
+                pid: process.pid,
+            };
+            try {
+                // Set heartbeat with TTL (3x interval for safety)
+                yield this.redis.setex(key, this.heartbeatTtl, JSON.stringify(data));
+            }
+            catch (error) {
+                this.logger.error('Error sending heartbeat:', error);
+            }
+        });
+    }
+    /**
+     * Remove heartbeat record from Redis
+     */
+    removeHeartbeat() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.redis) {
+                return;
+            }
+            const key = `heartbeat:${this.instanceId}`;
+            try {
+                yield this.redis.del(key);
+            }
+            catch (error) {
+                this.logger.error('Error removing heartbeat:', error);
+            }
+        });
+    }
+    /**
+     * Check if an instance is alive by checking its heartbeat
+     *
+     * @param instanceId - Instance identifier to check
+     * @returns True if instance is alive (heartbeat exists), false otherwise
+     */
+    isInstanceAlive(instanceId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.redis) {
+                this.logger.warn('Redis client not available, cannot check instance status');
+                return false;
+            }
+            const key = `heartbeat:${instanceId}`;
+            try {
+                const exists = yield this.redis.exists(key);
+                return exists === 1;
+            }
+            catch (error) {
+                this.logger.error(`Error checking instance ${instanceId} status:`, error);
+                return false;
+            }
+        });
+    }
+    /**
+     * Get heartbeat information for an instance
+     *
+     * @param instanceId - Instance identifier
+     * @returns Heartbeat data or null if not found
+     */
+    getHeartbeatInfo(instanceId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.redis) {
+                return null;
+            }
+            const key = `heartbeat:${instanceId}`;
+            try {
+                const data = yield this.redis.get(key);
+                if (!data) {
+                    return null;
+                }
+                return JSON.parse(data);
+            }
+            catch (error) {
+                this.logger.error(`Error getting heartbeat info for ${instanceId}:`, error);
+                return null;
+            }
+        });
+    }
+    /**
+     * Get all active instances (with heartbeat)
+     *
+     * **Note**: Uses SCAN command to avoid blocking Redis in production.
+     *
+     * @returns Array of instance IDs that are currently alive
+     */
+    getActiveInstances() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.redis) {
+                return [];
+            }
+            try {
+                let cursor = '0';
+                const pattern = 'heartbeat:*';
+                const allKeys = [];
+                // Use SCAN to iterate through keys without blocking Redis
+                do {
+                    const [nextCursor, keys] = yield this.redis.scan(cursor, 'MATCH', pattern, 'COUNT', 100);
+                    cursor = nextCursor;
+                    allKeys.push(...keys);
+                } while (cursor !== '0');
+                return allKeys.map((key) => key.replace('heartbeat:', ''));
+            }
+            catch (error) {
+                this.logger.error('Error getting active instances:', error);
+                return [];
+            }
+        });
+    }
+    /**
+     * Get current instance ID
+     */
+    getInstanceId() {
+        // 1. Kubernetes Pod name
+        if (process.env.HOSTNAME) {
+            return process.env.HOSTNAME;
+        }
+        // 2. Custom instance ID
+        if (process.env.INSTANCE_ID) {
+            return process.env.INSTANCE_ID;
+        }
+        // 3. Generate unique ID
+        return `instance-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+    }
+};
+exports.LockHeartbeatService = LockHeartbeatService;
+exports.LockHeartbeatService = LockHeartbeatService = LockHeartbeatService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [])
+], LockHeartbeatService);

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;

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,84 @@
 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;
+    /**
+     * Enable automatic lock cleanup on startup
+     * This includes heartbeat mechanism and comprehensive cleanup
+     * @default true
+     */
+    enableCleanup?: boolean;
 }
+/**
+ * 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[];