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

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

@@ -21,39 +21,93 @@ var RedisLockService_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RedisLockService = exports.LockStrategy = void 0;
 const common_1 = require("@nestjs/common");
+/**
+ * Lock acquisition strategy
+ */
 var LockStrategy;
 (function (LockStrategy) {
+    /**
+     * Skip execution if lock cannot be acquired immediately
+     * This is the default behavior for backward compatibility
+     */
     LockStrategy["SKIP"] = "SKIP";
+    /**
+     * Throw an error if lock cannot be acquired
+     * Useful for critical operations that must have exclusive access
+     */
     LockStrategy["THROW"] = "THROW";
+    /**
+     * Wait/block until the lock can be acquired
+     * Will retry indefinitely with the specified retry delay
+     */
     LockStrategy["WAIT"] = "WAIT";
 })(LockStrategy || (exports.LockStrategy = LockStrategy = {}));
+/**
+ * Redis-based distributed lock service
+ *
+ * Provides thread-safe, distributed locking mechanism using Redis.
+ * Supports automatic lock expiration, retries, proper lock release,
+ * and automatic lock extension.
+ *
+ * @example
+ * ```typescript
+ * constructor(private lockService: RedisLockService) {}
+ *
+ * async processTask() {
+ *   const result = await this.lockService.acquireLock('task:process', { ttl: 60000 });
+ *
+ *   if (result.acquired) {
+ *     try {
+ *       // Do work
+ *     } finally {
+ *       await this.lockService.releaseLock('task:process', result.lockValue);
+ *     }
+ *   }
+ * }
+ * ```
+ */
 let RedisLockService = RedisLockService_1 = class RedisLockService {
     constructor() {
         this.logger = new common_1.Logger(RedisLockService_1.name);
         this.redis = null;
         this.defaultOptions = {
-            ttl: 300000,
+            ttl: 300000, // 5 minutes
             retryCount: 0,
             retryDelay: 100,
             keyPrefix: 'lock',
             throwOnFailure: false,
             strategy: LockStrategy.SKIP,
             waitTimeout: undefined,
-            autoExtend: 0,
+            autoExtend: 0, // No auto-extension by default
         };
+        // Set global instance when created
         if (!RedisLockService_1.globalInstance) {
             RedisLockService_1.globalInstance = this;
         }
+        // Initialize instance ID
+        this.instanceId = this.getInstanceId();
     }
+    /**
+     * Get the global singleton instance
+     * This allows decorators to access the service without dependency injection
+     */
     static getGlobalInstance() {
         return RedisLockService_1.globalInstance;
     }
+    /**
+     * Get or create the global singleton instance
+     * If no instance exists, it will create one
+     */
     static getOrCreateGlobalInstance() {
         if (!RedisLockService_1.globalInstance) {
             RedisLockService_1.globalInstance = new RedisLockService_1();
         }
         return RedisLockService_1.globalInstance;
     }
+    /**
+     * Set the global singleton instance
+     * Useful for testing or manual setup
+     */
     static setGlobalInstance(instance) {
         RedisLockService_1.globalInstance = instance;
     }
@@ -69,37 +123,64 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
     }
     onModuleDestroy() {
         return __awaiter(this, void 0, void 0, function* () {
+            // We don't manage the Redis connection lifecycle anymore
+            // The injected Redis client is managed by the Redis module
             this.logger.log('RedisLockService destroyed');
         });
     }
+    /**
+     * Set Redis client (required for dependency injection)
+     * This service requires an external Redis client to function
+     */
     setRedisClient(redis) {
         this.redis = redis;
         this.logger.log('Redis client set for RedisLockService');
     }
+    /**
+     * Set default TTL for locks
+     */
     setDefaultTtl(ttl) {
         this.defaultOptions.ttl = ttl;
     }
+    /**
+     * Set default key prefix for locks
+     */
     setDefaultKeyPrefix(prefix) {
         this.defaultOptions.keyPrefix = prefix;
     }
+    /**
+     * Set default retry count for lock acquisition
+     */
     setDefaultRetryCount(count) {
         this.defaultOptions.retryCount = count;
     }
+    /**
+     * Set default retry delay for lock acquisition
+     */
     setDefaultRetryDelay(delay) {
         this.defaultOptions.retryDelay = delay;
     }
+    /**
+     * Acquire a distributed lock
+     *
+     * @param key - Lock key (will be prefixed with 'lock:')
+     * @param options - Lock options
+     * @returns Lock acquisition result
+     */
     acquireLock(key_1) {
         return __awaiter(this, arguments, void 0, function* (key, options = {}) {
             const redis = yield this.getRedis();
             const opts = Object.assign(Object.assign({}, this.defaultOptions), options);
+            // Handle backward compatibility: if throwOnFailure is true, use THROW strategy
             if (opts.throwOnFailure && !options.strategy) {
                 opts.strategy = LockStrategy.THROW;
             }
             const lockKey = this.buildLockKey(key, opts.keyPrefix);
             const lockValue = this.generateLockValue();
+            // Determine max attempts based on strategy
             let maxAttempts;
             if (opts.strategy === LockStrategy.WAIT) {
-                maxAttempts = Number.MAX_SAFE_INTEGER;
+                maxAttempts = Number.MAX_SAFE_INTEGER; // Infinite retries for WAIT strategy
             }
             else {
                 maxAttempts = opts.retryCount + 1;
@@ -107,6 +188,7 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             let attempts = 0;
             const startTime = Date.now();
             while (attempts < maxAttempts) {
+                // Check timeout for WAIT strategy
                 if (opts.strategy === LockStrategy.WAIT && opts.waitTimeout) {
                     const elapsed = Date.now() - startTime;
                     if (elapsed >= opts.waitTimeout) {
@@ -116,9 +198,11 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
                     }
                 }
                 try {
+                    // Use SET with NX (Not eXists) and PX (expiration in milliseconds)
                     const result = yield redis.set(lockKey, lockValue, 'PX', opts.ttl, 'NX');
                     if (result === 'OK') {
                         this.logger.debug(`Lock acquired: ${lockKey} (value: ${lockValue}, ttl: ${opts.ttl}ms, attempts: ${attempts + 1})`);
+                        // Set up auto-extension if enabled
                         let autoExtendTimer;
                         if (opts.autoExtend && opts.autoExtend > 0) {
                             autoExtendTimer = setInterval(() => __awaiter(this, void 0, void 0, function* () {
@@ -132,7 +216,9 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
                         }
                         return { acquired: true, lockValue, autoExtendTimer };
                     }
+                    // Lock acquisition failed
                     attempts++;
+                    // For WAIT strategy, log less frequently to avoid spam
                     if (opts.strategy === LockStrategy.WAIT) {
                         if (attempts === 1 || attempts % 10 === 0) {
                             this.logger.debug(`Waiting for lock ${lockKey}... (attempt ${attempts})`);
@@ -141,6 +227,7 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
                     else if (attempts < maxAttempts) {
                         this.logger.debug(`Lock acquisition failed for ${lockKey}, retrying... (${attempts}/${opts.retryCount})`);
                     }
+                    // Wait before next attempt (except for last attempt)
                     if (attempts < maxAttempts) {
                         yield this.sleep(opts.retryDelay);
                     }
@@ -154,6 +241,7 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
                     return { acquired: false, error: errorMessage };
                 }
             }
+            // Max attempts reached
             const failureMessage = `Failed to acquire lock for ${lockKey} after ${attempts} attempts`;
             this.logger.warn(failureMessage);
             if (opts.strategy === LockStrategy.THROW) {
@@ -162,11 +250,23 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             return { acquired: false, error: failureMessage };
         });
     }
+    /**
+     * Release a distributed lock
+     *
+     * Uses Lua script to ensure atomic check-and-delete operation
+     * Only releases the lock if the value matches (prevents releasing someone else's lock)
+     *
+     * @param key - Lock key
+     * @param lockValue - Lock value obtained during acquisition
+     * @param keyPrefix - Key prefix (must match acquisition)
+     * @returns True if lock was released, false otherwise
+     */
     releaseLock(key_1, lockValue_1) {
         return __awaiter(this, arguments, void 0, function* (key, lockValue, keyPrefix = 'lock') {
             const redis = yield this.getRedis();
             const lockKey = this.buildLockKey(key, keyPrefix);
             try {
+                // Lua script to atomically check and delete the lock
                 const script = `
         if redis.call("get", KEYS[1]) == ARGV[1] then
           return redis.call("del", KEYS[1])
@@ -190,11 +290,21 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             }
         });
     }
+    /**
+     * Extend the expiration time of an existing lock
+     *
+     * @param key - Lock key
+     * @param lockValue - Lock value obtained during acquisition
+     * @param ttl - New TTL in milliseconds
+     * @param keyPrefix - Key prefix (must match acquisition)
+     * @returns True if lock was extended, false otherwise
+     */
     extendLock(key_1, lockValue_1, ttl_1) {
         return __awaiter(this, arguments, void 0, function* (key, lockValue, ttl, keyPrefix = 'lock') {
             const redis = yield this.getRedis();
             const lockKey = this.buildLockKey(key, keyPrefix);
             try {
+                // Lua script to atomically check value and extend TTL
                 const script = `
         if redis.call("get", KEYS[1]) == ARGV[1] then
           return redis.call("pexpire", KEYS[1], ARGV[2])
@@ -218,6 +328,13 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             }
         });
     }
+    /**
+     * Check if a lock exists
+     *
+     * @param key - Lock key
+     * @param keyPrefix - Key prefix
+     * @returns True if lock exists, false otherwise
+     */
     isLocked(key_1) {
         return __awaiter(this, arguments, void 0, function* (key, keyPrefix = 'lock') {
             const redis = yield this.getRedis();
@@ -232,6 +349,14 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             }
         });
     }
+    /**
+     * Execute a function with automatic lock acquisition and release
+     *
+     * @param key - Lock key
+     * @param fn - Function to execute while holding the lock
+     * @param options - Lock options
+     * @returns Result of the function execution, or null if lock couldn't be acquired
+     */
     withLock(key_1, fn_1) {
         return __awaiter(this, arguments, void 0, function* (key, fn, options = {}) {
             const lockResult = yield this.acquireLock(key, options);
@@ -247,6 +372,7 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
                 throw error;
             }
             finally {
+                // Clear auto-extension timer if it exists
                 if (lockResult.autoExtendTimer) {
                     clearInterval(lockResult.autoExtendTimer);
                 }
@@ -254,6 +380,13 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             }
         });
     }
+    /**
+     * Get lock information from Redis
+     *
+     * @param key - Lock key
+     * @param keyPrefix - Key prefix
+     * @returns Lock information including TTL and value
+     */
     getLockInfo(key_1) {
         return __awaiter(this, arguments, void 0, function* (key, keyPrefix = 'lock') {
             const redis = yield this.getRedis();
@@ -274,6 +407,13 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             }
         });
     }
+    /**
+     * Force release a lock (use with caution)
+     *
+     * @param key - Lock key
+     * @param keyPrefix - Key prefix
+     * @returns True if lock was released, false otherwise
+     */
     forceRelease(key_1) {
         return __awaiter(this, arguments, void 0, function* (key, keyPrefix = 'lock') {
             const redis = yield this.getRedis();
@@ -295,6 +435,25 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             }
         });
     }
+    /**
+     * Clean up locks by pattern
+     * Useful for cleaning up locks after process restart or for specific services
+     *
+     * WARNING: Use with caution in production! This will forcefully delete locks.
+     *
+     * @param pattern - Lock pattern (e.g., 'MyService:*' or '*:migration:*')
+     * @param keyPrefix - Key prefix (default: 'lock')
+     * @returns Number of locks deleted
+     *
+     * @example
+     * ```typescript
+     * // Clean up all locks for MyService
+     * await lockService.cleanupLocksByPattern('MyService:*');
+     *
+     * // Clean up all migration locks
+     * await lockService.cleanupLocksByPattern('*:migration:*');
+     * ```
+     */
     cleanupLocksByPattern(pattern_1) {
         return __awaiter(this, arguments, void 0, function* (pattern, keyPrefix = 'lock') {
             const redis = yield this.getRedis();
@@ -315,6 +474,28 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             }
         });
     }
+    /**
+     * Clean up locks on startup
+     * This method is useful for cleaning up stale locks from previous process instances
+     *
+     * WARNING: Only use this if you're sure the locks are from previous process instances!
+     *
+     * @param patterns - Array of lock patterns to clean up
+     * @param keyPrefix - Key prefix (default: 'lock')
+     * @returns Total number of locks deleted
+     *
+     * @example
+     * ```typescript
+     * // In your module's onModuleInit
+     * async onModuleInit() {
+     *   // Clean up locks from this service that might be left from previous restart
+     *   await this.lockService.cleanupOnStartup([
+     *     'MyService:*',
+     *     'AnotherService:*'
+     *   ]);
+     * }
+     * ```
+     */
     cleanupOnStartup(patterns_1) {
         return __awaiter(this, arguments, void 0, function* (patterns, keyPrefix = 'lock') {
             this.logger.log(`Starting lock cleanup for ${patterns.length} pattern(s) on startup...`);
@@ -327,10 +508,17 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             return totalDeleted;
         });
     }
+    /**
+     * Health check for Redis connection
+     * Returns information about Redis connectivity and lock service status
+     *
+     * @returns Health check result
+     */
     healthCheck() {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 const redis = yield this.getRedis();
+                // Try to ping Redis
                 const pong = yield redis.ping();
                 if (pong === 'PONG') {
                     return {
@@ -356,6 +544,14 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             }
         });
     }
+    /**
+     * Get all active locks with optional pattern filtering
+     * Useful for monitoring and debugging
+     *
+     * @param pattern - Optional pattern to filter locks (e.g., 'MyService:*')
+     * @param keyPrefix - Key prefix (default: 'lock')
+     * @returns Array of active lock information
+     */
     getActiveLocks() {
         return __awaiter(this, arguments, void 0, function* (pattern = '*', keyPrefix = 'lock') {
             const redis = yield this.getRedis();
@@ -370,6 +566,7 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
                         redis.get(key),
                         redis.pttl(key),
                     ]);
+                    // Remove the key prefix for cleaner output
                     const cleanKey = key.startsWith(`${keyPrefix}:`)
                         ? key.substring(`${keyPrefix}:`.length)
                         : key;
@@ -387,6 +584,10 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             }
         });
     }
+    /**
+     * Get Redis connection
+     * Requires external Redis client to be set
+     */
     getRedis() {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.redis) {
@@ -395,12 +596,51 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             return this.redis;
         });
     }
+    /**
+     * Generate a unique lock value
+     * Format: instanceId:timestamp:random:pid
+     *
+     * @returns Unique lock identifier
+     */
     generateLockValue() {
-        return `${Date.now()}-${Math.random().toString(36).substring(2, 15)}-${process.pid}`;
+        const timestamp = Date.now();
+        const random = Math.random().toString(36).substring(2, 15);
+        const pid = process.pid;
+        return `${this.instanceId}:${timestamp}:${random}:${pid}`;
     }
+    /**
+     * Get instance identifier
+     * Used to distinguish different process instances in distributed environments
+     *
+     * @returns Instance identifier
+     */
+    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)}`;
+    }
+    /**
+     * Build the full Redis key for a lock
+     *
+     * @param key - Lock key
+     * @param prefix - Key prefix
+     * @returns Full Redis key
+     */
     buildLockKey(key, prefix = 'lock') {
         return `${prefix}:${key}`;
     }
+    /**
+     * Sleep for a specified duration
+     *
+     * @param ms - Milliseconds to sleep
+     */
     sleep(ms) {
         return new Promise((resolve) => setTimeout(resolve, ms));
     }

package/setup/bootstrap.setup.js

@@ -19,12 +19,15 @@ const process = require("process");
 const mode_setup_1 = require("./mode.setup");
 function findValidRootPath() {
     const getAppRootPath = () => {
+        // 优先使用 require.main.filename（应用入口文件）
         if (require.main && require.main.filename) {
             return (0, path_1.dirname)(require.main.filename);
         }
+        // fallback 到 process.argv[1]
         if (process.argv[1]) {
             return (0, path_1.dirname)(process.argv[1]);
         }
+        // 最后 fallback 到当前工作目录
         return process.cwd();
     };
     const possibleRootPaths = [getAppRootPath(), process.cwd(), __dirname];
@@ -56,6 +59,8 @@ function findValidRootPath() {
     throw new Error(`No valid .env file: ${envFilePath}`);
 }
 const { envFilePath, rootPath, baseEnvFilePath } = findValidRootPath();
+// 配置加载顺序: base.env < 环境.env < Vault
+// 1. 先加载本地配置文件 (base.env 和 环境.env)
 dotenv.config({ path: [envFilePath, baseEnvFilePath] });
 process.env.ROOT_PATH = rootPath;
 process.env.ENV_FILE_PATH = envFilePath;
@@ -121,34 +126,47 @@ const vault_1 = require("../vault");
 const dto_1 = require("../common/dto");
 function bootstrapSetup(AppModule, SetupSwagger) {
     return __awaiter(this, void 0, void 0, function* () {
+        // 2. 加载 Vault 配置（会覆盖 .env 中的配置）
         yield vault_1.VaultConfigLoader.loadVaultConfig();
+        // 获取应用模式
         const shouldStartHttp = (0, mode_setup_1.shouldStartHttpServer)();
+        // 创建应用实例
         const app = yield core_1.NestFactory.create(AppModule, {
             bufferLogs: true,
             autoFlushLogs: true,
         });
+        // 设置容器 - 类似class-validator的useContainer
         const appModuleRef = app.select(AppModule);
         (0, class_validator_1.useContainer)(appModuleRef, { fallbackOnErrors: true });
+        // 初始化DTO容器
         dto_1.DtoContainer.useContainer(appModuleRef);
+        // 获取核心服务
         const configService = app.select(__1.ServiceRegistryModule).get(__1.ApiConfigService);
         const logger = app.get(nestjs_pino_1.Logger);
         app.useLogger(logger);
         app.flushLogs();
+        // 记录应用模式
         logger.log(`Application Mode: ${(0, mode_setup_1.getModeDescription)()}`);
         logger.log(`Environment: ${process.env.NODE_ENV || 'unknown'}`);
         app.enableShutdownHooks();
+        // 基础配置
         app.enableVersioning();
         app.enable('trust proxy');
         app.set('query parser', 'extended');
+        // 中间件配置
         app.use(bodyParse.urlencoded({
             extended: true,
             parameterLimit: 1000,
         }), bodyParse.json({ limit: '50mb' }), new nestjs_cls_1.ClsMiddleware({
             saveReq: true,
+            // 启用请求保存，解决CLS相关的上下文问题
         }).use, (0, __1.RequestIdMiddleware)(), (0, __1.PowerByMiddleware)(), (0, __1.OmniAuthMiddleware)(), compression());
+        // 全局过滤器
         const reflector = app.get(core_1.Reflector);
         app.useGlobalFilters(new setup_1.SentryGlobalFilter(), new __1.HttpExceptionFilter(), new __1.QueryFailedFilter(reflector));
+        // 全局拦截器
         app.useGlobalInterceptors(new __1.LanguageInterceptor(), new __1.TranslationInterceptor(), new nestjs_pino_1.LoggerErrorInterceptor());
+        // 全局管道
         app.useGlobalPipes(new nestjs_i18n_1.I18nValidationPipe({
             whitelist: true,
             errorHttpStatusCode: common_1.HttpStatus.UNPROCESSABLE_ENTITY,
@@ -156,6 +174,7 @@ function bootstrapSetup(AppModule, SetupSwagger) {
             stopAtFirstError: true,
             validationError: { target: false, value: false },
         }));
+        // 可选功能模块 - 仅在 HTTP 或 Hybrid 模式下启用
         if (shouldStartHttp) {
             if (configService.documentationEnabled && SetupSwagger) {
                 SetupSwagger(app, configService.documentationPath);
@@ -181,6 +200,7 @@ function bootstrapSetup(AppModule, SetupSwagger) {
         else {
             logger.log('Running in Worker-only mode - HTTP server not started');
             logger.log('Application is ready to process background tasks');
+            // 在 Worker 模式下，应用会持续运行但不监听 HTTP 请求
             yield app.init();
         }
         return app;

package/setup/mode.setup.d.ts

@@ -1,12 +1,56 @@
+/**
+ * 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)
+ */
 export declare enum ApplicationMode {
     HTTP = "http",
     WORKER = "worker",
     HYBRID = "hybrid"
 }
+/**
+ * Get the current application mode from environment variables
+ * Supports both APP_MODE and MODE environment variables
+ *
+ * @returns The current application mode
+ */
 export declare function getApplicationMode(): ApplicationMode;
+/**
+ * Check if the current mode should process queues and scheduled tasks
+ *
+ * @returns True if workers should be registered
+ */
 export declare function shouldProcessQueues(): boolean;
+/**
+ * Check if the current mode should start HTTP server
+ *
+ * @returns True if HTTP server should be started
+ */
 export declare function shouldStartHttpServer(): boolean;
+/**
+ * Check if running in HTTP-only mode
+ *
+ * @returns True if running in HTTP-only mode
+ */
 export declare function isHttpMode(): boolean;
+/**
+ * Check if running in Worker-only mode
+ *
+ * @returns True if running in Worker-only mode
+ */
 export declare function isWorkerMode(): boolean;
+/**
+ * Check if running in Hybrid mode
+ *
+ * @returns True if running in Hybrid mode
+ */
 export declare function isHybridMode(): boolean;
+/**
+ * Get a human-readable description of the current mode
+ *
+ * @returns Description of the current mode
+ */
 export declare function getModeDescription(): string;

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) {