Have opinions about JavaScript? We want to hear them. Take the 2018 JavaScript Ecosystem Survey »

frs-replace

1.0.0 • Public • Published

NPM version Build Status Coverage Status semantic-release Greenkeeper badge

FRS-replace

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 = require('FRS-replace');
 
FRSReplace.sync({/* options */})
FRSReplace.async({/* options */})

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.

1. Replace all a occurences with b from given foo.js and returns result / writes result to console :

API
const FRSReplace = require('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 */
 
CLI
FRS-replace a b -i foo.js --stdout

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

API
const result = require('FRS-replace').sync({
  input       : 'foo.js',
  regex       : new RegExp('a', 'g'),
  replacement : 'b',
  output      : 'foo_replaced.js'
})
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 foo_replaced.js using default \n as result-joining string :

API
const result = require('FRS-replace').sync({
  input       : ['foo.js', 'foo2.js'],
  regex       : new RegExp('a', 'g'),
  replacement : 'b',
  output      : 'foo_replaced.js'
})
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).

4. Replace all 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 :

API
const result = require('FRS-replace').sync({
  input           : 'foo/*.js',
  regex           : new RegExp('a', 'g'),
  replacement     : 'b',
  inputJoinString : '\n/////\n',
  output          : 'foo_replaced.js'
})
CLI
FRS-replace a b -i foo/*.js -o foo_replaced.js --i-join-str "\n/////\n"

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

API
const result = require('FRS-replace').sync({
  content     : 'abcd',
  regex       : new RegExp('a', 'g'),
  replacement : 'b',
  output      : 'foo_replaced.js'
})
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 output file:

CLI
<read-file> | FRS-replace a b > <output-file-path>

7. Replaces all a occurences with b from piped stream and pass it through stdout stream to next command

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 next command

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

Benchmarks

input as glob pattern [1000 iterations x 100 repetitions]

Library (best bolded) Execution time [s] Difference percentage (comparing to best time)
FRS-replace async 0.36640944 0.0000%
FRS-replace sync 0.39553770 7.9496%
replace-in-file 1.78587186 387.3979%
replace async N/A N/A
replace sync 0.44655926 21.8744%
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.01015828 59.0095%
FRS-replace sync 0.00657347 2.8957%
replace-in-file N/A N/A
replace async N/A N/A
replace sync N/A N/A
replace-string 0.00638847 0.0000%

install

npm i frs-replace

Downloadsweekly downloads

42

version

1.0.0

license

Apache-2.0

homepage

github.com

repository

Gitgithub

last publish

collaborators

  • avatar
Report a vulnerability