@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.
128 lines (127 loc) • 6.05 kB
TypeScript
import { Collection, HashSet, Option } from "scats";
import pg from "pg";
import type { SchedulePeriodicTaskDetails, ScheduleTaskDetails } from "./tasks-model.js";
import { ScheduledTask, TaskPeriodType, TaskStatus } from "./tasks-model.js";
export declare class TasksQueueDao {
private readonly pool;
constructor(pool: pg.Pool);
private withClient;
/**
* Add new task to a queue, that will be executed once upon successful competition.
* @param task parameters of the new task
* @return the id of the created task
*/
schedule(task: ScheduleTaskDetails): Promise<Option<number>>;
/**
* Add new task to a queue, that will be executed periodically with the fixed rate.
* @param task parameters of the new task
* @param periodType how to repeat the task, based on fixed-rate or fixed-delay.
* @return the id of the created task or none if task was not scheduled (e.g. already exists)
*/
schedulePeriodic(task: SchedulePeriodicTaskDetails, periodType: TaskPeriodType): Promise<Option<number>>;
/**
* Fetches a new task to be processed from one of the specified queues.
*
* Conditions for fetching:
* - Task must have status = 'pending'
* - Task must belong to one of the specified queues
* - Task must have attempt count < max_attempts (default is 1 if unset)
* - Task must have start_after <= now() or be null
*
* Among the matching tasks, the one with the highest priority will be selected.
* If multiple tasks share the same priority, the one with the smallest id will be chosen.
*
* When fetched, the task's status will be set to 'in_progress', 'started' timestamp will be updated,
* and the attempt count will be incremented.
*
* @param queueNames the queues where the tasks are searched.
* @return the brief details of the fetched task, if any
*/
nextPending(queueNames: HashSet<string>): Promise<Option<ScheduledTask>>;
/**
* Returns the earliest upcoming `start_after` timestamp from the task queue.
*
* This can be used to calculate how long to sleep before polling again
* without increasing the overall polling frequency.
*
* Only considers tasks with status `'pending'` or `'error'` and where `start_after > now`.
*
* Returns `none` if no such task exists.
*
* @returns The earliest future `start_after` timestamp, if any.
*/
peekNextStartAfter(queueNames: HashSet<string>): Promise<Option<Date>>;
/**
* Mark task as finished. Task status will be set to 'finished'. The 'error' field will be cleared.
* The 'finished' field will be set to current timestamp.
* Task should have status='in_progress' to be updated.
* @param taskId the id of the task
*/
finish(taskId: number): Promise<void>;
/**
* Reschedule a periodic task by setting its status back to 'pending' and updating the 'start_after' field
* based on the task's repeat_interval and repeat_type.
*
* Task must have status='in_progress', repeat_interval != null and a valid repeat_type ('fixedRate' or 'fixedDelay').
*
* @param taskId the id of the task
*/
rescheduleIfPeriodic(taskId: number): Promise<void>;
/**
* Marks the task as failed.
*
* If the task has remaining attempts (i.e., attempt + 1 < max_attempts), it is rescheduled immediately:
* - Its status is set to 'pending'.
* - The 'start_after' field is set to a future time calculated using the 'backoff' and 'backoff_type' fields.
* - For 'constant' backoff: delay = backoff
* - For 'linear' backoff: delay = backoff * attempt
* - For 'exponential' backoff: delay = backoff * 2^attempt
* - The 'finished' timestamp is updated to the current time.
* - The 'error' field is updated with the provided message.
*
* If no attempts remain, the task is marked as permanently failed:
* - Its status is set to 'error'.
* - The 'start_after' field is cleared (set to NULL).
*
* This update will only take place if the task is currently in 'in_progress' status.
*
* @param taskId The ID of the task.
* @param error The error message to store in the task's 'error' field.
* @param nextPayload Replaces task payload, if set
* @returns The new status of the task after the update (`'pending'` or `'error'`).
*/
fail(taskId: number, error: string, nextPayload?: object): Promise<TaskStatus>;
/**
* Marks all stalled tasks as failed.
* The status field will be set to 'error'. A message 'Timeout' will be written into the 'error' field.
* The finished field will be set to current timestamp.
*
* To be updated The task should have
* - status='in_progress'
* - defined timeout and started + timeout should be less than current timestamp
* @return ids of the updated tasks.
*/
failStalled(): Promise<Collection<number>>;
/**
* Requeues all failed tasks.
* The task should have status='error', the number of attempts for a task should be less
* than a number of maximum allowed attempts (which is set in 'retries' field, defaults to 1).
*
* All suitable tasks will have the 'status' field set to 'pending', the 'finished' field cleared.
*/
resetFailed(): Promise<void>;
/**
* Removes all finished tasks.
* The task should have status='finished' and current timestamp should be greater then
* the time, when the task was finished plus the timeout.
*
* @param timeout the duration between the time, when the task was finished and current timestamp
*/
clearFinished(timeout?: number): Promise<void>;
/**
* Calculates the number of the tasks with specified status in a specified queue.
* @param queue the name of the queue.
* @param status the status of the task to be counted
*/
statusCount(queue: string, status: TaskStatus): Promise<number>;
}