async

What is async?

The async npm package provides utility functions for working with asynchronous JavaScript. It offers a variety of powerful control flow functions and utilities to work with asynchronous operations, helping to manage callbacks, reduce boilerplate code, and increase readability.

What are async's main functionalities?

Control Flow

Execute an array of functions in series, each one running once the previous function has completed. If any functions in the series pass an error to its callback, no more functions are run, and the main callback is immediately called with the value of the error.

async.series([
  function(callback) { 
    // do some stuff ...
    callback(null, 'one'); 
  },
  function(callback) { 
    // do some more stuff ...
    callback(null, 'two'); 
  }
],
function(err, results) {
  // results is now equal to ['one', 'two']
});

Collections

Apply a function to each item in a collection and collect the results. For example, you can use `async.map` to get the file stats for an array of file names.

async.map(['file1','file2','file3'], fs.stat, function(err, results) {
  // results is now an array of stats for each file
});

Utilities

Repeatedly call a function a set number of times and collect the results. It's useful for seeding databases, among other things.

async.times(5, function(n, next) {
  createUser(n, function(err, user) {
    next(err, user);
  });
}, function(err, users) {
  // we should now have 5 users
});

Other packages similar to async

bluebird

Bluebird is a fully-featured promise library with a focus on innovative features and performance. It allows for promise-based asynchronous control flow, which can lead to cleaner and more readable code compared to traditional callback patterns. Bluebird also provides utility functions similar to async but uses promises instead of callbacks.

q

Q is a tool for making and composing asynchronous promises in JavaScript. It helps in organizing asynchronous code with more maintainable and readable structures. Q is similar to async in that it helps manage asynchronous operations but does so through promises rather than callbacks.

co

Co is a generator based flow-control utility for Node.js and the browser, using promises. It allows you to work with generators for asynchronous control flow, which can make your code more readable and maintainable. Co is different from async in that it leverages generator functions to pause and resume execution, while async uses callbacks.

README

Async is a utility module which provides straight-forward, powerful functions for working with asynchronous JavaScript. Although originally designed for use with Node.js and installable via npm install async, it can also be used directly in the browser. A ESM version is included in the main async package that should automatically be used with compatible bundlers such as Webpack and Rollup.

A pure ESM version of Async is available as async-es.

For Documentation, visit https://caolan.github.io/async/

For Async v1.5.x documentation, go HERE

// for use with Node-style callbacks...
var async = require("async");

var obj = {dev: "/dev.json", test: "/test.json", prod: "/prod.json"};
var configs = {};

async.forEachOf(obj, (value, key, callback) => {
    fs.readFile(__dirname + value, "utf8", (err, data) => {
        if (err) return callback(err);
        try {
            configs[key] = JSON.parse(data);
        } catch (e) {
            return callback(e);
        }
        callback();
    });
}, err => {
    if (err) console.error(err.message);
    // configs is now a map of JSON data
    doSomethingWith(configs);
});

var async = require("async");

// ...or ES2017 async functions
async.mapLimit(urls, 5, async function(url) {
    const response = await fetch(url)
    return response.body
}, (err, results) => {
    if (err) throw err
    // results is now an array of the response bodies
    console.log(results)
})

Changelog

v3.0.0

The async/await release!

There are a lot of new features and subtle breaking changes in this major version, but the biggest feature is that most Async methods return a Promise if you omit the callback, meaning you can await them from within an async function.

const results = await async.mapLimit(urls, 5, async url => {
    const resp = await fetch(url)
    return resp.body
})

Breaking Changes

• Most Async methods return a Promise when the final callback is omitted, making them await-able! (#1572)
• We are now making heavy use of ES2015 features, this means we have dropped out-of-the-box support for Node 4 and earlier, and many old versions of browsers. (#1541, #1553)
• In queue, priorityQueue, cargo and cargoQueue, the "event"-style methods, like q.drain and q.saturated are now methods that register a callback, rather than properties you assign a callback to. They are now of the form q.drain(callback). If you do not pass a callback a Promise will be returned for the next occurrence of the event, making them await-able, e.g. await q.drain(). (#1586, #1641)
• Calling callback(false) will cancel an async method, preventing further iteration and callback calls. This is useful for preventing memory leaks when you break out of an async flow by calling an outer callback. (#1064, #1542)
• during and doDuring have been removed, and instead whilst, doWhilst, until and doUntil now have asynchronous test functions. (#850, #1557)
• limits of less than 1 now cause an error to be thrown in queues and collection methods. (#1249, #1552)
• memoize no longer memoizes errors (#1465, #1466)
• applyEach/applyEachSeries have a simpler interface, to make them more easily type-able. It always returns a function that takes in a single callback argument. If that callback is omitted, a promise is returned, making it awaitable. (#1228, #1640)

New Features

• Async generators are now supported in all the Collection methods. (#1560)
• Added cargoQueue, a queue with both concurrency and payload size parameters. (#1567)
• Queue objects returned from queue now have a Symbol.iterator method, meaning they can be iterated over to inspect the current list of items in the queue. (#1459, #1556)
• A ESM-flavored async.mjs is included in the async package. This is described in the package.json "module" field, meaning it should be automatically used by Webpack and other compatible bundlers.

Bug fixes

• Better handle arbitrary error objects in asyncify (#1568, #1569)

Other

• Removed Lodash as a dependency (#1283, #1528)
• Miscellaneous docs fixes (#1393, #1501, #1540, #1543, #1558, #1563, #1564, #1579, #1581)
• Miscellaneous test fixes (#1538)