pass-stream
v1.0.0
Published
pass-through stream which can filter/adapt and pause data as it passes through (streams2)
Downloads
41,308
Maintainers
Readme
pass-stream - pass-through node.js stream which can filter/adapt and pause data
pass-stream is a pass-through stream which allows transform fns for easily filtering or adapting the data that flows through the stream.
It is a light wrapper over the new (streams2) readable-stream functionality which is available as add in for node 0.8 and is built-in for node 0.10+
Installation
npm install pass-stream
Usage
passStream(writeFn, endFn, options)
optional writeFn, endFn, and options. Returns a pauseable stream which can be piped or used like any other. Options are the same as for standard streams (for instance set objectMode = true to allow arbitrary non-null objects to be used.
var passStream = require('pass-stream');
var ps = passStream(); // constructing stream without any transformations
readStream
.pipe(ps)
.pipe(anotherStream)
To add transform/filter functionality you may provide a writeFn and/or endFn which allows you to tap into the write and end processing.
If you provide a writeFn, then it is up to you to call this.push(data)
with whatever transformed data and call the cb. The writeFn has signature writeFn(chunk, encoding, cb)
If you provide an endFn, then it will be be fired after all the data has been read but before the end
event has been fired. You may do additional this.push(data)
and then call the cb when done. hooked up as a listener for on('end')
. The endFn has signature endFn(cb)
.
The cb
functions provided in writeFn and endFn can call the callback with an error if they wish to signal an error to the stream, ex: cb(new Error('bad...'))
The this
context of the writeFn and endFn is set to that of the stream so you have all the normal stream functions like emit
, pause
, and resume
. Note: you will not want to call write
or end
from within these functions since they will cause a recursive loop.
var passStream = require('pass-stream');
var length = 0;
function writeFn(data, encoding, cb) { // we are assuming data is strings
this.push(data.toUpperCase()); // upper case
length += data.length; // keep track of length
cb();
}
function endFn(cb) {
this.emit('length', length); // emit length now that it is done
cb();
}
var lengthResult = 0;
var options = {};
var rstream = new Stream();
rstream
.pipe(passStream(writeFn, endFn, options)) // construct a passStream with transformFns
.on('length', function (len) { lengthResult = len; })
.pipe(anotherStream);
Goals
- Easily use new streams2 functionality (readable-streams) with node 0.8 or 0.10+
- Built-in buffering pause capability (from streams2)
- Easy to use transformation filters with the stream
- Act as the base to build other specific pass through streams with
- Tested
- Allows any datatype (except null or undefined) to be used in the stream (String, Buffer, Number, Boolean, Array, Object)
Why
While node 0.8 is still needed, this creates easy wrapper to allow for the transition to node 0.10
Get involved
If you have input or ideas or would like to get involved, you may:
- contact me via twitter @jeffbski - http://twitter.com/jeffbski
- open an issue on github to begin a discussion - https://github.com/jeffbski/pass-stream/issues
- fork the repo and send a pull request (ideally with tests) - https://github.com/jeffbski/pass-stream