koatty_schedule 3.3.1 → 3.3.3

package/dist/index.js

@@ -1,6 +1,6 @@
 /*!
 * @Author: richen
-* @Date: 2025-06-22 23:41:54
+* @Date: 2025-10-31 17:50:55
 * @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 Redis = require('ioredis');
+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
  */
@@ -34,45 +33,110 @@ var DecoratorType;
     DecoratorType["REDLOCK"] = "REDLOCK";
 })(DecoratorType || (DecoratorType = {}));
 /**
- * Validate cron expression format
+ * Validate cron expression format (supports both 5-part and 6-part formats)
+ *
+ * 6-part format: second minute hour day month weekday
+ * 5-part format: minute hour day month weekday
+ *
  * @param cron - Cron expression to validate
  * @throws {Error} When cron expression is invalid
  */
 function validateCronExpression(cron) {
     if (!cron || typeof cron !== 'string') {
-        throw new Error('Cron expression must be a non-empty string');
+        throw new Error('Cron 表达式必须是非空字符串 (Cron expression must be a non-empty string)');
     }
     const cronParts = cron.trim().split(/\s+/);
     // Cron expressions should have 5 or 6 parts (with or without seconds)
     if (cronParts.length < 5 || cronParts.length > 6) {
-        throw new Error(`Invalid cron expression format. Expected 5 or 6 parts, got ${cronParts.length}`);
+        throw new Error(`Cron 表达式格式无效。期望 5 或 6 部分，实际得到 ${cronParts.length} 部分 (Invalid cron format. Expected 5 or 6 parts, got ${cronParts.length})`);
     }
-    // For 6-part cron (with seconds), validate each part
-    if (cronParts.length === 6) {
-        const [seconds, minutes, hours] = cronParts;
-        // Basic validation for obvious invalid values
-        if (!/^(\*|[0-9]|[0-5][0-9]|\*\/[0-9]+|[0-9]+-[0-9]+|[0-9]+(,[0-9]+)*)$/.test(seconds)) {
-            throw new Error('Invalid seconds field in cron expression');
+    // Determine if this is a 6-part (with seconds) or 5-part expression
+    const hasSecs = cronParts.length === 6;
+    const offset = hasSecs ? 0 : -1;
+    // Extract parts with proper indexing
+    const seconds = hasSecs ? cronParts[0] : null;
+    const minutes = cronParts[offset + 1];
+    const hours = cronParts[offset + 2];
+    const dayOfMonth = cronParts[offset + 3];
+    const month = cronParts[offset + 4];
+    const dayOfWeek = cronParts[offset + 5];
+    // Validate seconds (0-59) if present
+    if (seconds !== null) {
+        validateCronField(seconds, 0, 59, 'seconds', '秒');
+    }
+    // Validate minutes (0-59)
+    validateCronField(minutes, 0, 59, 'minutes', '分钟');
+    // Validate hours (0-23)
+    validateCronField(hours, 0, 23, 'hours', '小时');
+    // Validate day of month (1-31)
+    validateCronField(dayOfMonth, 1, 31, 'day of month', '日期');
+    // Validate month (1-12 or JAN-DEC)
+    validateCronField(month, 1, 12, 'month', '月份', ['JAN', 'FEB', 'MAR', 'APR', 'MAY', 'JUN', 'JUL', 'AUG', 'SEP', 'OCT', 'NOV', 'DEC']);
+    // Validate day of week (0-7 or SUN-SAT, where 0 and 7 both represent Sunday)
+    validateCronField(dayOfWeek, 0, 7, 'day of week', '星期', ['SUN', 'MON', 'TUE', 'WED', 'THU', 'FRI', 'SAT']);
+}
+/**
+ * Validate individual cron field
+ * @param field - Field value to validate
+ * @param min - Minimum allowed value
+ * @param max - Maximum allowed value
+ * @param fieldName - English field name for error messages
+ * @param fieldNameCN - Chinese field name for error messages
+ * @param allowedStrings - Optional array of allowed string values (e.g., month/weekday names)
+ */
+function validateCronField(field, min, max, fieldName, fieldNameCN, allowedStrings) {
+    // Allow wildcard
+    if (field === '*') {
+        return;
+    }
+    // Allow question mark (for day of month / day of week)
+    if (field === '?') {
+        return;
+    }
+    // Check for allowed string values (month/weekday names)
+    if (allowedStrings && allowedStrings.some(str => field.toUpperCase().includes(str))) {
+        return;
+    }
+    // Step values (e.g., */5, 0-30/5)
+    if (field.includes('/')) {
+        const [range, step] = field.split('/');
+        const stepValue = parseInt(step);
+        if (isNaN(stepValue) || stepValue <= 0) {
+            throw new Error(`${fieldNameCN}字段的步长值无效: ${step} (Invalid step value for ${fieldName}: ${step})`);
+        }
+        if (range !== '*') {
+            validateCronField(range, min, max, fieldName, fieldNameCN, allowedStrings);
         }
-        if (!/^(\*|[0-9]|[0-5][0-9]|\*\/[0-9]+|[0-9]+-[0-9]+|[0-9]+(,[0-9]+)*)$/.test(minutes)) {
-            throw new Error('Invalid minutes field in cron expression');
+        return;
+    }
+    // Range values (e.g., 1-5)
+    if (field.includes('-')) {
+        const [start, end] = field.split('-');
+        const startValue = parseInt(start);
+        const endValue = parseInt(end);
+        if (isNaN(startValue) || startValue < min || startValue > max) {
+            throw new Error(`${fieldNameCN}字段的范围起始值无效: ${start}，必须在 ${min}-${max} 之间 (Invalid range start for ${fieldName}: ${start}, must be between ${min}-${max})`);
         }
-        if (!/^(\*|[0-9]|1[0-9]|2[0-3]|\*\/[0-9]+|[0-9]+-[0-9]+|[0-9]+(,[0-9]+)*)$/.test(hours)) {
-            throw new Error('Invalid hours field in cron expression');
+        if (isNaN(endValue) || endValue < min || endValue > max) {
+            throw new Error(`${fieldNameCN}字段的范围结束值无效: ${end}，必须在 ${min}-${max} 之间 (Invalid range end for ${fieldName}: ${end}, must be between ${min}-${max})`);
         }
-        // Check for simple out-of-range values
-        const secondsValue = parseInt(seconds);
-        if (!isNaN(secondsValue) && (secondsValue < 0 || secondsValue > 59)) {
-            throw new Error('Seconds value must be between 0 and 59');
+        if (startValue > endValue) {
+            throw new Error(`${fieldNameCN}字段的范围无效: ${start}-${end}，起始值不能大于结束值 (Invalid range for ${fieldName}: ${start}-${end}, start cannot be greater than end)`);
         }
+        return;
     }
-    // Additional basic checks for common invalid patterns
-    if (cron.includes('60')) {
-        // Check if 60 appears as a standalone number (not part of a larger number)
-        const parts = cron.split(/[\s,\-\/]/);
-        if (parts.some(part => part === '60')) {
-            throw new Error('Invalid time value: 60 is not valid for any time field');
+    // List values (e.g., 1,3,5)
+    if (field.includes(',')) {
+        const values = field.split(',');
+        for (const value of values) {
+            validateCronField(value.trim(), min, max, fieldName, fieldNameCN, allowedStrings);
         }
+        return;
+    }
+    // Single numeric value
+    const numValue = parseInt(field);
+    if (isNaN(numValue) || numValue < min || numValue > max) {
+        throw new Error(`${fieldNameCN}字段的值无效: ${field}，必须在 ${min}-${max} 之间 (Invalid ${fieldName} value: ${field}, must be between ${min}-${max})`);
     }
 }
 /**
@@ -110,13 +174,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 +186,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
@@ -148,147 +205,247 @@ function getEffectiveRedLockOptions(methodOptions) {
 }
 
 /*
- * @Description:
+ * @Description: Abstract interfaces for Redis client and distributed lock
  * @Usage:
  * @Author: richen
- * @Date: 2025-06-09 16:00:00
- * @LastEditTime: 2025-06-09 16:00:00
+ * @Date: 2025-10-30 12:00:00
+ * @LastEditTime: 2025-10-30 12: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
- *   }
- * }
- * ```
+ * Redis connection mode
  */
-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);
-    };
-}
+exports.RedisMode = void 0;
+(function (RedisMode) {
+    RedisMode["STANDALONE"] = "standalone";
+    RedisMode["SENTINEL"] = "sentinel";
+    RedisMode["CLUSTER"] = "cluster"; // 集群模式
+})(exports.RedisMode || (exports.RedisMode = {}));
 
 /*
- * @Description:
+ * @Description: Redis client factory supporting multiple modes
  * @Usage:
  * @Author: richen
- * @Date: 2025-06-09 16:00:00
- * @LastEditTime: 2025-06-09 16:00:00
+ * @Date: 2025-10-30 12:00:00
+ * @LastEditTime: 2025-10-30 12: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
+ * Redis client wrapper that implements IRedisClient interface
+ * Wraps ioredis client to provide unified interface
  */
-function Scheduled(cron, timezone) {
-    // 参数验证
-    if (koatty_lib.Helper.isEmpty(cron)) {
-        throw Error("Cron expression is required and cannot be empty");
+class RedisClientAdapter {
+    client;
+    constructor(client) {
+        this.client = client;
     }
-    // 验证cron表达式格式
-    try {
-        validateCronExpression(cron);
+    get status() {
+        return this.client.status;
     }
-    catch (error) {
-        throw Error(`Invalid cron expression: ${error.message}`);
+    async call(command, ...args) {
+        return this.client.call(command, ...args);
     }
-    // 验证时区
-    if (timezone && typeof timezone !== 'string') {
-        throw Error("Timezone must be a string");
+    async set(key, value, mode, duration) {
+        if (mode && duration) {
+            // Use type assertion for mode parameter due to ioredis strict typing
+            return this.client.set(key, value, mode, duration);
+        }
+        return this.client.set(key, value);
     }
-    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.");
+    async get(key) {
+        return this.client.get(key);
+    }
+    async del(...keys) {
+        return this.client.del(...keys);
+    }
+    async exists(key) {
+        return this.client.exists(key);
+    }
+    async eval(script, numKeys, ...args) {
+        return this.client.eval(script, numKeys, ...args);
+    }
+    async quit() {
+        return this.client.quit();
+    }
+    disconnect() {
+        this.client.disconnect();
+    }
+    /**
+     * Get underlying Redis/Cluster instance
+     * Used for RedLock initialization
+     */
+    getClient() {
+        return this.client;
+    }
+}
+/**
+ * Redis client factory
+ * Creates appropriate Redis client based on configuration
+ */
+class RedisFactory {
+    /**
+     * Create Redis client based on configuration mode
+     * @param config - Redis configuration
+     * @returns Redis client adapter
+     */
+    static createClient(config) {
+        const mode = config.mode || exports.RedisMode.STANDALONE;
+        koatty_logger.DefaultLogger.Debug(`Creating Redis client in ${mode} mode`);
+        switch (mode) {
+            case exports.RedisMode.STANDALONE:
+                return this.createStandaloneClient(config);
+            case exports.RedisMode.SENTINEL:
+                return this.createSentinelClient(config);
+            case exports.RedisMode.CLUSTER:
+                return this.createClusterClient(config);
+            default:
+                throw new Error(`不支持的 Redis 模式: ${mode} (Unsupported Redis mode: ${mode})`);
         }
-        // 验证方法名
-        const methodName = propertyKey.toString();
-        if (!methodName || typeof methodName !== 'string') {
-            throw Error("Method name is required for @Scheduled decorator");
+    }
+    /**
+     * Create standalone Redis client
+     * @param config - Standalone configuration
+     */
+    static createStandaloneClient(config) {
+        koatty_logger.DefaultLogger.Debug(`Creating standalone Redis client: ${config.host}:${config.port}`);
+        const options = {
+            host: config.host,
+            port: config.port,
+            password: config.password || undefined,
+            db: config.db || 0,
+            keyPrefix: config.keyPrefix || '',
+            connectTimeout: config.connectTimeout || 10000,
+            commandTimeout: config.commandTimeout || 5000,
+            maxRetriesPerRequest: config.maxRetriesPerRequest || 3,
+            retryStrategy: (times) => {
+                const delay = Math.min(times * 50, 2000);
+                koatty_logger.DefaultLogger.Debug(`Redis reconnecting, attempt ${times}, delay ${delay}ms`);
+                return delay;
+            },
+            reconnectOnError: (err) => {
+                koatty_logger.DefaultLogger.Warn('Redis connection error, attempting reconnect:', err.message);
+                return true;
+            }
+        };
+        const client = new Redis(options);
+        client.on('connect', () => {
+            koatty_logger.DefaultLogger.Info('Redis standalone client connected successfully');
+        });
+        client.on('error', (err) => {
+            koatty_logger.DefaultLogger.Error('Redis standalone client error:', err);
+        });
+        return new RedisClientAdapter(client);
+    }
+    /**
+     * Create sentinel Redis client
+     * @param config - Sentinel configuration
+     */
+    static createSentinelClient(config) {
+        koatty_logger.DefaultLogger.Debug(`Creating sentinel Redis client for master: ${config.name}`);
+        const options = {
+            sentinels: config.sentinels,
+            name: config.name,
+            password: config.password || undefined,
+            sentinelPassword: config.sentinelPassword || undefined,
+            db: config.db || 0,
+            keyPrefix: config.keyPrefix || '',
+            connectTimeout: config.connectTimeout || 10000,
+            commandTimeout: config.commandTimeout || 5000,
+            maxRetriesPerRequest: config.maxRetriesPerRequest || 3,
+            retryStrategy: (times) => {
+                const delay = Math.min(times * 50, 2000);
+                koatty_logger.DefaultLogger.Debug(`Sentinel Redis reconnecting, attempt ${times}, delay ${delay}ms`);
+                return delay;
+            }
+        };
+        const client = new Redis(options);
+        client.on('connect', () => {
+            koatty_logger.DefaultLogger.Info(`Redis sentinel client connected to master: ${config.name}`);
+        });
+        client.on('error', (err) => {
+            koatty_logger.DefaultLogger.Error('Redis sentinel client error:', err);
+        });
+        return new RedisClientAdapter(client);
+    }
+    /**
+     * Create cluster Redis client
+     * @param config - Cluster configuration
+     */
+    static createClusterClient(config) {
+        koatty_logger.DefaultLogger.Debug(`Creating cluster Redis client with ${config.nodes.length} nodes`);
+        const clusterOptions = {
+            redisOptions: {
+                password: config.redisOptions?.password || config.password || undefined,
+                db: config.redisOptions?.db || config.db || 0,
+                keyPrefix: config.keyPrefix || '',
+                connectTimeout: config.connectTimeout || 10000,
+                commandTimeout: config.commandTimeout || 5000,
+                maxRetriesPerRequest: config.maxRetriesPerRequest || 3
+            },
+            clusterRetryStrategy: (times) => {
+                const delay = Math.min(times * 50, 2000);
+                koatty_logger.DefaultLogger.Debug(`Cluster Redis reconnecting, attempt ${times}, delay ${delay}ms`);
+                return delay;
+            }
+        };
+        const cluster = new Redis.Cluster(config.nodes, clusterOptions);
+        cluster.on('connect', () => {
+            koatty_logger.DefaultLogger.Info('Redis cluster client connected successfully');
+        });
+        cluster.on('error', (err) => {
+            koatty_logger.DefaultLogger.Error('Redis cluster client error:', err);
+        });
+        cluster.on('node error', (err, address) => {
+            koatty_logger.DefaultLogger.Error(`Redis cluster node error at ${address}:`, err);
+        });
+        return new RedisClientAdapter(cluster);
+    }
+    /**
+     * Validate Redis configuration
+     * @param config - Redis configuration to validate
+     */
+    static validateConfig(config) {
+        if (!config) {
+            throw new Error('Redis 配置不能为空 (Redis configuration cannot be empty)');
         }
-        // 验证方法描述符
-        if (!descriptor || typeof descriptor.value !== 'function') {
-            throw Error("@Scheduled decorator can only be applied to methods");
+        const mode = config.mode || exports.RedisMode.STANDALONE;
+        switch (mode) {
+            case exports.RedisMode.STANDALONE:
+                this.validateStandaloneConfig(config);
+                break;
+            case exports.RedisMode.SENTINEL:
+                this.validateSentinelConfig(config);
+                break;
+            case exports.RedisMode.CLUSTER:
+                this.validateClusterConfig(config);
+                break;
+            default:
+                throw new Error(`不支持的 Redis 模式: ${mode} (Unsupported Redis mode: ${mode})`);
         }
-        // 保存类到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);
-    };
+    }
+    static validateStandaloneConfig(config) {
+        if (!config.host) {
+            throw new Error('单机模式需要 host 配置 (Standalone mode requires host configuration)');
+        }
+        if (!config.port) {
+            throw new Error('单机模式需要 port 配置 (Standalone mode requires port configuration)');
+        }
+    }
+    static validateSentinelConfig(config) {
+        if (!config.sentinels || config.sentinels.length === 0) {
+            throw new Error('哨兵模式需要至少一个哨兵节点配置 (Sentinel mode requires at least one sentinel node)');
+        }
+        if (!config.name) {
+            throw new Error('哨兵模式需要 master name 配置 (Sentinel mode requires master name)');
+        }
+    }
+    static validateClusterConfig(config) {
+        if (!config.nodes || config.nodes.length === 0) {
+            throw new Error('集群模式需要至少一个节点配置 (Cluster mode requires at least one node)');
+        }
+    }
 }
 
 /*
@@ -308,12 +465,8 @@ const defaultRedLockConfig = {
     clockDriftFactor: 0.01,
     maxRetries: 3,
     retryDelayMs: 200,
-    driftFactor: 0.01,
-    retryCount: 3,
-    retryDelay: 200,
-    retryJitter: 200,
-    automaticExtensionThreshold: 500,
     redisConfig: {
+        mode: exports.RedisMode.STANDALONE,
         host: '127.0.0.1',
         port: 6379,
         password: '',
@@ -321,16 +474,27 @@ const defaultRedLockConfig = {
         keyPrefix: 'redlock:'
     }
 };
+/**
+ * Default Redlock Settings for @sesamecare-oss/redlock
+ */
+const defaultRedlockSettings = {
+    driftFactor: 0.01,
+    retryCount: 3,
+    retryDelay: 200,
+    retryJitter: 200,
+    automaticExtensionThreshold: 500
+};
 /**
  * RedLock distributed lock manager
  * Integrated with koatty IOC container
  * Implements singleton pattern for safe instance management
+ * Implements IDistributedLock interface for abstraction
  */
 class RedLocker {
     static instance = null;
     static instanceLock = Symbol('RedLocker.instanceLock');
     redlock = null;
-    redis = null;
+    redisClient = null;
     config;
     isInitialized = false;
     initializationPromise = null;
@@ -424,8 +588,12 @@ class RedLocker {
             await this.initializationPromise;
         }
         catch (error) {
-            // 初始化失败时清理缓存，允许重试
+            // 初始化失败时完整清理状态，允许重试
             this.initializationPromise = null;
+            this.isInitialized = false;
+            this.redlock = null;
+            // 注意：不清理 redis 连接，因为它可能来自 IOC 容器
+            koatty_logger.DefaultLogger.Warn('RedLocker initialization failed, state has been reset for retry');
             throw error;
         }
     }
@@ -435,34 +603,54 @@ class RedLocker {
      */
     async performInitialization() {
         try {
+            // Validate Redis configuration
+            if (this.config.redisConfig) {
+                RedisFactory.validateConfig(this.config.redisConfig);
+            }
             // Try to get Redis instance from IOC container first
             try {
-                this.redis = koatty_container.IOCContainer.get('Redis', 'COMPONENT');
-                koatty_logger.DefaultLogger.Debug('Using Redis instance from IOC container');
+                const existingRedis = koatty_container.IOCContainer.get('Redis', 'COMPONENT');
+                // If Redis instance exists in container, wrap it
+                if (existingRedis) {
+                    // Check if it's already a RedisClientAdapter
+                    if (existingRedis instanceof RedisClientAdapter) {
+                        this.redisClient = existingRedis;
+                    }
+                    else {
+                        // Wrap raw Redis/Cluster instance (type assertion needed)
+                        this.redisClient = new RedisClientAdapter(existingRedis);
+                    }
+                    koatty_logger.DefaultLogger.Debug('Using Redis instance from IOC container');
+                }
             }
             catch {
-                // Create new Redis connection if not available in container
-                this.redis = new ioredis.Redis({
-                    host: this.config.redisConfig.host,
-                    port: this.config.redisConfig.port,
-                    password: this.config.redisConfig.password || undefined,
-                    db: this.config.redisConfig.db || 0,
-                    keyPrefix: this.config.redisConfig.keyPrefix,
-                    maxRetriesPerRequest: 3
-                });
+                // IOC container doesn't have Redis, create new connection
+            }
+            // Create new Redis connection if not available in container
+            if (!this.redisClient && this.config.redisConfig) {
+                this.redisClient = RedisFactory.createClient(this.config.redisConfig);
                 koatty_logger.DefaultLogger.Debug('Created new Redis connection for RedLocker');
             }
-            if (!this.redis) {
-                throw new Error('Failed to initialize Redis connection');
+            if (!this.redisClient) {
+                throw new Error('Failed to initialize Redis connection: no configuration provided');
             }
+            // Get underlying client for Redlock
+            const underlyingClient = this.redisClient.getClient();
+            // Merge default settings with user configuration
+            // Extract Settings properties from config (which extends Partial<Settings>)
+            const userSettings = this.config;
+            const redlockSettings = {
+                ...defaultRedlockSettings,
+                ...(userSettings.driftFactor !== undefined && { driftFactor: userSettings.driftFactor }),
+                ...(userSettings.retryCount !== undefined && { retryCount: userSettings.retryCount }),
+                ...(userSettings.retryDelay !== undefined && { retryDelay: userSettings.retryDelay }),
+                ...(userSettings.retryJitter !== undefined && { retryJitter: userSettings.retryJitter }),
+                ...(userSettings.automaticExtensionThreshold !== undefined && {
+                    automaticExtensionThreshold: userSettings.automaticExtensionThreshold
+                })
+            };
             // Initialize Redlock with the Redis instance
-            this.redlock = new redlock.Redlock([this.redis], {
-                driftFactor: this.config.driftFactor,
-                retryCount: this.config.retryCount,
-                retryDelay: this.config.retryDelay,
-                retryJitter: this.config.retryJitter,
-                automaticExtensionThreshold: this.config.automaticExtensionThreshold
-            });
+            this.redlock = new redlock.Redlock([underlyingClient], redlockSettings);
             // Set up error handlers
             this.redlock.on('clientError', (err) => {
                 koatty_logger.DefaultLogger.Error('Redis client error in RedLock:', err);
@@ -563,7 +751,7 @@ class RedLocker {
      * @returns true if initialized, false otherwise
      */
     isReady() {
-        return this.isInitialized && !!this.redlock && !!this.redis;
+        return this.isInitialized && !!this.redlock && !!this.redisClient;
     }
     /**
      * Get current configuration
@@ -591,11 +779,11 @@ class RedLocker {
      */
     async close() {
         try {
-            if (this.redis && this.redis.status === 'ready') {
-                await this.redis.quit();
+            if (this.redisClient && this.redisClient.status === 'ready') {
+                await this.redisClient.quit();
                 koatty_logger.DefaultLogger.Debug('Redis connection closed');
             }
-            this.redis = null;
+            this.redisClient = null;
             this.redlock = null;
             this.isInitialized = false;
         }
@@ -629,13 +817,14 @@ class RedLocker {
     async healthCheck() {
         try {
             await this.initialize();
-            const redisStatus = this.redis?.status || 'unknown';
+            const redisStatus = this.redisClient?.status || 'unknown';
             const isReady = this.isReady();
             return {
                 status: isReady ? 'healthy' : 'unhealthy',
                 details: {
                     initialized: this.isInitialized,
                     redisStatus,
+                    redisMode: this.config.redisConfig?.mode || 'unknown',
                     redlockReady: !!this.redlock,
                     containerRegistered: this.getContainerInfo().registered
                 }
@@ -662,18 +851,22 @@ class RedLocker {
  * @License: BSD (3-Clause)
  * @Copyright (c): <richenlin(at)gmail.com>
  */
-/**
- * 返回一个 Promise，在指定时间后 reject
- * @param ms
- * @returns
- */
 function timeoutPromise(ms) {
-    return new Promise((resolve, reject) => {
-        const timeoutId = setTimeout(() => {
-            clearTimeout(timeoutId);
+    let timeoutId = null;
+    const promise = new Promise((resolve, reject) => {
+        timeoutId = setTimeout(() => {
+            timeoutId = null;
             reject(new Error('TIME_OUT_ERROR'));
         }, ms);
     });
+    // 添加取消方法，防止内存泄漏
+    promise.cancel = () => {
+        if (timeoutId !== null) {
+            clearTimeout(timeoutId);
+            timeoutId = null;
+        }
+    };
+    return promise;
 }
 
 /*
@@ -688,6 +881,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 +890,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 +906,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 +930,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
      */
@@ -811,15 +940,21 @@ function redLockerDescriptor(descriptor, name, method, methodOptions) {
         let extensionCount = 0;
         try {
             while (remainingTime > 0 && extensionCount < maxExtensions) {
+                // 创建可取消的超时 Promise
+                const timeoutHandler = timeoutPromise(remainingTime);
                 try {
                     // 执行业务方法，与超时竞争
                     const result = await Promise.race([
                         value.apply(self, props),
-                        timeoutPromise(remainingTime)
+                        timeoutHandler
                     ]);
-                    return result; // 成功执行，返回业务结果
+                    // 成功执行，取消超时定时器防止内存泄漏
+                    timeoutHandler.cancel();
+                    return result;
                 }
                 catch (error) {
+                    // 无论什么错误，都要取消超时定时器
+                    timeoutHandler.cancel();
                     // 处理超时错误，尝试续期锁
                     if (error instanceof Error && error.message === 'TIME_OUT_ERROR') {
                         extensionCount++;
@@ -864,6 +999,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 +1017,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 +1187,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 +1220,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 +1247,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))
@@ -979,6 +1298,7 @@ const defaultOptions = {
     maxRetries: 3,
     retryDelayMs: 200,
     redisConfig: {
+        mode: exports.RedisMode.STANDALONE,
         host: "localhost",
         port: 6379,
         password: "",
@@ -992,14 +1312,16 @@ 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;
 exports.RedLock = RedLock;
+exports.RedLocker = RedLocker;
+exports.RedisClientAdapter = RedisClientAdapter;
+exports.RedisFactory = RedisFactory;
 exports.Scheduled = Scheduled;
 exports.SchedulerLock = SchedulerLock;