Fspp-ext NPM | npm.io

fspp-ext

fspp-extended - A minimal augumentation to fs module, with promise support.

Why fspp-ext ?

No other dependent (fspp is just a bare warapper for fs with util.promisify from NodeJS official).
Cross-platform consideration (paths are dealed delicately for both Windows/Unix systems).
Minimal style (Single file implementation, readable code with easy adaptation).
Morden (Powered by ES7 async/await with util.promisify).
Reliable (Carefully tested with dedicate BDD Mocha tests).

Requirement

NodeJS v8.0.0 and up, as fspp is using util.promisify added in v8.0.0;

Install

npm install --save fspp-ext

Usage

const fs = require(`fspp-ext`); // fspp-ext is a drop-in replacement for fs or fspp.

API

Unique APIs

ensureDir( dirPath , force )

dirPath {string|Buffer} directory path to be created, can be either a relative path or absolute path.
force {bool} Optional if true, automatically remove existing file at dirPath with the same name (default: false).

Asynchronously create the dirPath directory and all the missing super directories.

Will do nothing if the dirPath is an existing directory.

Example:

fs.ensureDir(`hello/world/and/again`)
  .then(()=> console.log(`${process.cwd()}/hello/world/and/again exists now.`))
  .catch(err => console.error(err))
});
// or
await fs.ensureDir(`hello/world/and/again`);

Exception/Rejection Conditions:

When any of the super-directory is not writable by current process (e.g. /dev/root).
When accessing a non-existing Driver on windows (e.g. X:\X_DISK_DOES_NOT_EXIST).
When any part of dirPath is an existing file and force=false.

ensureDirSync( dirPath , force )

The synchronous version of ensureDir(dirPath).

rm( dirPath , force)

dirPath {string|Buffer} directory path to be destroyed, can be either a relative path or absolute path.
force {bool} Optional Do not prompt when dirPath does not exist and automatically accuires permissions for readonly folders (default:false).

Asynchronously remove dirPath file|directory and all of its sup-items recursively.

Example:

fs.rm(`hello`)
  .then(()=> console.log(`${process.cwd()}/hello is now removed.`))
  .catch(err => console.error(err))
});
// or
await fs.rm(`/tmp/hello/world/and/again`);

Exception/Rejection Conditions:

When dirPath is the root directory (e.g. / or D:/), that's likely a typo.
When dirPath does not exist. (When force=false)
When any of the item failed to be removed (due to permission or is activated or removed in progress).

rmSync( dirPath )

The synchronous version of rm(dirPath [, force]).

cp( srcPath, desPath , force)

srcPath {string|Buffer} path to the item to be copied.
desPath {string|Buffer} path to the folder to be copied into.
force {bool} Optional force overriding existing files. (default false)

Asynchronously copy everything from srcPath to desPath recursively.

Note: if desPath is an existing directory and srcPath is a directory with different name or a file, srcPath will be copied into a sub-item under desPath instead of been renamed into desPath.

Example:

fs.rm(`hello`)
  .then(()=> console.log(`${process.cwd()}/hello is now removed.`))
  .catch(err => console.error(err))
});
// or
await fs.rm(`/tmp/hello/world/and/again`);

Exception/Rejection Conditions:

When desPath is a sub directory of srcPath.
When srcPath does not exist.
When any of the item cannot be accessed (due to permission or is activated or removed in progress).

pathSearch(itemName , rootPath)

itemName {string} The target item name.
rootPath {string} Optional The root directory path to start the search with (default:.).

Asynchronously search the exact path of item with the name of itemName under rootPath, returns the absolute path of the first one find or false.

Example:

const p = await fs.pathSearch(`Local`, process.env.USERPROFILE);
// p === `C:\\User\\[username]\\AppData\\Local`

Exception/Rejection Conditions:

When rootPath does not exist or not accessable.

pathSearchSync(itemName , rootPath)

itemName {string} The target item name.
rootPath {string} Optional The root directory path to start the search with (default:.).

Sync version of pathSearch(itemName [, rootPath])

Example:

const p = fs.pathSearchSync(`Local`, process.env.USERPROFILE);
// p === `C:\\User\\[username]\\AppData\\Local`

Exception/Rejection Conditions:

When rootPath does not exist or not accessable.

Inherited fs/fspp APIs

Please check fspp and official document for fs

Changelog

1.2.1 / 2017-09-21

(Added) new API pathSearch(itemName [, rootPath]) and pathSearchSync(itemName [, rootPath]).

1.2.0 / 2017-07-15

(Added) new API ensureDir(dirPath, force) and ensureDirSync(dirPath, force).

(Deprecated) ensurePath( dirPath ) and ensurePathSync( dirPath ) are now deprecated due to ambigious behaviour on existing files, please use ensureDir(dirPath, force) and ensureDirSync(dirPath, force) instead.

Revised rm(dirPath, force) and rmSync(dirPath, force) that now provides a force paramater flag for readonly folders and keep silent when dirPath not exist.