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 { StreamFilter } from 'streamfilter';

const filter = new StreamFilter((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';

// Here we use the functionnal help
const filter = new filterStream(
  // Here we use an async callback instead
  async (chunk, encoding) => {
    const mustBeFiltered = chunk.length() > 128;

    if (mustBeFiltered) {
      return true;
    }
    return 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 { StreamFilter } from 'streamfilter';
import { Transform } from 'stream';

// Filter values
const filter = new StreamFilter(
  (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 it manually.

API

Classes

Functions

StreamFilter

Filter piped in streams according to the given filterCallback.

Kind: global class

new StreamFilter(filterCallback, options)

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.

Returns: StreamFilter - The filtering stream

| Param | Type | Description | | --- | --- | --- | | filterCallback | function | Callback applying the filters | | options | Object | Filtering options | | options.passthrough | boolean | Set to true, this option changes 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. |

filterStream(filterCallback, options) ⇒

Utility function if you prefer a functional way of using this lib

Kind: global function
Returns: Stream

| Param | | --- | | filterCallback | | options |

Authors

• Nicolas Froidure

License

MIT