map-stream

What is map-stream?

The map-stream npm package is a simple stream transformation tool that allows you to create a through stream from an asynchronous function. It is primarily used for applying a function to every item in a stream, effectively enabling transformation and processing of stream data in an easy and flexible manner.

What are map-stream's main functionalities?

Asynchronous Transformation

This feature allows for the asynchronous transformation of stream data. The provided code sample reads data from 'input.txt', transforms it to uppercase asynchronously, and writes the transformed data to 'output.txt'.

var map = require('map-stream');
var fs = require('fs');

var inputStream = fs.createReadStream('input.txt');
var outputStream = fs.createWriteStream('output.txt');

var transformStream = map(function(data, callback) {
  // Asynchronously transform data
  var transformedData = data.toString().toUpperCase();
  callback(null, transformedData);
});

inputStream.pipe(transformStream).pipe(outputStream);

Error Handling

This feature demonstrates how to handle errors within the map-stream. If the data contains the string 'error', an error is passed to the callback, which is then handled by listening to the 'error' event on the stream.

var map = require('map-stream');

var transformStream = map(function(data, callback) {
  // Simulate an error under certain condition
  if(data.toString().includes('error')) {
    callback(new Error('Error found in data'));
  } else {
    callback(null, data);
  }
});

transformStream.on('error', function(err) {
  console.error('Error:', err.message);
});

Other packages similar to map-stream

through2

through2 is a tiny wrapper around Node.js streams.Transform (Streams2/3) to avoid explicit subclassing noise. It's similar to map-stream but provides more flexibility in handling stream data, including object mode streams. through2 can be used for more complex transformations and offers a slightly different API.

event-stream

event-stream is a toolkit for working with Node.js streams in a more functional way. It includes a wide range of utilities for stream manipulation, including map, filter, and reduce functions. Compared to map-stream, event-stream offers a broader set of features for stream processing, making it suitable for more complex scenarios.

highland

highland.js wraps Node.js streams and provides a higher-level abstraction for using them. It allows you to use streams as first-class objects, with support for map, filter, reduce, and more. Highland can handle synchronous and asynchronous operations more gracefully than map-stream and is designed for more complex data processing tasks.

README

MapStream

Refactored out of event-stream

##map (asyncFunction[, options])

Create a through stream from an asyncronous function.

var map = require('map-stream')

map(function (data, callback) {
  //transform data
  // ...
  callback(null, data)
})

Each map MUST call the callback. It may callback with data, with an error or with no arguments,

• callback() drop this data.
  this makes the map work like filter,
  note:callback(null,null) is not the same, and will emit null

• callback(null, newData) turn data into newData

• callback(error) emit an error for this item.

Note: if a callback is not called, map will think that it is still being processed,
every call must be answered or the stream will not know when to end.

Also, if the callback is called more than once, every call but the first will be ignored.

##Options

• failures - boolean continue mapping even if error occured. On error map-stream will emit failure event. (default: false)