https://github.com/frsource/frs-replace
The fastest way to replace any text/file/piped stream content. Shipped with both NodeJS API & CLI out of the box!
https://github.com/frsource/frs-replace
cli command-line-interface fast frs-replace javascript nodejs performance pipe pipes regex regexp regular-expression replace replacement stream streams
Last synced: 6 months ago
JSON representation
The fastest way to replace any text/file/piped stream content. Shipped with both NodeJS API & CLI out of the box!
- Host: GitHub
- URL: https://github.com/frsource/frs-replace
- Owner: FRSOURCE
- License: apache-2.0
- Created: 2018-10-11T17:53:52.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2024-04-30T09:22:10.000Z (over 1 year ago)
- Last Synced: 2024-05-01T11:06:16.569Z (over 1 year ago)
- Topics: cli, command-line-interface, fast, frs-replace, javascript, nodejs, performance, pipe, pipes, regex, regexp, regular-expression, replace, replacement, stream, streams
- Language: JavaScript
- Homepage:
- Size: 817 KB
- Stars: 2
- Watchers: 4
- Forks: 2
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
@frsource/frs-replace - replace content directly in your files/streams with ease (CLI included)! 📝
File an Issue
·
Question or an idea?
·
Benchmarks
The fastest (see benchmarks) CLI & Node wrapper around javascript replace which allows in-file replacing (with possibility to save changed file as a copy), globbing, piping and many more!
Getting Started (CLI)
·
Examples and recipes (CLI)
Getting Started (Node)
·
Examples and recipes (Node)
## :scroll: Installation
```bash
npm install @frsource/frs-replace
```
or execute it right away:
```bash
npx @frsource/frs-replace
```
## :keyboard: CLI
```bash
frs-replace [flags]
```
Basic usage:
```bash
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](#mag_right-examples-and-recipes---cli).
### Arguments
| Argument | Type | Description |
| --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| \ | string | First parameter to [RegExp constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#Syntax) |
| \ | 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](https://github.com/yargs/yargs-parser#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](https://github.com/mrmlnc/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](https://nodejs.org/api/fs.html#fs_fs_readfilesync_path_options) when reading input file |
| ‑‑i-glob-opts | object | _undefined_ | Options which are passed directly to the [fast-glob package](https://github.com/mrmlnc/fast-glob#options-1) 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](https://www.npmjs.com/package/write#sync) |
| ‑‑o-join-str | string | \n | Used when joining multiple files, passed directly to [javascript join](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/join#Syntax) |
| ‑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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#Syntax) 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)
```bash
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)
```bash
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)
```bash
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)
```bash
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)
```bash
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)
```bash
| frs-replace a b >
```
##### 7. Replace all `a` occurrences with `b` from a piped stream and pass it through the `stdout` stream to the `` (using CLI)
```bash
| frs-replace a b |
```
## :books: Node API
@frsource/frs-replace package is shipped in 2 flavors: synchronous and asynchronous:
```javascript
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](https://github.com/mrmlnc/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](https://nodejs.org/api/fs.html#fs_fs_readfilesync_path_options) when reading input file |
| inputGlobOptions | object | _undefined_ | Options which are passed directly to the [fast-glob package](https://github.com/mrmlnc/fast-glob#options-1) 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#Syntax) | _-_ | Used as a first argument of [javascript replace](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#Syntax) |
| replacement | string | _-_ | Passed as a second argument to [javascript replace](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#Syntax) |
| output | string | _undefined_ | Path of an output file |
| outputWriteOptions | string or object | "utf8" | Passed as options argument of [write's .sync](https://www.npmjs.com/package/write#sync) |
| outputJoinString | string | \n | String used when joining multiple files, passed directly to [javascript join](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/join#Syntax) |
## :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
```javascript
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`
```javascript
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
```javascript
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
```javascript
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`
```javascript
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.06% | +0.00% |
| 2 | replace-in-file (sync) | 0.82 ± 1.30% | +80.14% |
| 3 | @frsource/frs-replace (async) | 1.79 ± 1.12% | +294.64% |
| 4 | replace-in-file (async) | 3.11 ± 1.20% | +583.53% |
### input & replacement as strings
| Rank | Library | Average latency [ms] | Difference percentage (comparing to best average latency) |
| ---- | ----------------------------- | -------------------- | ----------------------------------------------------------------------------- |
| 1 | @frsource/frs-replace (sync) | 0.01 ± 0.28% | +0.00% |
| 2 | @frsource/frs-replace (async) | 0.01 ± 0.30% | +15.09% |
| 3 | replaceString | 0.17 ± 0.94% | +2041.78% |