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

package/setup/bootstrap.setup.js

@@ -10,6 +10,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.bootstrapSetup = bootstrapSetup;
+require("../common/boilerplate.polyfill");
 const Sentry = require("@sentry/nestjs");
 const profiling_node_1 = require("@sentry/profiling-node");
 const dotenv = require("dotenv");
@@ -19,12 +20,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 +60,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,41 +127,55 @@ 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,
             transform: true,
             stopAtFirstError: true,
-            validationError: { target: false, value: false },
+            validationError: { target: true, value: true },
         }));
+        // 可选功能模块 - 仅在 HTTP 或 Hybrid 模式下启用
         if (shouldStartHttp) {
             if (configService.documentationEnabled && SetupSwagger) {
                 SetupSwagger(app, configService.documentationPath);
@@ -181,6 +201,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/index.d.ts

@@ -2,3 +2,4 @@ export * from './bootstrap.setup';
 export * from './mode.setup';
 export * from './worker.decorator';
 export * from './schedule.decorator';
+export * from './run-in-mode.decorator';

package/setup/index.js

@@ -18,3 +18,4 @@ __exportStar(require("./bootstrap.setup"), exports);
 __exportStar(require("./mode.setup"), exports);
 __exportStar(require("./worker.decorator"), exports);
 __exportStar(require("./schedule.decorator"), exports);
+__exportStar(require("./run-in-mode.decorator"), exports);

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

package/setup/run-in-mode.decorator.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Mode-Aware Method Decorators
+ *
+ * Conditional method execution based on application mode:
+ * - HTTP: Only HTTP server (no workers/schedulers)
+ * - WORKER: Only background workers and schedulers (no HTTP server)
+ * - HYBRID: Both HTTP server and workers (default)
+ */
+/**
+ * Method only executes in HTTP mode (skipped in WORKER and HYBRID)
+ *
+ * @example
+ * ```typescript
+ * @RunOnlyInHttp()
+ * async handleApiRequest() {
+ *   // Only runs when APP_MODE=http
+ * }
+ * ```
+ */
+export declare function RunOnlyInHttp(): MethodDecorator;
+/**
+ * Method only executes in WORKER mode (skipped in HTTP and HYBRID)
+ *
+ * @example
+ * ```typescript
+ * @RunOnlyInWorker()
+ * async processBackgroundJob() {
+ *   // Only runs when APP_MODE=worker
+ * }
+ * ```
+ */
+export declare function RunOnlyInWorker(): MethodDecorator;
+/**
+ * Method executes in HTTP or HYBRID mode (skipped in WORKER-only mode)
+ *
+ * @example
+ * ```typescript
+ * @RunInHttpOrHybrid()
+ * async handleWebRequest() {
+ *   // Runs in HTTP or HYBRID mode
+ * }
+ * ```
+ */
+export declare function RunInHttpOrHybrid(): MethodDecorator;
+/**
+ * Method executes in WORKER or HYBRID mode (skipped in HTTP-only mode)
+ *
+ * @example
+ * ```typescript
+ * @RunInWorkerOrHybrid()
+ * async processScheduledTask() {
+ *   // Runs in WORKER or HYBRID mode
+ * }
+ * ```
+ */
+export declare function RunInWorkerOrHybrid(): MethodDecorator;

package/setup/run-in-mode.decorator.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * Mode-Aware Method Decorators
+ *
+ * Conditional method execution based on application mode:
+ * - 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.RunOnlyInHttp = RunOnlyInHttp;
+exports.RunOnlyInWorker = RunOnlyInWorker;
+exports.RunInHttpOrHybrid = RunInHttpOrHybrid;
+exports.RunInWorkerOrHybrid = RunInWorkerOrHybrid;
+const common_1 = require("@nestjs/common");
+const mode_setup_1 = require("./mode.setup");
+/**
+ * Create mode-restricted decorator
+ */
+function createModeDecorator(allowedModes) {
+    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}`);
+        descriptor.value = function (...args) {
+            const currentMode = (0, mode_setup_1.getApplicationMode)();
+            if (!allowedModes.includes(currentMode)) {
+                logger.log(`Skipped (current: ${currentMode}, allowed: ${allowedModes.join(', ')})`);
+                return undefined;
+            }
+            return originalMethod.apply(this, args);
+        };
+        return descriptor;
+    };
+}
+/**
+ * Method only executes in HTTP mode (skipped in WORKER and HYBRID)
+ *
+ * @example
+ * ```typescript
+ * @RunOnlyInHttp()
+ * async handleApiRequest() {
+ *   // Only runs when APP_MODE=http
+ * }
+ * ```
+ */
+function RunOnlyInHttp() {
+    return createModeDecorator([mode_setup_1.ApplicationMode.HTTP]);
+}
+/**
+ * Method only executes in WORKER mode (skipped in HTTP and HYBRID)
+ *
+ * @example
+ * ```typescript
+ * @RunOnlyInWorker()
+ * async processBackgroundJob() {
+ *   // Only runs when APP_MODE=worker
+ * }
+ * ```
+ */
+function RunOnlyInWorker() {
+    return createModeDecorator([mode_setup_1.ApplicationMode.WORKER]);
+}
+/**
+ * Method executes in HTTP or HYBRID mode (skipped in WORKER-only mode)
+ *
+ * @example
+ * ```typescript
+ * @RunInHttpOrHybrid()
+ * async handleWebRequest() {
+ *   // Runs in HTTP or HYBRID mode
+ * }
+ * ```
+ */
+function RunInHttpOrHybrid() {
+    return createModeDecorator([mode_setup_1.ApplicationMode.HTTP, mode_setup_1.ApplicationMode.HYBRID]);
+}
+/**
+ * Method executes in WORKER or HYBRID mode (skipped in HTTP-only mode)
+ *
+ * @example
+ * ```typescript
+ * @RunInWorkerOrHybrid()
+ * async processScheduledTask() {
+ *   // Runs in WORKER or HYBRID mode
+ * }
+ * ```
+ */
+function RunInWorkerOrHybrid() {
+    return createModeDecorator([mode_setup_1.ApplicationMode.WORKER, mode_setup_1.ApplicationMode.HYBRID]);
+}

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;