and asynchronous iterators in a reactive, stream-like way. By using the
iterator interfaces as a common ground,
icw allows you to use common
stream-like idioms with any data structure that implements
Symbol.asyncIterator, including built-ins like strings and Arrays, as well
as libraries like
icw pairs especially well with Node.js v10's implementation of
ReadableStream, which has experimental support for the
AsyncIterator interface was added in ECMAScript 2018, so this library
build to support older runtimes.
The library is tested against Node.js >=10, but see the node.green compatibility table for more details on support for asynchronous iterators in Node.js.
For a list of browsers that should support this, see Kangax's ECMAScript 2016+ compatibility table.
npm install --save @icw/icw
yarn add @icw/icw
Design Goals & Philosophy
icw aims to be as idiomatic as possible, in the sense that the API should
example, all functions are iterable-first, and functions that accept
callbacks – e.g.
filter – should generally have an
optional final argument that allows users to set the
this context for the
Performance, in terms of operations per second, is not currently a priority for this project. In the words of Johnson & Kernighan (1983), 'the strategy is definitely: first make it work, then make it right, and, finally, make it fast.'
icw is asynchronous at its core, it will never approach
the peformance of a bare
Array#forEach, or any library that
focuses exclusively on synchronous iteration.
In general, if your project involves a lot of async workflows, the high-level
icw may be worth the trade-off in performance. If your only
iterating over synchronous iterators, however, you would probably be better
off using a library like
That's not to say you can't use
icw for heavily synchronous workloads.
But if you care about Maximum Performance
What's in a name?
The Intracoastal Waterway (ICW) is a 3,000-mile (4,800 km) inland waterway along the Atlantic and Gulf of Mexico coasts of the United States […] It provides a navigable route along its length without many of the hazards of travel on the open sea. ― Wikipedia
- Async iterators and generators by Jake Archibald
- ES2018: Asynchronous iteration by Dr Axel Rauschmayer
- Async Iterators: These Promises Are Killing My Performance by Dan Vanderkam