fs: add recursive option to readdir and opendir

Adds a naive, linear recursive algorithm for the following methods:
readdir, readdirSync, opendir, opendirSync, and the promise based
equivalents.

Fixes: #34992

Author: Ethan Arrowood

doc/api/fs.md

@@ -1204,6 +1204,9 @@ a colon, Node.js will open a file system stream, as described by
 <!-- YAML
 added: v12.12.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/41439
+    description: Added `recursive` option.
   - version:
      - v13.1.0
      - v12.16.0
@@ -1217,6 +1220,8 @@ changes:
   * `bufferSize` {number} Number of directory entries that are buffered
     internally when reading from the directory. Higher values lead to better
     performance but higher memory usage. **Default:** `32`
+  * `recursive` {boolean} Resolved `Dir` will be an {AsyncIterable}
+    containing all sub files and directories. **Default:** `false`
 * Returns: {Promise}  Fulfills with an {fs.Dir}.
 
 Asynchronously open a directory for iterative scanning. See the POSIX
@@ -1250,6 +1255,9 @@ closed after the iterator exits.
 <!-- YAML
 added: v10.0.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/41439
+    description: Added `recursive` option.
   - version: v10.11.0
     pr-url: https://github.com/nodejs/node/pull/22020
     description: New option `withFileTypes` was added.
@@ -1259,6 +1267,7 @@ changes:
 * `options` {string|Object}
   * `encoding` {string} **Default:** `'utf8'`
   * `withFileTypes` {boolean} **Default:** `false`
+  * `recursive` {boolean} **Default:** `false`
 * Returns: {Promise}  Fulfills with an array of the names of the files in
   the directory excluding `'.'` and `'..'`.
 
@@ -3368,6 +3377,9 @@ const { openAsBlob } = require('node:fs');
 <!-- YAML
 added: v12.12.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/41439
+    description: Added `recursive` option.
   - version: v18.0.0
     pr-url: https://github.com/nodejs/node/pull/41678
     description: Passing an invalid callback to the `callback` argument
@@ -3386,6 +3398,7 @@ changes:
   * `bufferSize` {number} Number of directory entries that are buffered
     internally when reading from the directory. Higher values lead to better
     performance but higher memory usage. **Default:** `32`
+  * `recursive` {boolean} **Default:** `false`
 * `callback` {Function}
   * `err` {Error}
   * `dir` {fs.Dir}
@@ -3504,6 +3517,9 @@ above values.
 <!-- YAML
 added: v0.1.8
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/41439
+    description: Added `recursive` option.
   - version: v18.0.0
     pr-url: https://github.com/nodejs/node/pull/41678
     description: Passing an invalid callback to the `callback` argument
@@ -3533,6 +3549,7 @@ changes:
 * `options` {string|Object}
   * `encoding` {string} **Default:** `'utf8'`
   * `withFileTypes` {boolean} **Default:** `false`
+  * `recursive` {boolean} **Default:** `false`
 * `callback` {Function}
   * `err` {Error}
   * `files` {string\[]|Buffer\[]|fs.Dirent\[]}
@@ -5501,6 +5518,9 @@ object with an `encoding` property specifying the character encoding to use.
 <!-- YAML
 added: v12.12.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/41439
+    description: Added `recursive` option.
   - version:
      - v13.1.0
      - v12.16.0
@@ -5514,6 +5534,7 @@ changes:
   * `bufferSize` {number} Number of directory entries that are buffered
     internally when reading from the directory. Higher values lead to better
     performance but higher memory usage. **Default:** `32`
+  * `recursive` {boolean} **Default:** `false`
 * Returns: {fs.Dir}
 
 Synchronously open a directory. See opendir(3).
@@ -5557,6 +5578,9 @@ this API: [`fs.open()`][].
 <!-- YAML
 added: v0.1.21
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/41439
+    description: Added `recursive` option.
   - version: v10.10.0
     pr-url: https://github.com/nodejs/node/pull/22020
     description: New option `withFileTypes` was added.
@@ -5570,6 +5594,7 @@ changes:
 * `options` {string|Object}
   * `encoding` {string} **Default:** `'utf8'`
   * `withFileTypes` {boolean} **Default:** `false`
+  * `recursive` {boolean} **Default:** `false`
 * Returns: {string\[]|Buffer\[]|fs.Dirent\[]}
 
 Reads the contents of the directory.
@@ -6421,6 +6446,16 @@ The file name that this {fs.Dirent} object refers to. The type of this
 value is determined by the `options.encoding` passed to [`fs.readdir()`][] or
 [`fs.readdirSync()`][].
 
+#### `dirent.path`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* {string}
+
+The base path that this {fs.Dirent} object refers to.
+
 ### Class: `fs.FSWatcher`
 
 <!-- YAML

lib/fs.js

@@ -1404,6 +1404,31 @@ function mkdirSync(path, options) {
   }
 }
 
+// TODO(Ethan-Arrowood): Make this iterative too
+function readdirSyncRecursive(path, origPath, options) {
+  nullCheck(path, 'path', true);
+  const ctx = { path };
+  const result = binding.readdir(pathModule.toNamespacedPath(path),
+                                 options.encoding, !!options.withFileTypes, undefined, ctx);
+  handleErrorFromBinding(ctx);
+  return options.withFileTypes ?
+    getDirents(path, result).flatMap((dirent) => {
+      return [
+        dirent,
+        ...(dirent.isDirectory() ? readdirSyncRecursive(pathModule.join(path, dirent.name), origPath, options) : []),
+      ];
+    }) :
+    result.flatMap((ent) => {
+      const innerPath = pathModule.join(path, ent);
+      const relativePath = pathModule.relative(origPath, innerPath);
+      const stat = fs.lstatSync(innerPath);
+      return [
+        relativePath,
+        ...(stat.isDirectory() ? readdirSyncRecursive(innerPath, origPath, options) : []),
+      ];
+    });
+}
+
 /**
  * Reads the contents of a directory.
  * @param {string | Buffer | URL} path
@@ -1421,6 +1446,14 @@ function readdir(path, options, callback) {
   callback = makeCallback(typeof options === 'function' ? options : callback);
   options = getOptions(options);
   path = getValidatedPath(path);
+  if (options.recursive != null) {
+    validateBoolean(options.recursive, 'options.recursive');
+  }
+
+  if (options.recursive) {
+    callback(null, readdirSyncRecursive(path, path, options));
+    return;
+  }
 
   const req = new FSReqCallback();
   if (!options.withFileTypes) {
@@ -1444,12 +1477,21 @@ function readdir(path, options, callback) {
  * @param {string | {
  *   encoding?: string;
  *   withFileTypes?: boolean;
+ *   recursive?: boolean;
  *   }} [options]
  * @returns {string | Buffer[] | Dirent[]}
  */
 function readdirSync(path, options) {
   options = getOptions(options);
   path = getValidatedPath(path);
+  if (options.recursive != null) {
+    validateBoolean(options.recursive, 'options.recursive');
+  }
+
+  if (options.recursive) {
+    return readdirSyncRecursive(path, path, options);
+  }
+
   const ctx = { path };
   const result = binding.readdir(pathModule.toNamespacedPath(path),
                                  options.encoding, !!options.withFileTypes,

lib/internal/fs/dir.js

@@ -2,8 +2,7 @@
 
 const {
   ArrayPrototypePush,
-  ArrayPrototypeSlice,
-  ArrayPrototypeSplice,
+  ArrayPrototypeShift,
   FunctionPrototypeBind,
   ObjectDefineProperty,
   PromiseReject,
@@ -99,13 +98,21 @@ class Dir {
     }
 
     if (this[kDirBufferedEntries].length > 0) {
-      const { 0: name, 1: type } =
-        ArrayPrototypeSplice(this[kDirBufferedEntries], 0, 2);
-      if (maybeSync)
-        process.nextTick(getDirent, this[kDirPath], name, type, callback);
-      else
-        getDirent(this[kDirPath], name, type, callback);
-      return;
+      try {
+        const dirent = ArrayPrototypeShift(this[kDirBufferedEntries]);
+
+        if (this[kDirOptions].recursive && dirent.isDirectory()) {
+          this.readSyncRecursive(dirent);
+        }
+
+        if (maybeSync)
+          process.nextTick(callback, null, dirent);
+        else
+          callback(null, dirent);
+        return;
+      } catch (error) {
+        return callback(error);
+      }
     }
 
     const req = new FSReqCallback();
@@ -120,8 +127,16 @@ class Dir {
         return callback(err, result);
       }
 
-      this[kDirBufferedEntries] = ArrayPrototypeSlice(result, 2);
-      getDirent(this[kDirPath], result[0], result[1], callback);
+      try {
+        this.processReadResult(this[kDirPath], result);
+        const dirent = ArrayPrototypeShift(this[kDirBufferedEntries]);
+        if (this[kDirOptions].recursive && dirent.isDirectory()) {
+          this.readSyncRecursive(dirent);
+        }
+        callback(null, dirent);
+      } catch (error) {
+        callback(error);
+      }
     };
 
     this[kDirOperationQueue] = [];
@@ -132,6 +147,45 @@ class Dir {
     );
   }
 
+  processReadResult(path, result) {
+    for (let i = 0; i < result.length; i += 2) {
+      ArrayPrototypePush(
+        this[kDirBufferedEntries],
+        getDirent(
+          pathModule.join(path, result[i]),
+          result[i],
+          result[i + 1],
+        ),
+      );
+    }
+  }
+
+  // TODO(Ethan-Arrowood): Review this implementation. Make it iterative.
+  // Can we better leverage the `kDirOperationQueue`?
+  readSyncRecursive(dirent) {
+    const ctx = { path: dirent.path };
+    const handle = dirBinding.opendir(
+      pathModule.toNamespacedPath(dirent.path),
+      this[kDirOptions].encoding,
+      undefined,
+      ctx,
+    );
+    handleErrorFromBinding(ctx);
+    const result = handle.read(
+      this[kDirOptions].encoding,
+      this[kDirOptions].bufferSize,
+      undefined,
+      ctx,
+    );
+
+    if (result) {
+      this.processReadResult(dirent.path, result);
+    }
+
+    handle.close(undefined, ctx);
+    handleErrorFromBinding(ctx);
+  }
+
   readSync() {
     if (this[kDirClosed] === true) {
       throw new ERR_DIR_CLOSED();
@@ -142,9 +196,11 @@ class Dir {
     }
 
     if (this[kDirBufferedEntries].length > 0) {
-      const { 0: name, 1: type } =
-          ArrayPrototypeSplice(this[kDirBufferedEntries], 0, 2);
-      return getDirent(this[kDirPath], name, type);
+      const dirent = ArrayPrototypeShift(this[kDirBufferedEntries]);
+      if (this[kDirOptions].recursive && dirent.isDirectory()) {
+        this.readSyncRecursive(dirent);
+      }
+      return dirent;
     }
 
     const ctx = { path: this[kDirPath] };
@@ -160,8 +216,13 @@ class Dir {
       return result;
     }
 
-    this[kDirBufferedEntries] = ArrayPrototypeSlice(result, 2);
-    return getDirent(this[kDirPath], result[0], result[1]);
+    this.processReadResult(this[kDirPath], result);
+
+    const dirent = ArrayPrototypeShift(this[kDirBufferedEntries]);
+    if (this[kDirOptions].recursive && dirent.isDirectory()) {
+      this.readSyncRecursive(dirent);
+    }
+    return dirent;
   }
 
   close(callback) {