:scroll: Installation

npm install @frsource/frs-replace

or execute it right away:

npx @frsource/frs-replace

:keyboard: CLI

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

Basic usage:

frs-replace something anything -i foo.js -o foo_replaced.js

# all of the occurences of "something" in `foo.js` will be replaced with "anything" and saved to `foo_replaced.js`

More examples below.

Arguments

| Argument | Type | Description | | --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- | | <regex> | string | First parameter to RegExp constructor | | <replacement> | string | String or path to replacement function file (see ‑‑replace‑fn switch for details) |

Flags

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 | string, 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: Examples and recipes - CLI

1. Replace all a occurrences with b from the foo.js file and return the result (using CLI)

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

2. Replace all a occurrences with b from foo.js and save the result to the foo_replaced.js (using CLI)

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

3. Replace all a occurrences with b from an array of files and save the result to the foo_replaced.js using default \n as a result-joining string (using CLI)

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

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

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

5. Replace all a occurrences with b in a content string abcd and save the result to the foo_replaced.js (using CLI)

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

6. Replace all a occurrences with b from a piped stream and save it to the output file (using CLI)

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

7. Replace all a occurrences with b from a piped stream and pass it through the stdout stream to the <next-command> (using CLI)

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

:books: Node API

@frsource/frs-replace package is shipped in 2 flavors: synchronous and asynchronous:

import { sync, async } from '@frsource/frs-replace';

sync({
  /* options */
});
await async({
  /* options */
});

Where /* options */ is an object containing:

Note: 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 |

:mag_right: Examples and recipes - Node

Note: While all of examples are using synchronous API method in all cases your can use async as well.

1. Replace all a occurrences with b from the foo.js file and return the result

import { sync } from '@frsource/frs-replace';

const result = sync({
  input: 'foo.js',
  regex: new RegExp('a', 'g'),
  replacement: 'b',
  output: 'foo_replaced.js',
});

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

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

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

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

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

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

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

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

:chart_with_upwards_trend: Benchmarks

Tested on Node v20.18.3.

input as glob pattern [40 files]

| Rank | Library | Average latency [ms] | Difference percentage (comparing to best average latency) | | ---- | ----------------------------- | -------------------- | ----------------------------------------------------------------------------- | | 1 | @frsource/frs-replace (sync) | 0.45 ± 1.17% | +0.00% | | 2 | replace-in-file (sync) | 0.88 ± 1.74% | +94.51% | | 3 | @frsource/frs-replace (async) | 1.81 ± 1.38% | +298.01% | | 4 | replace-in-file (async) | 3.10 ± 1.31% | +582.19% |

input & replacement as strings

| Rank | Library | Average latency [ms] | Difference percentage (comparing to best average latency) | | ---- | ----------------------------- | -------------------- | ----------------------------------------------------------------------------- | | 1 | @frsource/frs-replace (sync) | 0.01 ± 0.30% | +0.00% | | 2 | @frsource/frs-replace (async) | 0.01 ± 0.44% | +18.63% | | 3 | replaceString | 0.17 ± 1.11% | +2057.13% |