FRS-replace
The fastest (see benchmarks) CLI & Node wrapper around javascript replace which allows on-the-fly replacing (with or without changing input files), globbing, piping and many more!
Installation
yarn
yarn add frs-replace
npm
npm install frs-replace
download zipped from FRS-replace Releases
Node API usage
FRS-replace package provides 2 methods for synchronous / asynchronous (with promise and ES6 async
/await
syntax support) usage:
const FRSReplace = ; FRSReplaceFRSReplace
Where /* options */
is an object containing:
Note: remember that you need to provide some input for FRS-replace to work, so one of the parameters: input or content are required
Option | Type | Default | Description |
---|---|---|---|
input | string or <string>array | undefined | Path/fast-glob pattern to files to read & replace from, if multiple files are specified results are joined with inputJoinString option's value |
inputReadOptions | string or object | utf8 | Options passed to readFileSync when reading input file |
inputGlobOptions | object | undefined | Options passed to fast-glob when resolving glob patterns |
inputJoinString | string | \n | String used when joining multiple files, passed directly to javascript join |
content | string | undefined | Content to be replaced (takes precedence over file input) |
regex | string or RegExp Object | - | Used as a first argument of javascript replace |
replacement | string | - | Passed as a second argument to javascript replace |
output | string | undefined | Path of an output file |
outputWriteOptions | string or object | utf8 | Passed as options argument of write's .sync |
CLI usage
FRS-replace <regex> <replacement> [options]
Positionals
Option | Type | Description |
---|---|---|
<regex> | string | First parameter to RegExp constructor |
<replacement> | string | String or path to replacement function file (see ‑‑replace‑fn switch for details) |
Options
Note: Every boolean option can be negated with use of
--no-
prefix, e.g.--stdout
or--no-stdout
turn stdout output on or off, respectively.
Note: Object types can be set using dot notation. So, e.g. if you want to pass
utf8
value under i-read-opts encoding field you should write--i-read-opts.encoding utf8
.
Option | Type | Default | Description |
---|---|---|---|
‑i, ‑‑input | string or <string>array | - | Files/fast-glob pattern to files to read & replace from |
‑‑i-read-opts | string or object | utf8 | Passed to readFileSync when reading input file |
‑‑i-glob-opts | object | undefined | Passed to fast-glob when resolving glob patterns |
‑‑i-join-str | string | \n | Used when joining multiple files, passed directly to javascript join |
‑o, ‑‑output | string | - | Output file name/path (replaces the file if it already exists and creates any intermediate directories if they don't already exist) |
‑‑o-write-opts | string or object | utf8 | Passed as options argument of write's .sync |
‑f, ‑‑flags | combination of gim flags | g | RegExp flags |
‑c, ‑‑content | string | - | Content to be replaced (takes precedence over stream & file input) |
‑‑stdout | boolean | true if piped input present, false otherwise | Force sending output on stdout |
‑r, ‑‑replace‑fn | boolean | false | Treat replacement argument as path to file containing replacement function |
‑h, ‑‑help | boolean | - | Show help |
‑v, ‑‑version | boolean | - | Show version number |
Examples
Note: while most of examples is using synchronous API method, in all cases
.async
is applicable as well.
a
occurences with b
from given foo.js
and returns result / writes result to console
1. Replace all 1.1 API
const FRSReplace = /* synchronously */const resultSync = FRSReplace// work with result here /* asynchronously */FRSReplace /* asynchronously ES6 syntax (must be runned inside async function) */const resultAsync = await FRSReplace// work with result here */
1.2 CLI
FRS-replace a b -i foo.js --stdout
a
occurences with b
from given foo.js
and save result to foo_replaced.js
2. Replace all 2.1 API
const result =
2.2 CLI
FRS-replace a b -i foo.js -o foo_replaced.js
a
occurences with b
from given array of files and save result to foo_replaced.js
using default \n
as result-joining string
3. Replace all 3.1 API
const result =
3.2 CLI
FRS-replace a b -i foo.js foo2.js -o foo_replaced.js --i-join-str "\n/////\n"
or
FRS-replace a b -i foo.js -i foo2.js -o foo_replaced.js --i-join-str "\n/////\n"
Note: Arrays can be passed under single flag-entry as a space-separated list or under same flag repeated multiple times (all values will be concatenated into single array using, details - yargs array notation).
a
occurences with b
from all .js
files in foo
directory and save result to foo_replaced.js
using \n/////\n
as result-joining string
4. Replace all 4.1 API
const result =
4.2 CLI
FRS-replace a b -i foo/*.js -o foo_replaced.js --i-join-str "\n/////\n"
a
occurences with b
in given content string abcd
and save result to foo_replaced.js
5. Replace all 5.1 API
const result =
5.2 CLI
FRS-replace a b --content abcd -o foo_replaced.js
a
occurences with b
from piped stream and save it to output file
6. Replace all 6.1 CLI
<read-file> | FRS-replace a b > <output-file-path>
a
occurences with b
from piped stream and pass it through stdout
stream to next command
7. Replaces all 7.1 CLI
<read-file> | FRS-replace a b | <next-command>
i
argument and passing output down the stream to next command
8. Both pipe & options styles can be mixed together, here - getting input from 8.1 CLI
FRS-replace a b -i foo.js | <next-command>
Benchmarks (Node v10.16.0)
input as glob pattern [40 files x 1000 iterations x 100 repetitions]
Library (best bolded) | Execution time [s] | Difference percentage (comparing to best time) |
---|---|---|
FRS-replace async | 0.01764040 | 102.9716% |
FRS-replace sync | 0.00869107 | 0.0000% |
replace-in-file | 0.02243486 | 158.1369% |
replace async | N/A | N/A |
replace sync | 0.05524010 | 535.5961% |
replace-string | N/A | N/A |
input & replacement as strings [1000 iterations x 100 repetitions]
Library (best bolded) | Execution time [s] | Difference percentage (comparing to best time) |
---|---|---|
FRS-replace async | 0.00010628 | 231.1801% |
FRS-replace sync | 0.00003368 | 4.9407% |
replace-in-file | N/A | N/A |
replace async | N/A | N/A |
replace sync | N/A | N/A |
replace-string | 0.00003209 | 0.0000% |