Saturated NPM | npm.io

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 pushed.

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 next interval 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.