Combine-async-iterators

Combine Multiple Asynchronous Iterators in one (not a sequence). It use Promise.race under the hood (the code idea is from Targos).

[!IMPORTANT] This package was mainly built to work with native Asynchronous Generators (Iterators).

Requirements

• Node.js version 20 or higher

Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ npm i combine-async-iterators
# or
$ yarn add combine-async-iterators

Usage example

const timers = require("node:times/promises");
const combineAsyncIterators = require("combine-async-iterators");

async function* getValues(id) {
    for (let count = 0; count < 5; count++) {
        await timers.setTimeout(Math.ceil(Math.random() * 1000));
        yield `${id}_${count}`;
    }
}

async function main() {
    const asyncIterator = combineAsyncIterators({}, getValues("first"), getValues("second"));
    for await (const value of asyncIterator) {
        console.log(value);
    }
}
main().catch(console.error);

Since 2.0.0 it is also possible to recover errors through a callback. By default the method is stopped when an error is thrown (the throwError parameter allow to disable this behaviour).

function errorCallback(err) {
    console.error("got you:", err);
}

const iteratorOptions = { errorCallback, throwError: false };
const asyncIterator = combineAsyncIterators(
  iteratorOptions,
  getValues("first"),
  getValues("second")
);
for await (const value of asyncIterator) {
    console.log(value);
}

API

declare function combineAsyncIterators(
    ...iterators: AsyncIterableIterator<any>[]
): AsyncIterableIterator<any>;

declare namespace combineAsyncIterators {
    interface CombineOptions {
        throwError?: boolean;
        errorCallback?: (err: Error, index: number) => any;
    }
}

declare function combineAsyncIterators(
    options: combineAsyncIterators.CombineOptions,
    ...iterators: AsyncIterableIterator<any>[]
): AsyncIterableIterator<any>;

export = combineAsyncIterators;

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Licence

MIT