Transform stream which maps each streamed value to another value.
npm install flow-mapMap
===
[![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Coverage][codecov-image]][codecov-url] [![Dependencies][dependencies-image]][dependencies-url]
> Creates a transform stream which maps each streamed value to another value.
`` bash`
$ npm install flow-map
For use in the browser, use browserify.
` javascript`
var stream = require( 'flow-map' );
#### stream( [options,] fcn )
Creates a transform stream which maps each streamed value to another value using a provided function.
` javascript
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).false
* __allowHalfOpen__: specifies whether a stream should remain open even if one side ends. Default: .
To set stream options,
` javascript
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.
` javascript
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.
` javascript
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.
` javascript
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,
` bash`
$ DEBUG=* node ./examples/index.js
---
To use the module as a general utility, install the module globally
` bash`
$ npm install -g flow-map
` bash
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.
` bash`
$
* If the split separator is a regular expression, ensure that the split option is properly __escaped__.
` bash`
# Not escaped...
$
# Escaped...
$
` bash`
$ 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.,
` bash`
$ 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.,
` bash`
$ echo -n $'1\n2\n3\n4\n' | node ./bin/cli ./examples/script.js
---
Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:
` bash`
$ make test
All new feature development should have corresponding unit tests to validate correct functionality.
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:
` bash`
$ make test-cov
Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,
` bash``
$ make view-cov
---
Copyright © 2014-2015. The Flow.io Authors.
[npm-image]: http://img.shields.io/npm/v/flow-map.svg
[npm-url]: https://npmjs.org/package/flow-map
[travis-image]: http://img.shields.io/travis/flow-io/map/master.svg
[travis-url]: https://travis-ci.org/flow-io/map
[codecov-image]: https://img.shields.io/codecov/c/github/flow-io/map/master.svg
[codecov-url]: https://codecov.io/github/flow-io/map?branch=master
[dependencies-image]: http://img.shields.io/david/flow-io/map.svg
[dependencies-url]: https://david-dm.org/flow-io/map
[dev-dependencies-image]: http://img.shields.io/david/dev/flow-io/map.svg
[dev-dependencies-url]: https://david-dm.org/dev/flow-io/map
[github-issues-image]: http://img.shields.io/github/issues/flow-io/map.svg
[github-issues-url]: https://github.com/flow-io/map/issues