append

Transform stream which appends to each data string.

Installation

$ npm install flow-append

For use in the browser, use browserify.

Usage

To use the module,

var append = require( 'flow-append' );

append( value[, options] )

Returns a transform stream in which a value is appended to each streamed chunk.

To create a stream,

var stream = append( '\n' );

The default options are as follows:

• highWaterMark=16
• encoding=null
• allowHalfOpen=true
• objectMode=false
• decodeStrings=true

To set the options when creating a stream,

var opts = {
		'encoding': 'utf8',
		'highWaterMark': 8,
		'allowHalfOpen': false,
		'objectMode': true,
		'decodeStrings': false
	};

stream = append( '\n', opts );

append.factory( [options] )

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

var opts = {
		'encoding': 'utf8',
		'highWaterMark': 8,
		'allowHalfOpen': false,
		'objectMode': true,
		'decodeStrings': false
	};

var factory = append.factory( opts );

var streams = new Array( 10 );

// Create many streams configured identically but may each be independently written to...
for ( var i = 0; i < streams.length; i++ ) {
	streams[ i ] = factory();
}

append.objectMode( [options] )

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

var fromArray, append;

fromArray = require( 'flow-from-array' ).objectMode;
append = require( 'flow-append' ).objectMode;

fromArray( ['1','2','3','4'] )
	.pipe( append( '\n' ) )
	.pipe( process.stdout );

Examples

var fromArray = require( 'flow-from-array' ),
	append = require( 'flow-append' ).objectMode;

// Create some data...
var data = new Array( 1000 );
for ( var i = 0; i < data.length; i++ ) {
	data[ i ] = Math.random();
}

// Create a readable stream:
var readableStream = fromArray( data );

// Pipe the data:
readableStream
	.pipe( append( '\n' ) )
	.pipe( process.stdout );

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

$ node ./examples/index.js

Notes

This stream is best used with binary or object streams where each datum is a character string. Internally, each datum is coerced to a string and the value appended. Such behavior may have undesired side-effects when used with non-string data. For example,

var obj = {
	'beep': 'boop'	
};

console.log( obj.toString() );
// returns '[object Object]'

var arr = [1,2,3,4];

console.log( arr.toString() );
// returns '1,2,3,4'

If you want to append values to an array, you are probably best using some other means.

If the value undefined is written to the stream, the stream emits an error event and closes.

The primary use case is in delineating successive values; e.g., separating each value with a newline character or a comma. Undoubtedly, this stream can be used for other ends, but note that no guarantees can be made concerning behavior, as in the examples above.

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,

$ open reports/coverage/lcov-report/index.html

License

MIT license.

Copyright

Copyright © 2014. Athan Reines.