README.md

Qew

A tiny library for queuing and throttling asynchronous functions.

Perfect for managing resource-intensive processes and controlling access to rate-limited APIs.

This project has 0 (zero) runtime dependencies 👌.

1. Installation
2. API
   1. Qew.constructor
   2. Qew.push
3. Use cases
4. Methods & type signatures
5. Contributing

Installation

Qew is available on npm. Install via

$ npm install qew

or

$ yarn add qew

API

new Qew(maxConcurrency=1, delayOrDelayFunc=0)

The constructor's type signature is

constructor Qew(maxConcurrency: number = 1, delay: number | (() => number) = 0): Qew;

Examples

const Qew = require("qew");

const qew = new Qew(); // maxConcurrency of 1, delay of 0ms
const qew = new Qew(3); // maxConcurrency of 3, delay of 0ms
const qew = new Qew(2, 250); // maxConcurrency of 2, delay of 250ms between end and start of functions

The delay parameter doesn't need to be a hardcoded number, you can also pass in a function that returns a number.

const getRandomDelay = () => Math.random() * 1000;

const qew = new Qew(2, getRandomDelay);
// maxConcurrency of 2, delay will be a new random value between 0ms and 1000ms

Qew.push(asyncFunction)

Type signature

Qew.push(asyncFunc: () => Promise<T>): Promise<T>;

Examples

// returns a promise, that runs when it is its turn in the queue.
// will resolve or reject depending on asyncFunc's resolution
const prom = qew.push(asyncFunc);

prom
    .then(result => ...)
    .catch(error => ...);

// `push`'s result can also be `await`ed in an async function like any promise
const doStuff = async () => {
    const result = await qew.push(asyncFunc);
    // do something  with `result`
}

Use cases

Accessing rate-limited APIs

Basic example, queuing individual asynchronous functions.

const qew = new Qew(1, 100); // for API that has a rate limit of 10 reqs/sec

qew.push(() => accessApi("a")).then(callback);
qew.push(() => accessApi("b")).then(callback);
qew.push(() => accessApi("c")).then(callback);

function callback(err, result) {
  if (err) {
    return console.error(err);
  }
  console.log(result);
}

Methods and type signatures

constructor Qew(maxConcurrent: number = 1, delay: number | (() => number) = 0): Qew;

Qew.push(asyncFunc: () => Promise<T>): Promise<T>;

Contributing

Contributions are welcome! Feel free to file an issue or submit a pull request.