Filesystem wrapper for node.js. Provides a promisified API, along with a
consistent interface accross node.js versions. All changes to the node.js fs
API are tracked and accounted for in:
fs.exists(path, [mode]) (async) - A fixed version of fs.exists. Basically
a wrapper around fs.access which returns false on ENOENT or EACCESS.
Accepts fs.access flags as the second argument.
fs.move(src, dest) (async) - Try to rename file. Recursively copies across
devices, deleting the original, if necessary.
fs.moveSync(path, [mode]) - Synchronous fs.move.
fs.outputFile(path, data, [options]) (async) - Output file while ensuring
the preceding directory structure exists. Basically a mkdirp wrapper around
writeFile().
flags (number) - A bitfield to be passed to fs.copyFile{,Sync} as flags
(default: 0).
filter(path, stat, depth) (function) - A callback to filter determine which
files are copied (default: null).
follow (boolean) - Whether to follow symlinks for src (default: false).
overwrite (boolean) - Whether to overwrite existing files at the
destination (default: false).
timestamps (boolean) - Whether to preserve file timestamps (default:
false).
fs.readJSON options
Options are the standard fs.readFile options with some extras:
reviver(key, value) (function) - Reviver function for JSON parsing
(default: null).
Options may also be a function as an alias for the reviver option.
fs.remove options
filter(path, stat, depth) (function) - A callback to filter determine which
files are removed (default: null).
maxRetries (number) - Number of retries for EBUSY, EMFILE, ENFILE,
ENOTEMPTY, or EPERM (default: 3).
retryDelay (number) - Number of milliseconds to wait in between retries.
Options may also be a function as an alias for the filter option.
fs.stats options
fs.stats and fs.statsSync accept an object with properties:
follow (boolean) - Whether to attempt calling fs.stat before
fs.lstat. If false, behavior is identical to fs.lstat (default: true).
bigint (boolean) - Whether to use BigInts on the fs.Stats struct
(default: false).
Options may also be a boolean as an alias for the follow option.
fs.{traverse,walk} options
fs.traverse, fs.traverseSync, fs.walk, and fs.walkSync accept an object
with properties:
bigint (boolean) - Whether to use BigInts on the fs.Stats struct
(default: false).
dirs (boolean) - Whether to return directories in the iterated results
(default: false).
files (boolean) - Whether to return non-directory files in the iterated
results (default: false).
filter(path, stat, depth) (function) - A callback to filter determine which
directories are entered and which files are returned. Note that stat may be
null if options.throws is false (default: null).
follow (boolean) - Whether to follow symlinks. Note that the walking
functions are smart enough to avoid recursive symlink loops (default:
true).
maxDepth (number) - Maximum depth to traverse. For reference, paths are
depth 0. Set to -1 for no limit (default: -1).
throws (boolean) - Whether to throw on stat failure (default: false).
fs.writeJSON options
Options are the standard fs.writeFile options with some extras:
replacer(key, value) (function) - Replacer function for JSON
stringification (default: null).
spaces (number) - Number of spaces to indent by (default: 2).
eol (string) - Line ending to use for the output text (default: \n).
Options may also be a function as an alias for the reviver option, or a
number for the spaces option.
Detecting broken symlinks with fs.stats and fs.{traverse,walk}
fs.stats and the walking functions allow you to detect broken symlinks easily
when the follow option is on:
const stat = await fs.statsTry('./foobar');if (!stat) // ENOENT or EACCES throw new Error('File not found.');if (stat.isSymbolicLink()) // A symlink we couldn't resolve throw new Error('Broken symlink detected.');
Contribution and License Agreement
If you contribute code to this project, you are implicitly allowing your code
to be distributed under the MIT license. You are also implicitly verifying that
all code is your original work. </legalese>
License
Copyright (c) 2014-2019, Christopher Jeffrey (MIT License).
fs.stats(path, [options]) (async) - A stat function which will attempt to
call fs.lstat if fs.stat fails with ENOENT or EACCES (depending on
options). This is useful for detecting broken symlinks and getting their
appropriate stat object. Accepts options in the form of
{ follow: [boolean], bigint: [boolean] }.
fs.walk(paths, [options]) - An async iterator which recursively walks the
target path/paths. Returns entries in the form of [path, stat, depth].
Note that stat may be null in the event of an EACCES, EPERM, or
ELOOP if options.throws is false.