asyncbox

What is asyncbox?

The asyncbox npm package provides a set of utility functions to work with asynchronous code in JavaScript. It simplifies common asynchronous operations such as waiting for conditions, retrying operations, and handling promises.

What are asyncbox's main functionalities?

waitForCondition

The `waitForCondition` function allows you to wait for a specific condition to be met. In this example, the condition is met after 2 seconds, and the function waits up to 5 seconds, checking every 500 milliseconds.

const { waitForCondition } = require('asyncbox');

async function example() {
  let conditionMet = false;
  setTimeout(() => { conditionMet = true; }, 2000);
  await waitForCondition(() => conditionMet, { waitMs: 5000, intervalMs: 500 });
  console.log('Condition met!');
}

example();

retry

The `retry` function allows you to retry an asynchronous operation a specified number of times. In this example, the operation fails twice before succeeding on the third attempt.

const { retry } = require('asyncbox');

async function example() {
  let attempt = 0;
  const result = await retry(3, async () => {
    attempt++;
    if (attempt < 3) throw new Error('Failed attempt');
    return 'Success';
  });
  console.log(result); // 'Success'
}

example();

sleep

The `sleep` function pauses execution for a specified amount of time. In this example, the code waits for 2 seconds between logging 'Start' and 'End'.

const { sleep } = require('asyncbox');

async function example() {
  console.log('Start');
  await sleep(2000);
  console.log('End');
}

example();

Other packages similar to asyncbox

async

The `async` package provides a collection of functions for working with asynchronous JavaScript. It includes utilities for parallel and sequential execution, as well as flow control. Compared to asyncbox, it offers a broader range of utilities but may be more complex to use.

bluebird

The `bluebird` package is a fully-featured Promise library that provides additional functionality over native Promises, such as cancellation, progress tracking, and more. While it doesn't focus on utilities like asyncbox, it enhances promise handling and chaining.

p-retry

The `p-retry` package is a simple utility for retrying failed promises. It is similar to the retry functionality in asyncbox but is more focused and configurable, offering options like exponential backoff.

README

asyncbox

A collection of ES7 async/await utilities. Install via NPM:

npm install asyncbox

Then, behold!

Sleep

An async/await version of setTimeout

import { sleep } from 'asyncbox';

async function myFn () {
    // do some stuff
    await sleep(1000); // wait one second
    // do some other stuff
};

Retry

An async/await way of running a method until it doesn't throw an error

import { sleep, retry } from 'asyncbox';

async function flakeyFunction (val1, val2) {
    if (val1 < 10) {
        throw new Error("this is a flakey value");
    }
    await sleep(1000);
    return val1 + val2;
}

async function myFn () {
    let randVals = [Math.random() * 100, Math.random() * 100];

    // run flakeyFunction up to 3 times until it succeeds.
    // if it doesn't, we'll get the error thrown in this context
    let randSum = await retry(3, flakeyFunction, ...randVals);
}

You can also use retryInterval to add a sleep in between retries. This can be useful if you want to throttle how fast we retry:

await retryInterval(3, 1500, expensiveFunction, ...args);

Filter/Map

Filter and map are pretty handy concepts, and now you can write filter and map functions that execute asynchronously!

import { asyncmap, asyncfilter } from 'asyncbox';

Then in your async functions, you can do:

const items = [1, 2, 3, 4];
const slowSquare = async (n) => { await sleep(5); return n * 2; };
let newItems = await asyncmap(items, async (i) => { return await slowSquare(i); });
console.log(newItems);  // [1, 4, 9, 16];

const slowEven = async (n) => { await sleep(5); return n % 2 === 0; };
newItems = await asyncfilter(items, async (i) => { return await slowEven(i); });
console.log(newItems); // [2, 4];

By default, asyncmap and asyncfilter run their operations in parallel; you can pass false as a third argument to make sure it happens serially.

Nodeify

Export async functions (Promises) and import this with your ES5 code to use it with Node.

var asyncbox = require('asyncbox')
  , sleep = asyncbox.sleep
  , nodeify = asyncbox.nodeify;

nodeify(sleep(1000), function (err, timer) {
  console.log(err); // null
  console.log(timer); // timer obj
});

nodeifyAll

If you have a whole library you want to export nodeified versions of, it's pretty easy:

import { nodeifyAll } from 'asyncbox';

async function foo () { ... }
async function bar () { ... }
let cb = nodeifyAll({foo, bar});
export { foo, bar, cb };

Then in my ES5 script I can do:

var myLib = require('mylib').cb;

myLib.foo(function (err) { ... });
myLib.bar(function (err) { ... });

Run the tests

npm test