Nuptial Predicament Mediation

    throttled-queue

    1.0.7 • Public • Published

    throttled-queue

    Throttles arbitrary code to execute a maximum number of times per interval. Best for making throttled API requests.

    For example, making network calls to popular APIs such as Twitter is subject to rate limits. By wrapping all of your API calls in a throttle, it will automatically adjust your requests to be within the acceptable rate limits.

    Unlike the throttle functions of popular libraries like lodash and underscore, throttled-queue will not prevent any executions. Instead, every execution is placed into a queue, which will be drained at the desired rate limit.

    Installation

    Can be used in a Node.js environment, or directly in the browser.

    Node.js

    npm install throttled-queue

    Browser

    <script src="throttled-queue.min.js"></script>

    Usage

    1. If in node.js, require the factory function:
    var throttledQueue = require('throttled-queue');

    Else, include it in a script tag in your browser and throttledQueue will be globally available.

    1. Create an instance of a throttled queue by specifying the maximum number of requests as the first parameter, and the interval in milliseconds as the second:
    var throttle = throttledQueue(5, 1000); // at most 5 requests per second.
    1. Use the throttle instance as a function to enqueue actions:
    throttle(function() {
        // perform some type of activity in here.
    });

    Quick Examples

    Basic

    Rapidly assigning network calls to be run, but they will be limited to 1 request per second.

    var throttledQueue = require('throttled-queue');
    var throttle = throttledQueue(1, 1000); // at most make 1 request every second.
     
    for (var x = 0; x < 100; x++) {
     
        throttle(function() {
            // make a network request.
            fetch('https://api.github.com/search/users?q=shaunpersad').then(console.log);
        });
    }

    Reusable

    Wherever the throttle instance is used, your action will be placed into the same queue, and be subject to the same rate limits.

    var throttledQueue = require('throttled-queue');
    var throttle = throttledQueue(1, 60 * 1000); // at most make 1 request every minute.
     
    for (var x = 0; x < 50; x++) {
     
        throttle(function() {
            // make a network request.
            fetch('https://api.github.com/search/users?q=shaunpersad').then(console.log);
        });
    }
    for (var y = 0; y < 50; y++) {
     
        throttle(function() {
            // make another type of network request.
            fetch('https://api.github.com/search/repositories?q=throttled-queue+user:shaunpersad').then(console.log);
        });
    }

    Bursts

    By specifying a number higher than 1 as the first parameter, you can dequeue multiple actions within the given interval:

    var throttledQueue = require('throttled-queue');
    var throttle = throttledQueue(10, 1000); // at most make 10 requests every second.
     
    for (var x = 0; x < 100; x++) {
     
        throttle(function() {
            // This will fire at most 10 a second, as rapidly as possible.
            fetch('https://api.github.com/search/users?q=shaunpersad').then(console.log);
        });
    }

    Evenly spaced

    You can space out your actions by specifying true as the third (optional) parameter:

    var throttledQueue = require('throttled-queue');
    var throttle = throttledQueue(10, 1000, true); // at most make 10 requests every second, but evenly spaced.
     
    for (var x = 0; x < 100; x++) {
     
        throttle(function() {
            // This will fire at most 10 requests a second, spacing them out instead of in a burst.
            fetch('https://api.github.com/search/users?q=shaunpersad').then(console.log);
        });
    }

    Tests

    Note: The tests take a few minutes to run. Watch the console to see how closely the actual rate limit gets to the maximum.

    Node.js

    Run npm test.

    Browser

    Open test/index.html in your browser.

    Install

    npm i throttled-queue

    DownloadsWeekly Downloads

    4,814

    Version

    1.0.7

    License

    MIT

    Unpacked Size

    42.2 kB

    Total Files

    15

    Last publish

    Collaborators

    • shaunpersad