@frsource/frs-replace v4.1.1

@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

:keyboard: CLI API

frs-replace <regex> <replacement> [options]

Positionals

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.

: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

input & replacement as strings 1000 iterations x 100 repetitions