replacestream

What is replacestream?

The replacestream npm package allows you to perform stream-based search and replace operations on text. It is particularly useful for processing large files or streams of data where you want to replace specific patterns or strings efficiently.

What are replacestream's main functionalities?

Basic String Replacement

This feature allows you to replace occurrences of a specific string with another string in a stream. In this example, 'oldString' in 'input.txt' is replaced with 'newString' and the result is written to 'output.txt'.

const fs = require('fs');
const replaceStream = require('replacestream');

fs.createReadStream('input.txt')
  .pipe(replaceStream('oldString', 'newString'))
  .pipe(fs.createWriteStream('output.txt'));

Regex Replacement

This feature allows you to use regular expressions for more complex search and replace operations. In this example, all sequences of digits in 'input.txt' are replaced with the string 'number' and the result is written to 'output.txt'.

const fs = require('fs');
const replaceStream = require('replacestream');

fs.createReadStream('input.txt')
  .pipe(replaceStream(/\d+/g, 'number'))
  .pipe(fs.createWriteStream('output.txt'));

Function-based Replacement

This feature allows you to use a function to determine the replacement value. In this example, every occurrence of 'foo' in 'input.txt' is replaced with its uppercase version 'FOO' and the result is written to 'output.txt'.

const fs = require('fs');
const replaceStream = require('replacestream');

fs.createReadStream('input.txt')
  .pipe(replaceStream('foo', (match) => match.toUpperCase()))
  .pipe(fs.createWriteStream('output.txt'));

Other packages similar to replacestream

through2

through2 is a general-purpose stream utility that allows you to transform data in a stream. While it doesn't specifically focus on search and replace, you can use it to implement similar functionality with more flexibility.

string-replace-stream

string-replace-stream is another package that provides stream-based string replacement. It is simpler and more focused on basic string replacement compared to replacestream.

README

replacestream

A node.js through stream that does basic streaming text search and replace and is chunk boundary friendly.

Installation

Install via npm:

$ npm install replacestream

Examples

Search and replace over a test file

Say we want to do a search and replace over the following file:

// happybirthday.txt
Happy birthday to you!
Happy birthday to you!
Happy birthday to dear Liza!
Happy birthday to you!

var replaceStream = require('replacestream')
  , fs = require('fs')
  , path = require('path');

// Replace all the instances of 'birthday' with 'earthday'
fs.createReadStream(path.join(__dirname, 'happybirthday.txt'))
  .pipe(replaceStream('birthday', 'earthday'))
  .pipe(process.stdout);

Running this will print out:

$ node simple.js
Happy earthday to you!
Happy earthday to you!
Happy earthday to dear Liza!
Happy earthday to you!

You can also limit the number of replaces to first n:

// Replace the first 2 of the instances of 'birthday' with 'earthday'
fs.createReadStream(path.join(__dirname, 'happybirthday.txt'))
  .pipe(replaceStream('birthday', 'earthday', { limit: 2 } ))
  .pipe(process.stdout);

Which would output:

$ node simple.js
Happy earthday to you!
Happy earthday to you!
Happy birthday to dear Liza!
Happy birthday to you!

And you can also pass in a replacement function which will get called for each replacement:

// Replace the word 'Happy' with a different word each time
var words = ['Awesome', 'Good', 'Super', 'Joyous'];
function replaceFn(match) {
  return words.shift();
}
fs.createReadStream(path.join(__dirname, 'happybirthday.txt'))
  .pipe(replaceStream('birthday', replaceFn))
  .pipe(process.stdout);

Which would output:

$ node simple.js
Awesome birthday to you!
Good birthday to you!
Super birthday to dear Liza!
Joyous birthday to you!

Web server search and replace over a test file

Here's the same example, but kicked off from a HTTP server:

// server.js
var http = require('http')
  , fs = require('fs')
  , path = require('path')
  , replaceStream = require('replacestream');

var app = function (req, res) {
  if (req.url.match(/^\/happybirthday\.txt$/)) {
    res.writeHead(200, { 'Content-Type': 'text/plain' });
    fs.createReadStream(path.join(__dirname, 'happybirthday.txt'))
      .pipe(replaceStream('birthday', 'earthday'))
      .pipe(res);
  } else {
    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end('File not found');
  }
};
var server = http.createServer(app).listen(3000);

When you request the file:

$ curl -i "http://localhost:3000/happybirthday.txt"
HTTP/1.1 200 OK
Content-Type: text/plain
Date: Mon, 08 Jul 2013 06:45:21 GMT
Connection: keep-alive
Transfer-Encoding: chunked

Happy earthday to you!
Happy earthday to you!
Happy earthday to dear Liza!
Happy earthday to you!

NB: If your readable Stream that you're piping through the replacestream is paused, then you may have to call the .resume() method on it.

Changing the encoding

You can also change the text encoding of the search and replace by setting an encoding property on the options object:

// Replace the first 2 of the instances of 'birthday' with 'earthday'
fs.createReadStream(path.join(__dirname, 'happybirthday.txt'))
  .pipe(replaceStream('birthday', 'earthday', { limit: 2, encoding: 'ascii' } ))
  .pipe(process.stdout);

By default the encoding will be set to 'utf8'.