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

Composable helper functions for building reliable systems

import TasksQueue from "./TasksQueue";
import { AdaptiveTaskQueueOptions, AddTasksBaseOptions, BaseQueueTask } from "./docs";
/**
 * AdaptiveTaskQueue extends the base TasksQueue by dynamically adjusting
 * its concurrency limit based on the observed task addition rate (RPS).
 *
 * This class tracks the rate of tasks being added over a rolling time window,
 * then periodically recalculates and adjusts the concurrency limit to optimize
 * throughput and resource usage.
 *
 * It is especially useful in environments with variable workload, where
 * adapting concurrency based on real-time demand can improve performance and
 * efficiency without manual tuning.
 *
 * Key features:
 * - Tracks requests per second (RPS) using a sliding time window.
 * - Automatically increases or decreases concurrency limit based on RPS.
 * - Emits concurrency update events to allow external monitoring.
 * - Configurable time window for rate tracking and debounce delay for recalculations.
 *
 * @extends TasksQueue
 *
 * @param {AdaptiveTaskQueueOptions} [options] - Configuration options for adaptive behavior.
 * @param {number} [options.windowDurationMs=1000] - Duration of the rolling window in milliseconds for RPS calculation.
 * @param {number} [options.recalcDebounce=200] - Debounce delay in milliseconds before concurrency is recalculated.
 * @param {boolean} [options.autoRun] - Whether to automatically run the queue when tasks are added (inherited from TasksQueue).
 * @param {number} [options.concurrencyLimit] - Initial concurrency limit (inherited from TasksQueue).
 *
 * @example
 * ```ts
 * import { AdaptiveTaskQueue } from '@nasriya/atomix/tools';
 *
 * const queue = new AdaptiveTaskQueue({
 *   windowDurationMs: 500,
 *   recalcDebounce: 100,
 *   autoRun: true,
 * });
 *
 * queue.onConcurrencyUpdate(newLimit => {
 *   console.log(`Concurrency updated to: ${newLimit}`);
 * });
 *
 * queue.addTask({
 *   type: 'task',
 *   action: async () => {
 *     // Your async work here
 *   }
 * });
 *
 * await queue.untilComplete();
 * ```
 *
 * @since 1.0.23
 */
export declare class AdaptiveTaskQueue extends TasksQueue {
    #private;
    constructor(options?: AdaptiveTaskQueueOptions);
    /**
     * Adds a task to the adaptive task queue. This method overrides the base
     * implementation to include rate tracking and dynamic concurrency adjustment
     * before delegating to the parent method.
     *
     * @param task - The task to be added to the queue.
     * @param options - (Optional) Additional options for task handling, such as
     * whether to auto-run the queue for this task.
     * @returns The current instance of the task queue, allowing for method chaining.
     * @override
     * @since 1.0.23
     */
    addTask(task: BaseQueueTask<any, any>, options?: AddTasksBaseOptions): this;
    /**
     * Adds multiple tasks to the adaptive task queue. This method overrides the
     * base implementation to include rate tracking and dynamic concurrency
     * adjustment before delegating to the parent method.
     *
     * @param tasks - An array of tasks to be added to the queue.
     * @param options - (Optional) Additional options for task handling, such as
     * whether to auto-run the queue for this task.
     * @returns The current instance of the task queue, allowing for method chaining.
     * @override
     * @since 1.0.23
     */
    bulkAddTasks(tasks: BaseQueueTask[], options?: AddTasksBaseOptions): this;
    /**
     * The current requests per second (RPS) rate for this queue.
     *
     * This is a rolling average over the past `WINDOW_DURATION` milliseconds.
     * @readonly
     * @since 1.0.23
     */
    get rps(): number;
    /**
     * The current concurrency limit of the adaptive task queue.
     *
     * This value is dynamically adjusted based on the current requests per second (RPS)
     * to ensure optimal performance while avoiding overload.
     *
     * @readonly
     * @since 1.0.23
     */
    get concurrencyLimit(): number;
    /**
     * Registers a callback function to be executed when the concurrency level is updated.
     *
     * The provided callback will be called with the current requests per second (RPS)
     * as its argument whenever the concurrency level is adjusted.
     *
     * @param callback - A function that receives the current RPS as an argument.
     * @throws {TypeError} If the provided callback is not a function.
     * @throws {RangeError} If the callback function expects more than one parameter.
     * @since 1.0.23
     */
    onConcurrencyUpdate(callback: (rps: number) => void): void;
}
export default AdaptiveTaskQueue;