Iterator Stream

Create a readable stream from an iterator.

Usage

var iteratorStream = require( '@stdlib/streams/node/from-iterator' );

iteratorStream( iterator[, options] )

Returns a readable stream from an iterator.

var inspectStream = require( '@stdlib/streams/node/inspect-sink' );
var randu = require( '@stdlib/random/iter/randu' );

var iStream;
var stream;

function log( chunk, idx ) {
    console.log( chunk.toString() );
    if ( idx === 10 ) {
        stream.destroy();
    }
}

stream = iteratorStream( randu() );
iStream = inspectStream( log );

stream.pipe( iStream );

The function accepts the following options:

objectMode: specifies whether a stream should operate in objectMode. Default: false.
encoding: specifies how Buffer objects should be decoded to strings. Default: null.
highWaterMark: specifies the maximum number of bytes to store in an internal buffer before pausing iteration.
sep: separator used to join streamed data. This option is only applicable when a stream is not in objectMode. Default: '\n'.
serialize: custom serialization function. This option is only applicable when a stream is not in objectMode.

To set stream options,

var randu = require( '@stdlib/random/iter/randu' );

var opts = {
    'objectMode': true,
    'encoding': 'utf8',
    'highWaterMark': 64
};

var stream = iteratorStream( randu(), opts );

By default, when not operating in objectMode, a returned stream delineates iterated values using a newline character. To specify an alternative separator, set the sep option.

var inspectStream = require( '@stdlib/streams/node/inspect-sink' );
var randu = require( '@stdlib/random/iter/randu' );

function log( chunk ) {
    console.log( chunk.toString() );
}

var it = randu({
    'iter': 10
});

var stream = iteratorStream( it, {
    'sep': ','
});

var iStream = inspectStream( log );

stream.pipe( iStream );

By default, when not operating in objectMode, a returned stream serializes iterated values as JSON strings. To specify custom serialization behavior (either to a string or Buffer), set the serialize option.

var inspectStream = require( '@stdlib/streams/node/inspect-sink' );
var randu = require( '@stdlib/random/iter/randu' );

function serialize( v ) {
    return 'r::' + v.toString();
}

function log( chunk ) {
    console.log( chunk.toString() );
}

var it = randu({
    'iter': 10
});

var stream = iteratorStream( it, {
    'serialize': serialize
});

var iStream = inspectStream( log );

stream.pipe( iStream );

iteratorStream.factory( [options] )

Returns a function for creating readable streams from iterators.

var randu = require( '@stdlib/random/iter/randu' );

var opts = {
    'objectMode': true,
    'encoding': 'utf8',
    'highWaterMark': 64
};

var createStream = iteratorStream.factory( opts );

var stream1 = createStream( randu() );
var stream2 = createStream( randu() );
// ...

The method accepts the same options as iteratorStream().

iteratorStream.objectMode( iterator[, options] )

This method is a convenience function to create streams which always operate in objectMode.

var inspectStream = require( '@stdlib/streams/node/inspect-sink' );
var randu = require( '@stdlib/random/iter/randu' );

function log( v ) {
    console.log( v );
}

var opts = {
    'iter': 10
};
var stream = iteratorStream.objectMode( randu( opts ) );

opts = {
    'objectMode': true
};
var iStream = inspectStream( opts, log );

stream.pipe( iStream );

This method accepts the same options as iteratorStream(); however, the method will always override the objectMode option in options.

Notes

In objectMode, null is a reserved value. If an iterator generates null values (e.g., as a means to encode missing values), the stream will prematurely end. Consider an alternative encoding or explicitly map null values to a different value by wrapping the provided iterator with another iterator.
In binary mode, if an iterator generates undefined values, the stream will emit an error. Consider providing a custom serialization function or explicitly map undefined values to a different value by wrapping the provided iterator with another iterator.

Examples

var inspectStream = require( '@stdlib/streams/node/inspect-sink' );
var randu = require( '@stdlib/random/iter/randu' );
var iteratorStream = require( '@stdlib/streams/node/from-iterator' );

function log( v ) {
    console.log( v.toString() );
}

// Create an iterator which generates uniformly distributed pseudorandom numbers:
var opts = {
    'iter': 10
};
var it = randu( opts );

// Convert the iterator to a stream:
opts = {
    'objectMode': true
};
var stream = iteratorStream( it, opts );

// Create a writable stream for inspecting stream data:
opts = {
    'objectMode': true
};
var iStream = inspectStream( opts, log );

// Begin data flow:
stream.pipe( iStream );