koatty_schedule 3.3.1 → 3.3.2

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [3.3.2](https://github.com/thinkkoa/koatty_schedule/compare/v3.3.1...v3.3.2) (2025-06-22)
+
 ### [3.3.1](https://github.com/thinkkoa/koatty_schedule/compare/v3.3.0...v3.3.1) (2025-06-22)
 
 

package/README.md

@@ -16,6 +16,7 @@ Powerful scheduled tasks and distributed locking solution for Koatty framework.
 - 🌍 **Timezone Smart**: Three-tier priority system for timezone configuration
 - 📊 **Health Monitoring**: Built-in health checks and detailed status reporting
 - 🔧 **Easy Configuration**: Method-level and global configuration options
+- 🚀 **Smart Initialization**: Unified initialization timing for optimal dependency resolution
 
 ## Installation
 
@@ -391,7 +392,8 @@ DEBUG=koatty_schedule* npm start
 
 #### `@Scheduled(cron: string, timezone?: string)`
 - `cron`: Cron expression (6-part format with seconds)
-- `timezone`: Optional timezone override
+- `timezone`: Optional timezone override (defaults to 'Asia/Beijing')
+- **Processing**: Records metadata in IOC container, CronJob created at `appReady`
 
 #### `@RedLock(lockName?: string, options?: RedLockMethodOptions)`
 - `lockName`: Unique lock identifier (auto-generated if not provided)

package/dist/README.md

@@ -16,6 +16,7 @@ Powerful scheduled tasks and distributed locking solution for Koatty framework.
 - 🌍 **Timezone Smart**: Three-tier priority system for timezone configuration
 - 📊 **Health Monitoring**: Built-in health checks and detailed status reporting
 - 🔧 **Easy Configuration**: Method-level and global configuration options
+- 🚀 **Smart Initialization**: Unified initialization timing for optimal dependency resolution
 
 ## Installation
 
@@ -391,7 +392,8 @@ DEBUG=koatty_schedule* npm start
 
 #### `@Scheduled(cron: string, timezone?: string)`
 - `cron`: Cron expression (6-part format with seconds)
-- `timezone`: Optional timezone override
+- `timezone`: Optional timezone override (defaults to 'Asia/Beijing')
+- **Processing**: Records metadata in IOC container, CronJob created at `appReady`
 
 #### `@RedLock(lockName?: string, options?: RedLockMethodOptions)`
 - `lockName`: Unique lock identifier (auto-generated if not provided)

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /*!
 * @Author: richen
-* @Date: 2025-06-22 23:42:00
+* @Date: 2025-06-23 00:55:18
 * @License: BSD (3-Clause)
 * @Copyright (c) - <richenlin(at)gmail.com>
 * @HomePage: https://koatty.org/

package/dist/index.js

@@ -1,6 +1,6 @@
 /*!
 * @Author: richen
-* @Date: 2025-06-22 23:41:54
+* @Date: 2025-06-23 00:55:12
 * @License: BSD (3-Clause)
 * @Copyright (c) - <richenlin(at)gmail.com>
 * @HomePage: https://koatty.org/
@@ -8,10 +8,10 @@
 'use strict';
 
 var koatty_container = require('koatty_container');
-var koatty_lib = require('koatty_lib');
 var redlock = require('@sesamecare-oss/redlock');
 var ioredis = require('ioredis');
 var koatty_logger = require('koatty_logger');
+var koatty_lib = require('koatty_lib');
 var cron = require('cron');
 
 /*
@@ -24,7 +24,6 @@ var cron = require('cron');
  * @Copyright (c): <richenlin(at)gmail.com>
  */
 const COMPONENT_SCHEDULED = 'COMPONENT_SCHEDULED';
-const COMPONENT_REDLOCK = 'COMPONENT_REDLOCK';
 /**
  * Decorator types supported by the system
  */
@@ -110,13 +109,6 @@ function validateRedLockMethodOptions(options) {
  * Global configuration storage
  */
 let globalScheduledOptions = {};
-/**
- * Set global scheduled options
- * @param options - Global scheduled options
- */
-function setGlobalScheduledOptions(options) {
-    globalScheduledOptions = { ...options };
-}
 /**
  * Get global scheduled options
  * @returns Global scheduled options
@@ -129,8 +121,8 @@ function getGlobalScheduledOptions() {
  * @param userTimezone - User specified timezone
  * @returns Effective timezone
  */
-function getEffectiveTimezone(userTimezone) {
-    return userTimezone || globalScheduledOptions.timezone || 'Asia/Beijing';
+function getEffectiveTimezone(options, userTimezone) {
+    return userTimezone || options.timezone || 'Asia/Beijing';
 }
 /**
  * Get effective RedLock method options with priority: method options > global options > defaults
@@ -147,150 +139,6 @@ function getEffectiveRedLockOptions(methodOptions) {
     };
 }
 
-/*
- * @Description:
- * @Usage:
- * @Author: richen
- * @Date: 2025-06-09 16:00:00
- * @LastEditTime: 2025-06-09 16:00:00
- * @License: BSD (3-Clause)
- * @Copyright (c): <richenlin(at)gmail.com>
- */
-/**
- * Redis-based distributed lock decorator
- *
- * @export
- * @param {string} [name] - The locker name. If name is duplicated, lock sharing contention will result.
- *                          If not provided, a unique name will be auto-generated using method name + random suffix.
- *                          IMPORTANT: Auto-generated names are unique per method deployment and not predictable.
- * @param {RedLockMethodOptions} [options] - Lock configuration options for this method
- *
- * @returns {MethodDecorator}
- * @throws {Error} When decorator is used on wrong class type or invalid configuration
- *
- * @example
- * ```typescript
- * class UserService {
- *   @RedLock('user_update_lock', { lockTimeOut: 5000, maxRetries: 2 })
- *   async updateUser(id: string, data: any) {
- *     // This method will be protected by a distributed lock with predictable name
- *   }
- *
- *   @RedLock() // Auto-generated unique name like "deleteUser_abc123_xyz789"
- *   async deleteUser(id: string) {
- *     // This method will be protected by a distributed lock with auto-generated unique name
- *   }
- * }
- * ```
- */
-function RedLock(lockName, options) {
-    return (target, propertyKey, descriptor) => {
-        const methodName = propertyKey.toString();
-        // 验证装饰器使用的类型（从原型对象获取类构造函数）
-        const targetClass = target.constructor;
-        const componentType = koatty_container.IOCContainer.getType(targetClass);
-        if (componentType !== "SERVICE" && componentType !== "COMPONENT") {
-            throw Error("@RedLock decorator can only be used on SERVICE or COMPONENT classes.");
-        }
-        // 验证方法名
-        if (!methodName || typeof methodName !== 'string') {
-            throw Error("Method name is required for @RedLock decorator");
-        }
-        // 验证方法描述符
-        if (!descriptor || typeof descriptor.value !== 'function') {
-            throw Error("@RedLock decorator can only be applied to methods");
-        }
-        // 生成唯一的锁名称：用户指定的 > 自动生成的唯一名称
-        if (!lockName || lockName.trim() === '') {
-            const randomSuffix = Math.random().toString(36).substring(2, 8); // 6位随机字符
-            const timestamp = Date.now().toString(36); // 时间戳转36进制
-            lockName = `${methodName}_${randomSuffix}_${timestamp}`;
-        }
-        // 验证选项
-        if (options) {
-            validateRedLockMethodOptions(options);
-        }
-        // 保存类到IOC容器
-        koatty_container.IOCContainer.saveClass("COMPONENT", targetClass, targetClass.name);
-        // 保存RedLock元数据到 IOC 容器（lockName已确定）
-        koatty_container.IOCContainer.attachClassMetadata(COMPONENT_REDLOCK, DecoratorType.REDLOCK, {
-            method: methodName,
-            name: lockName, // 确定的锁名称，不会为undefined
-            options
-        }, target, methodName);
-    };
-}
-
-/*
- * @Description:
- * @Usage:
- * @Author: richen
- * @Date: 2025-06-09 16:00:00
- * @LastEditTime: 2025-06-09 16:00:00
- * @License: BSD (3-Clause)
- * @Copyright (c): <richenlin(at)gmail.com>
- */
-/**
- * Schedule task decorator with optimized preprocessing
- *
- * @export
- * @param {string} cron - Cron expression for task scheduling
- * @param {string} [timezone='Asia/Beijing'] - Timezone for the schedule
- *
- * Cron expression format:
- * * Seconds: 0-59
- * * Minutes: 0-59
- * * Hours: 0-23
- * * Day of Month: 1-31
- * * Months: 1-12 (Jan-Dec)
- * * Day of Week: 1-7 (Sun-Sat)
- *
- * @returns {MethodDecorator}
- * @throws {Error} When cron expression is invalid or decorator is used on wrong class type
- */
-function Scheduled(cron, timezone) {
-    // 参数验证
-    if (koatty_lib.Helper.isEmpty(cron)) {
-        throw Error("Cron expression is required and cannot be empty");
-    }
-    // 验证cron表达式格式
-    try {
-        validateCronExpression(cron);
-    }
-    catch (error) {
-        throw Error(`Invalid cron expression: ${error.message}`);
-    }
-    // 验证时区
-    if (timezone && typeof timezone !== 'string') {
-        throw Error("Timezone must be a string");
-    }
-    return (target, propertyKey, descriptor) => {
-        // 验证装饰器使用的类型（从原型对象获取类构造函数）
-        const targetClass = target.constructor;
-        const componentType = koatty_container.IOCContainer.getType(targetClass);
-        if (componentType !== "SERVICE" && componentType !== "COMPONENT") {
-            throw Error("@Scheduled decorator can only be used on SERVICE or COMPONENT classes.");
-        }
-        // 验证方法名
-        const methodName = propertyKey.toString();
-        if (!methodName || typeof methodName !== 'string') {
-            throw Error("Method name is required for @Scheduled decorator");
-        }
-        // 验证方法描述符
-        if (!descriptor || typeof descriptor.value !== 'function') {
-            throw Error("@Scheduled decorator can only be applied to methods");
-        }
-        // 保存类到IOC容器
-        koatty_container.IOCContainer.saveClass("COMPONENT", targetClass, targetClass.name);
-        // 保存调度元数据到 IOC 容器
-        koatty_container.IOCContainer.attachClassMetadata(COMPONENT_SCHEDULED, DecoratorType.SCHEDULED, {
-            method: methodName,
-            cron,
-            timezone // 保存用户指定的值，可能为undefined
-        }, target, methodName);
-    };
-}
-
 /*
  * @Description: RedLock utility for distributed locks
  * @Usage:
@@ -688,6 +536,8 @@ function timeoutPromise(ms) {
 /**
  * Initiation schedule locker client.
  *
+ * @param {RedLockOptions} options - RedLock 配置选项
+ * @param {Koatty} app - Koatty 应用实例
  * @returns {Promise<void>}
  */
 async function initRedLock(options, app) {
@@ -695,11 +545,12 @@ async function initRedLock(options, app) {
         koatty_logger.DefaultLogger.Warn(`RedLock initialization skipped: Koatty app not available or not initialized`);
         return;
     }
-    app.once("appStart", async function () {
+    app.once("appReady", async function () {
         try {
             if (koatty_lib.Helper.isEmpty(options)) {
                 throw Error(`Missing RedLock configuration. Please write a configuration item with the key name 'RedLock' in the db.ts file.`);
             }
+            // 获取RedLocker实例，在首次使用时自动初始化
             const redLocker = RedLocker.getInstance(options);
             await redLocker.initialize();
             koatty_logger.DefaultLogger.Info('RedLock initialized successfully');
@@ -710,72 +561,12 @@ async function initRedLock(options, app) {
         }
     });
 }
-/**
- * 批量注入RedLock锁 - 从IOC容器读取类元数据并应用所有RedLock装饰器
- *
- * @param {RedLockOptions} options - RedLock 配置选项
- * @param {Koatty} app - Koatty 应用实例
- */
-async function injectRedLock(_options, _app) {
-    try {
-        koatty_logger.DefaultLogger.Debug('Starting batch RedLock injection...');
-        const componentList = koatty_container.IOCContainer.listClass("COMPONENT");
-        for (const component of componentList) {
-            const classMetadata = koatty_container.IOCContainer.getClassMetadata(COMPONENT_REDLOCK, DecoratorType.REDLOCK, component.target);
-            if (!classMetadata) {
-                continue;
-            }
-            let redlockCount = 0;
-            for (const [className, metadata] of classMetadata) {
-                try {
-                    const instance = koatty_container.IOCContainer.get(className);
-                    if (!instance) {
-                        continue;
-                    }
-                    // 查找所有RedLock方法的元数据
-                    for (const [key, value] of Object.entries(metadata)) {
-                        if (key.startsWith('REDLOCK')) {
-                            const redlockData = value;
-                            const targetMethod = instance[redlockData.method];
-                            if (!koatty_lib.Helper.isFunction(targetMethod)) {
-                                koatty_logger.DefaultLogger.Warn(`RedLock injection skipped: method ${redlockData.method} is not a function in ${className}`);
-                                continue;
-                            }
-                            // 生成有效的RedLock选项：方法级别 > 全局配置 > 默认值
-                            const effectiveOptions = getEffectiveRedLockOptions(redlockData.options);
-                            // 应用RedLock增强描述符
-                            const originalDescriptor = {
-                                value: targetMethod,
-                                writable: true,
-                                enumerable: false,
-                                configurable: true
-                            };
-                            const enhancedDescriptor = redLockerDescriptor(originalDescriptor, redlockData.name, // 使用装饰器中确定的锁名称
-                            redlockData.method, effectiveOptions);
-                            // 替换原方法
-                            Object.defineProperty(instance, redlockData.method, enhancedDescriptor);
-                            redlockCount++;
-                            koatty_logger.DefaultLogger.Debug(`RedLock applied to ${className}.${redlockData.method} with lock name: ${redlockData.name}`);
-                        }
-                    }
-                }
-                catch (error) {
-                    koatty_logger.DefaultLogger.Error(`Failed to process class ${className}:`, error);
-                }
-            }
-            koatty_logger.DefaultLogger.Info(`Batch RedLock injection completed. ${redlockCount} locks applied.`);
-        }
-    }
-    catch (error) {
-        koatty_logger.DefaultLogger.Error('Failed to inject RedLocks:', error);
-    }
-}
 /**
  * Create redLocker Descriptor with improved error handling and type safety
  * @param descriptor - Property descriptor
  * @param name - Lock name
  * @param method - Method name
- * @param options - RedLock options
+ * @param methodOptions - Method-level RedLock options
  * @returns Enhanced property descriptor
  */
 function redLockerDescriptor(descriptor, name, method, methodOptions) {
@@ -794,13 +585,6 @@ function redLockerDescriptor(descriptor, name, method, methodOptions) {
     if (typeof value !== 'function') {
         throw new Error('Descriptor value must be a function');
     }
-    // 设置默认选项，合并方法级别的选项
-    const lockOptions = {
-        lockTimeOut: methodOptions?.lockTimeOut,
-        clockDriftFactor: methodOptions?.clockDriftFactor,
-        maxRetries: methodOptions?.maxRetries,
-        retryDelayMs: methodOptions?.retryDelayMs
-    };
     /**
      * Enhanced function wrapper with proper lock renewal and safety
      */
@@ -864,6 +648,7 @@ function redLockerDescriptor(descriptor, name, method, methodOptions) {
         async value(...props) {
             try {
                 const redlock = RedLocker.getInstance();
+                const lockOptions = getEffectiveRedLockOptions(methodOptions);
                 // Acquire a lock.
                 const lockTime = lockOptions.lockTimeOut || 10000;
                 if (lockTime <= 200) {
@@ -881,6 +666,169 @@ function redLockerDescriptor(descriptor, name, method, methodOptions) {
         },
     };
 }
+/**
+ * Generate lock name for RedLock decorator
+ */
+function generateLockName(configName, methodName, target) {
+    if (configName) {
+        return configName;
+    }
+    try {
+        const targetObj = target;
+        const identifier = koatty_container.IOCContainer.getIdentifier(targetObj);
+        if (identifier) {
+            return `${identifier}_${methodName}`;
+        }
+    }
+    catch {
+        // Fallback if IOC container is not available
+    }
+    const targetWithConstructor = target;
+    const className = targetWithConstructor.constructor?.name || 'Unknown';
+    return `${className}_${methodName}`;
+}
+
+/*
+ * @Description:
+ * @Usage:
+ * @Author: richen
+ * @Date: 2025-06-09 16:00:00
+ * @LastEditTime: 2025-06-09 16:00:00
+ * @License: BSD (3-Clause)
+ * @Copyright (c): <richenlin(at)gmail.com>
+ */
+/**
+ * Redis-based distributed lock decorator
+ *
+ * @export
+ * @param {string} [name] - The locker name. If name is duplicated, lock sharing contention will result.
+ *                          If not provided, a unique name will be auto-generated using method name + random suffix.
+ *                          IMPORTANT: Auto-generated names are unique per method deployment and not predictable.
+ * @param {RedLockMethodOptions} [options] - Lock configuration options for this method
+ *
+ * @returns {MethodDecorator}
+ * @throws {Error} When decorator is used on wrong class type or invalid configuration
+ *
+ * @example
+ * ```typescript
+ * class UserService {
+ *   @RedLock('user_update_lock', { lockTimeOut: 5000, maxRetries: 2 })
+ *   async updateUser(id: string, data: any) {
+ *     // This method will be protected by a distributed lock with predictable name
+ *   }
+ *
+ *   @RedLock() // Auto-generated unique name like "deleteUser_abc123_xyz789"
+ *   async deleteUser(id: string) {
+ *     // This method will be protected by a distributed lock with auto-generated unique name
+ *   }
+ * }
+ * ```
+ */
+function RedLock(lockName, options) {
+    return (target, propertyKey, descriptor) => {
+        const methodName = propertyKey.toString();
+        // 验证装饰器使用的类型（从原型对象获取类构造函数）
+        const targetClass = target.constructor;
+        const componentType = koatty_container.IOCContainer.getType(targetClass);
+        if (componentType !== "SERVICE" && componentType !== "COMPONENT") {
+            throw Error("@RedLock decorator can only be used on SERVICE or COMPONENT classes.");
+        }
+        // 验证方法名
+        if (!methodName || typeof methodName !== 'string') {
+            throw Error("Method name is required for @RedLock decorator");
+        }
+        // 验证方法描述符
+        if (!descriptor || typeof descriptor.value !== 'function') {
+            throw Error("@RedLock decorator can only be applied to methods");
+        }
+        // 生成锁名称：用户指定的 > 基于类名和方法名生成
+        const finalLockName = lockName || generateLockName(lockName, methodName, target);
+        // 验证选项
+        if (options) {
+            validateRedLockMethodOptions(options);
+        }
+        // 保存类到IOC容器
+        koatty_container.IOCContainer.saveClass("COMPONENT", targetClass, targetClass.name);
+        try {
+            // 直接在装饰器中包装方法，而不是延迟处理
+            const enhancedDescriptor = redLockerDescriptor(descriptor, finalLockName, methodName, options);
+            return enhancedDescriptor;
+        }
+        catch (error) {
+            throw new Error(`Failed to apply RedLock to ${methodName}: ${error.message}`);
+        }
+    };
+}
+
+/*
+ * @Description:
+ * @Usage:
+ * @Author: richen
+ * @Date: 2025-06-09 16:00:00
+ * @LastEditTime: 2025-06-09 16:00:00
+ * @License: BSD (3-Clause)
+ * @Copyright (c): <richenlin(at)gmail.com>
+ */
+/**
+ * Schedule task decorator with optimized preprocessing
+ *
+ * @export
+ * @param {string} cron - Cron expression for task scheduling
+ * @param {string} [timezone='Asia/Beijing'] - Timezone for the schedule
+ *
+ * Cron expression format:
+ * * Seconds: 0-59
+ * * Minutes: 0-59
+ * * Hours: 0-23
+ * * Day of Month: 1-31
+ * * Months: 1-12 (Jan-Dec)
+ * * Day of Week: 1-7 (Sun-Sat)
+ *
+ * @returns {MethodDecorator}
+ * @throws {Error} When cron expression is invalid or decorator is used on wrong class type
+ */
+function Scheduled(cron, timezone = 'Asia/Beijing') {
+    // 参数验证
+    if (koatty_lib.Helper.isEmpty(cron)) {
+        throw Error("Cron expression is required and cannot be empty");
+    }
+    // 验证cron表达式格式
+    try {
+        validateCronExpression(cron);
+    }
+    catch (error) {
+        throw Error(`Invalid cron expression: ${error.message}`);
+    }
+    // 验证时区
+    if (timezone && typeof timezone !== 'string') {
+        throw Error("Timezone must be a string");
+    }
+    return (target, propertyKey, descriptor) => {
+        // 验证装饰器使用的类型（从原型对象获取类构造函数）
+        const targetClass = target.constructor;
+        const componentType = koatty_container.IOCContainer.getType(targetClass);
+        if (componentType !== "SERVICE" && componentType !== "COMPONENT") {
+            throw Error("@Scheduled decorator can only be used on SERVICE or COMPONENT classes.");
+        }
+        // 验证方法名
+        const methodName = propertyKey.toString();
+        if (!methodName || typeof methodName !== 'string') {
+            throw Error("Method name is required for @Scheduled decorator");
+        }
+        // 验证方法描述符
+        if (!descriptor || typeof descriptor.value !== 'function') {
+            throw Error("@Scheduled decorator can only be applied to methods");
+        }
+        // 保存类到IOC容器
+        koatty_container.IOCContainer.saveClass("COMPONENT", targetClass, targetClass.name);
+        // 保存调度元数据到 IOC 容器
+        koatty_container.IOCContainer.attachClassMetadata(COMPONENT_SCHEDULED, DecoratorType.SCHEDULED, {
+            method: methodName,
+            cron,
+            timezone // 保存确定的时区值
+        }, target, methodName);
+    };
+}
 
 /**
  * @ author: richen
@@ -888,6 +836,29 @@ function redLockerDescriptor(descriptor, name, method, methodOptions) {
  * @ license: MIT
  * @ version: 2020-07-06 10:29:20
  */
+/**
+ * 初始化调度任务系统
+ * 在appReady时触发批量注入调度任务，确保所有初始化工作完成
+ *
+ * @param {Koatty} app - Koatty 应用实例
+ * @param {any} options - 调度任务配置
+ */
+async function initSchedule(options, app) {
+    if (!app || !koatty_lib.Helper.isFunction(app.once)) {
+        koatty_logger.DefaultLogger.Warn(`Schedule initialization skipped: Koatty app not available or not initialized`);
+        return;
+    }
+    app.once("appReady", async function () {
+        try {
+            await injectSchedule(options);
+            koatty_logger.DefaultLogger.Info('Schedule system initialized successfully');
+        }
+        catch (error) {
+            koatty_logger.DefaultLogger.Error('Failed to initialize Schedule system:', error);
+            throw error;
+        }
+    });
+}
 /**
  * Inject schedule job with enhanced error handling and validation
  *
@@ -898,11 +869,8 @@ function redLockerDescriptor(descriptor, name, method, methodOptions) {
  */
 /**
  * 批量注入调度任务 - 从IOC容器读取类元数据并创建所有CronJob
- *
- * @param {RedLockOptions} options - RedLock 配置选项
- * @param {Koatty} app - Koatty 应用实例
  */
-async function injectSchedule(_options, _app) {
+async function injectSchedule(options) {
     try {
         koatty_logger.DefaultLogger.Debug('Starting batch schedule injection...');
         const componentList = koatty_container.IOCContainer.listClass("COMPONENT");
@@ -928,7 +896,7 @@ async function injectSchedule(_options, _app) {
                                 continue;
                             }
                             const taskName = `${className}_${scheduleData.method}`;
-                            const tz = getEffectiveTimezone(scheduleData.timezone);
+                            const tz = getEffectiveTimezone(options, scheduleData.timezone);
                             new cron.CronJob(scheduleData.cron, () => {
                                 koatty_logger.DefaultLogger.Debug(`The schedule job ${taskName} started.`);
                                 Promise.resolve(targetMethod.call(instance))
@@ -992,11 +960,10 @@ const defaultOptions = {
  */
 async function KoattyScheduled(options, app) {
     options = { ...defaultOptions, ...options };
-    // 保存全局配置
-    setGlobalScheduledOptions(options);
+    // 初始化RedLock（appReady时触发，确保所有依赖就绪）
     await initRedLock(options, app);
-    await injectRedLock();
-    await injectSchedule();
+    // 初始化调度任务系统（appReady时触发，确保所有组件都已初始化）
+    await initSchedule(options, app);
 }
 
 exports.KoattyScheduled = KoattyScheduled;

package/dist/index.mjs

@@ -1,15 +1,15 @@
 /*!
 * @Author: richen
-* @Date: 2025-06-22 23:41:54
+* @Date: 2025-06-23 00:55:12
 * @License: BSD (3-Clause)
 * @Copyright (c) - <richenlin(at)gmail.com>
 * @HomePage: https://koatty.org/
 */
 import { IOCContainer } from 'koatty_container';
-import { Helper } from 'koatty_lib';
 import { Redlock } from '@sesamecare-oss/redlock';
 import { Redis } from 'ioredis';
 import { DefaultLogger } from 'koatty_logger';
+import { Helper } from 'koatty_lib';
 import { CronJob } from 'cron';
 
 /*
@@ -22,7 +22,6 @@ import { CronJob } from 'cron';
  * @Copyright (c): <richenlin(at)gmail.com>
  */
 const COMPONENT_SCHEDULED = 'COMPONENT_SCHEDULED';
-const COMPONENT_REDLOCK = 'COMPONENT_REDLOCK';
 /**
  * Decorator types supported by the system
  */
@@ -108,13 +107,6 @@ function validateRedLockMethodOptions(options) {
  * Global configuration storage
  */
 let globalScheduledOptions = {};
-/**
- * Set global scheduled options
- * @param options - Global scheduled options
- */
-function setGlobalScheduledOptions(options) {
-    globalScheduledOptions = { ...options };
-}
 /**
  * Get global scheduled options
  * @returns Global scheduled options
@@ -127,8 +119,8 @@ function getGlobalScheduledOptions() {
  * @param userTimezone - User specified timezone
  * @returns Effective timezone
  */
-function getEffectiveTimezone(userTimezone) {
-    return userTimezone || globalScheduledOptions.timezone || 'Asia/Beijing';
+function getEffectiveTimezone(options, userTimezone) {
+    return userTimezone || options.timezone || 'Asia/Beijing';
 }
 /**
  * Get effective RedLock method options with priority: method options > global options > defaults
@@ -145,150 +137,6 @@ function getEffectiveRedLockOptions(methodOptions) {
     };
 }
 
-/*
- * @Description:
- * @Usage:
- * @Author: richen
- * @Date: 2025-06-09 16:00:00
- * @LastEditTime: 2025-06-09 16:00:00
- * @License: BSD (3-Clause)
- * @Copyright (c): <richenlin(at)gmail.com>
- */
-/**
- * Redis-based distributed lock decorator
- *
- * @export
- * @param {string} [name] - The locker name. If name is duplicated, lock sharing contention will result.
- *                          If not provided, a unique name will be auto-generated using method name + random suffix.
- *                          IMPORTANT: Auto-generated names are unique per method deployment and not predictable.
- * @param {RedLockMethodOptions} [options] - Lock configuration options for this method
- *
- * @returns {MethodDecorator}
- * @throws {Error} When decorator is used on wrong class type or invalid configuration
- *
- * @example
- * ```typescript
- * class UserService {
- *   @RedLock('user_update_lock', { lockTimeOut: 5000, maxRetries: 2 })
- *   async updateUser(id: string, data: any) {
- *     // This method will be protected by a distributed lock with predictable name
- *   }
- *
- *   @RedLock() // Auto-generated unique name like "deleteUser_abc123_xyz789"
- *   async deleteUser(id: string) {
- *     // This method will be protected by a distributed lock with auto-generated unique name
- *   }
- * }
- * ```
- */
-function RedLock(lockName, options) {
-    return (target, propertyKey, descriptor) => {
-        const methodName = propertyKey.toString();
-        // 验证装饰器使用的类型（从原型对象获取类构造函数）
-        const targetClass = target.constructor;
-        const componentType = IOCContainer.getType(targetClass);
-        if (componentType !== "SERVICE" && componentType !== "COMPONENT") {
-            throw Error("@RedLock decorator can only be used on SERVICE or COMPONENT classes.");
-        }
-        // 验证方法名
-        if (!methodName || typeof methodName !== 'string') {
-            throw Error("Method name is required for @RedLock decorator");
-        }
-        // 验证方法描述符
-        if (!descriptor || typeof descriptor.value !== 'function') {
-            throw Error("@RedLock decorator can only be applied to methods");
-        }
-        // 生成唯一的锁名称：用户指定的 > 自动生成的唯一名称
-        if (!lockName || lockName.trim() === '') {
-            const randomSuffix = Math.random().toString(36).substring(2, 8); // 6位随机字符
-            const timestamp = Date.now().toString(36); // 时间戳转36进制
-            lockName = `${methodName}_${randomSuffix}_${timestamp}`;
-        }
-        // 验证选项
-        if (options) {
-            validateRedLockMethodOptions(options);
-        }
-        // 保存类到IOC容器
-        IOCContainer.saveClass("COMPONENT", targetClass, targetClass.name);
-        // 保存RedLock元数据到 IOC 容器（lockName已确定）
-        IOCContainer.attachClassMetadata(COMPONENT_REDLOCK, DecoratorType.REDLOCK, {
-            method: methodName,
-            name: lockName, // 确定的锁名称，不会为undefined
-            options
-        }, target, methodName);
-    };
-}
-
-/*
- * @Description:
- * @Usage:
- * @Author: richen
- * @Date: 2025-06-09 16:00:00
- * @LastEditTime: 2025-06-09 16:00:00
- * @License: BSD (3-Clause)
- * @Copyright (c): <richenlin(at)gmail.com>
- */
-/**
- * Schedule task decorator with optimized preprocessing
- *
- * @export
- * @param {string} cron - Cron expression for task scheduling
- * @param {string} [timezone='Asia/Beijing'] - Timezone for the schedule
- *
- * Cron expression format:
- * * Seconds: 0-59
- * * Minutes: 0-59
- * * Hours: 0-23
- * * Day of Month: 1-31
- * * Months: 1-12 (Jan-Dec)
- * * Day of Week: 1-7 (Sun-Sat)
- *
- * @returns {MethodDecorator}
- * @throws {Error} When cron expression is invalid or decorator is used on wrong class type
- */
-function Scheduled(cron, timezone) {
-    // 参数验证
-    if (Helper.isEmpty(cron)) {
-        throw Error("Cron expression is required and cannot be empty");
-    }
-    // 验证cron表达式格式
-    try {
-        validateCronExpression(cron);
-    }
-    catch (error) {
-        throw Error(`Invalid cron expression: ${error.message}`);
-    }
-    // 验证时区
-    if (timezone && typeof timezone !== 'string') {
-        throw Error("Timezone must be a string");
-    }
-    return (target, propertyKey, descriptor) => {
-        // 验证装饰器使用的类型（从原型对象获取类构造函数）
-        const targetClass = target.constructor;
-        const componentType = IOCContainer.getType(targetClass);
-        if (componentType !== "SERVICE" && componentType !== "COMPONENT") {
-            throw Error("@Scheduled decorator can only be used on SERVICE or COMPONENT classes.");
-        }
-        // 验证方法名
-        const methodName = propertyKey.toString();
-        if (!methodName || typeof methodName !== 'string') {
-            throw Error("Method name is required for @Scheduled decorator");
-        }
-        // 验证方法描述符
-        if (!descriptor || typeof descriptor.value !== 'function') {
-            throw Error("@Scheduled decorator can only be applied to methods");
-        }
-        // 保存类到IOC容器
-        IOCContainer.saveClass("COMPONENT", targetClass, targetClass.name);
-        // 保存调度元数据到 IOC 容器
-        IOCContainer.attachClassMetadata(COMPONENT_SCHEDULED, DecoratorType.SCHEDULED, {
-            method: methodName,
-            cron,
-            timezone // 保存用户指定的值，可能为undefined
-        }, target, methodName);
-    };
-}
-
 /*
  * @Description: RedLock utility for distributed locks
  * @Usage:
@@ -686,6 +534,8 @@ function timeoutPromise(ms) {
 /**
  * Initiation schedule locker client.
  *
+ * @param {RedLockOptions} options - RedLock 配置选项
+ * @param {Koatty} app - Koatty 应用实例
  * @returns {Promise<void>}
  */
 async function initRedLock(options, app) {
@@ -693,11 +543,12 @@ async function initRedLock(options, app) {
         DefaultLogger.Warn(`RedLock initialization skipped: Koatty app not available or not initialized`);
         return;
     }
-    app.once("appStart", async function () {
+    app.once("appReady", async function () {
         try {
             if (Helper.isEmpty(options)) {
                 throw Error(`Missing RedLock configuration. Please write a configuration item with the key name 'RedLock' in the db.ts file.`);
             }
+            // 获取RedLocker实例，在首次使用时自动初始化
             const redLocker = RedLocker.getInstance(options);
             await redLocker.initialize();
             DefaultLogger.Info('RedLock initialized successfully');
@@ -708,72 +559,12 @@ async function initRedLock(options, app) {
         }
     });
 }
-/**
- * 批量注入RedLock锁 - 从IOC容器读取类元数据并应用所有RedLock装饰器
- *
- * @param {RedLockOptions} options - RedLock 配置选项
- * @param {Koatty} app - Koatty 应用实例
- */
-async function injectRedLock(_options, _app) {
-    try {
-        DefaultLogger.Debug('Starting batch RedLock injection...');
-        const componentList = IOCContainer.listClass("COMPONENT");
-        for (const component of componentList) {
-            const classMetadata = IOCContainer.getClassMetadata(COMPONENT_REDLOCK, DecoratorType.REDLOCK, component.target);
-            if (!classMetadata) {
-                continue;
-            }
-            let redlockCount = 0;
-            for (const [className, metadata] of classMetadata) {
-                try {
-                    const instance = IOCContainer.get(className);
-                    if (!instance) {
-                        continue;
-                    }
-                    // 查找所有RedLock方法的元数据
-                    for (const [key, value] of Object.entries(metadata)) {
-                        if (key.startsWith('REDLOCK')) {
-                            const redlockData = value;
-                            const targetMethod = instance[redlockData.method];
-                            if (!Helper.isFunction(targetMethod)) {
-                                DefaultLogger.Warn(`RedLock injection skipped: method ${redlockData.method} is not a function in ${className}`);
-                                continue;
-                            }
-                            // 生成有效的RedLock选项：方法级别 > 全局配置 > 默认值
-                            const effectiveOptions = getEffectiveRedLockOptions(redlockData.options);
-                            // 应用RedLock增强描述符
-                            const originalDescriptor = {
-                                value: targetMethod,
-                                writable: true,
-                                enumerable: false,
-                                configurable: true
-                            };
-                            const enhancedDescriptor = redLockerDescriptor(originalDescriptor, redlockData.name, // 使用装饰器中确定的锁名称
-                            redlockData.method, effectiveOptions);
-                            // 替换原方法
-                            Object.defineProperty(instance, redlockData.method, enhancedDescriptor);
-                            redlockCount++;
-                            DefaultLogger.Debug(`RedLock applied to ${className}.${redlockData.method} with lock name: ${redlockData.name}`);
-                        }
-                    }
-                }
-                catch (error) {
-                    DefaultLogger.Error(`Failed to process class ${className}:`, error);
-                }
-            }
-            DefaultLogger.Info(`Batch RedLock injection completed. ${redlockCount} locks applied.`);
-        }
-    }
-    catch (error) {
-        DefaultLogger.Error('Failed to inject RedLocks:', error);
-    }
-}
 /**
  * Create redLocker Descriptor with improved error handling and type safety
  * @param descriptor - Property descriptor
  * @param name - Lock name
  * @param method - Method name
- * @param options - RedLock options
+ * @param methodOptions - Method-level RedLock options
  * @returns Enhanced property descriptor
  */
 function redLockerDescriptor(descriptor, name, method, methodOptions) {
@@ -792,13 +583,6 @@ function redLockerDescriptor(descriptor, name, method, methodOptions) {
     if (typeof value !== 'function') {
         throw new Error('Descriptor value must be a function');
     }
-    // 设置默认选项，合并方法级别的选项
-    const lockOptions = {
-        lockTimeOut: methodOptions?.lockTimeOut,
-        clockDriftFactor: methodOptions?.clockDriftFactor,
-        maxRetries: methodOptions?.maxRetries,
-        retryDelayMs: methodOptions?.retryDelayMs
-    };
     /**
      * Enhanced function wrapper with proper lock renewal and safety
      */
@@ -862,6 +646,7 @@ function redLockerDescriptor(descriptor, name, method, methodOptions) {
         async value(...props) {
             try {
                 const redlock = RedLocker.getInstance();
+                const lockOptions = getEffectiveRedLockOptions(methodOptions);
                 // Acquire a lock.
                 const lockTime = lockOptions.lockTimeOut || 10000;
                 if (lockTime <= 200) {
@@ -879,6 +664,169 @@ function redLockerDescriptor(descriptor, name, method, methodOptions) {
         },
     };
 }
+/**
+ * Generate lock name for RedLock decorator
+ */
+function generateLockName(configName, methodName, target) {
+    if (configName) {
+        return configName;
+    }
+    try {
+        const targetObj = target;
+        const identifier = IOCContainer.getIdentifier(targetObj);
+        if (identifier) {
+            return `${identifier}_${methodName}`;
+        }
+    }
+    catch {
+        // Fallback if IOC container is not available
+    }
+    const targetWithConstructor = target;
+    const className = targetWithConstructor.constructor?.name || 'Unknown';
+    return `${className}_${methodName}`;
+}
+
+/*
+ * @Description:
+ * @Usage:
+ * @Author: richen
+ * @Date: 2025-06-09 16:00:00
+ * @LastEditTime: 2025-06-09 16:00:00
+ * @License: BSD (3-Clause)
+ * @Copyright (c): <richenlin(at)gmail.com>
+ */
+/**
+ * Redis-based distributed lock decorator
+ *
+ * @export
+ * @param {string} [name] - The locker name. If name is duplicated, lock sharing contention will result.
+ *                          If not provided, a unique name will be auto-generated using method name + random suffix.
+ *                          IMPORTANT: Auto-generated names are unique per method deployment and not predictable.
+ * @param {RedLockMethodOptions} [options] - Lock configuration options for this method
+ *
+ * @returns {MethodDecorator}
+ * @throws {Error} When decorator is used on wrong class type or invalid configuration
+ *
+ * @example
+ * ```typescript
+ * class UserService {
+ *   @RedLock('user_update_lock', { lockTimeOut: 5000, maxRetries: 2 })
+ *   async updateUser(id: string, data: any) {
+ *     // This method will be protected by a distributed lock with predictable name
+ *   }
+ *
+ *   @RedLock() // Auto-generated unique name like "deleteUser_abc123_xyz789"
+ *   async deleteUser(id: string) {
+ *     // This method will be protected by a distributed lock with auto-generated unique name
+ *   }
+ * }
+ * ```
+ */
+function RedLock(lockName, options) {
+    return (target, propertyKey, descriptor) => {
+        const methodName = propertyKey.toString();
+        // 验证装饰器使用的类型（从原型对象获取类构造函数）
+        const targetClass = target.constructor;
+        const componentType = IOCContainer.getType(targetClass);
+        if (componentType !== "SERVICE" && componentType !== "COMPONENT") {
+            throw Error("@RedLock decorator can only be used on SERVICE or COMPONENT classes.");
+        }
+        // 验证方法名
+        if (!methodName || typeof methodName !== 'string') {
+            throw Error("Method name is required for @RedLock decorator");
+        }
+        // 验证方法描述符
+        if (!descriptor || typeof descriptor.value !== 'function') {
+            throw Error("@RedLock decorator can only be applied to methods");
+        }
+        // 生成锁名称：用户指定的 > 基于类名和方法名生成
+        const finalLockName = lockName || generateLockName(lockName, methodName, target);
+        // 验证选项
+        if (options) {
+            validateRedLockMethodOptions(options);
+        }
+        // 保存类到IOC容器
+        IOCContainer.saveClass("COMPONENT", targetClass, targetClass.name);
+        try {
+            // 直接在装饰器中包装方法，而不是延迟处理
+            const enhancedDescriptor = redLockerDescriptor(descriptor, finalLockName, methodName, options);
+            return enhancedDescriptor;
+        }
+        catch (error) {
+            throw new Error(`Failed to apply RedLock to ${methodName}: ${error.message}`);
+        }
+    };
+}
+
+/*
+ * @Description:
+ * @Usage:
+ * @Author: richen
+ * @Date: 2025-06-09 16:00:00
+ * @LastEditTime: 2025-06-09 16:00:00
+ * @License: BSD (3-Clause)
+ * @Copyright (c): <richenlin(at)gmail.com>
+ */
+/**
+ * Schedule task decorator with optimized preprocessing
+ *
+ * @export
+ * @param {string} cron - Cron expression for task scheduling
+ * @param {string} [timezone='Asia/Beijing'] - Timezone for the schedule
+ *
+ * Cron expression format:
+ * * Seconds: 0-59
+ * * Minutes: 0-59
+ * * Hours: 0-23
+ * * Day of Month: 1-31
+ * * Months: 1-12 (Jan-Dec)
+ * * Day of Week: 1-7 (Sun-Sat)
+ *
+ * @returns {MethodDecorator}
+ * @throws {Error} When cron expression is invalid or decorator is used on wrong class type
+ */
+function Scheduled(cron, timezone = 'Asia/Beijing') {
+    // 参数验证
+    if (Helper.isEmpty(cron)) {
+        throw Error("Cron expression is required and cannot be empty");
+    }
+    // 验证cron表达式格式
+    try {
+        validateCronExpression(cron);
+    }
+    catch (error) {
+        throw Error(`Invalid cron expression: ${error.message}`);
+    }
+    // 验证时区
+    if (timezone && typeof timezone !== 'string') {
+        throw Error("Timezone must be a string");
+    }
+    return (target, propertyKey, descriptor) => {
+        // 验证装饰器使用的类型（从原型对象获取类构造函数）
+        const targetClass = target.constructor;
+        const componentType = IOCContainer.getType(targetClass);
+        if (componentType !== "SERVICE" && componentType !== "COMPONENT") {
+            throw Error("@Scheduled decorator can only be used on SERVICE or COMPONENT classes.");
+        }
+        // 验证方法名
+        const methodName = propertyKey.toString();
+        if (!methodName || typeof methodName !== 'string') {
+            throw Error("Method name is required for @Scheduled decorator");
+        }
+        // 验证方法描述符
+        if (!descriptor || typeof descriptor.value !== 'function') {
+            throw Error("@Scheduled decorator can only be applied to methods");
+        }
+        // 保存类到IOC容器
+        IOCContainer.saveClass("COMPONENT", targetClass, targetClass.name);
+        // 保存调度元数据到 IOC 容器
+        IOCContainer.attachClassMetadata(COMPONENT_SCHEDULED, DecoratorType.SCHEDULED, {
+            method: methodName,
+            cron,
+            timezone // 保存确定的时区值
+        }, target, methodName);
+    };
+}
 
 /**
  * @ author: richen
@@ -886,6 +834,29 @@ function redLockerDescriptor(descriptor, name, method, methodOptions) {
  * @ license: MIT
  * @ version: 2020-07-06 10:29:20
  */
+/**
+ * 初始化调度任务系统
+ * 在appReady时触发批量注入调度任务，确保所有初始化工作完成
+ *
+ * @param {Koatty} app - Koatty 应用实例
+ * @param {any} options - 调度任务配置
+ */
+async function initSchedule(options, app) {
+    if (!app || !Helper.isFunction(app.once)) {
+        DefaultLogger.Warn(`Schedule initialization skipped: Koatty app not available or not initialized`);
+        return;
+    }
+    app.once("appReady", async function () {
+        try {
+            await injectSchedule(options);
+            DefaultLogger.Info('Schedule system initialized successfully');
+        }
+        catch (error) {
+            DefaultLogger.Error('Failed to initialize Schedule system:', error);
+            throw error;
+        }
+    });
+}
 /**
  * Inject schedule job with enhanced error handling and validation
  *
@@ -896,11 +867,8 @@ function redLockerDescriptor(descriptor, name, method, methodOptions) {
  */
 /**
  * 批量注入调度任务 - 从IOC容器读取类元数据并创建所有CronJob
- *
- * @param {RedLockOptions} options - RedLock 配置选项
- * @param {Koatty} app - Koatty 应用实例
  */
-async function injectSchedule(_options, _app) {
+async function injectSchedule(options) {
     try {
         DefaultLogger.Debug('Starting batch schedule injection...');
         const componentList = IOCContainer.listClass("COMPONENT");
@@ -926,7 +894,7 @@ async function injectSchedule(_options, _app) {
                                 continue;
                             }
                             const taskName = `${className}_${scheduleData.method}`;
-                            const tz = getEffectiveTimezone(scheduleData.timezone);
+                            const tz = getEffectiveTimezone(options, scheduleData.timezone);
                             new CronJob(scheduleData.cron, () => {
                                 DefaultLogger.Debug(`The schedule job ${taskName} started.`);
                                 Promise.resolve(targetMethod.call(instance))
@@ -990,11 +958,10 @@ const defaultOptions = {
  */
 async function KoattyScheduled(options, app) {
     options = { ...defaultOptions, ...options };
-    // 保存全局配置
-    setGlobalScheduledOptions(options);
+    // 初始化RedLock（appReady时触发，确保所有依赖就绪）
     await initRedLock(options, app);
-    await injectRedLock();
-    await injectSchedule();
+    // 初始化调度任务系统（appReady时触发，确保所有组件都已初始化）
+    await initSchedule(options, app);
 }
 
 export { KoattyScheduled, RedLock, Scheduled, SchedulerLock };

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koatty_schedule",
-  "version": "3.3.1",
+  "version": "3.3.2",
   "description": "Schedule for koatty.",
   "scripts": {
     "build": "npm run build:js && npm run build:dts && npm run build:doc && npm run build:cp",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koatty_schedule",
-  "version": "3.3.1",
+  "version": "3.3.2",
   "description": "Schedule for koatty.",
   "scripts": {
     "build": "npm run build:js && npm run build:dts && npm run build:doc && npm run build:cp",