The Interactive Extensions for JavaScript (IxJS)

Common errors

• TypeError: (some operator) is not a function

  cause Attempting to use an operator (e.g., `map`, `filter`) directly on an `IterableX` or `AsyncIterableX` instance without either importing it as a pipeable operator or adding it via the prototype extension.
  fix Ensure the operator is imported from `ix/iterable/operators` (or `ix/asynciterable/operators`) and used with the `.pipe()` method, or that the corresponding `ix/add/...` module has been imported for prototype extension.

• TypeError: Cannot read property 'Symbol.asyncIterator' of undefined

  cause Attempting to use an asynchronous operator or an `AsyncIterableX` method on a synchronous `Iterable` or a non-async data source.
  fix Verify that your data source is truly asynchronous (e.g., an `AsyncGenerator`, `Promise` of an `Iterable`) and that you are consistently using imports from `ix/asynciterable` and `ix/asynciterable/operators`.

• SyntaxError: Named export 'from' not found. The requested module 'ix' does not provide an export named 'from'.

  cause Incorrect import path for creation functions or operators; these are not directly exposed from the root `ix` package.
  fix Always use specific import paths for creators and operators, such as `import { from } from 'ix/iterable';` or `import { map } from 'ix/asynciterable/operators';`.

Warnings

• gotcha IxJS maintains separate modules for synchronous (`ix/iterable`) and asynchronous (`ix/asynciterable`) operations. Mixing operators or creators from these distinct modules on the wrong type of iterable will lead to runtime errors or incorrect behavior.
  Fix: Always ensure you are importing from either `ix/iterable` for sync operations or `ix/asynciterable` for async operations, and their respective `operators` submodules.
• gotcha Major version updates (e.g., v5.0.0, v6.0.0, v7.0.0) in IxJS often contain internal refactorings and bug fixes. While explicit breaking API changes might not always be prominently documented, minor behavioral changes or stricter type checks can occur, potentially affecting edge cases.
  Fix: Thoroughly test your application when upgrading major versions. Refer to the GitHub release notes and commit history for subtle behavioral changes or type definition improvements.
• deprecated The pattern of directly importing side-effect modules (e.g., `import 'ix/add/iterable-operators/map';`) to extend prototypes is less common in modern applications favoring tree-shaking. While supported, it can lead to larger bundle sizes if not all added operators are used.
  Fix: Prefer using pipeable operators by importing them directly (e.g., `import { map } from 'ix/iterable/operators';`) and composing them with the `.pipe()` method on your iterable instances. This enables better tree-shaking and avoids global prototype modifications.

Install

• npm install ix npm
• yarn add ix yarn
• pnpm add ix pnpm

Imports

• from
  wrong:

  import { from } from 'ix';

  correct:

  import { from } from 'ix/iterable';

  Use the specific `ix/iterable` or `ix/asynciterable` path for the `from` creation function, not the root package.
• pipeable operators
  wrong:

  import { filter, map } from 'ix';

  correct:

  import { filter, map } from 'ix/iterable/operators';

  Pipeable operators are imported from `ix/iterable/operators` for synchronous operations or `ix/asynciterable/operators` for asynchronous operations. Do not import directly from the root `ix` package.
• IterableX / AsyncIterableX
  wrong:

  const { IterableX } = require('ix/iterable'); // CommonJS is supported, but ESM is preferred in modern applications.

  correct:

  import { IterableX } from 'ix/iterable';
  import { AsyncIterableX } from 'ix/asynciterable';

  The `IterableX` and `AsyncIterableX` classes are the core types for working with these extensions. Use `IterableX` for synchronous and `AsyncIterableX` for asynchronous.
• Prototype extensions
  wrong:

  import { map } from 'ix/add/iterable-operators/map';

  correct:

  import 'ix/add/iterable/of';
  import 'ix/add/iterable-operators/map';

  To extend `IterableX` or `AsyncIterableX` prototypes, use side-effect imports from `ix/add/...`. These are global modifications and should be used with caution, typically for bundling scenarios where tree-shaking isn't as effective.

Quickstart

Demonstrates creating a synchronous `Iterable` from a generator function and transforming it using pipeable `filter` and `map` operators, then iterating through the results.

import { from } from 'ix/iterable';
import { filter, map } from 'ix/iterable/operators';

// A synchronous generator function
function* numberGenerator() {
  yield 1;
  yield 2;
  yield 3;
  yield 4;
  yield 5;
  yield 6;
}

// Create an Iterable from the generator and apply pipeable operators
const results = from(numberGenerator()).pipe(
  filter(x => x % 2 === 0), // Keep only even numbers
  map(x => x * 10)         // Multiply by 10
);

console.log('Synchronous Iterable results:');
for (const item of results) {
  console.log(`Next: ${item}`);
}

// To demonstrate AsyncIterable, imagine an async data source
// import { from as asyncFrom } from 'ix/asynciterable';
// import { filter as asyncFilter, map as asyncMap } from 'ix/asynciterable/operators';

// async function* asyncNumberGenerator() {
//   for (let i = 1; i <= 6; i++) {
//     await new Promise(resolve => setTimeout(resolve, 50));
//     yield i;
//   }
// }

// async function runAsyncExample() {
//   const asyncResults = asyncFrom(asyncNumberGenerator()).pipe(
//     asyncFilter(x => x % 2 !== 0), // Keep only odd numbers
//     asyncMap(x => x + 100)       // Add 100
//   );

//   console.log('\nAsynchronous Iterable results:');
//   for await (const item of asyncResults) {
//     console.log(`Next Async: ${item}`);
//   }
// }

// runAsyncExample();