Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lpinca/stopcock
Limit the execution rate of a function using the token bucket algorithm
https://github.com/lpinca/stopcock
leaky-bucket promise rate-limiting throttle token-bucket
Last synced: 18 days ago
JSON representation
Limit the execution rate of a function using the token bucket algorithm
- Host: GitHub
- URL: https://github.com/lpinca/stopcock
- Owner: lpinca
- License: mit
- Created: 2017-03-30T16:51:41.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-11-29T20:59:55.000Z (12 months ago)
- Last Synced: 2024-10-19T19:55:10.831Z (26 days ago)
- Topics: leaky-bucket, promise, rate-limiting, throttle, token-bucket
- Language: JavaScript
- Homepage:
- Size: 16.6 KB
- Stars: 18
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# stopcock
[![Version npm][npm-stopcock-badge]][npm-stopcock]
[![Build Status][ci-stopcock-badge]][ci-stopcock]
[![Coverage Status][coverage-stopcock-badge]][coverage-stopcock]
Limit the execution rate of a function using the token bucket algorithm. Useful
for scenarios such as REST APIs consumption where the amount of requests per
unit of time should not exceed a given threshold.
## Install
```
npm install --save stopcock
```
## API
The module exports a single function that takes two arguments.
### `stopcock(fn[, options])`
Returns a function which should be called instead of `fn`.
#### Arguments
- `fn` - The function to rate limit calls to.
- `options` - A plain JavaScript object that contains the configuration options.
#### Options
- `limit` - The maximum number of allowed calls per `interval`. Defaults to 2.
- `interval` - The timespan where `limit` is calculated. Defaults to 1000.
- `bucketSize` - The capacity of the bucket. Defaults to 40.
- `queueSize` - The maximum size of the internal queue. Defaults to 2^32 - 1
which is the maximum array size in JavaScript.
#### Return value
A function that returns a promise which resolves to the value returned by the
original `fn` function. The returned function has a `size` accessor property
which returns the internal queue size. When the queue is at capacity the promise
is rejected.
#### Example
```js
const stopcock = require('stopcock');
function request(i) {
return Promise.resolve(`${i} - ${new Date().toISOString()}`);
}
function log(data) {
console.log(data);
}
const get = stopcock(request, { bucketSize: 5 });
for (let i = 0; i < 10; i++) {
get(i).then(log);
}
/*
0 - 2017-03-30T16:46:39.938Z
1 - 2017-03-30T16:46:39.940Z
2 - 2017-03-30T16:46:39.940Z
3 - 2017-03-30T16:46:39.940Z
4 - 2017-03-30T16:46:39.940Z
5 - 2017-03-30T16:46:40.443Z
6 - 2017-03-30T16:46:40.943Z
7 - 2017-03-30T16:46:41.441Z
8 - 2017-03-30T16:46:41.942Z
9 - 2017-03-30T16:46:42.439Z
*/
```
## License
[MIT](LICENSE)
[npm-stopcock-badge]: https://img.shields.io/npm/v/stopcock.svg
[npm-stopcock]: https://www.npmjs.com/package/stopcock
[ci-stopcock-badge]:
https://img.shields.io/github/actions/workflow/status/lpinca/stopcock/ci.yml?branch=master&label=CI
[ci-stopcock]:
https://github.com/lpinca/stopcock/actions?query=workflow%3ACI+branch%3Amaster
[coverage-stopcock-badge]:
https://img.shields.io/coveralls/lpinca/stopcock/master.svg
[coverage-stopcock]: https://coveralls.io/r/lpinca/stopcock?branch=master