fs-syncx
v0.1.2fs-syncx
** It is recommended to use the async version of this package: m-fs. Use this package only when you can't use async functions **
Useful sync methods for file system.
Installation
# npm
npm install --save fs-syncx
# yarn
yarn add fs-syncx
JavaScript:
const fss = require('fs-syncx');
TypeScript:
import fss from 'fs-syncx';
Run tests
# npm
npm test
# yarn
yarn test
API
the catchExp
argument
It is crucial to first understand how fs-syncx API handles errors. Almost every API provided by fs-syncx contains an argument named catchExp
.
Possible values:
- [Default]
undefined
orfalse
: ignores all errors. Returns an empty valuenull
orfalse
. true
: let any error throw. This is the same behavior like original Node.js fs sync APIs.(state, error) => {}
callback: reports all errors in a callback.
Examples:
const fss = require('fs-syncx');
const FILE = '/__file_does_not_exist__';
// catchExp is false, no error is thrown, returns false if errors occur
fss.fileExists(FILE);
// false
// catchExp is a callback, use callback to get errors
fss.fileExists(FILE, (state, err) => {
console.log(`state: ${state}, error: ${err}`);
});
// state: /__file_does_not_exist__, error: Error: ENOENT: no such file or directory, lstat '/__file_does_not_exist__'
// false
// catchExp is true, just throw errors
fss.fileExists(FILE, true);
// *** Error thrown ***
/* Error: ENOENT: no such file or directory, lstat '/__file_does_not_exist__'
at Object.fs.lstatSync (fs.js:947:11)
...
*/
Note that using a callback as catchExp
is especially useful when you want to get multiple errors, for example:
/* list all files recursively in a directory */
// catchExp is true, if accessing a directory throws an error, the function failed with that error
fss.listFiles({ path: 'some directory', recursive: true }, true);
// *** Error thrown ***
/* Some directory is not accessible... */
// if catchExp is a callback, all errors will be reported and the function won't stop executing
fss.listFiles({ path: 'some directory', recursive: true }, (state, err) => {
console.log(`state: ${state}, error: ${err}`);
});
// state: some directory, error: not accessible
// state: some directory, error: not accessible
// state: some directory, error: system error
// returns an array of FileInfos
APIs
pathInfo
Returns an PathInfo
object containing information about a given path.
pathInfo(path, catchExp): PathInfo
PathInfo
object:
{
name: 'abc', // the name of the path
path: './abc', // the original path object you passed in
fullPath: '/users/mgen/documents/abc', // the absolute resolved path
isDir: true, // true if the path is a directory
isFile: false, // true if the path is a file,
stat: ..., // raw object returned from fs.lstatSync
}
fileExists
Returns true if the given path is a file.
fileExists(path, catchExp): bool
dirExists
Returns true if the given path is a directory.
dirExists(path, catchExp): bool
listDirs
, listFiles
, listPaths
listDirs
returns an array ofPathInfo
representing sub-directories in a directory.listStringDirs
likelistDirs
, returns an array ofstring
instead.listFiles
returns an array ofPathInfo
representing sub-files in a directory.listStringFiles
likelistFiles
, returns an array ofstring
instead.listPaths
returns an array ofPathInfo
representing all sub-paths in a directory.listStringPaths
likelistPaths
, returns an array ofstring
instead.
listDirs(path|opt, catchExp): [PathInfo]
listStringDirs(path|opt, catchExp): [string]
listFiles(path|opt, catchExp): [PathInfo]
listStringFiles(path|opt, catchExp): [string]
listPaths(path|opt, catchExp): [PathInfo]
listStringPaths(path|opt, catchExp): [string]
path
path string.opt
object, possible properties:path
path string.recursive
list children recursively, defaultfalse
.
Note that these functions return an array of PathInfo
objects, you can use JavaScript map
function to convert them to an array of strings.
const fss = require('fs-syncx');
const DIR = 'node_modules';
// PathInfo.name: relative path
fss.listDirs(DIR).map(d => d.name);
// [ 'fs-syncx', 'is-string' ]
// PathInfo.fullPath: absolute path
fss.listDirs(DIR).map(d => d.fullPath);
/* [ '/Users/me/proj/node_modules/fs-syncx',
'/Users/me/proj/node_modules/is-string' ] */
readTextFile
Reads the contents of a file in UTF8 encoding. Like fs.readFile
, but encoding defaults to utf8
.
readTextFile(path, catchExp): string
writeFileSync
Like fs.writeFileSync
, but calls mkdir -p
before writing the file.
License
MIT