fs2
Functions that complement and extend fs package
Originally derived from node-ext package.
Installation
$ npm install fs2
API
chmod(path, mode[, cb]) (fs2/chmod)
Same as fs.chmod. Returns promise.
Not available on Windows.
copy(src, dest[, options[, cb]]) (fs2/copy)
Copy file, returns promise but accepts as well regular callback.
Eventual options are passed to underlying fs.createWriteStream
copyDir(src, dest[, options[, cb]]) (fs2/copy-dir)
Copy directory recursively, returns promise but accepts as well regular callback.
Supported options:
- loose - Do not error if file doesn't exits or is inaccessible, return false instead.
descriptorsHandler() (fs2/descriptors-handler)
Initializes EMFILE errors prevention.
To be used only in main modules. Never require it in generic module that may be required in others
How it works? If limit of descriptors is reached it holds the calls to native functions and releases them when taken descriptors are freed.
Internally it provides same solution as fs-graceful module with following differences:
- Focuses only on file descriptors limit problem
- Gives access to taken/available descriptors count and allows setting of limit by external module. Thanks to that we can also cover descriptors opened by fs.watch module (watch is bound to that module)
- Covers readdir calls (which also happen to throw EMFILE errors)
- More bulletproof (I assume) error handling logic
isDirectory(path[, cb]) (fs2/is-directory)
Whether path points to a directory
Resolves with true
if provided path points to a directory, false
if provided path points to a non-directory file, null
if there's no file at path. Returns promise.
isIgnored(mode, path[, options[, cb]]) (fs2/is-ignored)
Whether file is ignored up to predefined rules. Returns promise but regular callback is also supported.
Rules are decided by mode argument. Currently only git
mode is supported, in that case rules are searched in .gitignore files (Rules have effect only if placed in valid git repositories).
Other modes can be easily configured by extending _ignoreModes
module (See lib/fs/_ignore-modes directory to see how it's done).
Supported options:
- globalRules
string|array
- additional global rules. They will be matched as if placed in filesystem root directory, it means that any rules found in existing ignore files may override them. - watch
bool
- whether to watch for changes. If ignore state would change, returned promise would emit change
event with new value (true/false)
isSymlink(path[, options[, cb]]) (fs2/is-symlink)
Whether path points to a symlimk
Resolves with true
if provided path points to symlink, false
if provided path points to a non-symlink file, null
if there's no file at path. Returns promise.
Additionally resultion can be fine tuned for specific needs with below options:
Supported options:
- linkPath
string
- Expected linkPath to which symlink should point. If provided and symlink points elsewhere false
is returned. - recursive
bool
- whether check for matching linkPath
should be applied to final path (so if symlink points to other symlink we check against the final path, and not linked symlink path)
lchmod(path, mode[, cb]) (fs2/lchmod)
Same as fs.lchmod. Returns promise.
Only available on Mac OS X.
lstat(path[, cb]) (fs2/lstat)
Same as fs.lstat. Returns promise.
mkdir(path[, options|mode[, cb]]) (fs2/mkdir)
Extended version of native mkdir. Returns promise
Supported options:
- mode - Reflects mode in native version
- intermediate - Whether to create directories recursively (if parent is not created), reflects
mkir -p
, internal implementation inspired by Substack's node-mkdirp
readFile(path[, options][, cb]) (fs2/read-file)
Extended version of native fs.readFile. Returns promise
Supported options:
- loose - Do not error if file doesn't exits or is inaccessible, return null instead.
- watch - Whether to watch file for changes. Changes are emited via change event on returned promise. If file was removed and loose option is off, end event is emitted and watcher is closed
readdir(path[, options[, cb]]) (fs2/readdir)
Extended version of native fs.readdir. Returns promise
Suported options:
- depth
number
- Level of recurse into subdirectories. Defaults to 0 which resembles behavior of native version. If you want to recurse without any nest limitation just provide Infinity - type
object
- Which type of files should be returned. By default all files are returned. Stats methods shows how many different types can be returned. To narrow it down provide a hash. e.g. { file: true, symbolicLink: true }
. - pattern
regexp
- Filter returned files by specific pattern. Pattern should be regular expression that would be matched against full path. - watch
bool
- Watch directory for changes. Changes are emitted on returned promise with data
events. event object states which files were added (event.added
) and which were removed (event.removed
), Starting from next release (v0.4) this functionality will most likely be provided as valid Node.js stream - stream
bool
- Whether to provide data continuously. Currently it's not provided as a stream per se (it would be starting from next release, v0.4), data is emited as data
events on returned promise object, structure of event objects described under watch option - ignoreRules
string|array
- Whether to obey ignore rules found in ignore files. See fs.isIgnored for more information - globalRules
string|array
- Global rules that complement ignoreRules. See fs.isIgnored for more information.
readlink(path[, options[, cb]]) (fs2/readlink)
Same as fs.readlink. Returns promise.
Supports loose: true
option, which when passed, resolves with null
(instead of exception) if file at path is not a symlink or it doesn't exist.
realpath(path[, options[, cb]]) (fs2/realpath)
Same as fs.realpath. Returns promise.
Supports loose: true
option, which when passed, resolves with null
(instead of exception) if path doesn't exist
rename(oldPath, newPath[, cb]) (fs2/rename)
Same as fs.rename. Returns promise.
rmdir(path[, options[, cb]]) (fs2/rmdir)
Extended version of native rmdir. Returns promise
Supported options:
- recursive - Attempt to remove directory with subdirectories recursively.
- force - Attempt to remove other files within directory as well.
stat(path[, cb]) (fs2/stat)
Same as fs.stat. Returns promise.
symlink(srcPath, dstPath[, type[, cb]]) (fs2/symlink)
Same as fs.symlink. Returns promise.
typeByStats(stats) (fs2/type-by-stats)
Returns type of file according to provided stats object.
unlink(path[, cb]) (fs2/unlink)
Same as fs.unlink. Returns promise.
watchPath(path) (fs2/watch-path)
Watch specific path for changes. It's about observing specific file path (not directory content). change
events are emitted with event object where event.type
says wether file was created, modified or removed.
watch(path) (fs2/watch)
Watch file for changes.
fs.watch wrapper that works same way on every platform, always configured in persistent: false mode.
It's aware of open file descriptors limitations, if EMFILE error is approach, switch to alternative mode that pings file stats (see fs.watchFile) is made.
writeFile(filename, data[, options|encoding[, callback]]) (fs2/write-file)
Same as native fs.writeFile but safe for simultaneous calls of write to same file (in such case current write will be abandonded, and new would be started).
Supported options:
- encoding - Reflects encoding in native version
- intermediate - In case directory doesn't exist, whether to create full directory path
Tests
$ npm test