@nasriya/atomix/dist/@types/tools/queues/TasksQueue.d.ts

Composable helper functions for building reliable systems

import { AddTasksBaseOptions, BaseQueueTask, TasksQueueOptions } from "./docs";
/**
 * A general-purpose, prioritized task queue utility for managing and executing
 * asynchronous tasks with optional concurrency control and auto-start behavior.
 *
 * Tasks are processed based on their priority, and the queue can be configured
 * to either auto-run on task addition or wait until manually triggered.
 *
 * Supports lifecycle hooks such as `onResolve`, `onReject`, and `onDone`
 * for per-task handling.
 *
 * @example
 * // Basic usage with autoRun (default true)
 * const queue = new atomix.tools.TasksQueue();
 *
 * queue.addTask({
 *     id: 'task-1',
 *     type: 'email',
 *     priority: 2,
 *     action: async () => {
 *         await sendEmail();
 *     },
 *     onResolve: () => console.log('Email sent!'),
 *     onReject: (err) => console.error('Failed to send email:', err)
 * });
 *
 * await queue.untilComplete();
 * // All tasks have finished processing
 *
 * @example
 * // Usage with manual execution control
 * import { TasksQueue } from '@nasriya/atomix/tools';
 *
 * const queue = new TasksQueue({ autoRun: false });
 *
 * queue.addTask({ id: 'x', type: 'job', priority: 1, action: async () => doWork() });
 *
 * await queue.run(); // Start processing tasks manually
 *
 * @since v1.0.2
 */
export declare class TasksQueue {
    #private;
    constructor(options?: TasksQueueOptions);
    /**
     * Cancels all pending tasks that have not started yet and waits for
     * the currently running task to complete before resolving.
     *
     * After calling this method, the queue remains operational: you can
     * still add new tasks and start processing them.
     *
     * Use this method to immediately stop processing queued tasks while
     * allowing the current task to finish gracefully.
     *
     * @returns {Promise<void>} A promise that resolves once the queue is
     *   paused and all pending tasks are cleared.
     * @since v1.0.16
     */
    cancelPending(): Promise<void>;
    /**
     * Pauses the queue after the currently running task finishes.
     * Pending tasks remain in the queue and can be resumed later.
     *
     * @returns A promise that resolves when the queue is successfully paused.
     * @since v1.0.16
     */
    pause(): Promise<void>;
    /**
     * Starts or resumes the queue execution.
     * If the queue is already running, this method returns a promise that resolves
     * when the current batch of tasks completes.
     *
     * @returns A promise that resolves when all currently queued tasks have been processed.
     * @since v1.0.16
     */
    run(): Promise<void>;
    /**
     * Generates and returns a unique task identifier.
     * Utilizes an internal helper to ensure that the ID is not already in use.
     *
     * @returns A unique task identifier.
     * @since v1.0.2
     */
    generateTaskId(): string;
    /**
     * Adds a task to the task queue. Tasks are added to one of four queues, based on their priority.
     * The task is validated before being added to the queue, so ensure that the task object is properly
     * configured before calling this method.
     *
     * @param task - The task to be added to the queue.
     * @since v1.0.2
     */
    addTask(task: BaseQueueTask<any, any>, options?: AddTasksBaseOptions): this;
    /**
     * Adds multiple tasks to the task queue. Tasks are added to one of four queues, based on their priority.
     * The tasks are validated before being added to the queue, so ensure that each task object is properly
     * configured before calling this method.
     *
     * @param tasks - An array of tasks to be added to the queue.
     * @since v1.0.2
     */
    bulkAddTasks(tasks: BaseQueueTask[], options?: AddTasksBaseOptions): this;
    /**
     * Waits for all tasks in the task queue to finish processing. Returns a promise that is resolved
     * once all tasks have been processed and the queue is idle. This method is useful for unit testing and
     * other cases where you need to wait for all tasks to finish before proceeding.
     *
     * @returns A promise that resolves once the queue is idle.
     * @since v1.0.2
     */
    untilComplete(): Promise<void>;
    /**
     * Checks if a task with the given ID exists in the queue.
     * @param id - The ID of the task to check for.
     * @returns true if the task exists in the queue, false otherwise.
     * @since v1.0.6
     */
    hasTask(id: string): boolean;
    /**
     * Retrieves a frozen copy of the current task queue statistics.
     *
     * @returns A frozen record containing the current task queue statistics.
     * @since v1.0.2
     */
    get stats(): import("../..").DeepReadonly<{
        total: number;
        processed: number;
        succeeded: number;
        failed: number;
        readonly pending: number;
    }>;
    /**
     * Indicates whether the task queue is currently processing tasks.
     *
     * @returns A boolean that is true if the queue is active, false otherwise.
     * @since v1.0.16
     */
    get isRunning(): boolean;
    /**
     * Retrieves the autoRun flag of the task queue. When set to true, the queue will automatically
     * start processing tasks as soon as they are added. When set to false, tasks must be started
     * manually with the `run()` method.
     *
     * @returns The autoRun flag of the task queue.
     * @since v1.0.16
     */
    get autoRun(): boolean;
    /**
     * Sets the autoRun flag for the task queue.
     *
     * When set to true, the queue will automatically begin processing tasks
     * as soon as they are added. If set to false, tasks will remain in the
     * queue and must be started manually using the `run()` method.
     *
     * @param value - A boolean indicating whether the queue should start
     * processing tasks automatically.
     * @throws TypeError if the provided value is not a boolean.
     * @since v1.0.16
     */
    set autoRun(value: boolean);
    /**
     * Retrieves the concurrency limit for the task queue.
     *
     * The concurrency limit controls the maximum number of tasks that can
     * be processed concurrently. If set to 1, tasks are processed
     * sequentially. If set to a number greater than 1, up to that many
     * tasks are processed in parallel. If set to 0, the concurrency limit
     * is treated as 1.
     *
     * @returns The concurrency limit of the task queue.
     * @since v1.0.16
     */
    get concurrencyLimit(): number;
    /**
     * Sets the concurrency limit for the task queue.
     *
     * This limit defines the maximum number of tasks that can be processed
     * concurrently. The provided value must be a positive integer. If the value
     * is not a number, integer, or positive, an error is thrown.
     *
     * @param value - A positive integer representing the maximum number of
     * concurrent tasks allowed.
     * @throws {TypeError} If the provided value is not a number.
     * @throws {RangeError} If the provided value is not an integer or is not
     * greater than zero.
     * @since v1.0.16
     */
    set concurrencyLimit(value: number);
}
export default TasksQueue;