through2

What is through2?

The through2 npm package is a thin wrapper around Node.js streams.Transform (a standard Node.js API) that makes it easier to create transform streams. It is designed to work with streams in object mode or non-object mode, allowing for simple function-based stream transformation. This package is particularly useful when you need to create a custom stream that modifies or transforms data as it passes through the stream pipeline.

What are through2's main functionalities?

Simple Transform

This feature allows you to create a simple transform stream that converts input data to uppercase. The code sample demonstrates how to use through2 to create a stream that reads from stdin, transforms the data, and writes to stdout.

const through2 = require('through2');
const stream = through2(function(chunk, enc, callback) {
  this.push(chunk.toString().toUpperCase());
  callback();
});
process.stdin.pipe(stream).pipe(process.stdout);

Object Mode Transform

This feature allows you to work with streams in object mode, where the stream chunks are JavaScript objects. The code sample shows how to create a transform stream that modifies properties of objects and how to use it with a readable stream of objects.

const through2 = require('through2').obj;
const stream = through2(function(obj, enc, callback) {
  obj.key = obj.key.toUpperCase();
  this.push(obj);
  callback();
});

// Usage with an array of objects
const objects = [{ key: 'value' }, { key: 'data' }];
const objectStream = require('stream').Readable.from(objects);
objectStream.pipe(stream).on('data', (transformedObj) => console.log(transformedObj));

Flush Function

This feature allows you to perform an action when the stream is ending, just before it finishes. The code sample demonstrates how to append a message to the stream output right before the stream ends.

const through2 = require('through2');
const stream = through2(function(chunk, enc, callback) {
  this.push(chunk);
  callback();
}, function(callback) {
  // This function is called before the stream is finished
  this.push('Stream is ending!');
  callback();
});

process.stdin.pipe(stream).pipe(process.stdout);

Other packages similar to through2

through

The 'through' package provides a simple way to create a readable-writable stream. It is similar to through2 but does not support object mode by default and has a less modern API.

stream-transform

The 'stream-transform' package is part of the Node.js CSV project and provides a standard transform stream with a simpler API for synchronous operations. It is specifically designed for CSV data transformation and is less generic compared to through2.

pumpify

The 'pumpify' package combines an array of streams into a single duplex stream using pump and duplexify. It is similar to through2 in that it deals with stream transformation but focuses on combining streams rather than creating individual transform streams.