@penkov/tasks_queue
Version:
A lightweight PostgreSQL-backed task queue system with scheduling, retries, backoff strategies, and priority handling. Designed for efficiency and observability in modern Node.js applications.
83 lines (82 loc) • 3.37 kB
TypeScript
import { Option } from "scats";
import { MissedRunStrategy, TaskPeriodType } from "./tasks-model.js";
import type { ScheduleCronTaskDetails, SchedulePeriodicTaskDetails } from "./tasks-model.js";
export interface PeriodicScheduleConfig {
repeatType: TaskPeriodType;
repeatInterval: Option<number>;
cronExpression: Option<string>;
startAfter: Date;
initialStart: Date;
missedRunsStrategy: MissedRunStrategy;
}
export declare class PeriodicScheduleUtils {
/**
* Resolves persisted repeat interval based on periodic type.
*
* For `cron` schedules interval is not used and `null` is returned.
* For fixed schedules, `period` must be present.
*
* @param task task schedule request
* @param periodType requested period type
* @returns repeat interval in milliseconds or `null` for cron
*/
static resolveRepeatInterval(task: SchedulePeriodicTaskDetails | ScheduleCronTaskDetails, periodType: TaskPeriodType): number | null;
/**
* Resolves persisted cron expression based on periodic type.
*
* For fixed schedules cron expression is not used and `null` is returned.
* For `cron` schedules a non-blank `cronExpression` is required.
*
* Supported expression formats:
* - 5 fields: minute, hour, day-of-month, month, day-of-week
* - 6 fields: second, minute, hour, day-of-month, month, day-of-week
*
* @param task task schedule request
* @param periodType requested period type
* @returns normalized cron expression or `null` for fixed schedules
*/
static resolveCronExpression(task: SchedulePeriodicTaskDetails | ScheduleCronTaskDetails, periodType: TaskPeriodType): string | null;
/**
* Calculates the next task start time for periodic tasks.
*
* Supported schedule sources:
* - fixed interval (`fixed_rate`, `fixed_delay`)
* - cron expression (`cron`)
*
* @param task periodic scheduling configuration
* @param now current timestamp used as a base for delay and skip-missed semantics
* @returns next start time
*/
static calculateNextStartAfter(task: PeriodicScheduleConfig, now: Date): Date;
/**
* Calculates next start for cron-based periodic tasks.
*
* Supported cron formats:
* - 5 fields: minute, hour, day-of-month, month, day-of-week
* - 6 fields: second, minute, hour, day-of-month, month, day-of-week
*
* Cron expressions are evaluated in UTC in the current implementation.
*
* @param task cron scheduling config
* @param now current timestamp
* @returns next start time for cron schedule
*/
private static calculateNextCronStartAfter;
/**
* Calculates next start for interval-based periodic tasks.
*
* @param task interval scheduling config
* @param now current timestamp
* @returns next start time for fixed-rate or fixed-delay schedule
*/
private static calculateNextIntervalStartAfter;
/**
* Calculates fixed-rate next start for skip-missed behavior.
*
* @param initialStart initial schedule anchor
* @param now current timestamp
* @param repeatInterval schedule period in milliseconds
* @returns nearest fixed-rate slot at or after `now`
*/
private static calculateFixedRateSkipMissedNextStartAfter;
}