@handy-common-utils/fs-utils

File system operations related utilities without any 3rd party dependency.

How to use

First add it as a dependency:

npm install @handy-common-utils/fs-utils

Then you can use it in the code:

import { FsUtils } from '@handy-common-utils/fs-utils';

const [,, filePath, matchPattern, beforeString, afterString] = process.argv;
await FsUtils.addSurroundingInFile(filePath, new RegExp(matchPattern), beforeString, afterString);

You can either import and use the class as shown above, or you can import individual functions directly like below:

import { addSurroundingInFile } from 'fs-utils';

await addSurroundingInFile(README_MD_FILE, /<example>(.*?)<\/example>/gms, '<example><b>', '</b></example>');

There are also several commands you can use directly from your shell/build scripts:

replace-in-file filePath matchPattern replacement
replace-in-files matchPattern replacement file1 file2 file3 ...
replace-in-file-with-file-content filePath matchPattern contentFilePath
add-surrounding-in-file filePath matchPattern beforeString afterString

API

Module: fs-utils

Re-exports

Functions

escapeRegExpReplacement = FsUtils.escapeRegExpReplacement
changeFileContent = FsUtils.changeFileContent
replaceInFile = FsUtils.replaceInFile
replaceInFilesWithEncoding = FsUtils.replaceInFilesWithEncoding
replaceInFiles = FsUtils.replaceInFiles
addSurroundingInFile = FsUtils.addSurroundingInFile
replaceInFileWithFileContent = FsUtils.replaceInFileWithFileContent

Exports

Classes

FsUtils

Type Aliases

FileEncoding

Ƭ FileEncoding: Parameters<Buffer["toString"]>["0"]

ReplacementOrBuilder

Ƭ ReplacementOrBuilder: string | (matchPattern: RegExp, filePath: string) => string | PromiseLike<string>

Classes

Class: FsUtils

fs-utils.FsUtils

Constructors

constructor

• new FsUtils()

Methods

addSurroundingInFile

▸ Static addSurroundingInFile(filePath, matchPattern, addBefore, addAfter, fileEncoding?): Promise<void>

Add surrounding content to the matching sections in the text file.

Parameters

Name	Type	Default value	Description
`filePath`	`string`	`undefined`	path to the file
`matchPattern`	`RegExp`	`undefined`	RegExp for deciding which section of the file would be processed. You must have a capturing group in the pattern. You may want to use these tricks: `m` flag, `g` flag, `s` flag, `[\s\S]`, `.?`
`addBefore`	`string`	`undefined`	the string to be added before the capturing group, no need to escape anything
`addAfter`	`string`	`undefined`	the string to be added before the capturing group, no need to escape anything
`fileEncoding`	`undefined` \| `BufferEncoding`	`'utf-8'`	encoding of the file

Returns

Promise<void>

Promise of void

changeFileContent

▸ Static changeFileContent(filePath, transformContent, fileEncoding?): Promise<void>

Change the text file content. This function loads the full content of the file into memory as string, so that it is not suitable for huge (for example, > 500MB) files. If the new content and original content are the same, the file won't be touched.

Parameters

Name	Type	Default value	Description
`filePath`	`string`	`undefined`	path to the file
`transformContent`	(`originalContent`: `string`, `filePath`: `string`) => `string` \| `PromiseLike`<`string`>	`undefined`	function for getting the new file content
`fileEncoding`	`undefined` \| `BufferEncoding`	`'utf-8'`	encoding of the file

Returns

Promise<void>

Promise of void

escapeRegExpReplacement

▸ Static escapeRegExpReplacement(input): string

Escape the ' sign in the string for using the string as the second argument to String.replace(...)

Parameters

Name	Type	Description
`input`	`string`	the original string

Returns

string

a new string with all ' in the original string being replaced by '$'

replaceInFile

▸ Static replaceInFile(filePath, matchPattern, replacementOrBuilder, fileEncoding?): Promise<void>

Replace the matching sections in the text file.

Parameters

Name	Type	Default value	Description
`filePath`	`string`	`undefined`	path to the file
`matchPattern`	`RegExp`	`undefined`	RegExp for deciding which section of the file would be replaced. You may want to use these tricks: `m` flag, `g` flag, `s` flag, `[\s\S]`, `.?`
`replacementOrBuilder`	`ReplacementOrBuilder`	`undefined`	The replacement string or a function for building the replacement string. Please note that you can use special replacement patterns but also you need to take care of the escaping. For details of special replacement patterns see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace
`fileEncoding`	`undefined` \| `BufferEncoding`	`'utf-8'`	encoding of the file

Returns

Promise<void>

Promise of void

replaceInFileWithFileContent

▸ Static replaceInFileWithFileContent(filePath, matchPattern, contentFilePath, fileEncoding?): Promise<void>

Replace the matching sections in the text file with content from another file.

Parameters

Name	Type	Default value	Description
`filePath`	`string`	`undefined`	path of the file
`matchPattern`	`RegExp`	`undefined`	RegExp for deciding which section of the file would be replaced. You must have a capturing group in the pattern. You may want to use these tricks: `m` flag, `g` flag, `s` flag, `[\s\S]`, `.?`
`contentFilePath`	`string`	`undefined`	path of the file for getting the replacement content
`fileEncoding`	`undefined` \| `BufferEncoding`	`'utf-8'`	encoding of the files

Returns

Promise<void>

Promise of void

replaceInFiles

▸ Static replaceInFiles(matchPattern, replacementOrBuilder, ...filePaths): Promise<void>

Replace the matching sections in multiple utf-8 text files. The replacing opertions on those files happen in parallel.

Parameters

Name	Type	Description
`matchPattern`	`RegExp`	RegExp for deciding which section of the file would be replaced. You may want to use these tricks: `m` flag, `g` flag, `s` flag, `[\s\S]`, `.?`
`replacementOrBuilder`	`ReplacementOrBuilder`	The replacement string or a function for building the replacement string. Please note that you can use special replacement patterns but also you need to take care of the escaping. For details of special replacement patterns see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace
`...filePaths`	`string`[]	patsh to the files

Returns

Promise<void>

Promise of void

replaceInFilesWithEncoding

▸ Static replaceInFilesWithEncoding(matchPattern, replacementOrBuilder, fileEncoding, ...filePaths): Promise<void>

Replace the matching sections in multiple text files. The replacing opertions on those files happen in parallel.

Parameters

Name	Type	Description
`matchPattern`	`RegExp`	RegExp for deciding which section of the file would be replaced. You may want to use these tricks: `m` flag, `g` flag, `s` flag, `[\s\S]`, `.?`
`replacementOrBuilder`	`ReplacementOrBuilder`	The replacement string or a function for building the replacement string. Please note that you can use special replacement patterns but also you need to take care of the escaping. For details of special replacement patterns see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace
`fileEncoding`	`undefined` \| `BufferEncoding`	encoding of the file, in most of the cases 'utf-8' should be used
`...filePaths`	`string`[]	patsh to the files

Returns

Promise<void>

Promise of void