premove

premove

A tiny (202B to 249B) utility to remove items recursively

This is a Promise-based, cross-platform utility that recursively removes files and directories. It's effectively a programmatic rm -rf for Node.js. There's also a CLI for easy, cross-platform usage.

Notice: Node v12.10.0 includes the recursive option for fs.rmdir and fs.rmdirSync.

Install

$ npm install --save premove

Modes

There are two "versions" of premove available:

"async"

Node.js: >= 8.x
Size (gzip): 249 bytes
Availability: CommonJS, ES Module

This is the primary/default mode. It makes use of async/await and util.promisify.

"sync"

Node.js: >= 6.x
Size (gzip): 202 bytes
Availability: CommonJS, ES Module

This is the opt-in mode, ideal for scenarios where async usage cannot be supported.
In order to use it, simply make the following changes:

-import { premove } from 'premove';
+import { premove } from 'premove/sync';

Usage

import { resolve } from 'path';
import { premove } from 'premove';

// Async/await
try {
  await premove('./foobar');
} catch (err) {
  //
}

// Promise
premove('./foobar').then(val => {
  console.log(val); //=> undefined
}).catch(err => {
  //
});

// Using `cwd` option
const dir = resolve('./foo/bar');
await premove('hello.txt', { cwd: dir });

CLI

A premove binary is available as of v4.0.0.
It accepts an optional --cwd value and a list of paths to delete.

Important: By default premove refuses to delete:

• the os.homedir
• the system root (/, C:\\, etc)
• items not contained by --cwd path

# remove "foo" and "bar" via `npx`
$ npx premove foo bar

# install globally, use whenever
$ npm install premove -g
$ premove foo bar

API

premove(str, opts={})

Returns: Promise<undefined> or false

Returns a Promise that resolves to undefined once complete.
Returns false immediately if the initial filepath (str) does not exist.

Important:
The sync and async versions share the same API.
The only difference is that sync is not Promise-based.

str

Type: String

The filepath to remove – may be a file or a directory.
An initial existence check is made for this filepath.

Important: This value is resolved to a full path.
Please be aware of how and from where the Node.js file system is resolving your path!

options.cwd

Type: String
Default: .

The directory to resolve your str from.
Defaults to the process.cwd() – aka, the directory that your command is run within.

Related

• totalist - A tiny (195B to 224B) utility to recursively list all (total) files in a directory
• mk-dirs - A tiny (420B) utility to make a directory and its parents, recursively
• escalade - A tiny (183B) and fast utility to ascend parent directories

License

MIT © Luke Edwards