Inspect Stream

Transform stream for inspecting streamed data.

Usage

var inspectStream = require( '@stdlib/streams/utils/inspect' );

inspectStream( [options,] clbk )

Creates a transform stream for inspecting streamed data.

function log( chunk, idx ) {
    console.log( 'index: %d', idx );
    console.log( chunk );
}

var stream = inspectStream( log );

stream.write( 'a' );
stream.write( 'b' );
stream.write( 'c' );

stream.end();
/* =>
'index: 0'
'a'
'index: 1'
'b'
'index: 2'
'c'
*/

The function accepts the following options:

  • objectMode: specifies whether a stream should operate in objectMode. Default: false.
  • highWaterMark: specifies the Buffer level at which write() calls start returning false.
  • allowHalfOpen: specifies whether a stream should remain open even if one side ends. Default: false.
  • readableObjectMode: specifies whether the readable side should be in objectMode. Default: false.

To set stream options,

function log( chunk, idx ) {
    console.log( 'index: %d', idx );
    console.log( chunk );
}

var opts = {
    'objectMode': true,
    'highWaterMark': 64,
    'allowHalfOpen': true,
    'readableObjectMode': false // overridden by `objectMode` option when `objectMode=true`
};

var stream = inspectStream( opts, log );

inspectStream.factory( [options] )

Creates a reusable stream factory. The factory method ensures streams are configured identically by using the same set of provided options.

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

var factory = inspectStream.factory( opts );

This method accepts all documented options.

factory( clbk )

Creates a transform stream for inspecting streamed data.

function log( chunk, idx ) {
    console.log( 'index: %d', idx );
    console.log( chunk );
}

var factory = inspectStream.factory();

// Create 10 identically configured streams...
var streams = [];
var i;
for ( i = 0; i < 10; i++ ) {
    streams.push( factory( log ) );
}

inspectStream.objectMode( [options,] clbk )

This method is a convenience function to create streams which always operate in objectMode. The method will always override the objectMode option in options.

function log( chunk, idx ) {
    console.log( 'index: %d', idx );
    console.log( chunk );
}

var stream = inspectStream.objectMode( log );

stream.write( { 'value': 'a' } );
stream.write( { 'value': 'b' } );
stream.write( { 'value': 'c' } );

stream.end();
/* =>
'index: 0'
{'value': 'a'}
'index: 1'
{'value': 'b'}
'index: 2'
{'value': 'c'}
*/

This method accepts all documented options.

Examples

var stdout = require( '@stdlib/streams/base/stdout' );
var transformFactory = require( '@stdlib/streams/utils/transform' ).factory;
var inspect = require( '@stdlib/streams/utils/inspect' ).objectMode;

function parse( chunk, enc, clbk ) {
    clbk( null, JSON.parse( chunk ) );
}

function pluck( chunk, enc, clbk ) {
    clbk( null, chunk.value );
}

function square( chunk, enc, clbk ) {
    var v = +chunk;
    clbk( null, v*v );
}

function toStr( chunk, enc, clbk ) {
    clbk( null, chunk.toString() );
}

function join( chunk, enc, clbk ) {
    clbk( null, chunk+'\n' );
}

function logger( name ) {
    return log;

    function log( chunk, idx ) {
        console.log( 'name: %s', name );
        console.log( 'index: %d', idx );
        console.log( chunk );
    }
}

// Create a factory for generating streams running in `objectMode`:
var tStream = transformFactory({
    'objectMode': true
});

// Create streams for each transform:
var s1 = tStream( parse );
var i1 = inspect( logger( 'parse' ) );
var s2 = tStream( pluck );
var i2 = inspect( logger( 'pluck' ) );
var s3 = tStream( square );
var i3 = inspect( logger( 'square' ) );
var s4 = tStream( toStr );
var i4 = inspect( logger( 'toString' ) );
var s5 = tStream( join );
var i5 = inspect( logger( 'join' ) );

// Create the pipeline:
s1.pipe( i1 )
    .pipe( s2 )
    .pipe( i2 )
    .pipe( s3 )
    .pipe( i3 )
    .pipe( s4 )
    .pipe( i4 )
    .pipe( s5 )
    .pipe( i5 )
    .pipe( stdout );

// Write data to the pipeline...
var v;
var i;
for ( i = 0; i < 100; i++ ) {
    v = '{"value":'+i+'}';
    s1.write( v, 'utf8' );
}
s1.end();