@nest-omni/core 4.1.3-0 → 4.1.3-10

package/setup/schedule.decorator.d.ts

@@ -1,23 +1,250 @@
+/**
+ * Enhanced Schedule Decorators for Worker Mode
+ *
+ * This module provides decorators for scheduled tasks that:
+ * - Only run in Worker or Hybrid mode (not in HTTP-only mode)
+ * - Support distributed locking via Redis
+ * - Support retry logic for failed tasks
+ * - Provide automatic lock key generation
+ * - Support task execution logging and error handling
+ */
 import type { CronOptions } from '@nestjs/schedule';
+/**
+ * Options for schedule decorators with lock support
+ */
 export interface ScheduleWithLockOptions {
+    /**
+     * Lock TTL in milliseconds
+     * For Cron: defaults to 3600000 (1 hour)
+     * For Interval: defaults to 80% of interval duration
+     * For Timeout: defaults to 300000 (5 minutes)
+     */
     lockTtl?: number;
+    /**
+     * Number of retry attempts if task fails
+     * @default 0
+     */
     retryCount?: number;
+    /**
+     * Delay between retry attempts in milliseconds
+     * @default 1000
+     */
     retryDelay?: number;
+    /**
+     * Whether to use exponential backoff for retries
+     * @default false
+     */
     useExponentialBackoff?: boolean;
+    /**
+     * Maximum retry delay in milliseconds (for exponential backoff)
+     * @default 60000 (1 minute)
+     */
     maxRetryDelay?: number;
+    /**
+     * Whether to log task execution
+     * @default true
+     */
     logExecution?: boolean;
+    /**
+     * Custom lock key prefix
+     * @default 'schedule'
+     */
     lockKeyPrefix?: string;
+    /**
+     * Automatic lock extension interval in milliseconds
+     * If set, the lock will be automatically extended at this interval
+     * @default 0 (no automatic extension)
+     */
     autoExtendLock?: number;
+    /**
+     * Callback function when task execution succeeds
+     */
     onSuccess?: (duration: number) => void | Promise<void>;
+    /**
+     * Callback function when task execution fails
+     */
     onError?: (error: Error) => void | Promise<void>;
+    /**
+     * Whether to skip execution if lock cannot be acquired
+     * @default true
+     */
     skipIfLocked?: boolean;
 }
+/**
+ * Cron decorator that only executes in Worker or Hybrid mode
+ *
+ * @param cronTime - Cron expression
+ * @param options - Cron options
+ *
+ * @example
+ * ```typescript
+ * @WorkerCron('0 0 * * *') // Run daily at midnight
+ * async dailyTask() {
+ *   // Task logic
+ * }
+ * ```
+ */
 export declare function WorkerCron(cronTime: string | Date, options?: CronOptions): MethodDecorator;
+/**
+ * Interval decorator that only executes in Worker or Hybrid mode
+ *
+ * @param timeout - Interval in milliseconds
+ * @param name - Optional name for the interval
+ *
+ * @example
+ * ```typescript
+ * @WorkerInterval(60000) // Run every minute
+ * async minutelyTask() {
+ *   // Task logic
+ * }
+ * ```
+ */
 export declare function WorkerInterval(timeout: number, name?: string): MethodDecorator;
+/**
+ * Timeout decorator that only executes in Worker or Hybrid mode
+ *
+ * @param timeout - Timeout in milliseconds
+ * @param name - Optional name for the timeout
+ *
+ * @example
+ * ```typescript
+ * @WorkerTimeout(5000) // Run once after 5 seconds
+ * async startupTask() {
+ *   // Task logic
+ * }
+ * ```
+ */
 export declare function WorkerTimeout(timeout: number, name?: string): MethodDecorator;
+/**
+ * Cron decorator with distributed lock support
+ * Automatically generates lock key from class and method name
+ *
+ * @param cronTime - Cron expression
+ * @param lockKeyOrOptions - Lock key (string) or options object
+ * @param lockTtl - Lock TTL in milliseconds (only if lockKeyOrOptions is a string)
+ *
+ * @param cronOptions
+ * @example
+ * ```typescript
+ * // Using string lock key
+ * @WorkerCronWithLock('0 * * * *', 'hourly-task', 3600000)
+ * async hourlyTask() {
+ *   // Task logic
+ * }
+ *
+ * // Using options object (auto-generates lock key)
+ * @WorkerCronWithLock('0 * * * *', { lockTtl: 3600000, retryCount: 3 })
+ * async hourlyTask() {
+ *   // Task logic
+ * }
+ * ```
+ */
 export declare function WorkerCronWithLock(cronTime: string | Date, lockKeyOrOptions: string | ScheduleWithLockOptions, lockTtl?: number, cronOptions?: CronOptions): MethodDecorator;
+/**
+ * Interval decorator with distributed lock support
+ *
+ * @param timeout - Interval in milliseconds
+ * @param lockKeyOrOptions - Lock key (string) or options object
+ * @param lockTtl - Lock TTL in milliseconds (only if lockKeyOrOptions is a string)
+ *
+ * @example
+ * ```typescript
+ * // Using string lock key
+ * @WorkerIntervalWithLock(60000, 'status-check', 50000)
+ * async checkStatus() {
+ *   // Task logic
+ * }
+ *
+ * // Using options object (auto-generates lock key)
+ * @WorkerIntervalWithLock(60000, { retryCount: 2 })
+ * async checkStatus() {
+ *   // Task logic
+ * }
+ * ```
+ */
 export declare function WorkerIntervalWithLock(timeout: number, lockKeyOrOptions: string | ScheduleWithLockOptions, lockTtl?: number): MethodDecorator;
+/**
+ * Timeout decorator with distributed lock support
+ *
+ * @param timeout - Timeout in milliseconds
+ * @param lockKeyOrOptions - Lock key (string) or options object
+ * @param lockTtl - Lock TTL in milliseconds (only if lockKeyOrOptions is a string)
+ *
+ * @example
+ * ```typescript
+ * // Using string lock key
+ * @WorkerTimeoutWithLock(5000, 'init-task', 10000)
+ * async initializeSystem() {
+ *   // Task logic
+ * }
+ *
+ * // Using options object (auto-generates lock key)
+ * @WorkerTimeoutWithLock(5000, { lockTtl: 10000 })
+ * async initializeSystem() {
+ *   // Task logic
+ * }
+ * ```
+ */
 export declare function WorkerTimeoutWithLock(timeout: number, lockKeyOrOptions: string | ScheduleWithLockOptions, lockTtl?: number): MethodDecorator;
+/**
+ * Smart Cron decorator with auto-generated lock key and intelligent defaults
+ * Recommended for most use cases
+ *
+ * @param cronTime - Cron expression
+ * @param options - Schedule options
+ *
+ * @example
+ * ```typescript
+ * @WorkerCronSmart('0 * * * *') // Run hourly with auto-generated lock key
+ * async hourlyTask() {
+ *   // Task logic
+ * }
+ *
+ * @WorkerCronSmart('0 0 * * *', {
+ *   lockTtl: 7200000, // 2 hours
+ *   retryCount: 3,
+ *   onError: (error) => console.error('Task failed:', error),
+ * })
+ * async dailyTask() {
+ *   // Task logic
+ * }
+ * ```
+ */
 export declare function WorkerCronSmart(cronTime: string | Date, options?: ScheduleWithLockOptions, cronOptions?: CronOptions): MethodDecorator;
+/**
+ * Smart Interval decorator with auto-generated lock key and intelligent defaults
+ * Lock TTL is automatically set to 80% of interval duration
+ *
+ * @param timeout - Interval in milliseconds
+ * @param options - Schedule options
+ *
+ * @example
+ * ```typescript
+ * @WorkerIntervalSmart(120000) // Run every 2 minutes, lock for ~1.6 minutes
+ * async checkStatus() {
+ *   // Task logic
+ * }
+ * ```
+ */
 export declare function WorkerIntervalSmart(timeout: number, options?: ScheduleWithLockOptions): MethodDecorator;
+/**
+ * Advanced Cron decorator with full control
+ * Alias for WorkerCronSmart with explicit lock key parameter
+ *
+ * @param cronTime - Cron expression
+ * @param lockKeyOrOptions - Lock key (string) or options object
+ * @param options - Schedule options (only if lockKeyOrOptions is a string)
+ *
+ * @example
+ * ```typescript
+ * @WorkerCronAdvanced('0 0 * * *', 'daily-report', {
+ *   lockTtl: 7200000,
+ *   retryCount: 5,
+ *   useExponentialBackoff: true,
+ * })
+ * async generateDailyReport() {
+ *   // Task logic
+ * }
+ * ```
+ */
 export declare function WorkerCronAdvanced(cronTime: string | Date, lockKeyOrOptions: string | ScheduleWithLockOptions, options?: ScheduleWithLockOptions, cronOptions?: CronOptions): MethodDecorator;

package/setup/schedule.decorator.js

@@ -1,4 +1,14 @@
 "use strict";
+/**
+ * Enhanced Schedule Decorators for Worker Mode
+ *
+ * This module provides decorators for scheduled tasks that:
+ * - Only run in Worker or Hybrid mode (not in HTTP-only mode)
+ * - Support distributed locking via Redis
+ * - Support retry logic for failed tasks
+ * - Provide automatic lock key generation
+ * - Support task execution logging and error handling
+ */
 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) {
@@ -21,10 +31,16 @@ exports.WorkerCronAdvanced = WorkerCronAdvanced;
 const common_1 = require("@nestjs/common");
 const schedule_1 = require("@nestjs/schedule");
 const mode_setup_1 = require("./mode.setup");
-const redis_lock_service_1 = require("../redis-lock/redis-lock.service");
+const redis_lock_1 = require("../redis-lock");
+/**
+ * Generate a lock key from class name and method name
+ */
 function generateLockKey(className, methodName) {
     return `${className}.${methodName}`;
 }
+/**
+ * Execute a function with retry logic
+ */
 function executeWithRetry(fn, options) {
     return __awaiter(this, void 0, void 0, function* () {
         const { retryCount = 0, retryDelay = 1000, useExponentialBackoff = false, maxRetryDelay = 60000, logger, taskName, } = options;
@@ -51,41 +67,55 @@ function executeWithRetry(fn, options) {
         throw lastError;
     });
 }
+/**
+ * Base decorator creator for worker-mode tasks
+ */
 function createWorkerDecorator(baseDecorator, decoratorName) {
     return function (target, propertyKey, descriptor) {
         const originalMethod = descriptor.value;
         descriptor.value = function (...args) {
             return __awaiter(this, void 0, void 0, function* () {
+                // Only execute in worker or hybrid mode
                 if (!(0, mode_setup_1.shouldProcessQueues)()) {
                     return;
                 }
                 return originalMethod.apply(this, args);
             });
         };
+        // Apply the base decorator
         baseDecorator(target, propertyKey, descriptor);
         return descriptor;
     };
 }
+/**
+ * Create a worker decorator with lock support
+ */
 function createWorkerDecoratorWithLock(baseDecorator, decoratorName, lockKey, options = {}) {
     return function (target, propertyKey, descriptor) {
         const originalMethod = descriptor.value;
         const className = target.constructor.name;
         const methodName = String(propertyKey);
         const logger = new common_1.Logger(`${className}.${methodName}`);
+        // Resolve lock key
         const resolvedLockKey = typeof lockKey === 'function' ? lockKey() : lockKey;
         descriptor.value = function (...args) {
             return __awaiter(this, void 0, void 0, function* () {
+                // Only execute in worker or hybrid mode
                 if (!(0, mode_setup_1.shouldProcessQueues)()) {
                     return;
                 }
-                const lockService = redis_lock_service_1.RedisLockService.getOrCreateGlobalInstance();
-                const { lockTtl = 3600000, retryCount = 0, retryDelay = 1000, useExponentialBackoff = false, maxRetryDelay = 60000, logExecution = true, lockKeyPrefix = 'schedule', autoExtendLock = 0, onSuccess, onError, skipIfLocked = true, } = options;
+                // Get or create global instance - auto-configures from environment variables
+                const lockService = redis_lock_1.RedisLockService.getOrCreateGlobalInstance();
+                const { lockTtl = 3600000, // 1 hour default
+                retryCount = 0, retryDelay = 1000, useExponentialBackoff = false, maxRetryDelay = 60000, logExecution = true, lockKeyPrefix = 'schedule', autoExtendLock = 0, onSuccess, onError, skipIfLocked = true, } = options;
                 const fullLockKey = `${lockKeyPrefix}:${resolvedLockKey}`;
                 const startTime = Date.now();
+                // Log task start
                 if (logExecution) {
                     logger.log(`Task starting...`);
                 }
                 try {
+                    // Acquire lock
                     const lockResult = yield lockService.acquireLock(resolvedLockKey, {
                         ttl: lockTtl,
                         keyPrefix: lockKeyPrefix,
@@ -101,6 +131,7 @@ function createWorkerDecoratorWithLock(baseDecorator, decoratorName, lockKey, op
                         }
                     }
                     try {
+                        // Execute with retry logic
                         const result = yield executeWithRetry(() => originalMethod.apply(this, args), {
                             retryCount,
                             retryDelay,
@@ -113,15 +144,18 @@ function createWorkerDecoratorWithLock(baseDecorator, decoratorName, lockKey, op
                         if (logExecution) {
                             logger.log(`Task completed successfully in ${duration}ms`);
                         }
+                        // Call success callback with proper this context
                         if (onSuccess) {
                             yield onSuccess.call(this, duration);
                         }
                         return result;
                     }
                     finally {
+                        // Clear auto-extension timer if it exists
                         if (lockResult.autoExtendTimer) {
                             clearInterval(lockResult.autoExtendTimer);
                         }
+                        // Always release the lock
                         yield lockService.releaseLock(resolvedLockKey, lockResult.lockValue, lockKeyPrefix);
                         if (logExecution) {
                             logger.debug(`Lock "${fullLockKey}" released`);
@@ -130,9 +164,9 @@ function createWorkerDecoratorWithLock(baseDecorator, decoratorName, lockKey, op
                 }
                 catch (error) {
                     const duration = Date.now() - startTime;
-                    if (logExecution) {
-                        logger.error(`Task failed after ${duration}ms: ${error.message}`, error.stack);
-                    }
+                    // Always log errors regardless of logExecution setting
+                    logger.error(`Task failed after ${duration}ms: ${error.message}`, error.stack);
+                    // Call error callback with proper this context
                     if (onError) {
                         yield onError.call(this, error);
                     }
@@ -140,25 +174,98 @@ function createWorkerDecoratorWithLock(baseDecorator, decoratorName, lockKey, op
                 }
             });
         };
+        // Apply the base decorator
         baseDecorator(target, propertyKey, descriptor);
         return descriptor;
     };
 }
+// ============================================================================
+// Basic Worker Decorators (without lock)
+// ============================================================================
+/**
+ * Cron decorator that only executes in Worker or Hybrid mode
+ *
+ * @param cronTime - Cron expression
+ * @param options - Cron options
+ *
+ * @example
+ * ```typescript
+ * @WorkerCron('0 0 * * *') // Run daily at midnight
+ * async dailyTask() {
+ *   // Task logic
+ * }
+ * ```
+ */
 function WorkerCron(cronTime, options) {
     return createWorkerDecorator((0, schedule_1.Cron)(cronTime, options), 'WorkerCron');
 }
+/**
+ * Interval decorator that only executes in Worker or Hybrid mode
+ *
+ * @param timeout - Interval in milliseconds
+ * @param name - Optional name for the interval
+ *
+ * @example
+ * ```typescript
+ * @WorkerInterval(60000) // Run every minute
+ * async minutelyTask() {
+ *   // Task logic
+ * }
+ * ```
+ */
 function WorkerInterval(timeout, name) {
     if (name) {
         return createWorkerDecorator((0, schedule_1.Interval)(name, timeout), 'WorkerInterval');
     }
     return createWorkerDecorator((0, schedule_1.Interval)(timeout), 'WorkerInterval');
 }
+/**
+ * Timeout decorator that only executes in Worker or Hybrid mode
+ *
+ * @param timeout - Timeout in milliseconds
+ * @param name - Optional name for the timeout
+ *
+ * @example
+ * ```typescript
+ * @WorkerTimeout(5000) // Run once after 5 seconds
+ * async startupTask() {
+ *   // Task logic
+ * }
+ * ```
+ */
 function WorkerTimeout(timeout, name) {
     if (name) {
         return createWorkerDecorator((0, schedule_1.Timeout)(name, timeout), 'WorkerTimeout');
     }
     return createWorkerDecorator((0, schedule_1.Timeout)(timeout), 'WorkerTimeout');
 }
+// ============================================================================
+// Worker Decorators with Lock Support
+// ============================================================================
+/**
+ * Cron decorator with distributed lock support
+ * Automatically generates lock key from class and method name
+ *
+ * @param cronTime - Cron expression
+ * @param lockKeyOrOptions - Lock key (string) or options object
+ * @param lockTtl - Lock TTL in milliseconds (only if lockKeyOrOptions is a string)
+ *
+ * @param cronOptions
+ * @example
+ * ```typescript
+ * // Using string lock key
+ * @WorkerCronWithLock('0 * * * *', 'hourly-task', 3600000)
+ * async hourlyTask() {
+ *   // Task logic
+ * }
+ *
+ * // Using options object (auto-generates lock key)
+ * @WorkerCronWithLock('0 * * * *', { lockTtl: 3600000, retryCount: 3 })
+ * async hourlyTask() {
+ *   // Task logic
+ * }
+ * ```
+ */
 function WorkerCronWithLock(cronTime, lockKeyOrOptions, lockTtl, cronOptions) {
     return function (target, propertyKey, descriptor) {
         let lockKey;
@@ -174,6 +281,28 @@ function WorkerCronWithLock(cronTime, lockKeyOrOptions, lockTtl, cronOptions) {
         return createWorkerDecoratorWithLock((0, schedule_1.Cron)(cronTime, cronOptions), 'WorkerCronWithLock', lockKey, options)(target, propertyKey, descriptor);
     };
 }
+/**
+ * Interval decorator with distributed lock support
+ *
+ * @param timeout - Interval in milliseconds
+ * @param lockKeyOrOptions - Lock key (string) or options object
+ * @param lockTtl - Lock TTL in milliseconds (only if lockKeyOrOptions is a string)
+ *
+ * @example
+ * ```typescript
+ * // Using string lock key
+ * @WorkerIntervalWithLock(60000, 'status-check', 50000)
+ * async checkStatus() {
+ *   // Task logic
+ * }
+ *
+ * // Using options object (auto-generates lock key)
+ * @WorkerIntervalWithLock(60000, { retryCount: 2 })
+ * async checkStatus() {
+ *   // Task logic
+ * }
+ * ```
+ */
 function WorkerIntervalWithLock(timeout, lockKeyOrOptions, lockTtl) {
     return function (target, propertyKey, descriptor) {
         let lockKey;
@@ -189,6 +318,28 @@ function WorkerIntervalWithLock(timeout, lockKeyOrOptions, lockTtl) {
         return createWorkerDecoratorWithLock((0, schedule_1.Interval)(timeout), 'WorkerIntervalWithLock', lockKey, options)(target, propertyKey, descriptor);
     };
 }
+/**
+ * Timeout decorator with distributed lock support
+ *
+ * @param timeout - Timeout in milliseconds
+ * @param lockKeyOrOptions - Lock key (string) or options object
+ * @param lockTtl - Lock TTL in milliseconds (only if lockKeyOrOptions is a string)
+ *
+ * @example
+ * ```typescript
+ * // Using string lock key
+ * @WorkerTimeoutWithLock(5000, 'init-task', 10000)
+ * async initializeSystem() {
+ *   // Task logic
+ * }
+ *
+ * // Using options object (auto-generates lock key)
+ * @WorkerTimeoutWithLock(5000, { lockTtl: 10000 })
+ * async initializeSystem() {
+ *   // Task logic
+ * }
+ * ```
+ */
 function WorkerTimeoutWithLock(timeout, lockKeyOrOptions, lockTtl) {
     return function (target, propertyKey, descriptor) {
         let lockKey;
@@ -204,18 +355,80 @@ function WorkerTimeoutWithLock(timeout, lockKeyOrOptions, lockTtl) {
         return createWorkerDecoratorWithLock((0, schedule_1.Timeout)(timeout), 'WorkerTimeoutWithLock', lockKey, options)(target, propertyKey, descriptor);
     };
 }
+// ============================================================================
+// Smart Decorators (Recommended)
+// ============================================================================
+/**
+ * Smart Cron decorator with auto-generated lock key and intelligent defaults
+ * Recommended for most use cases
+ *
+ * @param cronTime - Cron expression
+ * @param options - Schedule options
+ *
+ * @example
+ * ```typescript
+ * @WorkerCronSmart('0 * * * *') // Run hourly with auto-generated lock key
+ * async hourlyTask() {
+ *   // Task logic
+ * }
+ *
+ * @WorkerCronSmart('0 0 * * *', {
+ *   lockTtl: 7200000, // 2 hours
+ *   retryCount: 3,
+ *   onError: (error) => console.error('Task failed:', error),
+ * })
+ * async dailyTask() {
+ *   // Task logic
+ * }
+ * ```
+ */
 function WorkerCronSmart(cronTime, options = {}, cronOptions) {
     return function (target, propertyKey, descriptor) {
         const lockKey = generateLockKey(target.constructor.name, String(propertyKey));
         return createWorkerDecoratorWithLock((0, schedule_1.Cron)(cronTime, cronOptions), 'WorkerCronSmart', lockKey, Object.assign({ lockTtl: 3600000, logExecution: true }, options))(target, propertyKey, descriptor);
     };
 }
+/**
+ * Smart Interval decorator with auto-generated lock key and intelligent defaults
+ * Lock TTL is automatically set to 80% of interval duration
+ *
+ * @param timeout - Interval in milliseconds
+ * @param options - Schedule options
+ *
+ * @example
+ * ```typescript
+ * @WorkerIntervalSmart(120000) // Run every 2 minutes, lock for ~1.6 minutes
+ * async checkStatus() {
+ *   // Task logic
+ * }
+ * ```
+ */
 function WorkerIntervalSmart(timeout, options = {}) {
     return function (target, propertyKey, descriptor) {
         const lockKey = generateLockKey(target.constructor.name, String(propertyKey));
         return createWorkerDecoratorWithLock((0, schedule_1.Interval)(timeout), 'WorkerIntervalSmart', lockKey, Object.assign({ lockTtl: Math.floor(timeout * 0.8), logExecution: true }, options))(target, propertyKey, descriptor);
     };
 }
+/**
+ * Advanced Cron decorator with full control
+ * Alias for WorkerCronSmart with explicit lock key parameter
+ *
+ * @param cronTime - Cron expression
+ * @param lockKeyOrOptions - Lock key (string) or options object
+ * @param options - Schedule options (only if lockKeyOrOptions is a string)
+ *
+ * @example
+ * ```typescript
+ * @WorkerCronAdvanced('0 0 * * *', 'daily-report', {
+ *   lockTtl: 7200000,
+ *   retryCount: 5,
+ *   useExponentialBackoff: true,
+ * })
+ * async generateDailyReport() {
+ *   // Task logic
+ * }
+ * ```
+ */
 function WorkerCronAdvanced(cronTime, lockKeyOrOptions, options, cronOptions) {
     return function (target, propertyKey, descriptor) {
         let lockKey;