Iterall: JavaScript Iterables for All Environments

Common errors

• TypeError: 'Symbol.iterator' is not defined

  cause Attempting to iterate over a custom object or non-native iterable in an older JavaScript environment without leveraging `iterall`'s polyfill utilities, leading to the absence of the `Symbol.iterator` global.
  fix Use `iterall.forEach(myIterable, callback)` or `iterall.isIterable(myIterable)` to ensure compatibility across all environments, as `iterall` handles the fallback to `@@iterator`.

• SyntaxError: Cannot use import statement outside a module

  cause Using `import ... from 'iterall'` syntax in a Node.js environment configured for CommonJS (e.g., without `"type": "module"` in `package.json` or a transpiler like Babel).
  fix Change your import statements to CommonJS `require` syntax: `const { forEach } = require('iterall');` or configure your Node.js project or build pipeline to support ESM.

• Module not found: Error: Can't resolve 'iterall'

  cause A bundler (like Webpack) is failing to resolve the `iterall` package, potentially due to incorrect pathing or module resolution configuration, especially concerning its `.mjs` files.
  fix Verify `iterall` is correctly installed in `node_modules`. If using a bundler, ensure its configuration supports resolving `.mjs` files (e.g., `resolve.extensions` in Webpack should include `'.mjs'`).

Warnings

• gotcha Iterall's primary value is in providing polyfills and fallbacks for Iteration Protocols in older JavaScript environments (pre-ES2015 or limited browser support). If you are strictly targeting modern ES2015+ environments that fully support `Symbol.iterator`, you might be able to use native iteration directly without `iterall`.
  Fix: Assess your target environment compatibility. If only modern ES environments are targeted, native `for...of` loops and `Array.from` might suffice. Otherwise, `iterall` is beneficial for broader compatibility.
• gotcha For optimal tree-shaking and better ESM compatibility with bundlers like Rollup or Webpack, `iterall` has published `.mjs` files since `v1.2.0`. Ensure your build configuration is set up to resolve `.mjs` files correctly, especially in dual CommonJS/ESM setups.
  Fix: Check your bundler configuration (e.g., `resolve.extensions` in Webpack) to ensure `.mjs` is included. For Node.js, ensure your `package.json` specifies `type: 'module'` or uses `.mjs` extensions for ESM files.
• gotcha Early versions of `forAwaitEach` (before v1.1.2) had a memory leak issue, and v1.1.2 introduced a fix for this. Subsequently, v1.1.3 fixed an issue where errors within `forAwaitEach` were not caught.
  Fix: If using `forAwaitEach` for asynchronous iteration, ensure your project depends on `iterall` version `1.1.3` or newer to avoid memory leaks and unhandled promise rejections.

Install

• npm install iterall npm
• yarn add iterall yarn
• pnpm add iterall pnpm

Imports

• isCollection
  wrong:

  const isCollection = require('iterall').isCollection;

  correct:

  import { isCollection } from 'iterall';

  For ESM, use named imports. For CommonJS, use require. Since v1.2.0, `.mjs` files are published for better ESM compatibility and tree-shaking.
• forEach
  wrong:

  const forEach = require('iterall').forEach;

  correct:

  import { forEach } from 'iterall';

  This utility allows iterating over any Iterable or Array-like structure, even in environments without native Symbol.iterator.
• forAwaitEach
  wrong:

  const forAwaitEach = require('iterall').forAwaitEach;

  correct:

  import { forAwaitEach } from 'iterall';

  Introduced in v1.1.0, this function provides a universal way to iterate over AsyncIterables, returning a Promise. Ensure you are on v1.1.3 or higher for critical bug fixes.

Quickstart

Demonstrates how to use `isCollection` to check for iterable/array-like structures and `forEach` for synchronous iteration, along with `forAwaitEach` for handling asynchronous iterables, all compatible across environments.

import { isCollection, forEach, forAwaitEach } from 'iterall';

// Example 1: Handling various synchronous collections
function processCollection(data) {
  if (isCollection(data)) {
    forEach(data, (item, index) => {
      console.log(`Sync Item ${index}: ${item}`);
    });
    console.log('Finished synchronous iteration.');
  } else {
    console.log('Input is not a recognized collection.');
  }
}

processCollection([1, 2, 3]);
processCollection(new Set(['a', 'b']));

// Example 2: Handling asynchronous iterables
async function* asyncGenerator() {
  yield 'hello';
  await new Promise(resolve => setTimeout(resolve, 100));
  yield 'world';
}

async function processAsyncIterable(asyncData) {
  console.log('Starting asynchronous iteration...');
  await forAwaitEach(asyncData, (item, index) => {
    console.log(`Async Item ${index}: ${item}`);
  });
  console.log('Finished asynchronous iteration.');
}

processAsyncIterable(asyncGenerator());