README
fsxt
Improved fork of fs-extra
with extra [sic] features (and semicolons!)
fsxt
provides support for node.js 10 and above.
Installation
npm install --save fsxt
Or install with your preferred package manager (yarn, pnpm, ...)
Usage
fsxt
is a drop-in replacement for the node.js core fs
module. All methods in fs
can be used in their standard forms in fsxt, with some
improvements.
You don't ever need to include the original fs
module again:
const fs = require('fs'); // this is no longer necessary
you can now do this:
const fs = require('fsxt');
or if you prefer to make it clear that you're using fsxt
and not fs
, you may want to name your
fs
variable fsxt
like so:
const fsxt = require('fsxt');
you can also keep both, but it's redundant:
const fs = require('fs');
const fsxt = require('fsxt');
Improvements on fs
All the improvements from mz/fs
are included,
which also includes improvements from graceful-fs
.
Most methods are async by default, returning a Promise that resolves to the method's result, or rejects if the operation fails.
Sync methods on the other hand will throw if an error occurs, and directly return the resulting value to the caller if the operation succeeds.
You can also use the methods in the legacy node.js form, passing a callback as the last parameter,
as a function that takes (Error, <result>)
parameters, but it's not recommended, and those
variants may be removed in a later (major) version.
Additionally, see notes on fs.read()
& fs.write()
if you're using
either method.
Example use:
const fs = require('fsxt');
// Async with promises:
fs.copy('/tmp/myfile', '/tmp/mynewfile')
.then(() => console.log('success!'))
.catch(err => console.error(err));
// Async with callbacks:
fs.copy('/tmp/myfile', '/tmp/mynewfile', err => {
if (err) return console.error(err);
console.log('success!');
});
// Sync:
try {
fs.copySync('/tmp/myfile', '/tmp/mynewfile');
console.log('success!');
} catch (err) {
console.error(err);
}
// Async/Await:
async function copyFiles () {
try {
await fs.copy('/tmp/myfile', '/tmp/mynewfile');
console.log('success!');
} catch (err) {
console.error(err);
}
}
copyFiles();
Methods
The documentation is available at https://uwx-node-modules.github.io/fsxt/typedoc/globals.html.
You can also find the documentation for just the methods added in fsxt that aren't in fs-extra at https://uwx-node-modules.github.io/fsxt/typedoc-fsxt-only/globals.html.
The docs don't include descriptions for methods inherited from fs-extra, but you can find them here:
- copy | copySync
- emptyDir | emptyDirSync
- ensureFile | ensureFileSync
- ensureDir | ensureDirSync
- ensureLink | ensureLinkSync
- ensureSymlink | ensureSymlinkSync
- mkdirp | mkdirpSync
- mkdirs | mkdirsSync
- move | moveSync
- outputFile | outputFileSync
- outputJson | outputJsonSync
- pathExists | pathExistsSync
- readJson | readJsonSync
- remove | removeSync
- writeJson | writeJsonSync
The core node.js fs
module methods are also
available; although the node.js documentation doesn't show Promise overloads of the async methods,
you can find them at:
- Class: fs.Stats
- fs.access(path[, mode], callback)
- fs.accessSync(path[, mode])
- fs.appendFile(path, data[, options], callback)
- fs.appendFileSync(path, data[, options])
- fs.chmod(path, mode, callback)
- fs.chmodSync(path, mode)
- fs.chown(path, uid, gid, callback)
- fs.chownSync(path, uid, gid)
- fs.close(fd, callback)
- fs.closeSync(fd)
- fs.constants
- fs.copyFile(src, dest[, flags], callback)
- fs.copyFileSync(src, dest[, flags])
- fs.createReadStream(path[, options])
- fs.createWriteStream(path[, options])
- fs.exists(path, callback)
- fs.existsSync(path)
- fs.fchmod(fd, mode, callback)
- fs.fchmodSync(fd, mode)
- fs.fchown(fd, uid, gid, callback)
- fs.fchownSync(fd, uid, gid)
- fs.fdatasync(fd, callback)
- fs.fdatasyncSync(fd)
- fs.fstat(fd[, options], callback)
- fs.fstatSync(fd[, options])
- fs.fsync(fd, callback)
- fs.fsyncSync(fd)
- fs.ftruncate(fd[, len], callback)
- fs.ftruncateSync(fd[, len])
- fs.futimes(fd, atime, mtime, callback)
- fs.futimesSync(fd, atime, mtime)
- fs.lchmod(path, mode, callback)
- fs.lchmodSync(path, mode)
- fs.lchown(path, uid, gid, callback)
- fs.lchownSync(path, uid, gid)
- fs.link(existingPath, newPath, callback)
- fs.linkSync(existingPath, newPath)
- fs.lstat(path[, options], callback)
- fs.lstatSync(path[, options])
- fs.mkdir(path[, options], callback)
- fs.mkdirSync(path[, options])
- fs.mkdtemp(prefix[, options], callback)
- fs.mkdtempSync(prefix[, options])
- fs.open(path[, flags[, mode]], callback)
- fs.openSync(path[, flags, mode])
- fs.read(fd, buffer, offset, length, position, callback)
- fs.readdir(path[, options], callback)
- fs.readdirSync(path[, options])
- fs.readFile(path[, options], callback)
- fs.readFileSync(path[, options])
- fs.readlink(path[, options], callback)
- fs.readlinkSync(path[, options])
- fs.readSync(fd, buffer, offset, length, position)
- fs.realpath(path[, options], callback)
- fs.realpath.native(path[, options], callback)
- fs.realpathSync(path[, options])
- fs.realpathSync.native(path[, options])
- fs.rename(oldPath, newPath, callback)
- fs.renameSync(oldPath, newPath)
- fs.rmdir(path, callback)
- fs.rmdirSync(path)
- fs.stat(path[, options], callback)
- fs.statSync(path[, options])
- fs.symlink(target, path[, type], callback)
- fs.symlinkSync(target, path[, type])
- fs.truncate(path[, len], callback)
- fs.truncateSync(path[, len])
- fs.unlink(path, callback)
- fs.unlinkSync(path)
- fs.unwatchFile(filename[, listener])
- fs.utimes(path, atime, mtime, callback)
- fs.utimesSync(path, atime, mtime)
- fs.watch(filename[, options][, listener])
- fs.watchFile(filename[, options], listener)
- fs.write(fd, buffer[, offset[, length[, position]]], callback)
- fs.write(fd, string[, position[, encoding]], callback)
- fs.writeFile(file, data[, options], callback)
- fs.writeFileSync(file, data[, options])
- fs.writeSync(fd, buffer[, offset[, length[, position]]])
- fs.writeSync(fd, string[, position[, encoding]])
Third Party
File / Directory Watching
If you want to watch for changes to files or directories, then you should use chokidar.
Misc.
- mfs - Monitor your fsxt calls.
Hacking on fsxt
Do you want to hack on fsxt? Well, you probably shouldn't. Still, you can go ahead and send a PR.
Please, no changes to anything in the lib
folder; the contents of that folder are almost entirely
verbatim from fs-extra, so they should be submitted upstream.
fsxt uses the Google Style. It's pretty.
Running the Test Suite
fsxt contains like at least 4 tests that pass.
npm run lint
: runs eslintnpm run unit
: runs the unit testsnpm test
: runs both the linter and the tests
Windows
If you run the tests on the Windows and receive a lot of symbolic link EPERM
permission errors,
it's because on Windows you need elevated privilege to create symbolic links. You can either run the
tests as Administrator or run node testlite
to test only fsxt-exclusive methods, which doesn't
include symbolic links
Legal
Licensed under MIT. Full license text available at LICENSE.txt
fs-extra
is copyright (c) 2011-2017 JP Richardson
fsxt
is copyright © 2016-2018 uwx, some rights reserved.
Parts of the documentation were taken from other modules and the Node.js fs
module.
Relevant licenses are included at the following locations:
- LICENSE.DefinitelyTyped.txt
- LICENSE.DefinitelyTyped-generator.txt
- LICENSE.fs-extra.txt
- LICENSE.fs-vacuum.txt
- LICENSE.nodejs.txt
- external/LICENSE.fs-vacuum.txt
- external/LICENSE.path-is-inside.txt
- external/LICENSE.rimraf.txt
- external/LICENSE.append.txt
- external/LICENSE.dive.txt
- external/LICENSE.dive-sync.txt
fs-extra
and fsxt
are not endorsed by or affiliated with Joyent or the Node.js Foundation.
fsxt
is not endorsed by or affiliated with JP Richardson.