README
streamfilter
Filtering streams.
streamfilter
is a function based filter for streams inspired per gulp-filter
but no limited to Gulp nor to objectMode streams.
Installation
First, install streamfilter
in your project:
npm install --save streamfilter
Getting started
There are 3 common usages:
Simple filter
import FilterStream from 'streamfilter';
const filter = new FilterStream((chunk, encoding, cb) => {
const mustBeFiltered = chunk.length() > 128;
if(mustBeFiltered) {
cb(true);
return;
}
cb(false);
});
// Print to stdout a filtered stdin
process.stdin
.pipe(filter)
.pipe(process.stdout);
Filter and restore
import FilterStream from 'streamfilter';
const filter = new FilterStream((chunk, encoding, cb) => {
const mustBeFiltered = chunk.length() > 128;
if(mustBeFiltered) {
cb(true);
return;
}
cb(false);
}, {
restore: true
});
// Print accepted chunks in stdout
filter.pipe(process.stdout);
// Print filtered one to stderr
filter.restore.pipe(process.stderr);
Filter and restore as a passthrough stream
Let's reach total hype!
import FilterStream from 'streamfilter';
import { Transform } from 'stream';
// Filter values
const filter = new FilterStream((chunk, encoding, cb) => {
const mustBeFiltered = chunk.length() > 128;
if(mustBeFiltered) {
cb(true);
return;
}
cb(false);
}, {
restore: true,
passthrough: true
});
// Uppercase strings
const mySuperTransformStream = new Transform({
transform: (chunk, encoding, cb) => cb(
null,
Buffer.from(
chunk.toString(encoding).toUpperCase(),
encoding,
),
),
});
// Pipe stdin
process.stdin.pipe(filter)
// Edit kept chunks
.pipe(mySuperTransformStream)
// Restore filtered chunks
.pipe(filter.restore)
// and output!
.pipe(process.stdout)
Note that in this case, this is your responsibility to end the restore stream by piping in another stream or ending him manually.
API
Stream
StreamFilter(filterCallback, options) ⇒ Filter piped in streams according to the given filterCallback
that takes the
following arguments: chunk
the actual chunk, encoding
the chunk encoding,
filterResultCallbackthe function to call as the result of the filtering process with
truein argument to filter her or
false` otherwise.
Options are passed in as is in the various stream instances spawned by this
module. So, to use the objectMode, simply pass in the options.objectMode
value set to true
.
Kind: global function
Returns: Stream
- The filtering stream
Param | Type | Description |
---|---|---|
filterCallback | function |
Callback applying the filters |
options | Object |
Filtering options |
options.passthrough | boolean |
Set to true , this option change the restore stream nature from a readable stream to a passthrough one, allowing you to reuse the filtered chunks in an existing pipeline. |
options.restore | boolean |
Set to true , this option create a readable stream allowing you to use the filtered chunks elsewhere. The restore stream is exposed in the FilterStream instance as a restore named property. |