through2-map

What is through2-map?

The through2-map package is a small utility for creating object streams that can be easily transformed. It is built on top of the through2 package and provides a simple API for mapping input chunks to output chunks, making it useful for data transformation tasks in a stream pipeline.

What are through2-map's main functionalities?

Basic Mapping

This feature allows you to transform each chunk of data passing through the stream. In this example, the input data is converted to uppercase.

const through2Map = require('through2-map');
const stream = through2Map(chunk => chunk.toString().toUpperCase());
process.stdin.pipe(stream).pipe(process.stdout);

Object Mode

This feature allows you to work with object streams. In this example, each object passing through the stream is augmented with a new property.

const through2Map = require('through2-map');
const stream = through2Map({ objectMode: true }, obj => ({ ...obj, transformed: true }));
stream.write({ key: 'value' });
stream.on('data', data => console.log(data));

Asynchronous Mapping

This feature allows you to perform asynchronous transformations on the data chunks. In this example, each chunk is converted to uppercase after a delay of 1 second.

const through2Map = require('through2-map');
const stream = through2Map({ wantStrings: true }, (chunk, done) => {
  setTimeout(() => done(null, chunk.toUpperCase()), 1000);
});
process.stdin.pipe(stream).pipe(process.stdout);

Other packages similar to through2-map

through2

The through2 package is a core utility for creating transform streams. It provides a more general-purpose API compared to through2-map, which is specifically designed for mapping operations. through2 can be used to create a wide variety of stream transformations.

map-stream

The map-stream package is another utility for transforming streams. It provides a similar API to through2-map but is less feature-rich. It is a simpler alternative for basic mapping operations.

event-stream

The event-stream package is a collection of stream utilities, including map and filter functions. It offers more functionality than through2-map but can be more complex to use due to its broader scope.

README

through2-map

This is a super thin wrapper around through2 that works like Array.prototype.map but for streams.

For when through2 is just too verbose :wink:

Note you will NOT be able to skip chunks. This is intended for modification only. If you want filter the stream content, use either through2 or through2-filter. This transform also does not have a flush function.

IMPORTANT: If you return null from your function, the stream will end there.

var map = require("through2-map")

var truncate = map(function (chunk) {
  return chunk.slice(0, 10)
})

// vs. with through2:
var truncate = through2(function (chunk, encoding, callback) {
  this.push(chunk.slice(0, 10))
  return callback()
})

// Then use your map:
source.pipe(truncate).pipe(sink)

// Additionally accepts `wantStrings` argument to conver buffers into strings
var stripTags = map({wantStrings: true}, function (str) {
  // OMG don't actually use this
  return str.replace(/<.*?>/g, "")
})

// Works like `Array.prototype.map` meaning you can specify a function that
// takes up to two* arguments: fn(chunk, index)
var spaceout = map({wantStrings: true}, function (chunk, index) {
  return (index % 2 == 0) ? chunk + "\n\n" : chunk
})

// vs. with through2:
var spaceout = through2(function (chunk, encoding, callback) {
  if (this.index == undefined) this.index = 0
  var buf = (this.index++ % 2 == 0) ? Buffer.concat(chunk, new Buffer("\n\n")) : chunk
  this.push(buf)
  return callback()
})

*Differences from Array.prototype.map:

• Cannot insert null elements into the stream without aborting.
• No third array callback argument. That would require realizing the entire stream, which is generally counter-productive to stream operations.
• Array.prototype.map doesn't modify the source Array, which is somewhat nonsensical when applied to streams.

API

require("through2-map")([options,] fn)

Create a stream.Transform instance that will call fn(chunk, index) on each stream segment.

var Tx = require("through2-map").ctor([options,] fn)

Create a reusable stream.Transform TYPE that can be called via new Tx or Tx() to create an instance.

require("through2-map").obj([options,] fn)

Create a through2-map instance that defaults to objectMode: true.

require("through2-map").objCtor([options,] fn)

Just like ctor, but with objectMode: true defaulting to true.

Options

• wantStrings: Automatically call chunk.toString() for the super lazy.
• all other through2 options

LICENSE

MIT