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

package/setup/mode.setup.js

@@ -1,4 +1,12 @@
 "use strict";
+/**
+ * Application Mode Detection and Management System
+ *
+ * This module provides utilities for detecting and managing different application modes:
+ * - HTTP: Only HTTP server (no workers/schedulers)
+ * - WORKER: Only background workers and schedulers (no HTTP server)
+ * - HYBRID: Both HTTP server and workers (default)
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApplicationMode = void 0;
 exports.getApplicationMode = getApplicationMode;
@@ -14,6 +22,12 @@ var ApplicationMode;
     ApplicationMode["WORKER"] = "worker";
     ApplicationMode["HYBRID"] = "hybrid";
 })(ApplicationMode || (exports.ApplicationMode = ApplicationMode = {}));
+/**
+ * Get the current application mode from environment variables
+ * Supports both APP_MODE and MODE environment variables
+ *
+ * @returns The current application mode
+ */
 function getApplicationMode() {
     const mode = (process.env.APP_MODE || process.env.MODE || 'hybrid')
         .toLowerCase()
@@ -28,23 +42,53 @@ function getApplicationMode() {
             return ApplicationMode.HYBRID;
     }
 }
+/**
+ * Check if the current mode should process queues and scheduled tasks
+ *
+ * @returns True if workers should be registered
+ */
 function shouldProcessQueues() {
     const mode = getApplicationMode();
     return mode === ApplicationMode.WORKER || mode === ApplicationMode.HYBRID;
 }
+/**
+ * Check if the current mode should start HTTP server
+ *
+ * @returns True if HTTP server should be started
+ */
 function shouldStartHttpServer() {
     const mode = getApplicationMode();
     return mode === ApplicationMode.HTTP || mode === ApplicationMode.HYBRID;
 }
+/**
+ * Check if running in HTTP-only mode
+ *
+ * @returns True if running in HTTP-only mode
+ */
 function isHttpMode() {
     return getApplicationMode() === ApplicationMode.HTTP;
 }
+/**
+ * Check if running in Worker-only mode
+ *
+ * @returns True if running in Worker-only mode
+ */
 function isWorkerMode() {
     return getApplicationMode() === ApplicationMode.WORKER;
 }
+/**
+ * Check if running in Hybrid mode
+ *
+ * @returns True if running in Hybrid mode
+ */
 function isHybridMode() {
     return getApplicationMode() === ApplicationMode.HYBRID;
 }
+/**
+ * Get a human-readable description of the current mode
+ *
+ * @returns Description of the current mode
+ */
 function getModeDescription() {
     const mode = getApplicationMode();
     switch (mode) {

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;