throttles
v1.0.1
Published
A tiny (139B to 204B) utility to regulate the execution rate of your functions
Downloads
54,146
Readme
throttles
A tiny (139B to 204B) utility to regulate the execution rate of your functions
Install
$ npm install --save throttles
Modes
There are two "versions" of throttles
, each of which different purpose:
"single"
Size (gzip): 139 bytes Availability: UMD, CommonJS, ES Module
This is the primary/default mode, meant for managing single queues.
"priority"
This is the opt-in mode, meant for managing a low priority and a high priority queue system.
Items within the "high priority" queue are handled before the low/general queue. The limit
is still enforced.
Usage
Selecting a Mode
// import via npm module
import throttles from 'throttles';
import throttles from 'throttles/priority';
// import via unpkg
import throttles from 'https://unpkg.com/throttles/index.mjs';
import throttles from 'https://unpkg.com/throttles/priority/index.mjs';
Example Usage
import throttles from 'throttles';
const API = 'https://pokeapi.co/api/v2/pokemon';
const getPokemon = id => fetch(`${API}/${id}`).then(r => r.json());
// Limit concurrency to 3
const [toAdd, isDone] = throttles(3);
// What we'll fetch
const pokemon = ['bulbasaur', 'ivysaur', 'venusaur', 'charmander', 'charmeleon', 'charizard', ...];
// Loop list, enqueuing each Pokemon
// ~> Always keeps 3 requests active at a time
// ~> When complete, marks itself complete via `isDone()`
pokemon.forEach(name => {
toAdd(() => {
getPokemon(name).then(isDone);
});
});
// Or, use `Array.map` to wrap our `getPokemon` function
// ~> This still fetches Pokemon 3 at once
pokemon.map(x => () => getPokemon(x).then(isDone)).forEach(toAdd);
API
throttles(limit)
Returns: Array
Returns a tuple of [toAdd
, isDone
] actions.
limit
Type: Number
Default: 1
The throttle's concurrency limit. By default, runs your functions one at a time.
toAdd(fn[, isHigh])
Type: Function
Returns: void
Add a function to the throttle's queue.
Important: In "priority" mode, identical functions are ignored.
fn
Type: Function
The function to add to the queue.
isHigh
Type: Boolean
Default: false
If the fn
should be added to the "high priority" queue.
Important: Only available in "priority" mode!
isDone
Type: Function
Returns: void
Signifies that a function has been completed.
Important: Failure to call this will prevent
throttles
from continuing to the next item!
License
MIT © Luke Edwards