Repository files navigation

Throttle async and promise returning functions. Unlike similarly named packages, this behaves much like an async version oflodash.throttle:

• Only one invocation can be running at a time (similarly named packages don't do this)
• Has.cancel() and.flush()

• Noleading andtrailing options (they're both alwaystrue)
• getNextArgs option allows you to customize how the arguments for the next invocation are determined

npm install --save @jcoreio/async-throttle

constthrottle=require('@jcoreio/async-throttle')importthrottlefrom'@jcoreio/async-throttle'

functionthrottle<Args:Array<any>, Value>(func:(...args:Args)=>Promise<Value>,wait: ?number,options?:{getNextArgs?:(current:Args,next:Args)=>Args}):(...args:Args)=>Promise<Value>;

Creates a throttled function that only invokesfunc at most once per everywait milliseconds, and also waits for thePromise returned by the previous invocation to finish (it won't invokefunc in parallel).

The promise returned by the throttled function will track the promise returned by the next invocation offunc.

Ifwait is falsy, it is treated as 0, which causesfunc to be invoked on the next tick afte the previous invocationfinishes.

By default,func is called with the most recent arguments to the throttled function. You can change this with thegetNextArgs option -- for example, if you want to invokefunc with the minimum of all arguments since the lastinvocation:

constthrottledFn=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

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:

constthrottled=throttle(async(arg)=>{try{awaitdoSomething(arg)}catch(err){// handle error}})

Then callinvokeIgnoreResult instead of the throttled function:

throttled.invokeIgnoreResult(arg)

TheinvokeIgnoreResult method is useful because the following code example would leave 1000 pending promiseson the heap, even though the catch block is a no-op:

for(leti=0;i<1000;i++){throttled(arg).catch(()=>{})}

Cancels the pending invocation, if any. AllPromises tracking the pending invocation will berejected with aCancelationError (const {CancelationError} = require('@jcoreio/async-throttle')).However, if an invocation is currently running, allPromises tracking the current invocation will be fulfilled as usual.

Returns aPromise that will resolve once the current invocation (if any) is finished.

Cancels thewait 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 ifwait has not elapsed.

Returns aPromise that will resolve once the current invocation (if any) is finished.