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.