stream-replace-string
v2.0.0
Published
Replaces strings in a stream.
Downloads
403,640
Maintainers
Readme
stream-replace-string
Replaces strings in a stream.
Install
npm i stream-replace-string
Using
import replace from 'stream-replace-string'
import { createReadStream, createWriteStream } from 'fs'
createReadStream("./input.txt")
.pipe(replace("{fruit}", "apple"))
.pipe(createWriteStream("./output.txt"))
You can also replace multiple different words by piping your data through multiple replace streams
createReadStream("./input.txt")
.pipe(replace("good", "great"))
.pipe(replace("bad", "horrible"))
.pipe(replace("grey", "gray"))
.pipe(createWriteStream("./output.txt"))
The replace
function
replace(searchStr, replaceWith, options)
- Parameters
searchStr
- The string to search for. This must be a string, and cannot be a regex.replaceWith
- There are a couple of different things you can use:- String - Inserts the string.
- Promise resolving a string - Once the promise is resolved, the given string is used.
- Replacer function - This is a custom replacer function. The function can take a parameter,
matches
, which is the number of matches so far (for the first match, this will be0
). This function should return a string or a promise resolving a string. - Readable stream - A readable stream can be given, which can make more chunks available sooner. See
options.bufferReplaceStream
for options if you are using a readable stream.
options
(optional) - An object of options.limit
(optional, defaultInfinity
) - The maximum number of strings to replace. This can be useful if you know there is only 1 occurrence ofsearchStr
. Once this limit is reached, the transform stream will stop transforming anything.bufferReplaceStream
(optional, defaulttrue
) - This is for when you use a readable stream forreplaceWith
. If this is true, thereplaceWith
stream will be read right away, and be kept in memory to be used once a match is found. For fastest performance, keep this to betrue
. If yourreplaceWith
stream is very large and you have a limit of 1, you can set this tofalse
to save memory.
- Returns
- Returns a transform stream. See the How It Works section for more information.
How It Works
The transform stream
The replace
function returns a Node.js transform stream. Transform streams take in chunks and can also be read. In this particular transform stream, it takes a string and outputs the same string, except that it replaces the replace.
Efficient memory use.
The tricky part with this transform stream is knowing when to hold chunks, and when to pass them on. Let's say we were looking for 'paper'
in our text. If our first chunk was: 'perfect pot'
, this module knows that there is no way the string 'perfect pot'
will fit into the search string, 'paper'
. We can then pass the chunks onto the output of the transform stream, available right away for the stream consumer. However, if our first chunk was: 'p'
, we can't pass that on, because there is a change that the next chunk could start with 'aper'
. Since we aren't sure if the 'p'
will be replaced or not, we hold on to this text, and check it once we get the next chunk. If we get 'aper'
in the next chunk, we replace the text. If we get something else, like 'ear'
, we can attach it to the 'p'
and output 'pear'
. It gets even more complicated when multiple potential matches are possible. Let's say we get 'pap'
in our first chunk. We need to be watching the first 'p'
and the third 'p'
, because it could end up being 'paper'
, if the next chunk was 'er'
, or it could end of being 'papaper'
. This package is smart and it will efficiently find matches spanning multiple chunks, and get rid of text it knows won't have a match.
Importing with ESModules
import replace from 'stream-replace-string'