Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jcoreio/async-throttle
throttle async and promise-returning functions like lodash.throttle
https://github.com/jcoreio/async-throttle
async async-await promise throttle
Last synced: 4 days ago
JSON representation
throttle async and promise-returning functions like lodash.throttle
- Host: GitHub
- URL: https://github.com/jcoreio/async-throttle
- Owner: jcoreio
- License: mit
- Created: 2017-04-18T02:12:11.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2024-10-08T14:11:12.000Z (3 months ago)
- Last Synced: 2025-01-13T04:03:09.069Z (8 days ago)
- Topics: async, async-await, promise, throttle
- Language: TypeScript
- Homepage:
- Size: 1.92 MB
- Stars: 21
- Watchers: 4
- Forks: 1
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# async-throttle
[](https://circleci.com/gh/jcoreio/async-throttle)
[](undefined)
[](https://github.com/semantic-release/semantic-release)
[](http://commitizen.github.io/cz-cli/)
[](https://badge.fury.io/js/%40jcoreio%2Fasync-throttle)
Throttle async and promise returning functions. Unlike similarly named packages, this behaves much like an async version of
`lodash.throttle`:
- Only one invocation can be running at a time (similarly named packages don't do this)
- Has `.cancel()` and `.flush()`
## Differences from `lodash.throttle`
- No `leading` and `trailing` options
- `getNextArgs` option allows you to customize how the arguments for the next invocation are determined
## Installing
```sh
npm install --save @jcoreio/async-throttle
```
### Usage
```js
const throttle = require('@jcoreio/async-throttle')
import throttle from '@jcoreio/async-throttle'
```
```js
function throttle, Value>(
func: (...args: Args) => Promise,
wait: ?number,
options?: {
getNextArgs?: (current: Args, next: Args) => Args
}
): (...args: Args) => Promise;
```
Creates a throttled function that only invokes `func` at most once per every `wait` milliseconds, and also waits for the
`Promise` returned by the previous invocation to finish (it won't invoke `func` in parallel).
The promise returned by the throttled function will track the promise returned by the next invocation of `func`.
If `wait` is falsy, it is treated as 0, which causes `func` to be invoked on the next tick afte the previous invocation
finishes.
By default, `func` is called with the most recent arguments to the throttled function. You can change this with the
`getNextArgs` option -- for example, if you want to invoke `func` with the minimum of all arguments since the last
invocation:
```js
const throttledFn = throttle(foo, 10, {
getNextArgs: ([a], [b]) => [Math.min(a, b)],
})
throttledFn(2)
throttledFn(1)
throttledFn(3)
// foo will be called with 1
// time passes...
throttledFn(4)
throttledFn(6)
throttledFn(5)
// foo will be called with 4
```
### `throttledFn.invokeIgnoreResult(args)`
Calls the throttled function soon, but doesn't return a promise, catches any CanceledError, and doesn't create any new promises if a call is already pending.
To use this, you should handle all errors inside the throttled function:
```js
const throttled = throttle(async (arg) => {
try {
await doSomething(arg)
} catch (err) {
// handle error
}
})
```
Then call `invokeIgnoreResult` instead of the throttled function:
```js
throttled.invokeIgnoreResult(arg)
```
The `invokeIgnoreResult` method is useful because the following code example would leave 1000 pending promises
on the heap, even though the catch block is a no-op:
```js
for (let i = 0; i < 1000; i++) {
throttled(arg).catch(() => {})
}
```
### `throttledFn.cancel()`
Cancels the pending invocation, if any. All `Promise`s tracking the pending invocation will be
rejected with a `CancelationError` (`const {CancelationError} = require('@jcoreio/async-throttle')`).
However, if an invocation is currently running, all `Promise`s tracking the current invocation will be fulfilled as usual.
Returns a `Promise` that will resolve once the current invocation (if any) is finished.
### `throttledFn.flush()`
Cancels the `wait` before the pending invocation, if any. The pending invocation will still wait for the current invocation (if any)
to finish, but will begin immediately afterward, even if `wait` has not elapsed.
Returns a `Promise` that will resolve once the current invocation (if any) is finished.