time-to-botec/squiggle/node_modules/@stdlib/streams/node/from-array/README.md

Array Stream

Create a readable stream from an array-like object.

Usage

var arrayStream = require( '@stdlib/streams/node/from-array' );

arrayStream( src[, options] )

Returns a readable stream from an array-like object.

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

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

var stream = arrayStream( [ 1, 2, 3, 4 ] );
var 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 streaming.
• 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.
• dir: iteration direction. If set to -1, the stream iterates over elements from right-to-left. Default: 1.

To set stream options,

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

var stream = arrayStream( [ 1, 2, 3, 4 ], opts );

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

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

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

var stream = arrayStream( [ 1, 2, 3, 4 ], {
    'sep': ','
});

var iStream = inspectStream( log );

stream.pipe( iStream );

By default, when not operating in objectMode, a returned stream serializes 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' );

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

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

var stream = arrayStream( [ 1, 2, 3, 4 ], {
    'serialize': serialize
});

var iStream = inspectStream( log );

stream.pipe( iStream );

---

arrayStream.factory( [options] )

Returns a function for creating readable streams from array-like objects.

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

var createStream = arrayStream.factory( opts );

var stream1 = createStream( [ 1, 2, 3, 4 ] );
var stream2 = createStream( [ 5, 6, 7, 8 ] );
// ...

The method accepts the same options as arrayStream().

---

arrayStream.objectMode( src[, options] )

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

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

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

var stream = arrayStream.objectMode( [ 1, 2, 3, 4 ] );

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

stream.pipe( iStream );

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

---

Notes

• In objectMode, null is a reserved value. If an array contains null values (e.g., as a means to encode missing values), the stream will prematurely end. Consider an alternative encoding or filter null values prior to invocation.
• In binary mode, if an array contains undefined values, the stream will emit an error. Consider providing a custom serialization function or filtering undefined values prior to invocation.

---

Examples

var inspectStream = require( '@stdlib/streams/node/inspect-sink' );
var randu = require( '@stdlib/random/base/randu' );
var Float64Array = require( '@stdlib/array/float64' );
var arrayStream = require( '@stdlib/streams/node/from-array' );

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

// Create an array containing uniformly distributed pseudorandom numbers:
var arr = new Float64Array( 10 );

var i;
for ( i = 0; i < arr.length; i++ ) {
    arr[ i ] = randu();
}

// Convert the array to a stream:
var opts = {
    'objectMode': true
};
var stream = arrayStream( arr, opts );

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

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