119 lines
3 KiB
Markdown
119 lines
3 KiB
Markdown
# throttles [](https://github.com/lukeed/throttles/actions) [](https://codecov.io/gh/lukeed/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<br>
|
|
> **Availability:** [UMD](https://unpkg.com/throttles), [CommonJS](https://unpkg.com/throttles/dist/index.js), [ES Module](https://unpkg.com/throttles?module)
|
|
|
|
This is the primary/default mode, meant for managing single queues.
|
|
|
|
#### "priority"
|
|
> **Size (gzip):** 204 bytes<br>
|
|
> **Availability:** [UMD](https://unpkg.com/throttles/priority), [ES Module](https://unpkg.com/throttles/priority/index.mjs)
|
|
|
|
This is the opt-in mode, meant for managing a low priority _and_ a high priority queue system.<br>
|
|
Items within the "high priority" queue are handled before the low/general queue. The `limit` is still enforced.
|
|
|
|
|
|
## Usage
|
|
|
|
***Selecting a Mode***
|
|
|
|
```js
|
|
// 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***
|
|
|
|
```js
|
|
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`](#toaddfn-ishigh), [`isDone`](#isdone)] actions.
|
|
|
|
#### limit
|
|
Type: `Number`<br>
|
|
Default: `1`
|
|
|
|
The throttle's concurrency limit. By default, runs your functions one at a time.
|
|
|
|
|
|
### toAdd(fn[, isHigh])
|
|
Type: `Function`<br>
|
|
Returns: `void`
|
|
|
|
Add a function to the throttle's queue.
|
|
|
|
> **Important:** In "priority" mode, identical functions are ignored.
|
|
|
|
#### fn
|
|
Type: `Function`<br>
|
|
The function to add to the queue.
|
|
|
|
#### isHigh
|
|
Type: `Boolean`<br>
|
|
Default: `false`<br>
|
|
If the `fn` should be added to the "high priority" queue.
|
|
|
|
> **Important:** Only available in "priority" mode!
|
|
|
|
|
|
### isDone
|
|
Type: `Function`<br>
|
|
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](https://lukeed.com)
|