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

StreamFilter(filterCallback, options) ⇒ Stream

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 withtruein argument to filter her orfalse` 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.

Authors

• Nicolas Froidure

License

MIT