Skip to content

LimitedQueue

Jump to bottom
Eugene Lazutkin edited this page Feb 25, 2026 · 10 revisions

Description

Since version 1.3.0.

The LimitedQueue class is an extension of ListQueue that provides controlled concurrency for task execution. It limits the number of tasks that can run simultaneously, making it useful for managing resource-intensive operations or API calls that need to be throttled.

Key features

  • Concurrency control: Limits the maximum number of tasks that can execute simultaneously
  • Inherits from ListQueue: Maintains all functionality of the base queue implementation
  • Active task tracking: Provides visibility into how many tasks are currently running
  • Dynamic limit adjustment: Allows changing the concurrency limit at runtime
  • Automatic task processing: Automatically starts new tasks when others complete
  • Idle state monitoring: Provides ability to wait for queue to become idle

Technical specifications

LimitedQueue is available as a named and default export.

import LimitedQueue from 'time-queues/LimitedQueue.js';

Constructor

new LimitedQueue(limit: number, paused?: boolean)
  • Parameters:
    • limit: The maximum number of tasks that can be run in parallel
    • paused: Whether the queue should start paused (optional, default is false)

Instance properties

  • taskLimit: Gets or sets the maximum number of tasks that can run in parallel
  • activeTasks: Gets the number of currently running tasks
  • isIdle: Gets whether the queue is idle (no active tasks and no queued tasks)
  • paused: Inherits from ListQueue - indicates whether the queue is currently paused
  • stopQueue: Inherits from ListQueue - function that stops the queue or null

Instance methods

  • enqueue(fn): Enqueues a microtask

    • Parameters: fn - The function to execute when the microtask is scheduled
    • Returns: The enqueued microtask

  • dequeue(task): Dequeues a microtask

    • Parameters: task - The microtask to dequeue
    • Returns: The queue

  • schedule(fn): Schedules a microtask

    • Parameters: fn - The function to execute. If undefined or null, the task's promise will be resolved with the function's arguments. Otherwise, it is resolved with the function's return value
    • Returns: The task object

  • clear(): Clears the queue

    • Returns: The queue

  • pause(): Pauses the queue

    • Returns: The queue

  • resume(): Resumes the queue

    • Returns: The queue

  • waitForIdle(): Waits for the queue to become idle

    • Returns: A promise that resolves when the queue becomes idle

  • startQueue(): Starts the queue (internal use)

    • Returns: The function that stops the queue or null

fn is a function that will be executed when the task is scheduled:

  • It will be called with an object containing the following properties:
    • task: The task instance representing the current task.
    • queue: The LimitedQueue instance.
  • It will be called in the context of the task object.
  • Its return value will be ignored by enqueue(), but it can be used by schedule() to resolve the task's promise.

Additional exports

  • Task: Type definition for task objects used in the queue

Usage instructions

import LimitedQueue from 'time-queues/LimitedQueue.js';

// Create a queue with concurrency limit of 3
const queue = new LimitedQueue(3);

// Add tasks to the queue
queue.enqueue(async () => {
  console.log('Task 1 running');
  await new Promise(resolve => setTimeout(resolve, 1000));
  console.log('Task 1 completed');
});

queue.enqueue(async () => {
  console.log('Task 2 running');
  await new Promise(resolve => setTimeout(resolve, 500));
  console.log('Task 2 completed');
});

// Change concurrency limit dynamically
queue.taskLimit = 5; // Increase to 5 concurrent tasks

// Wait for queue to become idle
await queue.waitForIdle();

// Pause and resume the queue
queue.pause();
queue.resume();

Troubleshooting

  • Tasks not executing: Verify that the queue is not paused and that tasks are properly enqueued
  • Concurrency limit not respected: Ensure the limit is set to a positive integer value (minimum is 1)
  • Memory issues: Large numbers of queued tasks may cause memory pressure; consider processing tasks in batches
  • Task execution errors: Errors in individual tasks do not affect other tasks in the queue

See Also

Clone this wiki locally