saturated
v1.0.0
Published
A tiny (203B) utility to enqueue items for batch processing and/or satisfying rate limits
Downloads
874
Maintainers
Readme
saturated
A tiny (203B) utility to enqueue items for batch processing and/or satisfying rate limits.
Build a queue for your function – ideal for communicating with APIs that prefer batch/bulk processing or services that enforce rate limiting.
With saturated
you provide a handler
which will only be called every N items or after every X milliseconds... whichever comes first! This then allows you to push()
your payload(s) into the queue, waiting for the next tick.
This module exposes three module definitions:
- CommonJS:
dist/saturated.js
- ES Module:
dist/saturated.mjs
- UMD:
dist/saturated.min.js
Install
$ npm install --save saturated
Usage
import saturated from 'saturated';
// Setup an instance
const rated = saturated(arr => {
if (arr.length > 0) {
console.log('~> Received', arr);
} else {
console.log('~> Empty...');
}
}, {
max: 5, // limit
interval: 3e3 // 3s
});
// Now we have a `saturated` instance that will
// call our function every 3 seconds or once it
// has 5 items in its queue – whichever comes first.
// For demo purposes
const sleep = ms => new Promise(r => setTimeout(r, ms));
// Demo usage
async function demo() {
rated.push('hello'); //=> 1
rated.push('world'); //=> 2
rated.push('how'); //=> 3
rated.push('are'); //=> 4
rated.push('you'); //=> 5
// Queue received 5th item, immediately invoke!
// ~> Received ['hello', 'world', 'how', 'are', 'you']
rated.size(); //=> 0 (flushed)
rated.push('hola'); //=> 1
rated.push('mundo'); //=> 2
rated.size(); //=> 2
await sleep(3e3);
// Interval waited 3 seconds
// ~> Received ['hola', 'mundo']
rated.size(); //=> 0 (flushed)
// Wait another 3s ...
await sleep(3e3);
// ~> Empty...
rated.size(); //=> 0 (flushed anyway)
}
// Init demo
demo().then(() => {
rated.end(); // quit
});
API
saturated(handler, options)
Returns: ISaturated
handler
Type: Function
Required: true
The function to invoke once a threshold has been met.
It will always receive an Array
of whatever item(s) you previously push
ed.
Note: You may be passed an empty Array!
options.max
Type: Number
Default: Infinity
The maximum size of the queue.
For example, with max: 5
, your handler
will be invoked immediately after the 5th item was pushed to queue.
Important: Your function will be called if
max
is met before the nextinterval
tick.
options.interval
Type: Number
Default: 10000
The amount of time, in milliseconds, to wait before calling your handler
function.
Defaults to calling your handler
every 10 seconds, even if the queue is empty.
ISaturated.size()
Returns: Number
Get the current size of the queue.
ISaturated.push(value)
Returns: Number
Add an item/value into the queue stack. Doing so will return the current size of the queue.
value
Type: Any
You may push any value into queue.
Important: Anything you push will be added to an Array! Pushing an Array will have your
handler
receive an Array of your Arrays.
ISaturated.end(toFlush)
Returns: undefined
Cancels the internal setInterval
timer.
toFlush
Type: Boolean
Default: false
When true
, will also flush()
the queue so that remaining items will be passed to your handler
function.
ISaturated.flush()
Returns: undefined
Forcibly invoke your handler
will all items currently in the queue.
Calling flush
will restart the internal setInterval
timer and empty the queue.
License
MIT © Luke Edwards