Utility Functions for Callback-based Async Iterators

Common errors

• TypeError: iterators.forEach is not a function

  cause Attempting to use `async-iterators` in an ES module context with `import` syntax, or the variable holding the `require` result is not named `iterators` or correctly destructured.
  fix Ensure you are using CommonJS `require` syntax: `const iterators = require('async-iterators');`.

• ReferenceError: require is not defined in ES module scope

  cause Trying to use `require` in a JavaScript file explicitly defined as an ES module (e.g., via `"type": "module"` in `package.json` or `.mjs` extension).
  fix This package is not compatible with ES module projects. You must either convert your project to CommonJS or choose a modern async iterator library that supports ES modules.

Warnings

• breaking This package uses a custom callback-based async iterator pattern that is fundamentally different from the native ECMAScript `Symbol.asyncIterator` protocol (ES2018). It is not compatible with `for-await-of` loops or modern Promise-based async/await syntax.
  Fix: Migrate to native async iterators and modern async/await patterns, or use a contemporary library that provides similar utilities for `AsyncIterable`.
• gotcha The package was last updated over a decade ago (version 0.2.2 published in 2013) and targets Node.js versions >=0.10. It is highly unlikely to be compatible with current Node.js runtimes (e.g., Node.js 16+ or 20+) without significant environment setup or polyfills for ancient Node.js APIs.
  Fix: Avoid using this package in modern Node.js projects. Consider `data-async-iterators` or `buffered-async-iterable` for modern async iterable utilities.
• gotcha This library is CommonJS-only and does not support ES Modules (`import`/`export` syntax). Attempting to import it directly in an ESM context will result in errors.
  Fix: In an ESM project, you would need to use `const iterators = require('async-iterators')` within a CommonJS wrapper, or refactor to use a modern ESM-compatible async utility library.

Install

• npm install async-iterators npm
• yarn add async-iterators yarn
• pnpm add async-iterators pnpm

Imports

• iterators
  wrong:

  import * as iterators from 'async-iterators'

  correct:

  const iterators = require('async-iterators')

  This package is CommonJS-only and does not support ES modules. The default export is an object containing all utility functions.
• forEach
  wrong:

  import { forEach } from 'async-iterators'

  correct:

  const { forEach } = require('async-iterators')

  Individual functions can be destructured from the CommonJS `require` result, but direct ESM imports are not supported.
• map
  wrong:

  import { map } from 'async-iterators'

  correct:

  const map = require('async-iterators').map

  This package exports an object with properties; individual functions are accessed via dot notation or CommonJS destructuring.

Quickstart

Demonstrates the use of `forEach` with a custom callback-based async iterator, logging each item and an 'end' message.

const iterators = require('async-iterators');

// A dummy async iterator following the package's callback-based pattern
function createExampleIterator() {
  let i = 0;
  const data = [10, 20, 30, 40, 50];
  return {
    next: function(cb) {
      if (i < data.length) {
        setTimeout(() => {
          cb(null, data[i]);
          i++;
        }, 50);
      } else {
        cb(null, undefined); // Signal end of iteration
      }
    }
  };
}

const myIterator = createExampleIterator();

console.log('Starting iteration...');
iterators.forEach(myIterator, function(err, data) {
  if (err) {
    console.error('Error:', err);
    return;
  }
  if (data !== undefined) {
    console.log('Received data:', data);
  }
}, function() {
  console.log('End of iteration.');
});