async-iterators
Useful abstractions and utility functions for async iterators in Node.js.
An async iterator is an object with a next(cb)
method.
Invoking the method should return the next item of an underlying data source.
The callback should be a function of type function(err, value)
.
If the iterator has no more data to read, it will call the callback with value == undefined
.
Async iterators can easily be created from Node.js Readable Streams by using stream-iterator.
An example with a pointless iterator that asynchronously returns the numbers from 1 to 100:
var iterators ={var i = 0return{i++if i == 100 return}}var myIterator =// wrap myIterator with a map iterator that doubles all resultsvar doublingIterator = iterators// pipe the iterator to an arrayiterators
Documentation
Iterator Sources
Transforming Iterators
Iterator Targets
Utilities
Iterator Sources ### fromArray(array) Creates an iterator from an array.
### fromReadableStream(readableStream) Creates an iterator from a [Readable Stream](http://nodejs.org/api/stream.html#stream_class_stream_readable).var arrayIterator = iterators
var readStream = fsvar streamIterator = iterators
Transforming Iterators ### map(iterator, mapFn) Create an iterator that applies a map function to transform each value of the source iterator.
### mapAsync(iterator, mapFn)var mapIterator = iterators// pipe the iterator to an array:iterators
Create an iterator that filters the values of the source iterator using a filter function.var mapIterator = iterators
filter(iterator, filterFn)
### filterAsync(iterator, filterFn)var evenNumbersIterator = iterators
### range(iterator, range) Creates an iterator that only iteratores over the specified range.var evenNumbersIterator = iterators
range
is specified as {from: startIndex, to: endIndex}
where from
and to
are both inclusive.
### buffer(iterator, bufferSize) Creates an iterator with an internal buffer that is always filled until `bufferSize`. The buffer can abviously only grow if the buffer iterator is read slower than the underlying iterator source can return data.var rangeIterator = iterators
The current buffer fill ratio can be inspected at any time using bufferFillRatio()
which returns a number between 0..1.
The buffer size can be changed using setBufferSize(bufferSize)
.
var bufferedIterator = iterators// inspect buffer sizeconsole// change the buffer size laterbufferedIterator
Iterator Targets ### toArray(iterator, cb) Reads the source iterator and writes the results to an array.
### toWritableStream(iterator, writeStream, encoding, cb) Reads the source iterator and writes the result to a [Writable Stream](http://nodejs.org/api/stream.html#stream_class_stream_writable).iterators
var writeStream = fsiterators
Utilities ### forEach(iterator, fn, cb) Reads the source iterator and invokes `fn` for each value of the iterator.
### forEachAsync(iterator, fn, cb) Reads the source iterator and invokes `fn` for each value of the iterator. Only once the callback is invoked the next value is read from the source iterator.iterators
iterators
Other libraries
Some libraries using the async iterator pattern:
- stream-iterator - wrap any stream into an async iterator
- node-leveldown - allows you to iterate over entries in LevelDB
Contributors
This project was created by Mirko Kiefer (@mirkokiefer).