Map

Creates a transform stream which maps each streamed value to another value.

Installation

$ npm install flow-map

For use in the browser, use browserify.

Usage

var stream = require( 'flow-map' );

stream( [options,] fcn )

Creates a transform stream which maps each streamed value to another value using a provided function.

var mStream = stream( map );

// Note: the index is zero-based...
function map( value, idx ) {
	value = parseFloat( value );
	return (value * idx).toString();
}

// Pipe the output from the map stream to stdout:
mStream.pipe( process.stdout );

// Write data to the stream:
mStream.write( '5' );
// => 0

mStream.write( '4' );
// => 4

mStream.write( '10' );
// => 20

// End the stream:
mStream.end();

The function accepts the following options:

• highWaterMark: specifies the Buffer level at which write() calls start returning false. Default: 16 (i.e., 16 queued items).
• allowHalfOpen: specifies whether a stream should remain open even if one side ends. Default: false.

To set stream options,

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

var mStream = stream( map, opts );

Note: the returned stream always operates in objectMode.

stream.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 = {
	'highWaterMark': 64	
};

var factory = stream.factory( opts );

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

stream.objectMode( [options,] fcn )

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

var data = {
	'value': 5
};

function map( data, idx ) {
	return data.value * 10;
}

var mStream = stream.objectMode( map );
mStream.pipe( process.stdout );

mStream.write( data );
// => 50

mStream.end();

Note: this method behaves the same as the main method and is provided to maintain API consistency with other flow modules.

Examples

var createStream = require( 'flow-map' );

function map( value, idx ) {
	return value * idx;
}

function toString( value ) {
	return value.toString() + '\n';
}

var mStream = createStream( map ),
	tsStream = createStream( toString );

mStream
	.pipe( tsStream )
	.pipe( process.stdout );

for ( var i = 0; i < 1000; i++ ) {
	mStream.write( Math.random() );
}
mStream.end();

To run the example code from the top-level application directory,

$ DEBUG=* node ./examples/index.js

CLI

Installation

To use the module as a general utility, install the module globally

$ npm install -g flow-map

Usage

Usage: flow-map [options] module

Options:

  -h,   --help                 Print this message.
  -V,   --version              Print the package version.
        --split sep            Separator used to split incoming data. Default: '/\\r?\\n/'.
        --join sep             Separator used to join outgoing data. Default: '\n'.
  -hwm, --highwatermark hwm    Specify how much data can be buffered into memory
                               before applying back pressure. Default: 16.
  -aho, --allowhalfopen        Keep the stream open if either the readable or writable
                               side ends. Default: false.

The flow-map command is available as a standard stream.

$ <stdout> | flow-map <module> | <stdin>

Notes

• If the split separator is a regular expression, ensure that the split option is properly escaped.

  # Not escaped...
  $ <stdout> | flow-map <module> --split '/\r?\n/'
  	
  # Escaped...
  $ <stdout> | flow-map <module> --split '/\\r?\\n/'

Examples

$ echo -n $'1\n2\n3\n4\n' | flow-map ./examples/script.js
# => 0
# => 2
# => 6
# => 12

For local installations, modify the above command to point to the local installation directory; e.g.,

$ echo -n $'1\n2\n3\n4\n' | ./node_modules/.bin/flow-map ./examples/script.js

Or, if you have cloned this repository and run npm install, modify the command to point to the executable; e.g.,

$ echo -n $'1\n2\n3\n4\n' | node ./bin/cli ./examples/script.js

Tests

Unit

Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ make view-cov

License

MIT license.

Copyright

Copyright © 2014-2015. The Flow.io Authors.