koatty_schedule/dist/index.d.ts

Schedule for koatty.

/*!
* @Author: richen
* @Date: 2025-06-23 00:55:18
* @License: BSD (3-Clause)
* @Copyright (c) - <richenlin(at)gmail.com>
* @HomePage: https://koatty.org/
*/
import { Koatty } from 'koatty_core';
import { Settings } from '@sesamecare-oss/redlock';

/**
 * @param options - The options for the scheduled job
 * @param app - The Koatty application instance
 */
export declare function KoattyScheduled(options: ScheduledOptions, app: Koatty): Promise<void>;

/**
 * Redis connection configuration
 */
declare interface RedisConfig {
    host?: string;
    port?: number;
    password?: string;
    db?: number;
    keyPrefix?: string;
}

/**
 * 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
 *   }
 * }
 * ```
 */
export declare function RedLock(lockName?: string, options?: RedLockMethodOptions): MethodDecorator;

/**
 * RedLock method-level options (excluding Redis connection config)
 */
declare interface RedLockMethodOptions {
    lockTimeOut?: number;
    clockDriftFactor?: number;
    maxRetries?: number;
    retryDelayMs?: number;
}

/**
 * Configuration options for RedLock
 */
declare interface RedLockOptions extends Partial<Settings> {
    lockTimeOut?: number;
    clockDriftFactor?: number;
    maxRetries?: number;
    retryDelayMs?: number;
    redisConfig?: RedisConfig;
}

/**
 * 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
 */
export declare function Scheduled(cron: string, timezone?: string): MethodDecorator;

/**
 * Scheduled global options interface
 */
declare interface ScheduledOptions extends RedLockOptions {
    timezone?: string;
}

/**
 * @deprecated Use RedLock instead. This will be removed in v3.0.0
 */
export declare const SchedulerLock: typeof RedLock;

export { }