Split

Creates a transform stream which splits streamed data.

Installation

$ npm install flow-split

Usage

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

stream( [options] )

Creates a transform stream which splits streamed data.

var tStream = stream();

tStream.pipe( process.stdout );
tStream.write( '1\n2\n3' );
// => 1 => 2 => 3

tStream.end();

The function accepts the following options:

sep: separator used to split streamed data. Similar to String#split, a separator may be either a regular expression or a string. Default: /\r?\n/.
objectMode: boolean which specifies whether a stream should operate in object mode. Default: false.
encoding: specifies how Buffer objects should be decoded to strings. Default: null.
highWaterMark: specifies the Buffer level at which write() calls start returning false. Default: 16 (16kb).
allowHalfOpen: specifies whether a stream should remain open even if one side ends. Default: false.
writableObjectMode: specifies whether the writable side should be in object mode. Default: false.

To set stream options,

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

var tStream = stream( opts );

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 = {
	'sep': '\t',
	'objectMode': true,
	'encoding': 'utf8',
	'highWaterMark': 64	
};

var factory = stream.factory( opts );

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

stream.objectMode( [options] )

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 tStream = stream.objectMode({
	'sep': ','
});

tStream.pipe( process.stdout );
tStream.write( 'a,b,c' );
// => a => b => c

tStream.end();

Notes

Similar to String#split, a separator which is a regular expression containing a matching group will result in the separator being retained in the output stream.

var tStream = stream({
	'sep': /(,)/
});

tStream.pipe( process.stdout );
tStream.write( '1,2,3' );
// => 1 => , => 2 => , => 3

tStream.end();

Examples

var through2 = require( 'through2' ),
	stream = require( 'flow-split' );

// Create a stream to make newline delimited data...
var newlines = through2( function onData( chunk, enc, clbk ) {
	this.push( chunk.toString() + '\n' );
	clbk();
});

// Create a new split stream:
var tStream = stream({
	'sep': /\t/
});

// Create a stream pipeline:
tStream
	.pipe( newlines )
	.pipe( process.stdout );

// Write values to the stream...
for ( var i = 0; i < 10; i++ ) {
	tStream.write( i+'\t', 'utf8'  );
}
tStream.end();

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

$ node ./examples/index.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.

flow-io/split