@extra-fs/promises

Useful additions to inbuilt fs module{promises} .
📦 Node.js, 📜 Files, 📰 Docs.

This package provides async versions of functions (in addition to the existing sync and callback-based functions) in the inbuilt fs module, exposed as *Async() from the fs.promises namespace. They can be used with Promise-based asynchronous programming using the await keyword. In addition, callback-based functions, such as readFile, also behave as async functions when a callback is not provided. The idea behind using *Async() function names is to provide a flat module.

In addition, convenience functions such as readFileText and readJson are included. For performing file/directory existence check async exists, assertExists, and assertNotExists can be used. Cleanup of one-item outer directories can be performed with dehuskdir. This package previously included which(), which is now instead suitably included in extra-child-process package.

Stability: Experimental.

const fs = require('extra-fs');


// 1. Read file text.
async function example1() {
  var text = fs.readFileTextSync('.npmignore');
  var text = await fs.readFileText('.npmignore');
  // → # Source only
  // → .gitmodules
  // → .github/
  // → .docs/
  // → ...
}
example1();


// 2. Read JSON file.
async function example2() {
  var json = fs.readJsonSync('package.json');
  var json = await fs.readJson('package.json');
  // → {
  // →   name: 'extra-fs',
  // →   version: '3.0.27',
  // →   description: 'Useful additions to inbuilt fs module.',
  // →   ...
  // → }
}
example2();


// 3. Assert that a file exists.
async function example3() {
  if (!(await fs.exists('LICENSE'))) throw 'May I see you license sir?';
  await fs.assertExists('LICENSE');
}
example3();


// 4. Get contents of a directory.
async function example4() {
  var contents = fs.readdirSync('src');
  var contents = await fs.readdir('src');
  // → [
  // →   'index.ts',
  // →   'promises.ts',
  // →   '_all.ts',
  // →   ...
  // → ]
}
example4();

Index

Property	Description
open	Open a file.
close	Close a file.
read	Read data from a file.
write	Write data to a file.
readv	Read an array of buffers from file.
writev	Write an array of buffers to file.
ftruncate	Shorten (truncate) a file.
futimes	Change the file system timestamps of a file.
fstat	Get information about a file.
fchmod	Set the permissions of a file.
fchown	Set the owner of a file.
...
link	Create a hard link to a file or directory.
symlink	Create a symbolic link to a file or directory.
readlink	Read the contents of a symbolic link.
realpath	Get canonical pathname by resolving ., ..
lutimes	Change the file system timestamps of an object.
lstat	Get information about a file, without dereferencing symbolic links.
lchown	Set the owner of a symbolic link.
...
readFile	Read the entire contents of a file.
writeFile	Write data to the file, replace if it already exists.
appendFile	Append data to a file, create if it does not exist.
truncate	Shorten (truncate) a file.
unlink	Remove a file or symbolic link.
utimes	Change the file system timestamps of an object.
stat	Get file status.
copyFile	Copy source file to destination, overwite if exists.
readFileText	Read file text with Unix EOL.
writeFileText	Write file text with system EOL.
readJson	Read JSON file as value.
writeJson	Write object to JSON file.
watchFile	Watch for changes on `filename`.
unwatchFile	Stop watching for changes on `filename`.
watch	Watch for changes on `filename`, where `filename` is either a file or a directory.
createReadStream	Create a readable stream with 64kb `highWaterMark`.
createWriteStream	Create a writeable stream from a desired `start` position.
...
mkdir	Create a directory.
mkdtemp	Create a unique temporary directory.
opendir	Open a directory.
readdir	Open a directory.
rmdir	Remove a directory.
dehuskdir	Remove outer one-item directories.
...
access	Test a user's permissions for the file or directory.
chmod	Change the permissions of a file.
chown	Change owner and group of a file.
rename	Rename/move a file or directory.
cp	Copy source directory to destination, overwite if exists.
rm	Remove a file or directory.
exists	Check if file or directory exists.
assertExists	Assert that a file or directory exists.
assertNotExists	Assert that a file or directory does not exist.