Node.js: fs-hospitality

Source:

fs-hospitality.js, line 14

Methods

(static) convertEOL(strData, eol) → {string}

Source:

fs-hospitality.js, line 253

Replaces the EOL (End of Line) character of a String.

Example

const { convertEOL } = require('@tuckn/fs-hospitality');

const textCrLf = 'foo\r\n'
  + 'bar\r\n'
  + '\r\n'
  + 'baz';

const textLf = convertEOL(textCrLf, 'lf');
// Returns:
// 'foo\n'
//   + 'bar\n
//   + '\n
//   + 'baz'

Parameters:

Name	Type	Description
`strData`	string	A string to be replaced
`eol`	string	"(lf\|unix\|\n)" \| "(cr\|mac\|\r)" \| "(crlf\|dos\|\r\n)"

Returns:

A replaced string

Type: string

(static) decodeTextBuffer(textBuf, encodingopt) → {string}

Source:

fs-hospitality.js, line 90

Decodes a Buffer of text with automatically detecting encoding

Example

const { decodeTextBuffer } = require('@tuckn/fs-hospitality');

const textBuf = fs.readFileSync('D:\\Test\\SjisCRLF.txt');
const text = decodeTextBuffer(textBuf);
// Returns: 'これはshift-JISで書かれたファイルです。'

Parameters:

Name	Type	Attributes	Default	Description
`textBuf`	Buffer			A Buffer of text
`encoding`	string	<optional>	`''`	A specifying encoding. falsy to auto

Returns:

A encoded string

Type: string

(static) detectTextEncoding(textData) → {string}

Source:

fs-hospitality.js, line 65

Detects the character encoding of a Buffer or a file-path. A binary file would be detected as UTF32. See chardet Supported Encodings. If chardet detect windows-1252, Re-detect with encoding.js.

Example

const { detectTextEncoding } = require('@tuckn/fs-hospitality');

const encoding = detectTextEncoding('D:\\Test\\SjisNote.txt');
// Returns: 'SJIS'

const encoding2 = detectTextEncoding('D:\\Test\\Utf16LeNote.doc');
// Returns: 'UTF-16LE'

const encoding3 = detectTextEncoding('D:\\Test\\image.png');
// Returns: 'UTF32'

Parameters:

Name	Type	Description
`textData`	Buffer \| string	A Buffer or a file-path

Returns:

A name of character encoding. A binary file would be detected as UTF32.

Type: string

(static) detectTextEol(textData) → {string}

Source:

fs-hospitality.js, line 113

Detects the EOL (End of Line) character of a Buffer or a file-path.

Example

const { detectTextEol } = require('@tuckn/fs-hospitality');

const eol = detectTextEol('D:\\Test\\SjisCRLF.txt'); // file-path
// Returns: 'crlf'

const buf = 'D:\\Test\\Utf8.doc'
const eol2 = detectTextEol(buf); // Buffer
// Returns: 'lf'

Parameters:

Name	Type	Description
`textData`	Buffer \| string	Buffer of file-path

Returns:

"crlf" | "cr" | "lf" | ""

Type: string

(static) makeTmpPath(baseDiropt, prefixopt, postfixopt) → {string}

Source:

fs-hospitality.js, line 299

Create a temporary path on the Node.js os.tmpdir

Example

const { makeTmpPath } = require('@tuckn/fs-hospitality');

const tmpPath1 = makeTmpPath();
// Returns: 'C:\Users\YourName\AppData\Local\Temp\7c70ceef-28f6-4ae8-b4ef-5e5d459ef007'

// If necessary, make sure that the file does not exist.
const fs = require('fs');
if (fs.existsSync(tmpPath1)) throw new Error('Oops!');

// Makes on the current working directory
const tmpPath2 = makeTmpPath('.');
// Returns: 'D:\test\2a5d35c8-7214-4ec7-a41d-a371b19273e7'

// Make on SMB path
const tmpPath3 = makeTmpPath('\\\\server\\public');
// Returns: '\\server\public\01fa6ce7-e6d3-4b50-bdcd-19679c49bef2'

// with the prefix name
const tmpPath2 = makeTmpPath('', 'MyTemp_');
// Returns: 'C:\Users\YourName\AppData\Local\Temp\MyTemp_42dc1759-b744-4f2a-840f-e6fa27191cff'

const tmpPath4 = makeTmpPath('R:', 'tmp_', '.log');
// Returns: 'R:\tmp_14493643-792d-4b0d-b2af-c74531db625e.log'

Parameters:

Name	Type	Attributes	Description
`baseDir`	string	<optional>	The default is os.tmpdir
`prefix`	string	<optional>
`postfix`	string	<optional>

Returns:

A temporary path

Type: string

(async, static) mklink(existingPath, newPath) → {Promise.<string>}

Source:

fs-hospitality.js, line 494

Creates a new link (also known as Symbolic Link) to an existing file. Similar to Node.js-Path. But on Windows, use mklink of command in Command-Prompt. so requires admin rights.

Example

const { mklink } = require('@tuckn/fs-hospitality');

// on Windows, use mklink of command in Command-Prompt and requires admin rights
mklink('D:\\MySrc\\TestDir', 'C:\\Test').then((stdout) => {
  console.log(stdout);
  // Created the symbolic link on "C:\"
});

Parameters:

Name	Type	Description
`existingPath`	string	A source file or direcotry
`newPath`	string	A destination path

Returns:

Returns mklink stdout

Type: Promise.<string>

(static) mklinkSync(existingPath, newPath) → {string}

Source:

fs-hospitality.js, line 548

The synchronous version of this API: mklink().

Example

const { mklinkSync } = require('@tuckn/fs-hospitality');

// on Windows, use mklink of command in Command-Prompt and requires admin rights
const stdout = mklinkSync('D:\\MySrc\\TestDir', 'C:\\Test');
// Created the symbolic link on "C:\"

Parameters:

Name	Type	Description
`existingPath`	string	A source file or direcotry
`newPath`	string	A destination path

Returns:

Returns mklink stdout

Type: string

(async, static) readAsText(textFile, encodingopt) → {Promise.<string>}

Source:

fs-hospitality.js, line 181

Reads a Buffer or a file-path as text and encodes it into a String.

Example

const { readAsText } = require('@tuckn/fs-hospitality');

// Ex.1 From a file-path
const fileSjis = 'D:\\Test\\MyNoteSJIS.txt'

readAsText(fileSjis).then((textString) => {
  console.log(textString);
  // Returns String parsed with Shift_JIS
});

// Ex.2 From a Buffer
const fileUtf16LE = 'D:\\Test\\Utf16LE.log'

fs.readFile(fileUtf16LE, async (err, data) => {
  const textString = await readAsText(data);
  console.log(textString);
  // Returns String parsed with UTF-16LE
});

Parameters:

Name	Type	Attributes	Default	Description
`textFile`	Buffer \| string			Buffer or file-path
`encoding`	string	<optional>	`''`	If empty, auto-detecting

Returns:

Type: Promise.<string>

(static) readAsTextSync(textFile, encodingopt) → {string}

Source:

fs-hospitality.js, line 216

The synchronous version of this API: readAsText().

Example

const { readAsTextSync } = require('@tuckn/fs-hospitality');

// Ex.1 From the file-path
const textString = readAsTextSync('D:\\Test\\MyNoteSJIS.txt');
// Returns String parsed with Shift_JIS

// Ex.2 From the Buffer
const buf = fs.readFile('D:\\Test\\Utf16LE.log');
const textString2 = readAsTextSync(buf);
// Returns String parsed with UTF-16LE

Parameters:

Name	Type	Attributes	Default	Description
`textFile`	Buffer \| string			Buffer or file-path
`encoding`	string	<optional>	`''`	If empty, auto-detecting

Returns:

Type: string

(static) readdirPromise(dirPath, optionsopt) → {Promise.<(Array.<string>|Array.<Buffer>|Array.<fs.Dirent>)>}

Source:

fs-hospitality.js, line 581

fs.readdir Promisification. Node.js fs.readdir

Parameters:

Name	Type	Attributes	Description
`dirPath`	string		A directory path
`options`	object	<optional>	See Node.js fs.readdir

Returns:

Returns array of fs.Dirent

Type: Promise.<(Array.<string>|Array.<Buffer>|Array.<fs.Dirent>)>

(async, static) readdirRecursively(dirPath, options) → {Promise.<(Array.<string>|Array.<FileInfo>)>}

Source:

fs-hospitality.js, line 747

Recursively list all file paths in a directory.

Example

const { readdirRecursively } = require('@tuckn/fs-hospitality');

// D:\Test\
// │  FILE_ROOT1.TXT
// │  fileRoot2-Symlink.log
// │  fileRoot2.log
// │
// ├─DirBar
// │  │  fileBar1.txt
// │  │
// │  └─DirQuux
// │          fileQuux1-Symlink.txt
// │          fileQuux1.txt
// │
// ├─DirFoo
// └─DirFoo-Symlink

readdirRecursively('D:\\Test').then((files) => {
  console.dir(files);
  // Returns [
  //   'DirFoo-Symlink',
  //   'fileRoot2-Symlink.log',
  //   'fileRoot2.log',
  //   'FILE_ROOT1.TXT',
  //   'DirFoo',
  //   'DirBar',
  //   'DirBar\\fileBar1.txt',
  //   'DirBar\\DirQuux',
  //   'DirBar\\DirQuux\\fileQuux1-Symlink.txt',
  //   'DirBar\\DirQuux\\fileQuux1.txt' ]

readdirRecursively('D:\\Test', { withFileTypes: true }).then((files) => {
  console.dir(files);
  // Returns [
  //   {
  //     name: 'DirFoo-Symlink',
  //     relPath: 'DirFoo-Symlink',
  //     path: 'D:\\Test\\DirFoo-Symlink',
  //     isDirectory: false,
  //     isFile: false,
  //     isSymbolicLink: true
  //   },
  //   {
  //     name: 'fileRoot2-Symlink.log',
  //     relPath: 'fileRoot2-Symlink.log',
  //     path: 'D:\\Test\\fileRoot2-Symlink.log',
  //     isDirectory: false,
  //     isFile: false,
  //     isSymbolicLink: true
  //   },
  //   {
  //     name: 'fileRoot2.log',
  //     relPath: 'fileRoot2.log',
  //     path: 'D:\\Test\\fileRoot2.log',
  //     isDirectory: false,
  //     isFile: true,
  //     isSymbolicLink: false
  //   },
  //   {
  //     name: 'FILE_ROOT1.TXT',
  //     relPath: 'FILE_ROOT1.TXT',
  //     path: 'D:\\Test\\FILE_ROOT1.TXT',
  //     isDirectory: false,
  //     isFile: true,
  //     isSymbolicLink: false
  //   },
  //   {
  //     name: 'DirFoo',
  //     relPath: 'DirFoo',
  //     path: 'D:\\Test\\DirFoo',
  //     isDirectory: true,
  //     isFile: false,
  //     isSymbolicLink: false
  //   },
  //   {
  //     name: 'DirBar',
  //     relPath: 'DirBar',
  //     path: 'D:\\Test\\DirBar',
  //     isDirectory: true,
  //     isFile: false,
  //     isSymbolicLink: false
  //   },
  //   {
  //     name: 'fileBar1.txt',
  //     relPath: 'DirBar\\fileBar1.txt',
  //     path: 'D:\\Test\\DirBar\\fileBar1.txt',
  //     isDirectory: false,
  //     isFile: true,
  //     isSymbolicLink: false
  //   },
  //   {
  //     name: 'DirQuux',
  //     relPath: 'DirBar\\DirQuux',
  //     path: 'D:\\Test\\DirBar\\DirQuux',
  //     isDirectory: true,
  //     isFile: false,
  //     isSymbolicLink: false
  //   },
  //   {
  //     name: 'fileQuux1-Symlink.txt',
  //     relPath: 'DirBar\\DirQuux\\fileQuux1-Symlink.txt',
  //     path: 'D:\\Test\\DirBar\\DirQuux\\fileQuux1-Symlink.txt',
  //     isDirectory: false,
  //     isFile: false,
  //     isSymbolicLink: true
  //   },
  //   {
  //     name: 'fileQuux1.txt',
  //     relPath: 'DirBar\\DirQuux\\fileQuux1.txt',
  //     path: 'D:\\Test\\DirBar\\DirQuux\\fileQuux1.txt',
  //     isDirectory: false,
  //     isFile: true,
  //     isSymbolicLink: false
  //   }
  // ]
});

Parameters:

Name Type Description

dirPath

string

A directory path

options

object

Optional parameters

Properties

Name	Type	Attributes	Default	Description
`isOnlyDir`	boolean	<optional>	`false`	Exacting directories only
`isOnlyFile`	boolean	<optional>	`false`	Exacting files only
`excludesSymlink`	boolean	<optional>	`false`	Excluding symbolic-links
`matchedRegExp`	string \| RegExp	<optional>		Ex. "\d+\.txt$"
`ignoredRegExp`	string \| RegExp	<optional>		Ex. "[_\-.]cache\d+"
`withFileTypes`	boolean	<optional>	`false`	If true, return fs.Dirent[]
`_prefixDirName`	string	<optional>		@private The internal option

Returns:

{ resolve:string, reject:Error }

Type: Promise.<(Array.<string>|Array.<FileInfo>)>

(static) readdirRecursivelySync(dirPath, options) → {Array.<string>|Array.<FileInfo>}

Source:

fs-hospitality.js, line 888

The synchronous version of this API: readdirRecursivelySync().

Example

const { readdirRecursivelySync } = require('@tuckn/fs-hospitality');

// D:\Test\
// │  FILE_ROOT1.TXT
// │  fileRoot2-Symlink.log
// │  fileRoot2.log
// │
// ├─DirBar
// │  │  fileBar1.txt
// │  │
// │  └─DirQuux
// │          fileQuux1-Symlink.txt
// │          fileQuux1.txt
// │
// ├─DirFoo
// └─DirFoo-Symlink

const files = readdirRecursivelySync('D:\\Test');
console.dir(files);
// Returns [
//   'DirFoo-Symlink',
//   'fileRoot2-Symlink.log',
//   'fileRoot2.log',
//   'FILE_ROOT1.TXT',
//   'DirFoo',
//   'DirBar',
//   'DirBar\\fileBar1.txt',
//   'DirBar\\DirQuux',
//   'DirBar\\DirQuux\\fileQuux1-Symlink.txt',
//   'DirBar\\DirQuux\\fileQuux1.txt' ]

Parameters:

Name	Type	Description
`dirPath`	string	A directory path
`options`	object	See API.readdirRecursively

Returns:

Type: Array.<string> | Array.<FileInfo>

(static) readFilePromise(filePath, optionsopt) → {Promise.<(Buffer|string)>}

Source:

fs-hospitality.js, line 144

fs.readFile Promisification

Example

const { readFilePromise } = require('@tuckn/fs-hospitality');

// All arguments are same with fs.readFile
const data = await readFilePromise('D:\\Test\\myData.dat');
console.log(data);

Parameters:

Name	Type	Attributes	Description
`filePath`	string		A Filename
`options`	object	<optional>	See Node.js fs.readFile

Returns:

Type: Promise.<(Buffer|string)>

(static) textDataToBuf(textData) → {Buffer}

Source:

fs-hospitality.js, line 38

Reads the entire contents of a file. If a type of the param is Buffer, direct return it.

Example

const { textDataToBuf } = require('@tuckn/fs-hospitality');

const buf = textDataToBuf('D:\\Test\\SjisNote.txt'); // file-path
// Returns: fs.readFileSync('D:\\Test\\SjisNote.txt')

const buf2 = textDataToBuf(buf); // Buffer
// Returns: buf

Parameters:

Name	Type	Description
`textData`	Buffer \| string	A Buffer or a file-path

Returns:

The entire contents

Type: Buffer

(static) trimAllLines(strLines, optionopt) → {string}

Source:

fs-hospitality.js, line 362

Trims a string at every each line

Example

const { trimAllLines } = require('@tuckn/fs-hospitality');

const str = '  foo  \n'
  + '  bar  \n'
  + ' baz  ';

const trimmedStr1 = trimAllLines(str);
// Returns: 'foo\n'
//   + 'bar\n'
//   + 'baz';

const trimmedStr2 = trimAllLines(str, 'end');
// Returns: '  foo\n'
//   + '  bar\n'
//   + ' baz';

Parameters:

Name	Type	Attributes	Default	Description
`strLines`	string			A string to be trimmed
`option`	string	<optional>	`'all'`	'all' \| 'start' \| 'end';

Returns:

A trimmed string

Type: string

(static) writeAsText(destPath, strDataopt, optionsopt) → {Promise.<void>}

Source:

fs-hospitality.js, line 413

Write a String to the file as text. Also can specify an encoding, an EOL, BOM and trimming every line.

Example

const { writeAsText } = require('@tuckn/fs-hospitality');
const vbsFile = 'D:\\Test\\utf8bom.vbs';
const strData = 'Dim str As String  \n  str = "foo"\n  WScript.Echo str';
const options = {
  trim: 'all',
  eol: 'crlf',
  bom: true,
  encoding: 'UTF-8',
};

writeAsText(vbsFile, strData, options).then(() => {
  console.log('Writing successful');
});

Parameters:

Name	Type	Attributes	Default	Description
`destPath`	string			A destination file-path
`strData`	string	<optional>	`''`	A string of data to write
`options`	PrewriteAsTextOptions	<optional>		Optional parameters

Returns:

{ resolve:undefined, reject: Error }

Type: Promise.<void>

(static) writeAsTextSync(destPath, strDataopt, options) → {void}

Source:

fs-hospitality.js, line 462

The synchronous version of this API: writeAsText().

Example

const { writeAsTextSync } = require('@tuckn/fs-hospitality');
const vbsFile = 'D:\\Test\\utf8bom.vbs';
const strData = 'Dim str As String  \n  str = "foo"\n  WScript.Echo str';
const options = {
  trim: 'all',
  eol: 'crlf',
  bom: true,
  encoding: 'UTF-8',
};

writeAsTextSync(vbsFile, strData, options);
console.log('Writing successful');

Parameters:

Name	Type	Attributes	Default	Description
`destPath`	string			A destination file-path
`strData`	string	<optional>	`''`	A string of data to write
`options`	object			See API.writeAsText

Returns:

Type: void

(static) writeTmpFileSync(data, optionsopt) → {string}

Source:

fs-hospitality.js, line 324

Write the data to a new temporary path, and Return the path.

Example

const { writeTmpFileSync } = require('@tuckn/fs-hospitality');

const tmpStr = 'The Temporary Message';
const tmpPath = writeTmpFileSync(tmpStr);
// Returns: 'C:\Users\YourName\AppData\Local\Temp\7c70ceef-28f6-4ae8-b4ef-5e5d459ef007'

const fs = require('fs');
const readData = fs.readFileSync(tmpPath, { encoding: 'utf8' });
console.log(tmpStr === readData); // true

Parameters:

Name	Type	Attributes	Description
`data`	string \| NodeJS.ArrayBufferView		A data to write
`options`	object	<optional>	See Node.js fs.writeFileSync

Returns:

A temporary file path

Type: string