streamfilter

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 you project:

npm install --save streamfilter

Getting started

There are 3 scenarios of use :

Simple filter

var FilterStream = require('streamfilter');

var filter = new FilterStream(function(chunk, encoding, cb) {
  if(itmustbefiltered) {
    cb(true);
  } else {
    cb(false);
  }
});

// Print to stdout a filtered stdin
process.stdin
  .pipe(filter)
  .pipe(process.stdout);

Filter and restore

var FilterStream = require('streamfilter');

var filter = new FilterStream(function(chunk, encoding, cb) {
    if(itmustbefiltered) {
      cb(true);
    } else {
      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 be hype!

var FilterStream = require('streamfilter');

// Filter values
var filter = new FilterStream(function(chunk, encoding, cb) {
    if(itmustbefiltered) {
      cb(true);
    } else {
      cb(false);
    }
}, {
  restore: true,
  passthrough: true
});

// 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:Stream FilterStream(filterCallback:Function, options:Object)

Filter piped in streams according to the given filterCallback that takes the following arguments: chunk the actual chunk, encoding the chunk encoding, filterResultCallback the function to call as the result of the filtering process with true in 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.

options.restore

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.

options.passthrough

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.

Contribute

Feel free to submit us your improvements. To do so, you must accept to publish your code under the MIT license.

To start contributing, first run the following to setup the development environment:

git clone git@github.com:nfroidure/streamfilter.git
cd streamfilter
npm install

Then, run the tests:

npm test

Stats