koatty_schedule 3.3.1 → 3.3.3

package/dist/index.d.ts

@@ -1,12 +1,143 @@
 /*!
 * @Author: richen
-* @Date: 2025-06-22 23:42:00
+* @Date: 2025-10-31 17:51:00
 * @License: BSD (3-Clause)
 * @Copyright (c) - <richenlin(at)gmail.com>
 * @HomePage: https://koatty.org/
 */
+import { Cluster } from 'ioredis';
 import { Koatty } from 'koatty_core';
-import { Settings } from '@sesamecare-oss/redlock';
+import { Lock } from '@sesamecare-oss/redlock';
+import Redis from 'ioredis';
+import type { Settings } from '@sesamecare-oss/redlock';
+
+/**
+ * Base Redis configuration
+ */
+declare interface BaseRedisConfig {
+    mode?: RedisMode;
+    host?: string;
+    port?: number;
+    password?: string;
+    db?: number;
+    keyPrefix?: string;
+    connectTimeout?: number;
+    commandTimeout?: number;
+    maxRetriesPerRequest?: number;
+}
+
+/**
+ * Abstract distributed lock interface
+ * Allows for different lock implementations (RedLock, Zookeeper, etc.)
+ */
+export declare interface IDistributedLock {
+    /**
+     * Initialize the lock system
+     */
+    initialize(): Promise<void>;
+    /**
+     * Acquire a distributed lock
+     * @param resources - Resource identifiers
+     * @param ttl - Time to live in milliseconds
+     */
+    acquire(resources: string[], ttl: number): Promise<Lock>;
+    /**
+     * Release a lock
+     * @param lock - Lock instance
+     */
+    release(lock: Lock): Promise<void>;
+    /**
+     * Extend lock TTL
+     * @param lock - Lock instance
+     * @param ttl - New TTL in milliseconds
+     */
+    extend(lock: Lock, ttl: number): Promise<Lock>;
+    /**
+     * Check if the lock system is ready
+     */
+    isReady(): boolean;
+    /**
+     * Get current configuration
+     */
+    getConfig(): any;
+    /**
+     * Close and cleanup
+     */
+    close(): Promise<void>;
+    /**
+     * Health check
+     */
+    healthCheck(): Promise<{
+        status: 'healthy' | 'unhealthy';
+        details: Record<string, any>;
+    }>;
+}
+
+/**
+ * Lock configuration options
+ */
+export declare interface ILockOptions extends Partial<Settings> {
+    lockTimeOut?: number;
+    clockDriftFactor?: number;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    redisConfig?: RedisConfig;
+}
+
+/**
+ * Abstract Redis client interface
+ * Provides unified interface for different Redis implementations
+ */
+export declare interface IRedisClient {
+    /**
+     * Get connection status
+     */
+    readonly status: string;
+    /**
+     * Execute Redis command
+     * @param command - Command name
+     * @param args - Command arguments
+     */
+    call(command: string, ...args: any[]): Promise<any>;
+    /**
+     * Set a key-value pair
+     * @param key - Key name
+     * @param value - Value
+     * @param mode - Optional mode (e.g., 'EX' for expiration)
+     * @param duration - Optional duration in seconds
+     */
+    set(key: string, value: string | Buffer, mode?: string, duration?: number): Promise<'OK' | null>;
+    /**
+     * Get value by key
+     * @param key - Key name
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Delete one or more keys
+     * @param keys - Key names
+     */
+    del(...keys: string[]): Promise<number>;
+    /**
+     * Check if key exists
+     * @param key - Key name
+     */
+    exists(key: string): Promise<number>;
+    /**
+     * Evaluate Lua script
+     * @param script - Lua script
+     * @param numKeys - Number of keys
+     * @param args - Script arguments
+     */
+    eval(script: string, numKeys: number, ...args: any[]): Promise<any>;
+    /**
+     * Close the connection
+     */
+    quit(): Promise<'OK'>;
+    /**
+     * Disconnect immediately
+     */
+    disconnect(): void;
+}
 
 /**
  * @param options - The options for the scheduled job
@@ -15,14 +146,106 @@ import { Settings } from '@sesamecare-oss/redlock';
 export declare function KoattyScheduled(options: ScheduledOptions, app: Koatty): Promise<void>;
 
 /**
- * Redis connection configuration
+ * Redis client wrapper that implements IRedisClient interface
+ * Wraps ioredis client to provide unified interface
  */
-declare interface RedisConfig {
-    host?: string;
-    port?: number;
-    password?: string;
-    db?: number;
-    keyPrefix?: string;
+export declare class RedisClientAdapter implements IRedisClient {
+    constructor(client: Redis | Cluster);
+    get status(): string;
+    call(command: string, ...args: any[]): Promise<any>;
+    set(key: string, value: string | Buffer, mode?: string, duration?: number): Promise<'OK' | null>;
+    get(key: string): Promise<string | null>;
+    del(...keys: string[]): Promise<number>;
+    exists(key: string): Promise<number>;
+    eval(script: string, numKeys: number, ...args: any[]): Promise<any>;
+    quit(): Promise<'OK'>;
+    disconnect(): void;
+    /**
+     * Get underlying Redis/Cluster instance
+     * Used for RedLock initialization
+     */
+    getClient(): Redis | Cluster;
+}
+
+/**
+ * Cluster configuration
+ */
+export declare interface RedisClusterConfig extends BaseRedisConfig {
+    mode: RedisMode.CLUSTER;
+    nodes: Array<{
+        host: string;
+        port: number;
+    }>;
+    redisOptions?: {
+        password?: string;
+        db?: number;
+    };
+}
+
+/**
+ * Union type for all Redis configurations
+ */
+export declare type RedisConfig = RedisStandaloneConfig | RedisSentinelConfig | RedisClusterConfig;
+
+/**
+ * Redis client factory
+ * Creates appropriate Redis client based on configuration
+ */
+export declare class RedisFactory {
+    /**
+     * Create Redis client based on configuration mode
+     * @param config - Redis configuration
+     * @returns Redis client adapter
+     */
+    static createClient(config: RedisConfig): RedisClientAdapter;
+    /**
+     * Create standalone Redis client
+     * @param config - Standalone configuration
+     */
+    /**
+     * Create sentinel Redis client
+     * @param config - Sentinel configuration
+     */
+    /**
+     * Create cluster Redis client
+     * @param config - Cluster configuration
+     */
+    /**
+     * Validate Redis configuration
+     * @param config - Redis configuration to validate
+     */
+    static validateConfig(config: RedisConfig): void;
+}
+
+/**
+ * Redis connection mode
+ */
+export declare enum RedisMode {
+    STANDALONE = "standalone",// 单机模式
+    SENTINEL = "sentinel",// 哨兵模式
+    CLUSTER = "cluster"
+}
+
+/**
+ * Sentinel configuration
+ */
+export declare interface RedisSentinelConfig extends BaseRedisConfig {
+    mode: RedisMode.SENTINEL;
+    sentinels: Array<{
+        host: string;
+        port: number;
+    }>;
+    name: string;
+    sentinelPassword?: string;
+}
+
+/**
+ * Standalone configuration
+ */
+export declare interface RedisStandaloneConfig extends BaseRedisConfig {
+    mode?: RedisMode.STANDALONE;
+    host: string;
+    port: number;
 }
 
 /**
@@ -54,6 +277,95 @@ declare interface RedisConfig {
  */
 export declare function RedLock(lockName?: string, options?: RedLockMethodOptions): MethodDecorator;
 
+/**
+ * RedLock distributed lock manager
+ * Integrated with koatty IOC container
+ * Implements singleton pattern for safe instance management
+ * Implements IDistributedLock interface for abstraction
+ */
+export declare class RedLocker implements IDistributedLock {
+    /**
+     * Register RedLocker in IOC container
+     * @private
+     */
+    /**
+     * Get RedLocker singleton instance with thread-safe initialization
+     * @static
+     * @param options - RedLock configuration options (only used for first initialization)
+     * @returns RedLocker singleton instance
+     */
+    static getInstance(options?: RedLockOptions): RedLocker;
+    /**
+     * Reset singleton instance (主要用于测试)
+     * @static
+     */
+    static resetInstance(): void;
+    /**
+     * Initialize RedLock with Redis connection
+     * Uses cached promise to avoid duplicate initialization
+     * @private
+     */
+    initialize(): Promise<void>;
+    /**
+     * 执行实际的初始化操作
+     * @private
+     */
+    /**
+     * Acquire a distributed lock
+     * @param resources - Resource identifiers to lock
+     * @param ttl - Time to live in milliseconds
+     * @returns Promise<Lock>
+     */
+    acquire(resources: string[], ttl?: number): Promise<Lock>;
+    /**
+     * Release a lock
+     * @param lock - Lock instance to release
+     */
+    release(lock: Lock): Promise<void>;
+    /**
+     * Extend a lock's TTL
+     * @param lock - Lock instance to extend
+     * @param ttl - New TTL in milliseconds
+     * @returns Extended lock
+     */
+    extend(lock: Lock, ttl: number): Promise<Lock>;
+    /**
+     * Check if RedLocker is initialized
+     * @returns true if initialized, false otherwise
+     */
+    isReady(): boolean;
+    /**
+     * Get current configuration
+     * @returns Current RedLock configuration
+     */
+    getConfig(): RedLockOptions;
+    /**
+     * Update configuration (requires reinitialization)
+     * @param options - New RedLock options
+     */
+    updateConfig(options?: Partial<RedLockOptions>): void;
+    /**
+     * Close Redis connection and cleanup
+     */
+    close(): Promise<void>;
+    /**
+     * Get container registration status
+     * @returns Registration information
+     */
+    getContainerInfo(): {
+        registered: boolean;
+        identifier: string;
+    };
+    /**
+     * Health check for RedLocker
+     * @returns Health status
+     */
+    healthCheck(): Promise<{
+        status: 'healthy' | 'unhealthy';
+        details: Record<string, any>;
+    }>;
+}
+
 /**
  * RedLock method-level options (excluding Redis connection config)
  */
@@ -66,12 +378,9 @@ declare interface RedLockMethodOptions {
 
 /**
  * Configuration options for RedLock
+ * @deprecated Use ILockOptions from interface instead
  */
-declare interface RedLockOptions extends Partial<Settings> {
-    lockTimeOut?: number;
-    clockDriftFactor?: number;
-    maxRetries?: number;
-    retryDelayMs?: number;
+export declare interface RedLockOptions extends ILockOptions {
     redisConfig?: RedisConfig;
 }