Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lukeed/throttles
A tiny (139B to 204B) utility to regulate the execution rate of your functions
https://github.com/lukeed/throttles
Last synced: about 1 month ago
JSON representation
A tiny (139B to 204B) utility to regulate the execution rate of your functions
- Host: GitHub
- URL: https://github.com/lukeed/throttles
- Owner: lukeed
- License: mit
- Created: 2019-08-21T23:21:52.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2023-08-14T20:24:21.000Z (about 1 year ago)
- Last Synced: 2024-04-14T11:43:55.607Z (5 months ago)
- Language: JavaScript
- Homepage:
- Size: 17.6 KB
- Stars: 195
- Watchers: 4
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: readme.md
- License: license
Awesome Lists containing this project
README
# 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
> **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
> **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.
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`
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](https://lukeed.com)