fspp-ext

1.2.1 • Public • Published

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.
  • Revised and rewritten all the test cases, line coverage tools added.

1.1.0 / 2017-07-12

  • Simplefied implementation to match fspp 1.1.0 update.

1.0.7 / 2017-07-11

  • Bug-fix for Symbolic-link handling.

1.0.6 / 2017-07-10

  • Updated fspp for missing fs.write and fs.writeFile inheritance.

Lisense

Licensed under MIT Copyright (c) 2017 Phoenix Song

Package Sidebar

Install

npm i fspp-ext

Weekly Downloads

1

Version

1.2.1

License

MIT

Last publish

Collaborators

  • azusa0127