@penkov/tasks_queue/dist/tasks-pools.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 { TasksPool } from "./tasks-pool.js";
import { Option } from "scats";
import { TasksQueueDao } from "./tasks-queue.dao.js";
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";
/**
 * Default pool name used by {@link TasksPoolsService.registerWorker} when no
 * explicit pool is provided.
 *
 * See also {@link TasksQueueModuleOptions.pools}.
 */
export declare const DEFAULT_POOL = "default";
/**
 * Service that manages multiple task-processing pools and routes queue events to them.
 *
 * Periodic scheduling supports fixed rate, fixed delay, and cron expressions.
 * Cron schedules are currently evaluated in UTC timezone.
 */
export declare class TasksPoolsService {
    private readonly dao;
    private readonly clock;
    private readonly pools;
    private readonly queuesPool;
    private readonly auxiliaryWorker;
    constructor(dao: TasksQueueDao, manageTasksQueueService: ManageTasksQueueService, runAuxiliaryWorker: boolean, pools?: TasksPool[], clock?: Clock);
    /**
     * Start all configured pools and optional auxiliary worker.
     *
     * Each pool starts its own polling pipeline with its configured concurrency
     * and loop interval.
     *
     * After this call, registered queues become eligible for processing.
     */
    start(): void;
    /**
     * Stop all pools gracefully.
     *
     * The method races pool shutdown against a timeout to avoid hanging forever.
     *
     * @param timeoutMs maximum time to wait for graceful stop
     * @returns resolved promise when all pools stop cleanly
     */
    stop(timeoutMs?: number): Promise<void>;
    /**
     * Register a queue worker in the selected pool.
     *
     * A queue can be bound to only one pool. Attempting to register the same
     * queue twice throws an error.
     *
     * @param queueName queue identifier
     * @param worker worker implementation
     * @param poolName target pool name, defaults to `default`
     * @returns nothing; subsequent scheduled tasks for this queue will be routed to the selected pool
     */
    registerWorker(queueName: string, worker: TasksWorker, poolName?: string): void;
    /**
     * Schedule a one-time task.
     *
     * After persistence, the task notification is routed to the pool where
     * the queue worker is registered.
     *
     * @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 scheduling keeps the cadence aligned to the original schedule.
     * It does not wait for the previous run to finish before calculating the next
     * nominal trigger time.
     *
     * @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 scheduling computes the next run relative to completion time
     * rather than to the original nominal cadence.
     *
     * @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 by cron expression.
     *
     * Supported 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 expression validation is performed in DAO before insert.
     * Cron schedule calculations currently use UTC timezone.
     *
     * @param task cron task details
     * @returns created task id if insert succeeded, otherwise `none`
     */
    scheduleAtCron(task: ScheduleCronTaskDetails): Promise<Option<number>>;
    /**
     * Route scheduling signal to the pool that owns the queue.
     *
     * If no worker is registered for the queue, task remains pending until
     * a worker appears.
     *
     * @param queue queue identifier
     * @param taskId created task id if available
     */
    private taskScheduled;
    private notifyQueue;
}