koatty_schedule 3.3.2 → 3.3.4

package/dist/index.mjs

@@ -1,14 +1,14 @@
 /*!
 * @Author: richen
-* @Date: 2025-06-23 00:55:12
+* @Date: 2026-01-28 13:35:25
 * @License: BSD (3-Clause)
 * @Copyright (c) - <richenlin(at)gmail.com>
 * @HomePage: https://koatty.org/
 */
 import { IOCContainer } from 'koatty_container';
 import { Redlock } from '@sesamecare-oss/redlock';
-import { Redis } from 'ioredis';
 import { DefaultLogger } from 'koatty_logger';
+import Redis, { Cluster } from 'ioredis';
 import { Helper } from 'koatty_lib';
 import { CronJob } from 'cron';
 
@@ -31,45 +31,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})`);
+    }
+    // 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;
     }
-    // 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');
+    // 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 (!/^(\*|[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');
+        if (range !== '*') {
+            validateCronField(range, min, max, fieldName, fieldNameCN, allowedStrings);
         }
-        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');
+        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})`);
         }
-        // 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 (isNaN(endValue) || endValue < min || endValue > max) {
+            throw new Error(`${fieldNameCN}字段的范围结束值无效: ${end}，必须在 ${min}-${max} 之间 (Invalid range end for ${fieldName}: ${end}, must be between ${min}-${max})`);
         }
+        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})`);
     }
 }
 /**
@@ -130,13 +195,257 @@ function getEffectiveTimezone(options, userTimezone) {
 function getEffectiveRedLockOptions(methodOptions) {
     const globalOptions = getGlobalScheduledOptions();
     return {
-        lockTimeOut: methodOptions?.lockTimeOut || globalOptions.lockTimeOut || 10000,
-        clockDriftFactor: methodOptions?.clockDriftFactor || globalOptions.clockDriftFactor || 0.01,
-        maxRetries: methodOptions?.maxRetries || globalOptions.maxRetries || 3,
-        retryDelayMs: methodOptions?.retryDelayMs || globalOptions.retryDelayMs || 200
+        lockTimeOut: (methodOptions === null || methodOptions === void 0 ? void 0 : methodOptions.lockTimeOut) || globalOptions.lockTimeOut || 10000,
+        clockDriftFactor: (methodOptions === null || methodOptions === void 0 ? void 0 : methodOptions.clockDriftFactor) || globalOptions.clockDriftFactor || 0.01,
+        maxRetries: (methodOptions === null || methodOptions === void 0 ? void 0 : methodOptions.maxRetries) || globalOptions.maxRetries || 3,
+        retryDelayMs: (methodOptions === null || methodOptions === void 0 ? void 0 : methodOptions.retryDelayMs) || globalOptions.retryDelayMs || 200
     };
 }
 
+/*
+ * @Description: Abstract interfaces for Redis client and distributed lock
+ * @Usage:
+ * @Author: richen
+ * @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 connection mode
+ */
+var RedisMode;
+(function (RedisMode) {
+    RedisMode["STANDALONE"] = "standalone";
+    RedisMode["SENTINEL"] = "sentinel";
+    RedisMode["CLUSTER"] = "cluster"; // 集群模式
+})(RedisMode || (RedisMode = {}));
+
+/*
+ * @Description: Redis client factory supporting multiple modes
+ * @Usage:
+ * @Author: richen
+ * @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 client wrapper that implements IRedisClient interface
+ * Wraps ioredis client to provide unified interface
+ */
+class RedisClientAdapter {
+    constructor(client) {
+        this.client = client;
+    }
+    get status() {
+        return this.client.status;
+    }
+    async call(command, ...args) {
+        return this.client.call(command, ...args);
+    }
+    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);
+    }
+    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 || RedisMode.STANDALONE;
+        DefaultLogger.Debug(`Creating Redis client in ${mode} mode`);
+        switch (mode) {
+            case RedisMode.STANDALONE:
+                return this.createStandaloneClient(config);
+            case RedisMode.SENTINEL:
+                return this.createSentinelClient(config);
+            case RedisMode.CLUSTER:
+                return this.createClusterClient(config);
+            default:
+                throw new Error(`不支持的 Redis 模式: ${mode} (Unsupported Redis mode: ${mode})`);
+        }
+    }
+    /**
+     * Create standalone Redis client
+     * @param config - Standalone configuration
+     */
+    static createStandaloneClient(config) {
+        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);
+                DefaultLogger.Debug(`Redis reconnecting, attempt ${times}, delay ${delay}ms`);
+                return delay;
+            },
+            reconnectOnError: (err) => {
+                DefaultLogger.Warn('Redis connection error, attempting reconnect:', err.message);
+                return true;
+            }
+        };
+        const client = new Redis(options);
+        client.on('connect', () => {
+            DefaultLogger.Info('Redis standalone client connected successfully');
+        });
+        client.on('error', (err) => {
+            DefaultLogger.Error('Redis standalone client error:', err);
+        });
+        return new RedisClientAdapter(client);
+    }
+    /**
+     * Create sentinel Redis client
+     * @param config - Sentinel configuration
+     */
+    static createSentinelClient(config) {
+        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);
+                DefaultLogger.Debug(`Sentinel Redis reconnecting, attempt ${times}, delay ${delay}ms`);
+                return delay;
+            }
+        };
+        const client = new Redis(options);
+        client.on('connect', () => {
+            DefaultLogger.Info(`Redis sentinel client connected to master: ${config.name}`);
+        });
+        client.on('error', (err) => {
+            DefaultLogger.Error('Redis sentinel client error:', err);
+        });
+        return new RedisClientAdapter(client);
+    }
+    /**
+     * Create cluster Redis client
+     * @param config - Cluster configuration
+     */
+    static createClusterClient(config) {
+        var _a, _b;
+        DefaultLogger.Debug(`Creating cluster Redis client with ${config.nodes.length} nodes`);
+        const clusterOptions = {
+            redisOptions: {
+                password: ((_a = config.redisOptions) === null || _a === void 0 ? void 0 : _a.password) || config.password || undefined,
+                db: ((_b = config.redisOptions) === null || _b === void 0 ? void 0 : _b.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);
+                DefaultLogger.Debug(`Cluster Redis reconnecting, attempt ${times}, delay ${delay}ms`);
+                return delay;
+            }
+        };
+        const cluster = new Cluster(config.nodes, clusterOptions);
+        cluster.on('connect', () => {
+            DefaultLogger.Info('Redis cluster client connected successfully');
+        });
+        cluster.on('error', (err) => {
+            DefaultLogger.Error('Redis cluster client error:', err);
+        });
+        cluster.on('node error', (err, address) => {
+            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)');
+        }
+        const mode = config.mode || RedisMode.STANDALONE;
+        switch (mode) {
+            case RedisMode.STANDALONE:
+                this.validateStandaloneConfig(config);
+                break;
+            case RedisMode.SENTINEL:
+                this.validateSentinelConfig(config);
+                break;
+            case RedisMode.CLUSTER:
+                this.validateClusterConfig(config);
+                break;
+            default:
+                throw new Error(`不支持的 Redis 模式: ${mode} (Unsupported Redis mode: ${mode})`);
+        }
+    }
+    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)');
+        }
+    }
+}
+
 /*
  * @Description: RedLock utility for distributed locks
  * @Usage:
@@ -154,12 +463,8 @@ const defaultRedLockConfig = {
     clockDriftFactor: 0.01,
     maxRetries: 3,
     retryDelayMs: 200,
-    driftFactor: 0.01,
-    retryCount: 3,
-    retryDelay: 200,
-    retryJitter: 200,
-    automaticExtensionThreshold: 500,
     redisConfig: {
+        mode: RedisMode.STANDALONE,
         host: '127.0.0.1',
         port: 6379,
         password: '',
@@ -167,21 +472,29 @@ 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;
-    config;
-    isInitialized = false;
-    initializationPromise = null;
     // 私有构造函数防止外部直接实例化
     constructor(options) {
+        this.redlock = null;
+        this.redisClient = null;
+        this.isInitialized = false;
+        this.initializationPromise = null;
         this.config = { ...defaultRedLockConfig, ...options };
         // Register this instance in IOC container
         this.registerInContainer();
@@ -270,8 +583,12 @@ class RedLocker {
             await this.initializationPromise;
         }
         catch (error) {
-            // 初始化失败时清理缓存，允许重试
+            // 初始化失败时完整清理状态，允许重试
             this.initializationPromise = null;
+            this.isInitialized = false;
+            this.redlock = null;
+            // 注意：不清理 redis 连接，因为它可能来自 IOC 容器
+            DefaultLogger.Warn('RedLocker initialization failed, state has been reset for retry');
             throw error;
         }
     }
@@ -281,34 +598,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 = IOCContainer.get('Redis', 'COMPONENT');
-                DefaultLogger.Debug('Using Redis instance from IOC container');
+                const existingRedis = 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);
+                    }
+                    DefaultLogger.Debug('Using Redis instance from IOC container');
+                }
             }
             catch {
-                // Create new Redis connection if not available in container
-                this.redis = new 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);
                 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([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([underlyingClient], redlockSettings);
             // Set up error handlers
             this.redlock.on('clientError', (err) => {
                 DefaultLogger.Error('Redis client error in RedLock:', err);
@@ -409,7 +746,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
@@ -437,11 +774,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();
                 DefaultLogger.Debug('Redis connection closed');
             }
-            this.redis = null;
+            this.redisClient = null;
             this.redlock = null;
             this.isInitialized = false;
         }
@@ -473,15 +810,17 @@ class RedLocker {
      * @returns Health status
      */
     async healthCheck() {
+        var _a, _b;
         try {
             await this.initialize();
-            const redisStatus = this.redis?.status || 'unknown';
+            const redisStatus = ((_a = this.redisClient) === null || _a === void 0 ? void 0 : _a.status) || 'unknown';
             const isReady = this.isReady();
             return {
                 status: isReady ? 'healthy' : 'unhealthy',
                 details: {
                     initialized: this.isInitialized,
                     redisStatus,
+                    redisMode: ((_b = this.config.redisConfig) === null || _b === void 0 ? void 0 : _b.mode) || 'unknown',
                     redlockReady: !!this.redlock,
                     containerRegistered: this.getContainerInfo().registered
                 }
@@ -498,6 +837,8 @@ class RedLocker {
         }
     }
 }
+RedLocker.instance = null;
+RedLocker.instanceLock = Symbol('RedLocker.instanceLock');
 
 /*
  * @Description:
@@ -508,18 +849,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;
 }
 
 /*
@@ -543,21 +888,19 @@ async function initRedLock(options, app) {
         DefaultLogger.Warn(`RedLock initialization skipped: Koatty app not available or not initialized`);
         return;
     }
-    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');
-        }
-        catch (error) {
-            DefaultLogger.Error('Failed to initialize RedLock:', error);
-            throw error;
+    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');
+    }
+    catch (error) {
+        DefaultLogger.Error('Failed to initialize RedLock:', error);
+        throw error;
+    }
 }
 /**
  * Create redLocker Descriptor with improved error handling and type safety
@@ -593,15 +936,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++;
@@ -668,6 +1017,7 @@ function redLockerDescriptor(descriptor, name, method, methodOptions) {
  * Generate lock name for RedLock decorator
  */
 function generateLockName(configName, methodName, target) {
+    var _a;
     if (configName) {
         return configName;
     }
@@ -682,7 +1032,7 @@ function generateLockName(configName, methodName, target) {
         // Fallback if IOC container is not available
     }
     const targetWithConstructor = target;
-    const className = targetWithConstructor.constructor?.name || 'Unknown';
+    const className = ((_a = targetWithConstructor.constructor) === null || _a === void 0 ? void 0 : _a.name) || 'Unknown';
     return `${className}_${methodName}`;
 }
 
@@ -846,16 +1196,14 @@ async function initSchedule(options, app) {
         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;
-        }
-    });
+    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
@@ -945,6 +1293,7 @@ const defaultOptions = {
     maxRetries: 3,
     retryDelayMs: 200,
     redisConfig: {
+        mode: RedisMode.STANDALONE,
         host: "localhost",
         port: 6379,
         password: "",
@@ -958,10 +1307,12 @@ const defaultOptions = {
  */
 async function KoattyScheduled(options, app) {
     options = { ...defaultOptions, ...options };
-    // 初始化RedLock（appReady时触发，确保所有依赖就绪）
-    await initRedLock(options, app);
-    // 初始化调度任务系统（appReady时触发，确保所有组件都已初始化）
-    await initSchedule(options, app);
+    app.once("appReady", async function () {
+        // 初始化RedLock
+        await initRedLock(options, app);
+        // 初始化调度任务系统
+        await initSchedule(options, app);
+    });
 }
 
-export { KoattyScheduled, RedLock, Scheduled, SchedulerLock };
+export { KoattyScheduled, RedLock, RedLocker, RedisClientAdapter, RedisFactory, RedisMode, Scheduled, SchedulerLock };