just-queue

JustQueue: A Simple-To-Use Promise Based Queue For Concurrency & Throttle Limiting.

Motivation

JustQueue aims to simplify the process of setting up local queues in which you may need to throttle or limit the concurrency of asynchronous operations. The most common use case would using JustQueue in front an outgoing third party API request that may have its own rate and concurrency limits. In this scenario, JustQueue can allow asynchronous calls to this API to be appropriately throttled without going over the specified limits.

Some of the prominent features implemented are:

• Promise Based Queue
• Asynchronous By Nature
• CPU & Memory Efficient
• Various Limiting Options

Installation

JustQueue can be installed using node package manager (npm)

npm i just-queue

Table Of Contents

• JustQueue: A Simple-To-Use Promise Based Queue For Concurrency & Throttle Limiting.
  • Motivation
  • Installation
  • Table Of Contents
  • Examples
    • Example: Concurrenly Limiting Queue To Third-Party API
    • Example: Throttle Limiting Queue To Third-Party API
  • JustQueue
    • JustQueue Constructor Options
    • JustQueue Instance Properties
    • JustQueue Instance Methods
  • License

Examples

Below are various examples that make use of JustQueue.

Example: Concurrenly Limiting Queue To Third-Party API

const JustQueue = new JustQueue({
    max_concurrent: 4
});

async function get_currency_data(){
    // Assume this function makes a POST request to a third-party API
    // that only allows 4 conncurrent requests to be made with your API key
}

async function throttled_get(){
    return JustQueue.queue(() => get_currency_data());
}

// We can now call this function more than 4 times but JustQueue will
// automatically ensure that no more than 4 maximum concurrent requests are made at any given time
throttled_get()
.then((data) => console.log('Got Currency Data!', data))
.catch((error) => console.log('Failed To Get Currency Data: ', error));
});

Example: Throttle Limiting Queue To Third-Party API

const JustQueue = new JustQueue({
    throttle: {
        rate: 4,
        interval: 5000
    }
});

async function get_currency_data(){
    // Assume this function makes a POST request to a third-party API
    // that only allows 4 requests every 5 seconds with your API key.
}

async function throttled_get(){
    return JustQueue.queue(() => get_currency_data());
}

// We can now call this function more than 4 times but JustQueue will
// automatically ensure that no more than 4 requests are made every 5 seconds.
throttled_get()
.then((data) => console.log('Got Currency Data!', data))
.catch((error) => console.log('Failed To Get Currency Data: ', error));
});

JustQueue

Below is a breakdown of the JustQueue object class generated while creating a new JustQueue instance.

JustQueue Constructor Options

• max_concurrent [Number]: Maximum number of operations to execute concurrently.
  • Default: Infinity
• max_queued [Number]: Maximum number of operations to have queued at any given time.
  • Default: Infinity
  • Note: The operation will reject with an Error that has the message QUEUE_FULL.
• timeout [Number]: Maximum amount of time in milliseconds after which a queued operation is aborted.
  • Default: Infinity
  • Note: The operation will reject with an Error that has the message TIMED_OUT.
• throttle [Object]: Throttle limiter options.
  • rate [Number]: Number of operations to execute in a throttle interval.
    • Default: Infinity
  • interval [Number]: Interval time in milliseconds to throttle operations.
    • Default: Infinity

JustQueue Instance Properties

Property	Type	Description
active	Number	Number of concurrently active operations.
queued	Number	Number of queued operations.

JustQueue Instance Methods

• queue(Function: operation): Queues an operation
  • Returns a Promise
  • Note operation must be async or return a Promise.
  • Asynchronous Example: queue(async () => { /* Your Code Here */});
  • Promise Example: queue(() => new Promise((resolve, reject) => { /* Your Code Here */});

License

MIT