@frsource/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!

• :scroll: Installation
• :books: Node API
• :keyboard: CLI API
• :mag_right: Example usage
  • 1. Replace all a occurences with b from given foo.js file and return result / write result to the console
  • 2. Replace all a occurences with b from given foo.js and save result to the foo_replaced.js
  • 3. Replace all a occurences with b from given array of files and save result to the foo_replaced.js using default \n as result-joining string
  • 4. Replace all a occurences with b from all .js files in foo directory and save result to the foo_replaced.js using \n/////\n as result-joining string
  • 5. Replace all a occurences with b in given content string abcd and save result to the foo_replaced.js
  • 6. Replace all a occurences with b from piped stream and save it to the output file
  • 7. Replace all a occurences with b from piped stream and pass it through stdout stream to the <next-command>
  • 8. Both pipe & options styles can be mixed together, here - getting input from -i argument and passing output down the stream to the <next-command>
• :chart_with_upwards_trend: Benchmarks

:scroll: Installation

yarn add @frsource/frs-replace

or

npm install @frsource/frs-replace

or download zipped from @frsource/frs-replace releases

:books: Node API

@frsource/frs-replace package provides 2 methods: for synchronous or for asynchronous (with promise and ES6 async/await syntax support) usage:

const FRSReplace = require('@frsource/frs-replace');
// or
import * as FRSReplace from '@frsource/frs-replace';

FRSReplace.sync({/* options */})
FRSReplace.async({/* options */})

// you might also want to import methods separately (e.g. import only one of them):
const FRSReplaceSync = require('@frsource/frs-replace/sync');
const FRSReplaceAsync = require('@frsource/frs-replace/async');
// or
import { sync, async } from '@frsource/frs-replace';

Where /* options */ is an object containing:

Note: remember that you need to provide some input for @frsource/frs-replace to work, so one of parameters: input or content is required

| Option | Type | Default | Description | | --- | --- | --- | --- | | input | string or string[] | undefined | Path to files or fast-glob pattern pointing to files to be read & replaced from. If multiple files specified results will be joined using outputJoinString option's value) | | inputReadOptions | string or object | utf8 | Options which are passed directly to the readFileSync method when reading input file | | inputGlobOptions | object | undefined | Options which are passed directly to the fast-glob package when resolving glob patterns | | content | string | undefined | Content to be replaced (takes precedence over file input) | | strategy | "join" or "flatten" or "preserve-structure" | "join" | Output file generation strategy. "join" - joins all input files and outputs them as a single file using path passed as: "output". "preserve-structure" - saves all files to the "output" directory keeping relative directory structure."flatten" - same as "preserve-structure" but flattens the directory structure | | needle | 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 | | outputJoinString | string | \n | String used when joining multiple files, passed directly to javascript join |

:keyboard: CLI API

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[] | - | Path to files or fast-glob pattern pointing to files to be read & replaced from. If multiple files specified results will be joined using outputJoinString option's value) | | ‑‑i-read-opts | string or object | utf8 | Options which are passed directly to the readFileSync method when reading input file | | ‑‑i-glob-opts | object | undefined | Options which are passed directly to the fast-glob package when resolving glob patterns | | ‑‑stdin | boolean | true | Wait for stdin input (should be set to false when used in non-interactive terminals) | | ‑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 | | ‑‑o-join-str | string | \n | Used when joining multiple files, passed directly to javascript join | | ‑c, ‑‑content | string | - | Content to be replaced (takes precedence over stream & file input) | | ‑s, ‑‑strategy | "join" or "flatten" or "preserve-structure" | "join" | Output file generation strategy. "join" - joins all input files and outputs them as a single file using path passed as: "output". "preserve-structure" - saves all files to the "output" directory keeping relative directory structure."flatten" - same as "preserve-structure" but flattens the directory structure | | ‑f, ‑‑flags | combination of gim flags | g | RegExp flags | | ‑‑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 |

:mag_right: Example usage

Note: While most of examples are using synchronous API method in all cases .async is applicable as well.

1. Replace all a occurences with b from given foo.js file and return result / write result to the console

1.1 API

const FRSReplace = require('@frsource/frs-replace')

/* synchronously */
const resultSync = FRSReplace.sync({
  input       : 'foo.js',
  regex       : new RegExp('a', 'g'),
  replacement : 'b',
  output      : 'foo_replaced.js'
})
// work with result here
  
/* asynchronously */
FRSReplace.async({
  input       : 'foo.js',
  regex       : new RegExp('a', 'g'),
  replacement : 'b'
})
.then(resultAsync => {
  // work with result here */
})

/* asynchronously ES6 syntax (must be runned inside async function) */
const resultAsync = await FRSReplace.async({
  input       : 'foo.js',
  regex       : new RegExp('a', 'g'),
  replacement : 'b'
})
// work with result here */

1.2 CLI

frs-replace a b -i foo.js --stdout

2. Replace all a occurences with b from given foo.js and save result to the foo_replaced.js

2.1 API

const result = require('@frsource/frs-replace').sync({
  input       : 'foo.js',
  regex       : new RegExp('a', 'g'),
  replacement : 'b',
  output      : 'foo_replaced.js'
})

2.2 CLI

frs-replace a b -i foo.js -o foo_replaced.js

3. Replace all a occurences with b from given array of files and save result to the foo_replaced.js using default \n as result-joining string

3.1 API

const result = require('@frsource/frs-replace').sync({
  input       : ['foo.js', 'foo2.js'],
  regex       : new RegExp('a', 'g'),
  replacement : 'b',
  output      : 'foo_replaced.js'
})

3.2 CLI

frs-replace a b -i foo.js foo2.js -o foo_replaced.js

or

frs-replace a b -i foo.js -i foo2.js -o foo_replaced.js

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).

4. Replace all a occurences with b from all .js files in foo directory and save result to the foo_replaced.js using \n/////\n as result-joining string

4.1 API

const result = require('@frsource/frs-replace').sync({
  input           : 'foo/*.js',
  regex           : new RegExp('a', 'g'),
  replacement     : 'b',
  outputJoinString : '\n/////\n',
  output          : 'foo_replaced.js'
})

4.2 CLI

frs-replace a b -i foo/*.js -o foo_replaced.js --o-join-str "\n/////\n"

5. Replace all a occurences with b in given content string abcd and save result to the foo_replaced.js

5.1 API

const result = require('@frsource/frs-replace').sync({
  content     : 'abcd',
  regex       : new RegExp('a', 'g'),
  replacement : 'b',
  output      : 'foo_replaced.js'
})

5.2 CLI

frs-replace a b --content abcd -o foo_replaced.js

6. Replace all a occurences with b from piped stream and save it to the output file

6.1 CLI

<read-file> | frs-replace a b > <output-file-path>

7. Replace all a occurences with b from piped stream and pass it through stdout stream to the <next-command>

7.1 CLI

<read-file> | frs-replace a b | <next-command>

8. Both pipe & options styles can be mixed together, here - getting input from -i argument and passing output down the stream to the <next-command>

8.1 CLI

frs-replace a b -i foo.js | <next-command>

:chart_with_upwards_trend: Benchmarks

Tested on Node v15.0.1.

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.01959564 | 57.5020% | | frs-replace sync | 0.01244152 | 0.0000% | | replace-in-file | 0.02223758 | 78.7368% | | replace async | N/A | N/A | | replace sync | 0.06111267 | 391.1992% | | 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.00020093 | 516.9883% | | frs-replace sync | 0.00003257 | 0.0000% | | replace-in-file | N/A | N/A | | replace async | N/A | N/A | | replace sync | N/A | N/A | | replace-string | 0.00003438 | 5.5692% |