@guren/server 0.2.0-alpha.7 → 1.0.0-rc.9

package/dist/Scheduler-BstvSca7.d.ts

@@ -0,0 +1,469 @@
+/**
+ * Scheduled task callback.
+ */
+type TaskCallback = () => void | Promise<void>;
+/**
+ * Task definition.
+ */
+interface TaskDefinition {
+    /**
+     * Task name.
+     */
+    name?: string;
+    /**
+     * Cron expression.
+     */
+    expression: string;
+    /**
+     * Timezone for the schedule.
+     */
+    timezone?: string;
+    /**
+     * Task callback.
+     */
+    callback: TaskCallback;
+    /**
+     * Prevent overlapping executions.
+     */
+    withoutOverlapping?: boolean;
+    /**
+     * Overlap expiration in milliseconds.
+     */
+    overlapExpiresAt?: number;
+    /**
+     * Only run on one server (requires distributed lock).
+     */
+    onOneServer?: boolean;
+    /**
+     * Condition callback to determine if task should run.
+     */
+    when?: () => boolean | Promise<boolean>;
+    /**
+     * Condition callback to skip execution.
+     */
+    skip?: () => boolean | Promise<boolean>;
+    /**
+     * Before execution callback.
+     */
+    before?: () => void | Promise<void>;
+    /**
+     * After execution callback.
+     */
+    after?: () => void | Promise<void>;
+    /**
+     * On success callback.
+     */
+    onSuccess?: () => void | Promise<void>;
+    /**
+     * On failure callback.
+     */
+    onFailure?: (error: Error) => void | Promise<void>;
+}
+/**
+ * Scheduler options.
+ */
+interface SchedulerOptions {
+    /**
+     * Timezone for all scheduled tasks.
+     * @default 'UTC'
+     */
+    timezone?: string;
+    /**
+     * Check interval in milliseconds.
+     * @default 60000 (1 minute)
+     */
+    checkInterval?: number;
+    /**
+     * Logger function.
+     */
+    logger?: (message: string) => void;
+}
+/**
+ * Parsed cron expression.
+ */
+interface ParsedCron {
+    minute: number[];
+    hour: number[];
+    dayOfMonth: number[];
+    month: number[];
+    dayOfWeek: number[];
+}
+/**
+ * Job class interface for scheduling.
+ */
+interface JobClass<T = unknown> {
+    dispatch(payload: T): Promise<void>;
+    dispatchAfter?(delayMs: number, payload: T): Promise<void>;
+}
+
+/**
+ * Represents a scheduled task.
+ */
+declare class ScheduledTask {
+    private readonly definition;
+    private lastRun;
+    private isRunning;
+    constructor(definition: TaskDefinition);
+    /**
+     * Get the task name.
+     */
+    getName(): string;
+    /**
+     * Get the cron expression.
+     */
+    getExpression(): string;
+    /**
+     * Get the timezone.
+     */
+    getTimezone(): string | undefined;
+    /**
+     * Check if the task is due.
+     */
+    isDue(date?: Date): boolean;
+    /**
+     * Check if the task should run based on conditions.
+     * Note: Overlap checking is handled separately in run() to prevent race conditions.
+     */
+    shouldRun(): Promise<boolean>;
+    /**
+     * Run the task.
+     */
+    run(): Promise<void>;
+    /**
+     * Get the last run time.
+     */
+    getLastRun(): Date | null;
+    /**
+     * Check if the task is currently running.
+     */
+    isCurrentlyRunning(): boolean;
+    /**
+     * Get the task definition.
+     */
+    getDefinition(): TaskDefinition;
+}
+
+/**
+ * Pending schedule builder for fluent API.
+ */
+declare class PendingSchedule {
+    private readonly callback;
+    private expression;
+    private timezone?;
+    private taskName?;
+    private withoutOverlapping;
+    private overlapExpiresAt?;
+    private onOneServer;
+    private whenCallback?;
+    private skipCallback?;
+    private beforeCallback?;
+    private afterCallback?;
+    private successCallback?;
+    private failureCallback?;
+    constructor(callback: TaskCallback);
+    /**
+     * Run every minute.
+     */
+    everyMinute(): this;
+    /**
+     * Run every two minutes.
+     */
+    everyTwoMinutes(): this;
+    /**
+     * Run every three minutes.
+     */
+    everyThreeMinutes(): this;
+    /**
+     * Run every four minutes.
+     */
+    everyFourMinutes(): this;
+    /**
+     * Run every five minutes.
+     */
+    everyFiveMinutes(): this;
+    /**
+     * Run every ten minutes.
+     */
+    everyTenMinutes(): this;
+    /**
+     * Run every fifteen minutes.
+     */
+    everyFifteenMinutes(): this;
+    /**
+     * Run every thirty minutes.
+     */
+    everyThirtyMinutes(): this;
+    /**
+     * Run hourly.
+     */
+    hourly(): this;
+    /**
+     * Run hourly at a specific minute.
+     */
+    hourlyAt(minute: number): this;
+    /**
+     * Run every two hours.
+     */
+    everyTwoHours(): this;
+    /**
+     * Run every three hours.
+     */
+    everyThreeHours(): this;
+    /**
+     * Run every four hours.
+     */
+    everyFourHours(): this;
+    /**
+     * Run every six hours.
+     */
+    everySixHours(): this;
+    /**
+     * Run daily at midnight.
+     */
+    daily(): this;
+    /**
+     * Run daily at a specific time.
+     * @param time Time in HH:MM format
+     */
+    dailyAt(time: string): this;
+    /**
+     * Alias for dailyAt.
+     */
+    at(time: string): this;
+    /**
+     * Run twice daily.
+     */
+    twiceDaily(firstHour?: number, secondHour?: number): this;
+    /**
+     * Run weekly on Sunday at midnight.
+     */
+    weekly(): this;
+    /**
+     * Run weekly on a specific day at a specific time.
+     * @param day Day of week (0 = Sunday, 6 = Saturday)
+     * @param time Time in HH:MM format
+     */
+    weeklyOn(day: number, time?: string): this;
+    sundays(): this;
+    mondays(): this;
+    tuesdays(): this;
+    wednesdays(): this;
+    thursdays(): this;
+    fridays(): this;
+    saturdays(): this;
+    /**
+     * Run on weekdays (Monday-Friday).
+     */
+    weekdays(): this;
+    /**
+     * Run on weekends (Saturday-Sunday).
+     */
+    weekends(): this;
+    /**
+     * Run monthly on the first day at midnight.
+     */
+    monthly(): this;
+    /**
+     * Run monthly on a specific day at a specific time.
+     */
+    monthlyOn(day: number, time?: string): this;
+    /**
+     * Run on the last day of the month.
+     */
+    lastDayOfMonth(time?: string): this;
+    /**
+     * Run quarterly.
+     */
+    quarterly(): this;
+    /**
+     * Run yearly on January 1st at midnight.
+     */
+    yearly(): this;
+    /**
+     * Run yearly on a specific date.
+     */
+    yearlyOn(month: number, day: number, time?: string): this;
+    /**
+     * Set a custom cron expression.
+     */
+    cron(expression: string): this;
+    /**
+     * Set the task name.
+     */
+    name(name: string): this;
+    /**
+     * Set the timezone.
+     */
+    tz(timezone: string): this;
+    /**
+     * Alias for tz().
+     */
+    setTimezone(timezone: string): this;
+    /**
+     * Prevent overlapping executions.
+     */
+    preventOverlapping(expiresAt?: number): this;
+    /**
+     * Alias for preventOverlapping().
+     */
+    withoutOverlaps(expiresAt?: number): this;
+    /**
+     * Only run on one server.
+     */
+    runOnOneServer(): this;
+    /**
+     * Set a condition for running.
+     */
+    when(callback: () => boolean | Promise<boolean>): this;
+    /**
+     * Set a condition to skip execution.
+     */
+    skip(callback: () => boolean | Promise<boolean>): this;
+    /**
+     * Set a before callback.
+     */
+    before(callback: () => void | Promise<void>): this;
+    /**
+     * Set an after callback.
+     */
+    after(callback: () => void | Promise<void>): this;
+    /**
+     * Set a success callback.
+     */
+    onSuccess(callback: () => void | Promise<void>): this;
+    /**
+     * Set a failure callback.
+     */
+    onFailure(callback: (error: Error) => void | Promise<void>): this;
+    /**
+     * Build the task definition.
+     */
+    build(): TaskDefinition;
+    /**
+     * Build as a ScheduledTask.
+     */
+    toTask(): ScheduledTask;
+}
+/**
+ * Schedule builder for defining multiple tasks.
+ */
+declare class Schedule {
+    private readonly tasks;
+    /**
+     * Schedule a callback.
+     */
+    call(callback: TaskCallback): PendingSchedule;
+    /**
+     * Schedule a job.
+     */
+    job<T>(jobClass: JobClass<T>, payload: T): PendingSchedule;
+    /**
+     * Schedule a shell command.
+     */
+    command(cmd: string): PendingSchedule;
+    /**
+     * Get all pending schedules.
+     */
+    getPendingSchedules(): PendingSchedule[];
+    /**
+     * Build all tasks.
+     */
+    buildTasks(): ScheduledTask[];
+}
+
+/**
+ * Task scheduler for running periodic tasks.
+ *
+ * @example
+ * ```ts
+ * const scheduler = new Scheduler()
+ *
+ * scheduler.schedule((schedule) => {
+ *   schedule.call(async () => {
+ *     await cleanupOldSessions()
+ *   }).daily().at('03:00').name('cleanup-sessions')
+ *
+ *   schedule.job(SendWeeklyDigestJob, {})
+ *     .weekly()
+ *     .sundays()
+ *     .at('09:00')
+ *     .tz('Asia/Tokyo')
+ * })
+ *
+ * scheduler.start()
+ * ```
+ */
+declare class Scheduler {
+    private tasks;
+    private readonly options;
+    private interval;
+    private isRunning;
+    private lastCheck;
+    constructor(options?: SchedulerOptions);
+    /**
+     * Define schedules using a callback.
+     */
+    schedule(definer: (schedule: Schedule) => void): void;
+    /**
+     * Add a pre-built task.
+     */
+    addTask(task: ScheduledTask): void;
+    /**
+     * Get all scheduled tasks.
+     */
+    getTasks(): ScheduledTask[];
+    /**
+     * Get tasks that are due now.
+     */
+    getDueTasks(date?: Date): ScheduledTask[];
+    /**
+     * Run all due tasks.
+     */
+    runDueTasks(date?: Date): Promise<void>;
+    /**
+     * Start the scheduler.
+     */
+    start(): void;
+    /**
+     * Stop the scheduler.
+     */
+    stop(): void;
+    /**
+     * Check and run due tasks.
+     */
+    private tick;
+    /**
+     * Check if the scheduler is running.
+     */
+    getIsRunning(): boolean;
+    /**
+     * Get the check interval.
+     */
+    getCheckInterval(): number;
+    /**
+     * Get the default timezone.
+     */
+    getTimezone(): string;
+    /**
+     * Clear all tasks.
+     */
+    clear(): void;
+    /**
+     * Get the number of tasks.
+     */
+    count(): number;
+    /**
+     * Get task by name.
+     */
+    getTask(name: string): ScheduledTask | undefined;
+    /**
+     * Remove a task by name.
+     */
+    removeTask(name: string): boolean;
+}
+/**
+ * Create a scheduler instance.
+ */
+declare function createScheduler(options?: SchedulerOptions): Scheduler;
+
+export { type JobClass as J, type ParsedCron as P, Scheduler as S, type TaskCallback as T, PendingSchedule as a, Schedule as b, ScheduledTask as c, type SchedulerOptions as d, type TaskDefinition as e, createScheduler as f };