through

What is through?

The 'through' npm package is a simple wrapper around Node.js streams.Transform to create readable/writable streams easily using simple functions for the 'write' and 'end' parts of a stream. It is often used to transform or manipulate data in a stream.

What are through's main functionalities?

Stream Transformation

This code sample demonstrates how to create a simple stream transformation that converts all incoming data to uppercase. The 'write' function is called for every chunk of data, and 'end' is called when there is no more data.

var through = require('through');
var tr = through(function write(data) {
  this.queue(data.toString().toUpperCase());
}, function end() { // optional
  this.queue(null);
});
process.stdin.pipe(tr).pipe(process.stdout);

Stream Filtering

This code sample shows how to filter the stream to only pass through data chunks longer than 10 characters. It uses the 'write' function to decide whether to pass the data along or not.

var through = require('through');
var tr = through(function write(data) {
  if (data.length > 10) {
    this.queue(data);
  }
});
process.stdin.pipe(tr).pipe(process.stdout);

Other packages similar to through

through2

through2 is a tiny wrapper around Node.js streams.Transform that makes it easier to implement a transform stream. It is similar to 'through' but with a more modern API and additional features like object mode and flush function support.

stream-combiner

stream-combiner allows you to create a pipeline of streams that gets combined into a single stream. It is similar to 'through' in that it deals with stream transformation, but it focuses on combining multiple streams into one.

pumpify

pumpify combines an array of streams into a single duplex stream using pump and duplexify. It is similar to 'through' in that it can be used to transform data in streams, but it also handles the stream lifecycle and cleanup.

README

#through

Easy way to create a Stream that is both readable and writable.

• Pass in optional write and end methods.
• through takes care of pause/resume logic if you use this.queue(data) instead of this.emit('data', data).
• Use this.pause() and this.resume() to manage flow.
• Check this.paused to see current flow state. (write always returns !this.paused).

This function is the basis for most of the synchronous streams in event-stream.

var through = require('through')

through(function write(data) {
    this.queue(data) //data *must* not be null
  },
  function end () { //optional
    this.queue(null)
  })

Or, can also be used without buffering on pause, use this.emit('data', data), and this.emit('end')

var through = require('through')

through(function write(data) {
    this.emit('data', data)
    //this.pause() 
  },
  function end () { //optional
    this.emit('end')
  })

Extended Options

You will probably not need these 99% of the time.

autoDestroy=false

By default, through emits close when the writable and readable side of the stream has ended. If that is not desired, set autoDestroy=false.

var through = require('through')

//like this
var ts = through(write, end, {autoDestroy: false})
//or like this
var ts = through(write, end)
ts.autoDestroy = false

License

MIT / Apache2