Skip to content

nodef/extra-fs

Repository files navigation

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

The file system we use today has its origins in the UNIX file system. A file is simply a chunk of data (bytes). Each file has a locally unique name and associated properties which can be grouped together in a hierarchy of directories. A directory is a list of files and other directories, and has a parent directory (except the root directory /). Given the tree-structure, a file can be uniquely identified by its full path.

Access to a file is provided by the file system though the use of a file descriptor. This can be obtained from open by providing the file path, and open mode (read/write). Once a file has been opened and necessary operations performed, such as reading it with read or writing to it with write, it should be closed with close. Reading or writing multiple blocks of a file at a time can be achieved with readv and writev. Once data is written to a file beyond it current size, it is automatically expanded. However, to reduce the size of a file (i.e., to truncate it), ftruncate is used. The additional properties attached to a file, such as access/update time, access permissions, or ownership of a file can be obtained with fstat, and updated with futimes, fchmod, and fchown respectively.

Convenience methods for accessing a file can also be used, which do not require us to go through the process of opening and closing files, and meticulously reading it or writing to it in blocks. These include readFile, writeFile, appendFile, truncate, stat, utimes. chmod and chown are applicable or directories as well. A file can be opened as a stream for reading with createReadStream and for writing with createWriteStream, and copied to another path with copyFile. Access to a file or directory can be checked with access, renamed/moved with rename, copied to another path (recursively) with cp, and removed (recursively) with rm.

Similar to opening/closing of a file, a directory can be opened (to read its contents) with opendir, and read with readdir. A new directory can be created with mkdir, and an empty directory can be removed with rmdir (a non-empty directory can be recursively removed with rm). A temporary directory (with a unique random suffix) can be created with mkdtemp. Changes to a file or dierctory can be observed with watch.

The file system also provides symbolic links and hard links which simply point to an existing file or directory. Symbolic (or soft) links point to a file or directory through its path, while hard links point directly to the file. Therefore renaming/moving or removing the original file makes symbolic links dangling (pointing to non-existent file, and thus will not work) but hard links continue to work (think of them as shared pointers to a memory block). A hard link can be created with link, and a symbolic link (also called symlink) with symlink. Note that symlinks are basically files containing the path of target file or directory, and this path can be read with readlink. The full path of a symlink can be resolved with realpath. Hard links point directly to files, and thus do not have a "target" path. The additional properties attached to a symlink, such as access/update time, or ownership of the symlink can be obtained with lstat, and updated with lutimes, and lchown respectively. The access permissions of a symlink cannot be changed.

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, writeFileText, readJson and writeJson are included. For performing file/directory existence check async exists, assertExists, and assertNotExists can be used. Cleanup of one-item outer directories (which are usually created upon extracting a compressed file) can be performed with dehuskdir. This package previously included which(), which is now instead suitably included in extra-child-process package.

Stability: Experimental.


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


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


// 2. Read JSON file.
async function example2() {
  var json = xfs.readJsonSync('package.json');
  var json = await xfs.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 xfs.exists('LICENSE'))) throw 'May I see you license sir?';
  await xfs.assertExists('LICENSE');
}
example3();


// 4. Get contents of a directory.
async function example4() {
  var contents = xfs.readdirSync('src');
  var contents = await xfs.readdir('src');
  // → [ 'index.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.


References



ORG DOI