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.

1const xfs = require('extra-fs');
2
3
4// 1. Read file text.
5async function example1() {
6  var text = xfs.readFileTextSync('.npmignore');
7  var text = await xfs.readFileText('.npmignore');
8  // → # Source only
9  // → .gitmodules
10  // → .github/
11  // → .docs/
12  // → ...
13}
14example1();
15
16
17// 2. Read JSON file.
18async function example2() {
19  var json = xfs.readJsonSync('package.json');
20  var json = await xfs.readJson('package.json');
21  // → {
22  // →   name: 'extra-fs',
23  // →   version: '3.0.27',
24  // →   description: 'Useful additions to inbuilt fs module.',
25  // →   ...
26  // → }
27}
28example2();
29
30
31// 3. Assert that a file exists.
32async function example3() {
33  if (!(await xfs.exists('LICENSE'))) throw 'May I see you license sir?';
34  await xfs.assertExists('LICENSE');
35}
36example3();
37
38
39// 4. Get contents of a directory.
40async function example4() {
41  var contents = xfs.readdirSync('src');
42  var contents = await xfs.readdir('src');
43  // → [ 'index.ts' ]
44}
45example4();

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