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

• Node.js File system API
• fs-extra package
• Soft and Hard links in Unix/Linux
• Why do Linux/POSIX have lchown but not lchmod?
• Linux Commands
• RegExr