@frsource/frs-replace

    3.0.3 • Public • Published

    @frsource/frs-replace

    NPM version semantic-release Build Status Coverage Status Dependabot badge Dependencies status Dev dependencies status codebeat badge JavaScript Style Guide

    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 add @frsource/frs-replace

    or

    npm install @frsource/frs-replace

    or download zipped from @frsource/frs-replace releases

    📚 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

    ⌨️ 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
    ‑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

    🔎 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

    Click to expand

    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

    Click to expand

    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

    Click to expand

    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

    Click to expand

    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

    Click to expand

    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>

    📈 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%

    Install

    npm i @frsource/frs-replace

    DownloadsWeekly Downloads

    14

    Version

    3.0.3

    License

    Apache-2.0

    Unpacked Size

    240 kB

    Total Files

    15

    Last publish

    Collaborators

    • frsgit