fs: add rm method

nodejs · iansu · Oct 4, 2020 · Oct 4, 2020 · Oct 7, 2020 · Oct 7, 2020
commit 9845d05844288b7d66f4bd2e6835ed9fd04059fc
diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
@@ -2650,6 +2650,16 @@ Type: Documentation-only
 The [`crypto.Certificate()` constructor][] is deprecated. Use
 [static methods of `crypto.Certificate()`][] instead.
 
+### DEP0147: `Permissive rmdir recursive is deprecated, use rm recursive`
+<!-- YAML
+changes:
+  - version: v15.0.0
+    pr-url: https://github.com/nodejs/node/pull/?
+    description: Runtime deprecation.
+-->
+
+Type: Runtime
+
 [Legacy URL API]: url.md#url_legacy_url_api
 [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
 [RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3

diff --git a/doc/api/errors.md b/doc/api/errors.md
@@ -928,6 +928,11 @@ added: v14.0.0
 Used when a feature that is not available
 to the current platform which is running Node.js is used.
 
+<a id="ERR_FS_EISDIR"></a>
+### `ERR_FS_EISDIR`
+
+Path is a directory.
+
 <a id="ERR_FS_FILE_TOO_LARGE"></a>
 ### `ERR_FS_FILE_TOO_LARGE`
 

diff --git a/doc/api/fs.md b/doc/api/fs.md
@@ -3598,6 +3598,51 @@ that represent files will be deleted. The permissive behavior of the
 `recursive` option is deprecated, `ENOTDIR` and `ENOENT` will be thrown in
 the future.
 
+## `fs.rm(path[, options], callback)`
+<!-- YAML
+added: v15.0.0
+-->
+
+* `path` {string|Buffer|URL}
+* `options` {Object}
+  * `force` Ignore errors
+  * `maxRetries` {integer} If an `EBUSY`, `EMFILE`, `ENFILE`, `ENOTEMPTY`, or
+    `EPERM` error is encountered, Node.js will retry the operation with a linear
+    backoff wait of `retryDelay` ms longer on each try. This option represents
+    the number of retries. This option is ignored if the `recursive` option is
+    not `true`. **Default:** `0`.
+  * `recursive` {boolean} If `true`, perform a recursive removal. In
+    recursive mode operations are retried on failure. **Default:** `false`.
+  * `retryDelay` {integer} The amount of time in milliseconds to wait between
+    retries. This option is ignored if the `recursive` option is not `true`.
+    **Default:** `100`.
+* `callback` {Function}
+  * `err` {Error}
+
+Asynchronous rm(2). No arguments other than a possible exception are given
+to the completion callback.
+
+## `fs.rmSync(path[, options])`
+<!-- YAML
+added: v15.0.0
+-->
+
+* `path` {string|Buffer|URL}
+* `options` {Object}
+  * `force` Ignore errors
+  * `maxRetries` {integer} If an `EBUSY`, `EMFILE`, `ENFILE`, `ENOTEMPTY`, or
+    `EPERM` error is encountered, Node.js will retry the operation with a linear
+    backoff wait of `retryDelay` ms longer on each try. This option represents
+    the number of retries. This option is ignored if the `recursive` option is
+    not `true`. **Default:** `0`.
+  * `recursive` {boolean} If `true`, perform a recursive directory removal. In
+    recursive mode operations are retried on failure. **Default:** `false`.
+  * `retryDelay` {integer} The amount of time in milliseconds to wait between
+    retries. This option is ignored if the `recursive` option is not `true`.
+    **Default:** `100`.
+
+Synchronous rm(2). Returns `undefined`.
+
 ## `fs.stat(path[, options], callback)`
 <!-- YAML
 added: v0.0.2

diff --git a/lib/fs.js b/lib/fs.js
@@ -93,6 +93,8 @@ const {
   validateOffsetLengthRead,
   validateOffsetLengthWrite,
   validatePath,
+  validateRmOptions,
+  validateRmOptionsSync,
   validateRmdirOptions,
   validateStringAfterArrayBufferView,
   warnOnNonPortableTemplate
@@ -847,30 +849,64 @@ function rmdir(path, options, callback) {
 
   callback = makeCallback(callback);
   path = pathModule.toNamespacedPath(getValidatedPath(path));
-  options = validateRmdirOptions(options);
 
-  if (options.recursive) {
-    lazyLoadRimraf();
-    return rimraf(path, options, callback);
-  }
+  if (options && options.recursive) {
+    options = validateRmOptions(
+      path,
+      { ...options, force: true },
+      true,
+      (err, options) => {
+        if (err) {
+          return callback(err);
+        }
 
-  const req = new FSReqCallback();
-  req.oncomplete = callback;
-  binding.rmdir(path, req);
+        lazyLoadRimraf();
+        return rimraf(path, options, callback);
+      });
+
+  } else {
+    options = validateRmdirOptions(options);
+    const req = new FSReqCallback();
+    req.oncomplete = callback;
+    return binding.rmdir(path, req);
+  }
 }
 
 function rmdirSync(path, options) {
   path = getValidatedPath(path);
-  options = validateRmdirOptions(options);
 
-  if (options.recursive) {
+  if (options && options.recursive) {
+    options = validateRmOptionsSync(path, { ...options, force: true }, true);
     lazyLoadRimraf();
     return rimrafSync(pathModule.toNamespacedPath(path), options);
   }
 
+  options = validateRmdirOptions(options);
   const ctx = { path };
   binding.rmdir(pathModule.toNamespacedPath(path), undefined, ctx);
-  handleErrorFromBinding(ctx);
+  return handleErrorFromBinding(ctx);
+}
+
+function rm(path, options, callback) {
+  if (typeof options === 'function') {
+    callback = options;
+    options = undefined;
+  }
+
+  validateRmOptions(path, options, false, (err, options) => {
+    if (err) {
+      return callback(err);
+    }
+    lazyLoadRimraf();
+    return rimraf(path, options, callback);
+  });
+}
+
+function rmSync(path, options) {
+  options = validateRmOptionsSync(path, options, false);
+
+  lazyLoadRimraf();
+  return rimrafSync(path, options);
 }
 
 function fdatasync(fd, callback) {
@@ -2022,6 +2058,8 @@ module.exports = fs = {
   realpathSync,
   rename,
   renameSync,
+  rm,
+  rmSync,
   rmdir,
   rmdirSync,
   stat,

diff --git a/lib/internal/errors.js b/lib/internal/errors.js
@@ -838,6 +838,7 @@ E('ERR_FEATURE_UNAVAILABLE_ON_PLATFORM',
   'The feature %s is unavailable on the current platform' +
   ', which is being used to run Node.js',
   TypeError);
+E('ERR_FS_EISDIR', 'is a directory', SystemError);
 E('ERR_FS_FILE_TOO_LARGE', 'File size (%s) is greater than 2 GB', RangeError);
 E('ERR_FS_INVALID_SYMLINK_TYPE',
   'Symlink type must be one of "dir", "file", or "junction". Received "%s"',

diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js
@@ -52,6 +52,7 @@ const {
   validateBufferArray,
   validateOffsetLengthRead,
   validateOffsetLengthWrite,
+  validateRmOptionsSync,
   validateRmdirOptions,
   validateStringAfterArrayBufferView,
   warnOnNonPortableTemplate
@@ -417,6 +418,13 @@ async function ftruncate(handle, len = 0) {
   return binding.ftruncate(handle.fd, len, kUsePromises);
 }
 
+async function rm(path, options) {
+  path = pathModule.toNamespacedPath(getValidatedPath(path));
+  options = validateRmOptionsSync(path, options);
+
+  return rimrafPromises(path, options);
+}
+
 async function rmdir(path, options) {
   path = pathModule.toNamespacedPath(getValidatedPath(path));
   options = validateRmdirOptions(options);
@@ -635,6 +643,7 @@ module.exports = {
     opendir: promisify(opendir),
     rename,
     truncate,
+    rm,
     rmdir,
     mkdir,
     readdir,

diff --git a/lib/internal/fs/utils.js b/lib/internal/fs/utils.js
@@ -17,6 +17,7 @@ const {
 const { Buffer } = require('buffer');
 const {
   codes: {
+    ERR_FS_EISDIR,
     ERR_FS_INVALID_SYMLINK_TYPE,
     ERR_INVALID_ARG_TYPE,
     ERR_INVALID_ARG_VALUE,
@@ -650,28 +651,127 @@ function warnOnNonPortableTemplate(template) {
   }
 }
 
+const defaultRmOptions = {
+  recursive: false,
+  force: false,
+  retryDelay: 100,
+  maxRetries: 0
+};
+
 const defaultRmdirOptions = {
   retryDelay: 100,
   maxRetries: 0,
   recursive: false,
 };
 
-const validateRmdirOptions = hideStackFrames((options) => {
-  if (options === undefined)
-    return defaultRmdirOptions;
-  if (options === null || typeof options !== 'object')
-    throw new ERR_INVALID_ARG_TYPE('options', 'object', options);
+let permissiveRmdirWarned = false;
 
-  options = { ...defaultRmdirOptions, ...options };
+function emitPermissiveRmdirWarning() {
+  if (!permissiveRmdirWarned) {
+    process.emitWarning(
+      'Permissive rmdir recursive is deprecated, use rm recursive instead',
+      'DEP0147'
+    );
+    permissiveRmdirWarned = true;
+  }
+}
 
-  if (typeof options.recursive !== 'boolean')
-    throw new ERR_INVALID_ARG_TYPE('recursive', 'boolean', options.recursive);
+const validateRmOptions = (path, options, warn, callback) => {
+  try {
+    options = validateRmdirOptions(options, defaultRmOptions);
+  } catch (err) {
+    return callback(err);
+  }
 
-  validateInt32(options.retryDelay, 'retryDelay', 0);
-  validateUint32(options.maxRetries, 'maxRetries');
+  if (typeof options.force !== 'boolean')
+    return callback(
+      new ERR_INVALID_ARG_TYPE('force', 'boolean', options.force)
+    );
+
+  lazyLoadFs().stat(path, (err, stats) => {
+    if (err && err.code === 'ENOENT') {
+      if (options.force) {
+        if (warn) {
+          emitPermissiveRmdirWarning();
+        }
+        return callback(null, options);
+      }
+      return callback(err, options);
+    }
+
+    if (err) {
+      return callback(err);
+    }
+
+    if (warn && !stats.isDirectory()) {
+      emitPermissiveRmdirWarning();
+    }
+
+    if (stats.isDirectory() && !options.recursive) {
+      return callback(new ERR_FS_EISDIR({
+        code: 'EISDIR',
+        message: 'is a directory',
+        path,
+        syscall: 'rm',
+        errno: -21
+      }));
+    }
+    return callback(null, options);
+  });
+};
+
+const validateRmOptionsSync = (path, options, warn) => {
+  options = validateRmdirOptions(options, defaultRmOptions);
+
+  if (typeof options.force !== 'boolean')
+    throw new ERR_INVALID_ARG_TYPE('force', 'boolean', options.force);
+
+  try {
+    const stats = lazyLoadFs().statSync(path);
+
+    if (warn && !stats.isDirectory()) {
+      emitPermissiveRmdirWarning();
+    }
+
+    if (stats.isDirectory() && !options.recursive) {
+      throw new ERR_FS_EISDIR({
+        code: 'EISDIR',
+        message: 'is a directory',
+        path,
+        syscall: 'rm',
+        errno: -21
+      });
+    }
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      throw err;
+    } else if (err.code === 'ENOENT' && !options.force) {
+      throw err;
+    } else if (warn && err.code === 'ENOENT') {
+      emitPermissiveRmdirWarning();
+    }
+  }
 
   return options;
-});
+};
+
+const validateRmdirOptions = hideStackFrames(
+  (options, defaults = defaultRmdirOptions) => {
+    if (options === undefined)
+      return defaults;
+    if (options === null || typeof options !== 'object')
+      throw new ERR_INVALID_ARG_TYPE('options', 'object', options);
+
+    options = { ...defaults, ...options };
+
+    if (typeof options.recursive !== 'boolean')
+      throw new ERR_INVALID_ARG_TYPE('recursive', 'boolean', options.recursive);
+
+    validateInt32(options.retryDelay, 'retryDelay', 0);
+    validateUint32(options.maxRetries, 'maxRetries');
+
+    return options;
+  });
 
 const getValidMode = hideStackFrames((mode, type) => {
   let min = kMinimumAccessMode;
@@ -741,6 +841,8 @@ module.exports = {
   validateOffsetLengthRead,
   validateOffsetLengthWrite,
   validatePath,
+  validateRmOptions,
+  validateRmOptionsSync,
   validateRmdirOptions,
   validateStringAfterArrayBufferView,
   warnOnNonPortableTemplate

diff --git a/test/common/tmpdir.js b/test/common/tmpdir.js
@@ -5,8 +5,8 @@ const fs = require('fs');
 const path = require('path');
 const { isMainThread } = require('worker_threads');
 
-function rimrafSync(pathname) {
-  fs.rmdirSync(pathname, { maxRetries: 3, recursive: true });
+function rmSync(pathname) {
+  fs.rmSync(pathname, { maxRetries: 3, recursive: true, force: true });
 }
 
 const testRoot = process.env.NODE_TEST_DIR ?
@@ -20,7 +20,7 @@ const tmpPath = path.join(testRoot, tmpdirName);
 
 let firstRefresh = true;
 function refresh() {
-  rimrafSync(this.path);
+  rmSync(this.path);
   fs.mkdirSync(this.path);
 
   if (firstRefresh) {
@@ -37,7 +37,7 @@ function onexit() {
     process.chdir(testRoot);
 
   try {
-    rimrafSync(tmpPath);
+    rmSync(tmpPath);
   } catch (e) {
     console.error('Can\'t clean tmpdir:', tmpPath);