@penkov/tasks_queue/dist/tasks-queue.service.d.ts

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.

import { TasksQueueDao } from "./tasks-queue.dao.js";
import { Option } from "scats";
import { ScheduleCronTaskDetails, SchedulePeriodicTaskDetails, ScheduleTaskDetails } from "./tasks-model.js";
import { TasksWorker } from "./tasks-worker.js";
import { ManageTasksQueueService } from "./manage-tasks-queue.service.js";
import { Clock } from "./clock.js";
export interface TasksQueueConfig {
    /**
     * Maximum number of tasks that may run concurrently in this service instance.
     */
    concurrency: number;
    /**
     * Whether to run the background auxiliary worker for stalled-task handling,
     * failed-task reset, finished-task cleanup, and metrics sync.
     */
    runAuxiliaryWorker: boolean;
    /**
     * Fallback polling interval in milliseconds for the worker pipeline.
     */
    loopInterval: number;
    /**
     * Optional queue-level notifier used when a running task schedules work for a
     * queue that may belong to another pool.
     */
    queueNotifier?: (queueName: string) => void;
}
/**
 * Service for scheduling tasks and controlling queue workers in a single-pool setup.
 *
 * Periodic scheduling is supported via:
 * - fixed rate
 * - fixed delay
 * - cron expressions
 *
 * Cron expressions are interpreted in UTC by default in the current implementation.
 */
export declare class TasksQueueService {
    private readonly tasksQueueDao;
    private readonly clock;
    private readonly poolName;
    private readonly worker;
    private readonly auxiliaryWorker;
    constructor(tasksQueueDao: TasksQueueDao, manageTasksQueueService: ManageTasksQueueService, config: TasksQueueConfig, clock?: Clock, poolName?: string);
    /**
     * Schedule a one-time task for execution.
     *
     * The task is stored in the queue and processed once by a registered worker.
     * After successful persistence, the worker loop is nudged to reduce latency.
     *
     * @param task one-time task details
     * @returns created task id if insert succeeded, otherwise `none`
     */
    schedule(task: ScheduleTaskDetails): Promise<Option<number>>;
    /**
     * Schedule a periodic task with fixed-rate semantics.
     *
     * Fixed-rate means the next execution time is aligned to the configured period
     * regardless of task processing duration.
     *
     * @param task periodic task details with `period` in milliseconds
     * @returns created task id if insert succeeded, otherwise `none`
     */
    scheduleAtFixedRate(task: SchedulePeriodicTaskDetails): Promise<Option<number>>;
    /**
     * Schedule a periodic task with fixed-delay semantics.
     *
     * Fixed-delay means the next execution is calculated as `now + period`
     * after the current run has finished.
     *
     * @param task periodic task details with `period` in milliseconds
     * @returns created task id if insert succeeded, otherwise `none`
     */
    scheduleAtFixedDelay(task: SchedulePeriodicTaskDetails): Promise<Option<number>>;
    /**
     * Schedule a periodic task using a cron expression.
     *
     * 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
     *
     * The expression is validated before persistence in the DAO layer.
     * Cron schedule calculations currently use UTC timezone.
     *
     * @param task cron task details including `cronExpression`
     * @returns created task id if insert succeeded, otherwise `none`
     */
    scheduleAtCron(task: ScheduleCronTaskDetails): Promise<Option<number>>;
    /**
     * Notify internal polling loop that a task was scheduled for the given queue.
     *
     * @param queueName queue identifier
     * @returns nothing; if the service is already started, the polling loop is nudged immediately
     */
    taskScheduled(queueName: string): void;
    /**
     * Register a worker implementation for the queue.
     *
     * @param queueName queue identifier
     * @param worker queue worker instance
     * @returns nothing; the worker becomes eligible to receive future tasks from this queue
     */
    registerWorker(queueName: string, worker: TasksWorker): void;
    /**
     * Run at most one eligible task-processing cycle synchronously.
     *
     * This method is mainly useful in tests or in applications that want manual
     * control over queue polling. It respects the same ownership, timeout, retry,
     * and periodic semantics as the background loop.
     *
     * @returns resolved promise after the current cycle completes
     */
    runOnce(): Promise<void>;
    /**
     * Start processing loops.
     *
     * Starts the main worker and, if enabled, the auxiliary worker responsible
     * for maintenance tasks.
     *
     * See also {@link stop}.
     */
    start(): void;
    /**
     * Stop processing loops gracefully.
     *
     * The method stops auxiliary processing first and then waits for the main
     * worker pipeline to finish in-flight tasks.
     *
     * @returns resolved promise once the service has stopped
     */
    stop(): Promise<void>;
}