Async.js Deployment & Usage Guide

A comprehensive guide for installing, developing, and deploying the Async.js utility library.

Prerequisites

• Node.js: Version 12.x or higher (required for ES6 module support)
• npm: Version 6.x or higher (comes with Node.js)
• Git: For cloning the repository
• Optional: A modern bundler (Webpack 4+, Rollup, or Parcel) if building for browser usage

Installation

As a Project Dependency

# Using npm
npm install async

# Using yarn
yarn add async

# For pure ESM projects (tree-shakeable)
npm install async-es

For Development/Contribution

# Clone the repository
git clone https://github.com/caolan/async.git
cd async

# Install dependencies
npm install

Configuration

Browser Usage (CDN)

No configuration required. Include directly via jsDelivr:

<script src="https://cdn.jsdelivr.net/npm/async@3.2.4/dist/async.min.js"></script>
<script>
  // Async available as global `async` object
  async.waterfall([...], callback);
</script>

Module System Selection

The package automatically detects your environment:

• CommonJS (Node.js): const async = require('async');
• ES Modules: import async from 'async'; or import { waterfall } from 'async';
• TypeScript: Types are included; no additional @types package needed

JSDoc Documentation Configuration

If regenerating documentation, ensure the custom theme is available:

# Documentation uses custom theme in support/jsdoc/theme/
# Output directory is typically ./docs/v3/
export JSDOC_THEME=./support/jsdoc/theme

Build & Run

Running Tests

# Run full test suite
npm test

# Run with coverage (Coveralls integration)
npm run coverage

# Run specific test file
npm test -- --grep "auto"

Building Documentation

# Generate JSDoc documentation
npm run docs

# Or manually with jsdoc
npx jsdoc -c jsdoc.json -t ./support/jsdoc/theme -R README.md -d ./docs/v3 ./lib

# Serve docs locally
npx http-server ./docs/v3

Building Distribution Files

# Build browser-compatible bundles (if build script exists)
npm run build

# Build ESM-specific version
npm run build:esm

Development Workflow

# Watch mode for development
npm run watch

# Linting
npm run lint

# Validate TypeScript definitions
npx tsc --noEmit

Deployment

Publishing to npm (Maintainers)

# Version bump (patch/minor/major)
npm version patch

# Run full validation
npm test
npm run build

# Publish to npm registry
npm publish

# For ESM-only package (async-es)
cd dist/async-es
npm publish

Deploying Documentation

The documentation is hosted on GitHub Pages:

# Generate fresh docs
npm run docs

# Deploy to gh-pages branch
npm run deploy:docs
# Or manually copy ./docs/v3 to gh-pages branch

Using in Production Applications

Node.js Applications:

// Standard callback style
const async = require('async');

// Modern async/await style
const { mapLimit } = require('async');
const results = await mapLimit(urls, 5, async (url) => {
  const res = await fetch(url);
  return res.json();
});

Browser Applications:

// ES Modules with bundler
import { auto, waterfall } from 'async';

// Webpack/Rollup will automatically use the ESM entry point

Serverless/Lambda: No special configuration required. The library is stateless and works in serverless environments without modification.

Troubleshooting

Common Issues

Error: "Cannot find module 'async'" with ES Modules

• Solution: Use named imports: import { series } from 'async'; instead of default import
• For full ESM compatibility, install async-es: npm install async-es

Browser Build Errors with Webpack/Rollup

• Symptom: "process is not defined" or Node.js polyfill errors
• Solution: The library detects browser environment automatically. Ensure you're importing the ESM build:

  import async from 'async/dist/async.esm.js';
  

JSDoc Generation Fails

• Symptom: "Template not found" errors
• Solution: Verify the theme path:

  ls support/jsdoc/theme/publish.js  # Should exist
  npx jsdoc -t ./support/jsdoc/theme ...
  

Callback Never Called / Hanging Operations

• Cause: Missing callback invocation in user code
• Debug: Use async.timeout wrapper:

  const timedFn = async.timeout(myAsyncFn, 5000);
  timedFn(args, (err, result) => {
    if (err && err.code === 'ETIMEDOUT') console.error('Operation timed out');
  });
  

Migration from v1.x to v3.x

• forEachOf replaced forEach for objects (key order guarantee)
• async.reflect is now preferred over manual error handling
• All methods support native Promises/await automatically via wrapAsync

Performance Issues with Large Arrays

• Use mapLimit, eachLimit, or parallelLimit instead of unbounded versions
• Default concurrency is Infinity; set explicit limits for I/O operations:

  async.mapLimit(files, 10, fs.readFile, callback);
  

Getting Help

• Documentation: https://caolan.github.io/async/
• Issues: https://github.com/caolan/async/issues
• Chat: https://gitter.im/caolan/async
• CI Status: Check GitHub Actions badge in README before reporting build failures