Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sindresorhus/p-throttle
Throttle promise-returning & async functions
https://github.com/sindresorhus/p-throttle
Last synced: about 2 months ago
JSON representation
Throttle promise-returning & async functions
- Host: GitHub
- URL: https://github.com/sindresorhus/p-throttle
- Owner: sindresorhus
- License: mit
- Created: 2016-10-21T08:10:07.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2024-02-21T04:32:31.000Z (4 months ago)
- Last Synced: 2024-04-12T21:15:16.122Z (3 months ago)
- Language: JavaScript
- Size: 40 KB
- Stars: 382
- Watchers: 8
- Forks: 27
- Open Issues: 8
-
Metadata Files:
- Readme: readme.md
- License: license
- Security: .github/security.md
Lists
- awesome-promises - p-throttle - Throttle promise-returning & async functions (Convenience Utilities / sindresorhus's many Promise utilities ([see notes](https://github.com/sindresorhus/promise-fun)))
- promise-fun - p-throttle - returning & async functions (Packages)
- awesome-stars - sindresorhus/p-throttle - Throttle promise-returning & async functions (others)
README
# p-throttle
> Throttle promise-returning & async functions
It also works with normal functions.
It rate-limits function calls without discarding them, making it ideal for external API interactions where avoiding call loss is crucial.
## Install
```sh
npm install p-throttle
```
## Usage
Here, the throttled function is only called twice a second:
```js
import pThrottle from 'p-throttle';
const now = Date.now();
const throttle = pThrottle({
limit: 2,
interval: 1000
});
const throttled = throttle(async index => {
const secDiff = ((Date.now() - now) / 1000).toFixed();
return `${index}: ${secDiff}s`;
});
for (let index = 1; index <= 6; index++) {
(async () => {
console.log(await throttled(index));
})();
}
//=> 1: 0s
//=> 2: 0s
//=> 3: 1s
//=> 4: 1s
//=> 5: 2s
//=> 6: 2s
```
## API
### pThrottle(options)
Returns a throttle function.
#### options
Type: `object`
Both the `limit` and `interval` options must be specified.
##### limit
Type: `number`
The maximum number of calls within an `interval`.
##### interval
Type: `number`
The timespan for `limit` in milliseconds.
##### strict
Type: `boolean`\
Default: `false`
Use a strict, more resource intensive, throttling algorithm. The default algorithm uses a windowed approach that will work correctly in most cases, limiting the total number of calls at the specified limit per interval window. The strict algorithm throttles each call individually, ensuring the limit is not exceeded for any interval.
##### onDelay
Type: `Function`
Get notified when function calls are delayed due to exceeding the `limit` of allowed calls within the given `interval`.
Can be useful for monitoring the throttling efficiency.
In the following example, the third call gets delayed and triggers the `onDelay` callback:
```js
import pThrottle from 'p-throttle';
const throttle = pThrottle({
limit: 2,
interval: 1000,
onDelay: () => {
console.log('Reached interval limit, call is delayed');
},
});
const throttled = throttle(() => {
console.log('Executing...');
});
await throttled();
await throttled();
await throttled();
//=> Executing...
//=> Executing...
//=> Reached interval limit, call is delayed
//=> Executing...
```
### throttle(function_)
Returns a throttled version of `function_`.
#### function_
Type: `Function`
A promise-returning/async function or a normal function.
### throttledFn.abort()
Abort pending executions. All unresolved promises are rejected with a `pThrottle.AbortError` error.
### throttledFn.isEnabled
Type: `boolean`\
Default: `true`
Whether future function calls should be throttled and count towards throttling thresholds.
### throttledFn.queueSize
Type: `number`
The number of queued items waiting to be executed.
## Related
- [p-debounce](https://github.com/sindresorhus/p-debounce) - Debounce promise-returning & async functions
- [p-limit](https://github.com/sindresorhus/p-limit) - Run multiple promise-returning & async functions with limited concurrency
- [p-memoize](https://github.com/sindresorhus/p-memoize) - Memoize promise-returning & async functions
- [More…](https://github.com/sindresorhus/promise-fun)