From 7273ef53b3771037971f48822aaf25badc6f2b5c Mon Sep 17 00:00:00 2001
From: Ethan Arrowood <ethan.arrowood@vercel.com>
Date: Thu, 20 Apr 2023 11:50:27 -0600
Subject: [PATCH] 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: https://github.com/nodejs/node/issues/34992
PR-URL: https://github.com/nodejs/node/pull/41439
Refs: https://github.com/nodejs/tooling/issues/130
Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
---
 doc/api/fs.md                                |  35 +++
 lib/fs.js                                    |  47 ++++
 lib/internal/fs/dir.js                       |  93 ++++++--
 lib/internal/fs/promises.js                  |  77 ++++++-
 lib/internal/fs/utils.js                     |  25 ++-
 test/sequential/test-fs-opendir-recursive.js | 220 +++++++++++++++++++
 test/sequential/test-fs-readdir-recursive.js | 193 ++++++++++++++++
 7 files changed, 659 insertions(+), 31 deletions(-)
 create mode 100644 test/sequential/test-fs-opendir-recursive.js
 create mode 100644 test/sequential/test-fs-readdir-recursive.js

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 8daaf8ee9685ca..b85bd039795834 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -1214,6 +1214,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
@@ -1227,6 +1230,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
@@ -1260,6 +1265,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.
@@ -1269,6 +1277,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 `'..'`.
 
@@ -3344,6 +3353,9 @@ Functions based on `fs.open()` exhibit this behavior as well:
 <!-- 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
@@ -3362,6 +3374,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}
@@ -3478,6 +3491,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
@@ -3507,6 +3523,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\[]}
@@ -5470,6 +5487,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
@@ -5483,6 +5503,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).
@@ -5526,6 +5547,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.
@@ -5539,6 +5563,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.
@@ -6384,6 +6409,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
diff --git a/lib/fs.js b/lib/fs.js
index dbab47174eea56..92aaabdab50eca 100644
--- a/lib/fs.js
+++ b/lib/fs.js
@@ -1399,6 +1399,36 @@ 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 = binding.internalModuleStat(innerPath);
+      return [
+        relativePath,
+        ...(stat === 1 ? readdirSyncRecursive(innerPath, origPath, options) : []),
+      ];
+    });
+}
+
 /**
  * Reads the contents of a directory.
  * @param {string | Buffer | URL} path
@@ -1416,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) {
@@ -1439,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,
diff --git a/lib/internal/fs/dir.js b/lib/internal/fs/dir.js
index c12bb4cfe5fb22..6a9114adace50b 100644
--- a/lib/internal/fs/dir.js
+++ b/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) {
diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js
index 12e4aa0aadc2eb..6e348c89b792ef 100644
--- a/lib/internal/fs/promises.js
+++ b/lib/internal/fs/promises.js
@@ -2,6 +2,7 @@
 
 const {
   ArrayPrototypePush,
+  ArrayPrototypePop,
   Error,
   MathMax,
   MathMin,
@@ -770,13 +771,81 @@ async function mkdir(path, options) {
                        kUsePromises);
 }
 
+async function readdirRecursive(originalPath, options) {
+  const result = [];
+  const queue = [
+    [
+      originalPath,
+      await binding.readdir(
+        pathModule.toNamespacedPath(originalPath),
+        options.encoding,
+        !!options.withFileTypes,
+        kUsePromises,
+      ),
+    ],
+  ];
+
+
+  if (options.withFileTypes) {
+    while (queue.length > 0) {
+      // If we want to implement BFS make this a `shift` call instead of `pop`
+      const { 0: path, 1: readdir } = ArrayPrototypePop(queue);
+      for (const dirent of getDirents(path, readdir)) {
+        ArrayPrototypePush(result, dirent);
+        if (dirent.isDirectory()) {
+          const direntPath = pathModule.join(path, dirent.name);
+          ArrayPrototypePush(queue, [
+            direntPath,
+            await binding.readdir(
+              direntPath,
+              options.encoding,
+              true,
+              kUsePromises,
+            ),
+          ]);
+        }
+      }
+    }
+  } else {
+    while (queue.length > 0) {
+      const { 0: path, 1: readdir } = ArrayPrototypePop(queue);
+      for (const ent of readdir) {
+        const direntPath = pathModule.join(path, ent);
+        const stat = binding.internalModuleStat(direntPath);
+        ArrayPrototypePush(
+          result,
+          pathModule.relative(originalPath, direntPath),
+        );
+        if (stat === 1) {
+          ArrayPrototypePush(queue, [
+            direntPath,
+            await binding.readdir(
+              pathModule.toNamespacedPath(direntPath),
+              options.encoding,
+              false,
+              kUsePromises,
+            ),
+          ]);
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
 async function readdir(path, options) {
   options = getOptions(options);
   path = getValidatedPath(path);
-  const result = await binding.readdir(pathModule.toNamespacedPath(path),
-                                       options.encoding,
-                                       !!options.withFileTypes,
-                                       kUsePromises);
+  if (options.recursive) {
+    return readdirRecursive(path, options);
+  }
+  const result = await binding.readdir(
+    pathModule.toNamespacedPath(path),
+    options.encoding,
+    !!options.withFileTypes,
+    kUsePromises,
+  );
   return options.withFileTypes ?
     getDirectoryEntriesPromise(path, result) :
     result;
diff --git a/lib/internal/fs/utils.js b/lib/internal/fs/utils.js
index 7b88ae5574f024..23865845bac59e 100644
--- a/lib/internal/fs/utils.js
+++ b/lib/internal/fs/utils.js
@@ -160,8 +160,9 @@ function assertEncoding(encoding) {
 }
 
 class Dirent {
-  constructor(name, type) {
+  constructor(name, type, path) {
     this.name = name;
+    this.path = path;
     this[kType] = type;
   }
 
@@ -195,8 +196,8 @@ class Dirent {
 }
 
 class DirentFromStats extends Dirent {
-  constructor(name, stats) {
-    super(name, null);
+  constructor(name, stats, path) {
+    super(name, null, path);
     this[kStats] = stats;
   }
 }
@@ -231,7 +232,7 @@ function join(path, name) {
   }
 
   if (typeof path === 'string' && typeof name === 'string') {
-    return pathModule.join(path, name);
+    return pathModule.basename(path) === name ? path : pathModule.join(path, name);
   }
 
   if (isUint8Array(path) && isUint8Array(name)) {
@@ -266,13 +267,13 @@ function getDirents(path, { 0: names, 1: types }, callback) {
             callback(err);
             return;
           }
-          names[idx] = new DirentFromStats(name, stats);
+          names[idx] = new DirentFromStats(name, stats, path);
           if (--toFinish === 0) {
             callback(null, names);
           }
         });
       } else {
-        names[i] = new Dirent(names[i], types[i]);
+        names[i] = new Dirent(names[i], types[i], path);
       }
     }
     if (toFinish === 0) {
@@ -302,16 +303,17 @@ function getDirent(path, name, type, callback) {
           callback(err);
           return;
         }
-        callback(null, new DirentFromStats(name, stats));
+        callback(null, new DirentFromStats(name, stats, filepath));
       });
     } else {
-      callback(null, new Dirent(name, type));
+      callback(null, new Dirent(name, type, path));
     }
   } else if (type === UV_DIRENT_UNKNOWN) {
-    const stats = lazyLoadFs().lstatSync(join(path, name));
-    return new DirentFromStats(name, stats);
+    const filepath = join(path, name);
+    const stats = lazyLoadFs().lstatSync(filepath);
+    return new DirentFromStats(name, stats, path);
   } else {
-    return new Dirent(name, type);
+    return new Dirent(name, type, path);
   }
 }
 
@@ -334,6 +336,7 @@ function getOptions(options, defaultOptions = kEmptyObject) {
   if (options.signal !== undefined) {
     validateAbortSignal(options.signal, 'options.signal');
   }
+
   return options;
 }
 
diff --git a/test/sequential/test-fs-opendir-recursive.js b/test/sequential/test-fs-opendir-recursive.js
new file mode 100644
index 00000000000000..935be957e903c2
--- /dev/null
+++ b/test/sequential/test-fs-opendir-recursive.js
@@ -0,0 +1,220 @@
+'use strict';
+
+const common = require('../common');
+const assert = require('assert');
+const fs = require('fs');
+const fsPromises = fs.promises;
+const pathModule = require('path');
+const tmpdir = require('../common/tmpdir');
+
+const testDir = tmpdir.path;
+
+const fileStructure = [
+  [ 'a', [ 'foo', 'bar' ] ],
+  [ 'b', [ 'foo', 'bar' ] ],
+  [ 'c', [ 'foo', 'bar' ] ],
+  [ 'd', [ 'foo', 'bar' ] ],
+  [ 'e', [ 'foo', 'bar' ] ],
+  [ 'f', [ 'foo', 'bar' ] ],
+  [ 'g', [ 'foo', 'bar' ] ],
+  [ 'h', [ 'foo', 'bar' ] ],
+  [ 'i', [ 'foo', 'bar' ] ],
+  [ 'j', [ 'foo', 'bar' ] ],
+  [ 'k', [ 'foo', 'bar' ] ],
+  [ 'l', [ 'foo', 'bar' ] ],
+  [ 'm', [ 'foo', 'bar' ] ],
+  [ 'n', [ 'foo', 'bar' ] ],
+  [ 'o', [ 'foo', 'bar' ] ],
+  [ 'p', [ 'foo', 'bar' ] ],
+  [ 'q', [ 'foo', 'bar' ] ],
+  [ 'r', [ 'foo', 'bar' ] ],
+  [ 's', [ 'foo', 'bar' ] ],
+  [ 't', [ 'foo', 'bar' ] ],
+  [ 'u', [ 'foo', 'bar' ] ],
+  [ 'v', [ 'foo', 'bar' ] ],
+  [ 'w', [ 'foo', 'bar' ] ],
+  [ 'x', [ 'foo', 'bar' ] ],
+  [ 'y', [ 'foo', 'bar' ] ],
+  [ 'z', [ 'foo', 'bar' ] ],
+  [ 'aa', [ 'foo', 'bar' ] ],
+  [ 'bb', [ 'foo', 'bar' ] ],
+  [ 'cc', [ 'foo', 'bar' ] ],
+  [ 'dd', [ 'foo', 'bar' ] ],
+  [ 'ee', [ 'foo', 'bar' ] ],
+  [ 'ff', [ 'foo', 'bar' ] ],
+  [ 'gg', [ 'foo', 'bar' ] ],
+  [ 'hh', [ 'foo', 'bar' ] ],
+  [ 'ii', [ 'foo', 'bar' ] ],
+  [ 'jj', [ 'foo', 'bar' ] ],
+  [ 'kk', [ 'foo', 'bar' ] ],
+  [ 'll', [ 'foo', 'bar' ] ],
+  [ 'mm', [ 'foo', 'bar' ] ],
+  [ 'nn', [ 'foo', 'bar' ] ],
+  [ 'oo', [ 'foo', 'bar' ] ],
+  [ 'pp', [ 'foo', 'bar' ] ],
+  [ 'qq', [ 'foo', 'bar' ] ],
+  [ 'rr', [ 'foo', 'bar' ] ],
+  [ 'ss', [ 'foo', 'bar' ] ],
+  [ 'tt', [ 'foo', 'bar' ] ],
+  [ 'uu', [ 'foo', 'bar' ] ],
+  [ 'vv', [ 'foo', 'bar' ] ],
+  [ 'ww', [ 'foo', 'bar' ] ],
+  [ 'xx', [ 'foo', 'bar' ] ],
+  [ 'yy', [ 'foo', 'bar' ] ],
+  [ 'zz', [ 'foo', 'bar' ] ],
+  [ 'abc', [ ['def', [ 'foo', 'bar' ] ], ['ghi', [ 'foo', 'bar' ] ] ] ],
+];
+
+function createFiles(path, fileStructure) {
+  for (const fileOrDir of fileStructure) {
+    if (typeof fileOrDir === 'string') {
+      fs.writeFileSync(pathModule.join(path, fileOrDir), '');
+    } else {
+      const dirPath = pathModule.join(path, fileOrDir[0]);
+      fs.mkdirSync(dirPath);
+      createFiles(dirPath, fileOrDir[1]);
+    }
+  }
+}
+
+// Make sure tmp directory is clean
+tmpdir.refresh();
+
+createFiles(testDir, fileStructure);
+const symlinksRootPath = pathModule.join(testDir, 'symlinks');
+const symlinkTargetFile = pathModule.join(symlinksRootPath, 'symlink-target-file');
+const symlinkTargetDir = pathModule.join(symlinksRootPath, 'symlink-target-dir');
+fs.mkdirSync(symlinksRootPath);
+fs.writeFileSync(symlinkTargetFile, '');
+fs.mkdirSync(symlinkTargetDir);
+fs.symlinkSync(symlinkTargetFile, pathModule.join(symlinksRootPath, 'symlink-src-file'));
+fs.symlinkSync(symlinkTargetDir, pathModule.join(symlinksRootPath, 'symlink-src-dir'));
+
+const expected = [
+  'a', 'a/bar', 'a/foo', 'aa', 'aa/bar', 'aa/foo',
+  'abc', 'abc/def', 'abc/def/bar', 'abc/def/foo', 'abc/ghi', 'abc/ghi/bar', 'abc/ghi/foo',
+  'b', 'b/bar', 'b/foo', 'bb', 'bb/bar', 'bb/foo',
+  'c', 'c/bar', 'c/foo', 'cc', 'cc/bar', 'cc/foo',
+  'd', 'd/bar', 'd/foo', 'dd', 'dd/bar', 'dd/foo',
+  'e', 'e/bar', 'e/foo', 'ee', 'ee/bar', 'ee/foo',
+  'f', 'f/bar', 'f/foo', 'ff', 'ff/bar', 'ff/foo',
+  'g', 'g/bar', 'g/foo', 'gg', 'gg/bar', 'gg/foo',
+  'h', 'h/bar', 'h/foo', 'hh', 'hh/bar', 'hh/foo',
+  'i', 'i/bar', 'i/foo', 'ii', 'ii/bar', 'ii/foo',
+  'j', 'j/bar', 'j/foo', 'jj', 'jj/bar', 'jj/foo',
+  'k', 'k/bar', 'k/foo', 'kk', 'kk/bar', 'kk/foo',
+  'l', 'l/bar', 'l/foo', 'll', 'll/bar', 'll/foo',
+  'm', 'm/bar', 'm/foo', 'mm', 'mm/bar', 'mm/foo',
+  'n', 'n/bar', 'n/foo', 'nn', 'nn/bar', 'nn/foo',
+  'o', 'o/bar', 'o/foo', 'oo', 'oo/bar', 'oo/foo',
+  'p', 'p/bar', 'p/foo', 'pp', 'pp/bar', 'pp/foo',
+  'q', 'q/bar', 'q/foo', 'qq', 'qq/bar', 'qq/foo',
+  'r', 'r/bar', 'r/foo', 'rr', 'rr/bar', 'rr/foo',
+  's', 's/bar', 's/foo', 'ss', 'ss/bar', 'ss/foo',
+  'symlinks', 'symlinks/symlink-src-dir', 'symlinks/symlink-src-file',
+  'symlinks/symlink-target-dir', 'symlinks/symlink-target-file',
+  't', 't/bar', 't/foo', 'tt', 'tt/bar', 'tt/foo',
+  'u', 'u/bar', 'u/foo', 'uu', 'uu/bar', 'uu/foo',
+  'v', 'v/bar', 'v/foo', 'vv', 'vv/bar', 'vv/foo',
+  'w', 'w/bar', 'w/foo', 'ww', 'ww/bar', 'ww/foo',
+  'x', 'x/bar', 'x/foo', 'xx', 'xx/bar', 'xx/foo',
+  'y', 'y/bar', 'y/foo', 'yy', 'yy/bar', 'yy/foo',
+  'z', 'z/bar', 'z/foo', 'zz', 'zz/bar', 'zz/foo',
+];
+
+// Normalize paths once for non POSIX platforms
+for (let i = 0; i < expected.length; i++) {
+  expected[i] = pathModule.normalize(expected[i]);
+}
+
+function getDirentPath(dirent) {
+  return pathModule.relative(testDir, dirent.path);
+}
+
+function assertDirents(dirents) {
+  dirents.sort((a, b) => (getDirentPath(a) < getDirentPath(b) ? -1 : 1));
+  for (const [i, dirent] of dirents.entries()) {
+    assert(dirent instanceof fs.Dirent);
+    assert.strictEqual(getDirentPath(dirent), expected[i]);
+  }
+}
+
+function processDirSync(dir) {
+  const dirents = [];
+  let dirent = dir.readSync();
+  while (dirent !== null) {
+    dirents.push(dirent);
+    dirent = dir.readSync();
+  }
+  assertDirents(dirents);
+}
+
+// Opendir read results sync
+
+{
+  const dir = fs.opendirSync(testDir, { recursive: true });
+  processDirSync(dir);
+  dir.closeSync();
+}
+
+{
+  fs.opendir(testDir, { recursive: true }, common.mustSucceed((dir) => {
+    processDirSync(dir);
+    dir.close(common.mustSucceed());
+  }));
+}
+
+// Opendir read result using callback
+
+function processDirCb(dir, cb) {
+  const acc = [];
+
+  function _process(dir, acc, cb) {
+    dir.read((err, dirent) => {
+      if (err) {
+        return cb(err);
+      }
+
+      if (dirent !== null) {
+        acc.push(dirent);
+        _process(dir, acc, cb);
+      } else {
+        cb(null, acc);
+      }
+    });
+  }
+
+  _process(dir, acc, cb);
+}
+
+{
+  const dir = fs.opendirSync(testDir, { recursive: true });
+  processDirCb(dir, common.mustSucceed((dirents) => {
+    assertDirents(dirents);
+    dir.close(common.mustSucceed());
+  }));
+}
+
+{
+  fs.opendir(testDir, { recursive: true }, common.mustSucceed((dir) => {
+    processDirCb(dir, common.mustSucceed((dirents) => {
+      assertDirents(dirents);
+      dir.close(common.mustSucceed());
+    }));
+  }));
+}
+
+// Opendir read result using AsyncIterator
+
+{
+  async function test() {
+    const dir = await fsPromises.opendir(testDir, { recursive: true });
+    const dirents = [];
+    for await (const dirent of dir) {
+      dirents.push(dirent);
+    }
+    assertDirents(dirents);
+  }
+
+  test().then(common.mustCall());
+}
diff --git a/test/sequential/test-fs-readdir-recursive.js b/test/sequential/test-fs-readdir-recursive.js
new file mode 100644
index 00000000000000..3ced1434f303b7
--- /dev/null
+++ b/test/sequential/test-fs-readdir-recursive.js
@@ -0,0 +1,193 @@
+'use strict';
+
+const common = require('../common');
+const assert = require('assert');
+const fs = require('fs');
+const pathModule = require('path');
+const tmpdir = require('../common/tmpdir');
+
+const readdirDir = tmpdir.path;
+
+const fileStructure = [
+  [ 'a', [ 'foo', 'bar' ] ],
+  [ 'b', [ 'foo', 'bar' ] ],
+  [ 'c', [ 'foo', 'bar' ] ],
+  [ 'd', [ 'foo', 'bar' ] ],
+  [ 'e', [ 'foo', 'bar' ] ],
+  [ 'f', [ 'foo', 'bar' ] ],
+  [ 'g', [ 'foo', 'bar' ] ],
+  [ 'h', [ 'foo', 'bar' ] ],
+  [ 'i', [ 'foo', 'bar' ] ],
+  [ 'j', [ 'foo', 'bar' ] ],
+  [ 'k', [ 'foo', 'bar' ] ],
+  [ 'l', [ 'foo', 'bar' ] ],
+  [ 'm', [ 'foo', 'bar' ] ],
+  [ 'n', [ 'foo', 'bar' ] ],
+  [ 'o', [ 'foo', 'bar' ] ],
+  [ 'p', [ 'foo', 'bar' ] ],
+  [ 'q', [ 'foo', 'bar' ] ],
+  [ 'r', [ 'foo', 'bar' ] ],
+  [ 's', [ 'foo', 'bar' ] ],
+  [ 't', [ 'foo', 'bar' ] ],
+  [ 'u', [ 'foo', 'bar' ] ],
+  [ 'v', [ 'foo', 'bar' ] ],
+  [ 'w', [ 'foo', 'bar' ] ],
+  [ 'x', [ 'foo', 'bar' ] ],
+  [ 'y', [ 'foo', 'bar' ] ],
+  [ 'z', [ 'foo', 'bar' ] ],
+  [ 'aa', [ 'foo', 'bar' ] ],
+  [ 'bb', [ 'foo', 'bar' ] ],
+  [ 'cc', [ 'foo', 'bar' ] ],
+  [ 'dd', [ 'foo', 'bar' ] ],
+  [ 'ee', [ 'foo', 'bar' ] ],
+  [ 'ff', [ 'foo', 'bar' ] ],
+  [ 'gg', [ 'foo', 'bar' ] ],
+  [ 'hh', [ 'foo', 'bar' ] ],
+  [ 'ii', [ 'foo', 'bar' ] ],
+  [ 'jj', [ 'foo', 'bar' ] ],
+  [ 'kk', [ 'foo', 'bar' ] ],
+  [ 'll', [ 'foo', 'bar' ] ],
+  [ 'mm', [ 'foo', 'bar' ] ],
+  [ 'nn', [ 'foo', 'bar' ] ],
+  [ 'oo', [ 'foo', 'bar' ] ],
+  [ 'pp', [ 'foo', 'bar' ] ],
+  [ 'qq', [ 'foo', 'bar' ] ],
+  [ 'rr', [ 'foo', 'bar' ] ],
+  [ 'ss', [ 'foo', 'bar' ] ],
+  [ 'tt', [ 'foo', 'bar' ] ],
+  [ 'uu', [ 'foo', 'bar' ] ],
+  [ 'vv', [ 'foo', 'bar' ] ],
+  [ 'ww', [ 'foo', 'bar' ] ],
+  [ 'xx', [ 'foo', 'bar' ] ],
+  [ 'yy', [ 'foo', 'bar' ] ],
+  [ 'zz', [ 'foo', 'bar' ] ],
+  [ 'abc', [ ['def', [ 'foo', 'bar' ] ], ['ghi', [ 'foo', 'bar' ] ] ] ],
+];
+
+function createFiles(path, fileStructure) {
+  for (const fileOrDir of fileStructure) {
+    if (typeof fileOrDir === 'string') {
+      fs.writeFileSync(pathModule.join(path, fileOrDir), '');
+    } else {
+      const dirPath = pathModule.join(path, fileOrDir[0]);
+      fs.mkdirSync(dirPath);
+      createFiles(dirPath, fileOrDir[1]);
+    }
+  }
+}
+
+// Make sure tmp directory is clean
+tmpdir.refresh();
+
+createFiles(readdirDir, fileStructure);
+const symlinksRootPath = pathModule.join(readdirDir, 'symlinks');
+const symlinkTargetFile = pathModule.join(symlinksRootPath, 'symlink-target-file');
+const symlinkTargetDir = pathModule.join(symlinksRootPath, 'symlink-target-dir');
+fs.mkdirSync(symlinksRootPath);
+fs.writeFileSync(symlinkTargetFile, '');
+fs.mkdirSync(symlinkTargetDir);
+fs.symlinkSync(symlinkTargetFile, pathModule.join(symlinksRootPath, 'symlink-src-file'));
+fs.symlinkSync(symlinkTargetDir, pathModule.join(symlinksRootPath, 'symlink-src-dir'));
+
+const expected = [
+  'a', 'a/bar', 'a/foo', 'aa', 'aa/bar', 'aa/foo',
+  'abc', 'abc/def', 'abc/def/bar', 'abc/def/foo', 'abc/ghi', 'abc/ghi/bar', 'abc/ghi/foo',
+  'b', 'b/bar', 'b/foo', 'bb', 'bb/bar', 'bb/foo',
+  'c', 'c/bar', 'c/foo', 'cc', 'cc/bar', 'cc/foo',
+  'd', 'd/bar', 'd/foo', 'dd', 'dd/bar', 'dd/foo',
+  'e', 'e/bar', 'e/foo', 'ee', 'ee/bar', 'ee/foo',
+  'f', 'f/bar', 'f/foo', 'ff', 'ff/bar', 'ff/foo',
+  'g', 'g/bar', 'g/foo', 'gg', 'gg/bar', 'gg/foo',
+  'h', 'h/bar', 'h/foo', 'hh', 'hh/bar', 'hh/foo',
+  'i', 'i/bar', 'i/foo', 'ii', 'ii/bar', 'ii/foo',
+  'j', 'j/bar', 'j/foo', 'jj', 'jj/bar', 'jj/foo',
+  'k', 'k/bar', 'k/foo', 'kk', 'kk/bar', 'kk/foo',
+  'l', 'l/bar', 'l/foo', 'll', 'll/bar', 'll/foo',
+  'm', 'm/bar', 'm/foo', 'mm', 'mm/bar', 'mm/foo',
+  'n', 'n/bar', 'n/foo', 'nn', 'nn/bar', 'nn/foo',
+  'o', 'o/bar', 'o/foo', 'oo', 'oo/bar', 'oo/foo',
+  'p', 'p/bar', 'p/foo', 'pp', 'pp/bar', 'pp/foo',
+  'q', 'q/bar', 'q/foo', 'qq', 'qq/bar', 'qq/foo',
+  'r', 'r/bar', 'r/foo', 'rr', 'rr/bar', 'rr/foo',
+  's', 's/bar', 's/foo', 'ss', 'ss/bar', 'ss/foo',
+  'symlinks', 'symlinks/symlink-src-dir', 'symlinks/symlink-src-file',
+  'symlinks/symlink-target-dir', 'symlinks/symlink-target-file',
+  't', 't/bar', 't/foo', 'tt', 'tt/bar', 'tt/foo',
+  'u', 'u/bar', 'u/foo', 'uu', 'uu/bar', 'uu/foo',
+  'v', 'v/bar', 'v/foo', 'vv', 'vv/bar', 'vv/foo',
+  'w', 'w/bar', 'w/foo', 'ww', 'ww/bar', 'ww/foo',
+  'x', 'x/bar', 'x/foo', 'xx', 'xx/bar', 'xx/foo',
+  'y', 'y/bar', 'y/foo', 'yy', 'yy/bar', 'yy/foo',
+  'z', 'z/bar', 'z/foo', 'zz', 'zz/bar', 'zz/foo',
+];
+
+// Normalize paths once for non POSIX platforms
+for (let i = 0; i < expected.length; i++) {
+  expected[i] = pathModule.normalize(expected[i]);
+}
+
+function getDirentPath(dirent) {
+  return pathModule.relative(readdirDir, pathModule.join(dirent.path, dirent.name));
+}
+
+function assertDirents(dirents) {
+  dirents.sort((a, b) => (getDirentPath(a) < getDirentPath(b) ? -1 : 1));
+  for (const [i, dirent] of dirents.entries()) {
+    assert(dirent instanceof fs.Dirent);
+    assert.strictEqual(getDirentPath(dirent), expected[i]);
+  }
+}
+
+// readdirSync
+
+// readdirSync { recursive }
+{
+  const result = fs.readdirSync(readdirDir, { recursive: true });
+  assert.deepStrictEqual(result.sort(), expected);
+}
+
+// readdirSync { recursive, withFileTypes }
+{
+  const result = fs.readdirSync(readdirDir, { recursive: true, withFileTypes: true });
+  assertDirents(result);
+}
+
+// readdir
+
+// readdir { recursive } callback
+{
+  fs.readdir(readdirDir, { recursive: true },
+             common.mustSucceed((result) => {
+               assert.deepStrictEqual(result.sort(), expected);
+             }));
+}
+
+// Readdir { recursive, withFileTypes } callback
+{
+  fs.readdir(readdirDir, { recursive: true, withFileTypes: true },
+             common.mustSucceed((result) => {
+               assertDirents(result);
+             }));
+}
+
+// fs.promises.readdir
+
+// fs.promises.readdir { recursive }
+{
+  async function test() {
+    const result = await fs.promises.readdir(readdirDir, { recursive: true });
+    assert.deepStrictEqual(result.sort(), expected);
+  }
+
+  test().then(common.mustCall());
+}
+
+// fs.promises.readdir { recursive, withFileTypes }
+{
+  async function test() {
+    const result = await fs.promises.readdir(readdirDir, { recursive: true, withFileTypes: true });
+    assertDirents(result);
+  }
+
+  test().then(common.mustCall());
+}