@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.
148 lines (147 loc) • 5.9 kB
TypeScript
import pg from "pg";
import { Collection, Option } from "scats";
import { FindTasksParameters, QueueStat, TaskDto, TasksCount, TasksResult, UpdatePendingPeriodicScheduleDetails, UpdatePendingTaskDetails } from "./manage.model.js";
/**
* Operational management service for inspecting and mutating queued tasks.
*
* This service is intended for admin panels, support tooling, and maintenance
* workflows. It does not execute tasks itself; execution belongs to
* {@link TasksQueueService} and {@link TasksPoolsService}.
*
* See also {@link TaskDto}, {@link TasksResult}, {@link QueueStat}, and
* {@link TasksCount}.
*/
export declare class ManageTasksQueueService {
private readonly pool;
constructor(pool: pg.Pool);
private mapTaskRow;
/**
* Finds a task by its identifier.
*
* Returns the full management view of the task if it exists, otherwise `none`.
*
* @param taskId task identifier
* @returns task details wrapped in Option
*/
findById(taskId: number): Promise<Option<TaskDto>>;
/**
* Finds all descendant tasks for the provided root task.
*
* The root task itself is not included in the result; only direct and nested
* children are returned.
*
* @param rootTaskId root task identifier
* @returns descendant tasks ordered by id ascending
*/
findChildrenTree(rootTaskId: number): Promise<Collection<TaskDto>>;
/**
* Finds tasks using optional management filters.
*
* Supported filters include task status, queue name, and periodic flag.
* Result ordering supports whitelisted task date fields.
*
* @param params search and pagination parameters
* @returns paginated tasks result
*/
findByParameters(params: FindTasksParameters): Promise<TasksResult>;
/**
* Count tasks currently in terminal `error` state.
*
* @returns number of failed tasks as returned by PostgreSQL
*/
failedCount(): Promise<any>;
/**
* Delete all tasks currently in terminal `error` state.
*
* This is a bulk cleanup operation and does not filter by queue.
*
* @returns PostgreSQL query promise for the delete operation
*/
clearFailed(): Promise<pg.QueryResult<any>>;
/**
* Deletes a task by id only when it is safe to remove from the queue.
*
* Deletion is allowed only for tasks in one of the terminal or inactive states:
* - `pending`
* - `error`
* - `finished`
*
* Tasks in `in_progress` state are never deleted because removing an actively
* processed task can break worker execution semantics. Tasks that still have
* an unfinished ancestor in the parent chain are also preserved, because
* removing them can break parent-child workflow recovery.
*
* @param taskId task identifier
* @returns true if the task was deleted, false if it was not found or is in a non-deletable status
*/
deleteTask(taskId: number): Promise<boolean>;
/**
* Updates the editable runtime configuration of a pending task.
*
* Only tasks currently in `pending` state can be updated. This method changes
* task execution and retry settings, but does not modify periodic scheduling fields.
*
* @param taskId task identifier
* @param details full replacement of editable task fields
* @returns true if the pending task was updated, false if it was not found or is no longer pending
*/
updatePendingTask(taskId: number, details: UpdatePendingTaskDetails): Promise<boolean>;
/**
* Updates the periodic schedule of a pending periodic task.
*
* Only tasks currently in `pending` state and already configured as periodic can be updated.
* This method changes scheduling fields only and does not modify payload, priority, timeout,
* or retry settings.
*
* @param taskId task identifier
* @param details full replacement of editable periodic scheduling fields
* @returns true if the pending periodic task was updated, false if it was not found, is not periodic, or is no longer pending
*/
updatePendingPeriodicSchedule(taskId: number, details: UpdatePendingPeriodicScheduleDetails): Promise<boolean>;
/**
* Compute queue-level wait-time percentiles.
*
* Wait time is measured as `started - created` for first-attempt executions
* only. Results are grouped by queue and returned in seconds.
*
* @returns queue wait-time percentile stats
*/
waitTimeByQueue(): Promise<Collection<QueueStat>>;
/**
* Restart a single failed task by resetting it back to `pending`.
*
* This operation affects only tasks currently in terminal `error` state and
* resets their attempt counter to `0`.
*
* @param taskId task identifier
* @returns resolved promise when the update completes
*/
restartFailedTask(taskId: number): Promise<void>;
/**
* Restart all failed tasks in the selected queue.
*
* Only tasks currently in terminal `error` state are affected.
*
* @param queue queue name
* @returns resolved promise when the update completes
*/
restartAllFailedInQueue(queue: string): Promise<void>;
/**
* Count tasks grouped by queue and status.
*
* This method is used both by management UIs and by the auxiliary worker's
* metrics synchronization.
*
* @returns queue/status aggregate counts
*/
tasksCount(): Promise<Collection<TasksCount>>;
/**
* Compute queue-level work-time percentiles.
*
* Work time is measured as `finished - started` for tasks that have both
* timestamps. Results are grouped by queue and returned in seconds.
*
* @returns queue work-time percentile stats
*/
workTimeByQueue(): Promise<Collection<QueueStat>>;
}