fs: stop stat()ing every entry in recursive readdir

readdir({ recursive: true }) asked the binding for names only and then
called internalModuleStat() on every entry to find the directories to
descend into; with withFileTypes it built the Dirents and still stat()ed
every entry that was not already a directory. Both variants also ran
path.join() and path.relative() per entry to build the relative result.
Ask the binding for file types in all cases, descend into directories
directly, and only stat() symbolic links and entries of unknown type
(which is what could point to a directory). The relative name is the
parent's prefix plus the entry name. Results, their order and the
symlink-following behavior are unchanged for fs.readdirSync, fs.readdir
and fs.promises.readdir.
The known_issues test for Buffer paths (#58892) called back without
checking the error; the error now reaches the callback instead of being
thrown from the completion handler, so the test asserts success to keep
expressing the issue.
Signed-off-by: Shelley Vohr <shelley.vohr@gmail.com>
PR-URL: #65487
Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>
Reviewed-By: Gürgün Dayıoğlu <hey@gurgun.day>

Author: codebytere

benchmark/fs/bench-readdir.js

@@ -8,16 +8,18 @@ const bench = common.createBenchmark(main, {
 n: [10],
 dir: ['lib','test/parallel'],
 withFileTypes: ['true','false'],
+recursive: ['true','false'],
 });
 
-functionmain({ n, dir, withFileTypes }){
+functionmain({ n, dir, withFileTypes, recursive}){
 withFileTypes=withFileTypes==='true';
+recursive=recursive==='true';
 constfullPath=path.resolve(__dirname,'../../',dir);
 bench.start();
 (functionr(cntr){
 if(cntr--<=0)
 returnbench.end(n);
-fs.readdir(fullPath,{ withFileTypes },()=>{
+fs.readdir(fullPath,{ withFileTypes, recursive},()=>{
 r(cntr);
 });
 }(n));

benchmark/fs/bench-readdirSync.js

@@ -8,15 +8,17 @@ const bench = common.createBenchmark(main, {
 n: [10],
 dir: ['lib','test/parallel'],
 withFileTypes: ['true','false'],
+recursive: ['true','false'],
 });
 
 
-functionmain({ n, dir, withFileTypes }){
+functionmain({ n, dir, withFileTypes, recursive}){
 withFileTypes=withFileTypes==='true';
+recursive=recursive==='true';
 constfullPath=path.resolve(__dirname,'../../',dir);
 bench.start();
 for(leti=0;i<n;i++){
-fs.readdirSync(fullPath,{ withFileTypes });
+fs.readdirSync(fullPath,{ withFileTypes, recursive});
 }
 bench.end(n);
 }

lib/fs.js

@@ -57,6 +57,9 @@ const {
 F_OK,
 O_WRONLY,
 O_SYMLINK,
+UV_DIRENT_DIR,
+UV_DIRENT_LINK,
+UV_DIRENT_UNKNOWN,
 }=constants;
 
 constpathModule=require('path');
@@ -1739,6 +1742,43 @@ function mkdirSync(path, options) {
 }
 }
 
+/**
+ * Appends one directory's entries to `context.results` and the subdirectories
+ * still to visit to `context.dirs` (with the prefix their entries get in
+ * string results in `context.prefixes`). `result` is a `binding.readdir()`
+ * result with file types, so only symbolic links and entries of unknown type
+ * need a stat() to find out whether they lead to a directory.
+ * @param {string} dir
+ * @param {string} prefix
+ * @param {[string[], number[]]} result
+ * @param {{ withFileTypes: boolean, results: (string | Dirent)[], dirs: string[], prefixes: string[] }} context
+ */
+functioncollectRecursiveReaddirResult(dir,prefix,{0: names,1: types},context){
+const{ length }=names;
+for(leti=0;i<length;i++){
+constname=names[i];
+constrelative=prefix==='' ? name : `${prefix}${pathModule.sep}${name}`;
+letisDirectory;
+if(context.withFileTypes){
+constdirent=getDirent(dir,name,types[i]);
+ArrayPrototypePush(context.results,dirent);
+// Follow symbolic links to directories, see https://github.com/nodejs/node/issues/52663
+isDirectory=dirent.isDirectory()||
+(dirent.isSymbolicLink()&&binding.internalModuleStat(pathModule.join(dir,name))===1);
+}else{
+ArrayPrototypePush(context.results,relative);
+consttype=types[i];
+isDirectory=type===UV_DIRENT_DIR||
+((type===UV_DIRENT_LINK||type===UV_DIRENT_UNKNOWN)&&
+binding.internalModuleStat(pathModule.join(dir,name))===1);
+}
+if(isDirectory){
+ArrayPrototypePush(context.dirs,pathModule.join(dir,name));
+ArrayPrototypePush(context.prefixes,relative);
+}
+}
+}
+
 /*
  * An recursive algorithm for reading the entire contents of the `basePath` directory.
  * This function does not validate `basePath` as a directory. It is passed directly to
@@ -1754,15 +1794,20 @@ function mkdirSync(path, options) {
 functionreaddirRecursive(basePath,options,callback){
 constcontext={
 withFileTypes: Boolean(options.withFileTypes),
-encoding: options.encoding,
- basePath,
-readdirResults: [],
-pathsQueue: [basePath],
+results: [],
+dirs: [basePath],
+prefixes: [''],
 };
 
 leti=0;
 
-functionread(path){
+/**
+ * Reads one directory from `context.dirs` and then moves on to the next
+ * one, or calls back once none are left.
+ * @param {string} path
+ * @param {string} prefix path of this directory relative to `basePath`
+ */
+functionread(path,prefix){
 constreq=newFSReqCallback();
 req.oncomplete=(err,result)=>{
 if(err){
@@ -1771,68 +1816,28 @@ function readdirRecursive(basePath, options, callback) {
 }
 
 if(result===undefined){
-callback(null,context.readdirResults);
+callback(null,context.results);
 return;
 }
 
-processReaddirResult({
- result,
-currentPath: path,
- context,
-});
+try{
+collectRecursiveReaddirResult(path,prefix,result,context);
+}catch(err){
+callback(err);
+return;
+}
 
-if(i<context.pathsQueue.length){
-read(context.pathsQueue[i++]);
+if(i<context.dirs.length){
+read(context.dirs[i],context.prefixes[i++]);
 }else{
-callback(null,context.readdirResults);
+callback(null,context.results);
 }
 };
 
-binding.readdir(
-path,
-context.encoding,
-context.withFileTypes,
-req,
-);
-}
-
-read(context.pathsQueue[i++]);
-}
-
-// Calling `readdir` with `withFileTypes=true`, the result is an array of arrays.
-// The first array is the names, and the second array is the types.
-// They are guaranteed to be the same length; hence, setting `length` to the length
-// of the first array within the result.
-constprocessReaddirResult=(args)=>(args.context.withFileTypes ? handleDirents(args) : handleFilePaths(args));
-
-functionhandleDirents({ result, currentPath, context }){
-const{0: names,1: types}=result;
-const{ length }=names;
-
-for(leti=0;i<length;i++){
-// Avoid excluding symlinks, as they are not directories.
-// Refs: https://github.com/nodejs/node/issues/52663
-constfullPath=pathModule.join(currentPath,names[i]);
-constdirent=getDirent(currentPath,names[i],types[i]);
-ArrayPrototypePush(context.readdirResults,dirent);
-
-if(dirent.isDirectory()||binding.internalModuleStat(fullPath)===1){
-ArrayPrototypePush(context.pathsQueue,fullPath);
-}
+binding.readdir(path,options.encoding,true,req);
 }
-}
-
-functionhandleFilePaths({ result, currentPath, context }){
-for(leti=0;i<result.length;i++){
-constresultPath=pathModule.join(currentPath,result[i]);
-constrelativeResultPath=pathModule.relative(context.basePath,resultPath);
-conststat=binding.internalModuleStat(resultPath);
-ArrayPrototypePush(context.readdirResults,relativeResultPath);
 
-if(stat===1){
-ArrayPrototypePush(context.pathsQueue,resultPath);
-}
-}
+read(context.dirs[i],context.prefixes[i++]);
 }
 
 /**
@@ -1846,35 +1851,20 @@ function handleFilePaths({ result, currentPath, context }) {
 functionreaddirSyncRecursive(basePath,options){
 constcontext={
 withFileTypes: Boolean(options.withFileTypes),
-encoding: options.encoding,
- basePath,
-readdirResults: [],
-pathsQueue: [basePath],
+results: [],
+dirs: [basePath],
+prefixes: [''],
 };
 
-functionread(path){
-constreaddirResult=binding.readdir(
-path,
-context.encoding,
-context.withFileTypes,
-);
-
-if(readdirResult===undefined){
-return;
+for(leti=0;i<context.dirs.length;i++){
+constdir=context.dirs[i];
+constresult=binding.readdir(dir,options.encoding,true);
+if(result!==undefined){
+collectRecursiveReaddirResult(dir,context.prefixes[i],result,context);
 }
-
-processReaddirResult({
-result: readdirResult,
-currentPath: path,
- context,
-});
-}
-
-for(leti=0;i<context.pathsQueue.length;i++){
-read(context.pathsQueue[i]);
 }
 
-returncontext.readdirResults;
+returncontext.results;
 }
 
 /**

lib/internal/fs/promises.js

@@ -32,6 +32,9 @@ const {
 O_WRONLY,
 S_IFMT,
 S_IFREG,
+UV_DIRENT_DIR,
+UV_DIRENT_LINK,
+UV_DIRENT_UNKNOWN,
 }=constants;
 
 constbinding=internalBinding('fs');
@@ -63,6 +66,7 @@ const {
  kWriteFileMaxChunkSize,
 },
  copyObject,
+ getDirent,
  getDirents,
  getOptions,
  getStatFsFromBinding,
@@ -1638,73 +1642,37 @@ async function mkdir(path, options) {
 }
 
 asyncfunctionreaddirRecursive(originalPath,options){
+constwithFileTypes=!!options.withFileTypes;
+constreaddirWithTypes=(path)=>PromisePrototypeThen(
+binding.readdir(path,options.encoding,true,kUsePromises),
+undefined,
+handleErrorFromBinding,
+);
 constresult=[];
-constqueue=[
-[
-originalPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-originalPath,
-options.encoding,
-!!options.withFileTypes,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-],
-];
-
-
-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(constdirentofgetDirents(path,readdir)){
+constqueue=[[originalPath,'',awaitreaddirWithTypes(originalPath)]];
+
+while(queue.length>0){
+// If we want to implement BFS make this a `shift` call instead of `pop`
+const{0: path,1: prefix,2: {0: names,1: types}}=ArrayPrototypePop(queue);
+for(leti=0;i<names.length;i++){
+constname=names[i];
+constrelative=prefix==='' ? name : `${prefix}${pathModule.sep}${name}`;
+letisDirectory;
+if(withFileTypes){
+constdirent=getDirent(path,name,types[i]);
 ArrayPrototypePush(result,dirent);
-if(dirent.isDirectory()){
-constdirentPath=pathModule.join(path,dirent.name);
-ArrayPrototypePush(queue,[
-direntPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-direntPath,
-options.encoding,
-true,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-]);
-}
+isDirectory=dirent.isDirectory();
+}else{
+ArrayPrototypePush(result,relative);
+// Entries that are, or may be, symbolic links to directories are followed.
+consttype=types[i];
+isDirectory=type===UV_DIRENT_DIR||
+((type===UV_DIRENT_LINK||type===UV_DIRENT_UNKNOWN)&&
+binding.internalModuleStat(pathModule.join(path,name))===1);
 }
-}
-}else{
-while(queue.length>0){
-const{0: path,1: readdir}=ArrayPrototypePop(queue);
-for(constentofreaddir){
-constdirentPath=pathModule.join(path,ent);
-conststat=binding.internalModuleStat(direntPath);
-ArrayPrototypePush(
-result,
-pathModule.relative(originalPath,direntPath),
-);
-if(stat===1){
-ArrayPrototypePush(queue,[
-direntPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-direntPath,
-options.encoding,
-false,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-]);
-}
+if(isDirectory){
+constdirentPath=pathModule.join(path,name);
+ArrayPrototypePush(queue,[direntPath,relative,awaitreaddirWithTypes(direntPath)]);
 }
 }
 }

test/known_issues/test-fs-readdir-recursive-with-buffer.js

@@ -12,4 +12,4 @@ const { readdir } = require('node:fs');
 const{ join }=require('node:path');
 
 consttestDirPath=join(__dirname,'..','..');
-readdir(Buffer.from(testDirPath),{recursive: true},common.mustCall());
+readdir(Buffer.from(testDirPath),{recursive: true},common.mustSucceed());

benchmark/fs/bench-readdir.js

@@ -8,16 +8,18 @@ const bench = common.createBenchmark(main, {
 n: [10],
 dir: ['lib','test/parallel'],
 withFileTypes: ['true','false'],
+recursive: ['true','false'],
 });
 
-functionmain({ n, dir, withFileTypes }){
+functionmain({ n, dir, withFileTypes, recursive}){
 withFileTypes=withFileTypes==='true';
+recursive=recursive==='true';
 constfullPath=path.resolve(__dirname,'../../',dir);
 bench.start();
 (functionr(cntr){
 if(cntr--<=0)
 returnbench.end(n);
-fs.readdir(fullPath,{ withFileTypes },()=>{
+fs.readdir(fullPath,{ withFileTypes, recursive},()=>{
 r(cntr);
 });
 }(n));

benchmark/fs/bench-readdirSync.js

@@ -8,15 +8,17 @@ const bench = common.createBenchmark(main, {
 n: [10],
 dir: ['lib','test/parallel'],
 withFileTypes: ['true','false'],
+recursive: ['true','false'],
 });
 
 
-functionmain({ n, dir, withFileTypes }){
+functionmain({ n, dir, withFileTypes, recursive}){
 withFileTypes=withFileTypes==='true';
+recursive=recursive==='true';
 constfullPath=path.resolve(__dirname,'../../',dir);
 bench.start();
 for(leti=0;i<n;i++){
-fs.readdirSync(fullPath,{ withFileTypes });
+fs.readdirSync(fullPath,{ withFileTypes, recursive});
 }
 bench.end(n);
 }

lib/fs.js

@@ -57,6 +57,9 @@ const {
 F_OK,
 O_WRONLY,
 O_SYMLINK,
+UV_DIRENT_DIR,
+UV_DIRENT_LINK,
+UV_DIRENT_UNKNOWN,
 }=constants;
 
 constpathModule=require('path');
@@ -1739,6 +1742,43 @@ function mkdirSync(path, options) {
 }
 }
 
+/**
+ * Appends one directory's entries to `context.results` and the subdirectories
+ * still to visit to `context.dirs` (with the prefix their entries get in
+ * string results in `context.prefixes`). `result` is a `binding.readdir()`
+ * result with file types, so only symbolic links and entries of unknown type
+ * need a stat() to find out whether they lead to a directory.
+ * @param {string} dir
+ * @param {string} prefix
+ * @param {[string[], number[]]} result
+ * @param {{ withFileTypes: boolean, results: (string | Dirent)[], dirs: string[], prefixes: string[] }} context
+ */
+functioncollectRecursiveReaddirResult(dir,prefix,{0: names,1: types},context){
+const{ length }=names;
+for(leti=0;i<length;i++){
+constname=names[i];
+constrelative=prefix==='' ? name : `${prefix}${pathModule.sep}${name}`;
+letisDirectory;
+if(context.withFileTypes){
+constdirent=getDirent(dir,name,types[i]);
+ArrayPrototypePush(context.results,dirent);
+// Follow symbolic links to directories, see https://github.com/nodejs/node/issues/52663
+isDirectory=dirent.isDirectory()||
+(dirent.isSymbolicLink()&&binding.internalModuleStat(pathModule.join(dir,name))===1);
+}else{
+ArrayPrototypePush(context.results,relative);
+consttype=types[i];
+isDirectory=type===UV_DIRENT_DIR||
+((type===UV_DIRENT_LINK||type===UV_DIRENT_UNKNOWN)&&
+binding.internalModuleStat(pathModule.join(dir,name))===1);
+}
+if(isDirectory){
+ArrayPrototypePush(context.dirs,pathModule.join(dir,name));
+ArrayPrototypePush(context.prefixes,relative);
+}
+}
+}
+
 /*
  * An recursive algorithm for reading the entire contents of the `basePath` directory.
  * This function does not validate `basePath` as a directory. It is passed directly to
@@ -1754,15 +1794,20 @@ function mkdirSync(path, options) {
 functionreaddirRecursive(basePath,options,callback){
 constcontext={
 withFileTypes: Boolean(options.withFileTypes),
-encoding: options.encoding,
- basePath,
-readdirResults: [],
-pathsQueue: [basePath],
+results: [],
+dirs: [basePath],
+prefixes: [''],
 };
 
 leti=0;
 
-functionread(path){
+/**
+ * Reads one directory from `context.dirs` and then moves on to the next
+ * one, or calls back once none are left.
+ * @param {string} path
+ * @param {string} prefix path of this directory relative to `basePath`
+ */
+functionread(path,prefix){
 constreq=newFSReqCallback();
 req.oncomplete=(err,result)=>{
 if(err){
@@ -1771,68 +1816,28 @@ function readdirRecursive(basePath, options, callback) {
 }
 
 if(result===undefined){
-callback(null,context.readdirResults);
+callback(null,context.results);
 return;
 }
 
-processReaddirResult({
- result,
-currentPath: path,
- context,
-});
+try{
+collectRecursiveReaddirResult(path,prefix,result,context);
+}catch(err){
+callback(err);
+return;
+}
 
-if(i<context.pathsQueue.length){
-read(context.pathsQueue[i++]);
+if(i<context.dirs.length){
+read(context.dirs[i],context.prefixes[i++]);
 }else{
-callback(null,context.readdirResults);
+callback(null,context.results);
 }
 };
 
-binding.readdir(
-path,
-context.encoding,
-context.withFileTypes,
-req,
-);
-}
-
-read(context.pathsQueue[i++]);
-}
-
-// Calling `readdir` with `withFileTypes=true`, the result is an array of arrays.
-// The first array is the names, and the second array is the types.
-// They are guaranteed to be the same length; hence, setting `length` to the length
-// of the first array within the result.
-constprocessReaddirResult=(args)=>(args.context.withFileTypes ? handleDirents(args) : handleFilePaths(args));
-
-functionhandleDirents({ result, currentPath, context }){
-const{0: names,1: types}=result;
-const{ length }=names;
-
-for(leti=0;i<length;i++){
-// Avoid excluding symlinks, as they are not directories.
-// Refs: https://github.com/nodejs/node/issues/52663
-constfullPath=pathModule.join(currentPath,names[i]);
-constdirent=getDirent(currentPath,names[i],types[i]);
-ArrayPrototypePush(context.readdirResults,dirent);
-
-if(dirent.isDirectory()||binding.internalModuleStat(fullPath)===1){
-ArrayPrototypePush(context.pathsQueue,fullPath);
-}
+binding.readdir(path,options.encoding,true,req);
 }
-}
-
-functionhandleFilePaths({ result, currentPath, context }){
-for(leti=0;i<result.length;i++){
-constresultPath=pathModule.join(currentPath,result[i]);
-constrelativeResultPath=pathModule.relative(context.basePath,resultPath);
-conststat=binding.internalModuleStat(resultPath);
-ArrayPrototypePush(context.readdirResults,relativeResultPath);
 
-if(stat===1){
-ArrayPrototypePush(context.pathsQueue,resultPath);
-}
-}
+read(context.dirs[i],context.prefixes[i++]);
 }
 
 /**
@@ -1846,35 +1851,20 @@ function handleFilePaths({ result, currentPath, context }) {
 functionreaddirSyncRecursive(basePath,options){
 constcontext={
 withFileTypes: Boolean(options.withFileTypes),
-encoding: options.encoding,
- basePath,
-readdirResults: [],
-pathsQueue: [basePath],
+results: [],
+dirs: [basePath],
+prefixes: [''],
 };
 
-functionread(path){
-constreaddirResult=binding.readdir(
-path,
-context.encoding,
-context.withFileTypes,
-);
-
-if(readdirResult===undefined){
-return;
+for(leti=0;i<context.dirs.length;i++){
+constdir=context.dirs[i];
+constresult=binding.readdir(dir,options.encoding,true);
+if(result!==undefined){
+collectRecursiveReaddirResult(dir,context.prefixes[i],result,context);
 }
-
-processReaddirResult({
-result: readdirResult,
-currentPath: path,
- context,
-});
-}
-
-for(leti=0;i<context.pathsQueue.length;i++){
-read(context.pathsQueue[i]);
 }
 
-returncontext.readdirResults;
+returncontext.results;
 }
 
 /**

lib/internal/fs/promises.js

@@ -32,6 +32,9 @@ const {
 O_WRONLY,
 S_IFMT,
 S_IFREG,
+UV_DIRENT_DIR,
+UV_DIRENT_LINK,
+UV_DIRENT_UNKNOWN,
 }=constants;
 
 constbinding=internalBinding('fs');
@@ -63,6 +66,7 @@ const {
  kWriteFileMaxChunkSize,
 },
  copyObject,
+ getDirent,
  getDirents,
  getOptions,
  getStatFsFromBinding,
@@ -1638,73 +1642,37 @@ async function mkdir(path, options) {
 }
 
 asyncfunctionreaddirRecursive(originalPath,options){
+constwithFileTypes=!!options.withFileTypes;
+constreaddirWithTypes=(path)=>PromisePrototypeThen(
+binding.readdir(path,options.encoding,true,kUsePromises),
+undefined,
+handleErrorFromBinding,
+);
 constresult=[];
-constqueue=[
-[
-originalPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-originalPath,
-options.encoding,
-!!options.withFileTypes,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-],
-];
-
-
-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(constdirentofgetDirents(path,readdir)){
+constqueue=[[originalPath,'',awaitreaddirWithTypes(originalPath)]];
+
+while(queue.length>0){
+// If we want to implement BFS make this a `shift` call instead of `pop`
+const{0: path,1: prefix,2: {0: names,1: types}}=ArrayPrototypePop(queue);
+for(leti=0;i<names.length;i++){
+constname=names[i];
+constrelative=prefix==='' ? name : `${prefix}${pathModule.sep}${name}`;
+letisDirectory;
+if(withFileTypes){
+constdirent=getDirent(path,name,types[i]);
 ArrayPrototypePush(result,dirent);
-if(dirent.isDirectory()){
-constdirentPath=pathModule.join(path,dirent.name);
-ArrayPrototypePush(queue,[
-direntPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-direntPath,
-options.encoding,
-true,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-]);
-}
+isDirectory=dirent.isDirectory();
+}else{
+ArrayPrototypePush(result,relative);
+// Entries that are, or may be, symbolic links to directories are followed.
+consttype=types[i];
+isDirectory=type===UV_DIRENT_DIR||
+((type===UV_DIRENT_LINK||type===UV_DIRENT_UNKNOWN)&&
+binding.internalModuleStat(pathModule.join(path,name))===1);
 }
-}
-}else{
-while(queue.length>0){
-const{0: path,1: readdir}=ArrayPrototypePop(queue);
-for(constentofreaddir){
-constdirentPath=pathModule.join(path,ent);
-conststat=binding.internalModuleStat(direntPath);
-ArrayPrototypePush(
-result,
-pathModule.relative(originalPath,direntPath),
-);
-if(stat===1){
-ArrayPrototypePush(queue,[
-direntPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-direntPath,
-options.encoding,
-false,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-]);
-}
+if(isDirectory){
+constdirentPath=pathModule.join(path,name);
+ArrayPrototypePush(queue,[direntPath,relative,awaitreaddirWithTypes(direntPath)]);
 }
 }
 }

test/known_issues/test-fs-readdir-recursive-with-buffer.js

@@ -12,4 +12,4 @@ const { readdir } = require('node:fs');
 const{ join }=require('node:path');
 
 consttestDirPath=join(__dirname,'..','..');
-readdir(Buffer.from(testDirPath),{recursive: true},common.mustCall());
+readdir(Buffer.from(testDirPath),{recursive: true},common.mustSucceed());

benchmark/fs/bench-readdir.js

@@ -8,16 +8,18 @@ const bench = common.createBenchmark(main, {
 n: [10],
 dir: ['lib','test/parallel'],
 withFileTypes: ['true','false'],
+recursive: ['true','false'],
 });
 
-functionmain({ n, dir, withFileTypes }){
+functionmain({ n, dir, withFileTypes, recursive}){
 withFileTypes=withFileTypes==='true';
+recursive=recursive==='true';
 constfullPath=path.resolve(__dirname,'../../',dir);
 bench.start();
 (functionr(cntr){
 if(cntr--<=0)
 returnbench.end(n);
-fs.readdir(fullPath,{ withFileTypes },()=>{
+fs.readdir(fullPath,{ withFileTypes, recursive},()=>{
 r(cntr);
 });
 }(n));

benchmark/fs/bench-readdirSync.js

@@ -8,15 +8,17 @@ const bench = common.createBenchmark(main, {
 n: [10],
 dir: ['lib','test/parallel'],
 withFileTypes: ['true','false'],
+recursive: ['true','false'],
 });
 
 
-functionmain({ n, dir, withFileTypes }){
+functionmain({ n, dir, withFileTypes, recursive}){
 withFileTypes=withFileTypes==='true';
+recursive=recursive==='true';
 constfullPath=path.resolve(__dirname,'../../',dir);
 bench.start();
 for(leti=0;i<n;i++){
-fs.readdirSync(fullPath,{ withFileTypes });
+fs.readdirSync(fullPath,{ withFileTypes, recursive});
 }
 bench.end(n);
 }

lib/fs.js

@@ -57,6 +57,9 @@ const {
 F_OK,
 O_WRONLY,
 O_SYMLINK,
+UV_DIRENT_DIR,
+UV_DIRENT_LINK,
+UV_DIRENT_UNKNOWN,
 }=constants;
 
 constpathModule=require('path');
@@ -1739,6 +1742,43 @@ function mkdirSync(path, options) {
 }
 }
 
+/**
+ * Appends one directory's entries to `context.results` and the subdirectories
+ * still to visit to `context.dirs` (with the prefix their entries get in
+ * string results in `context.prefixes`). `result` is a `binding.readdir()`
+ * result with file types, so only symbolic links and entries of unknown type
+ * need a stat() to find out whether they lead to a directory.
+ * @param {string} dir
+ * @param {string} prefix
+ * @param {[string[], number[]]} result
+ * @param {{ withFileTypes: boolean, results: (string | Dirent)[], dirs: string[], prefixes: string[] }} context
+ */
+functioncollectRecursiveReaddirResult(dir,prefix,{0: names,1: types},context){
+const{ length }=names;
+for(leti=0;i<length;i++){
+constname=names[i];
+constrelative=prefix==='' ? name : `${prefix}${pathModule.sep}${name}`;
+letisDirectory;
+if(context.withFileTypes){
+constdirent=getDirent(dir,name,types[i]);
+ArrayPrototypePush(context.results,dirent);
+// Follow symbolic links to directories, see https://github.com/nodejs/node/issues/52663
+isDirectory=dirent.isDirectory()||
+(dirent.isSymbolicLink()&&binding.internalModuleStat(pathModule.join(dir,name))===1);
+}else{
+ArrayPrototypePush(context.results,relative);
+consttype=types[i];
+isDirectory=type===UV_DIRENT_DIR||
+((type===UV_DIRENT_LINK||type===UV_DIRENT_UNKNOWN)&&
+binding.internalModuleStat(pathModule.join(dir,name))===1);
+}
+if(isDirectory){
+ArrayPrototypePush(context.dirs,pathModule.join(dir,name));
+ArrayPrototypePush(context.prefixes,relative);
+}
+}
+}
+
 /*
  * An recursive algorithm for reading the entire contents of the `basePath` directory.
  * This function does not validate `basePath` as a directory. It is passed directly to
@@ -1754,15 +1794,20 @@ function mkdirSync(path, options) {
 functionreaddirRecursive(basePath,options,callback){
 constcontext={
 withFileTypes: Boolean(options.withFileTypes),
-encoding: options.encoding,
- basePath,
-readdirResults: [],
-pathsQueue: [basePath],
+results: [],
+dirs: [basePath],
+prefixes: [''],
 };
 
 leti=0;
 
-functionread(path){
+/**
+ * Reads one directory from `context.dirs` and then moves on to the next
+ * one, or calls back once none are left.
+ * @param {string} path
+ * @param {string} prefix path of this directory relative to `basePath`
+ */
+functionread(path,prefix){
 constreq=newFSReqCallback();
 req.oncomplete=(err,result)=>{
 if(err){
@@ -1771,68 +1816,28 @@ function readdirRecursive(basePath, options, callback) {
 }
 
 if(result===undefined){
-callback(null,context.readdirResults);
+callback(null,context.results);
 return;
 }
 
-processReaddirResult({
- result,
-currentPath: path,
- context,
-});
+try{
+collectRecursiveReaddirResult(path,prefix,result,context);
+}catch(err){
+callback(err);
+return;
+}
 
-if(i<context.pathsQueue.length){
-read(context.pathsQueue[i++]);
+if(i<context.dirs.length){
+read(context.dirs[i],context.prefixes[i++]);
 }else{
-callback(null,context.readdirResults);
+callback(null,context.results);
 }
 };
 
-binding.readdir(
-path,
-context.encoding,
-context.withFileTypes,
-req,
-);
-}
-
-read(context.pathsQueue[i++]);
-}
-
-// Calling `readdir` with `withFileTypes=true`, the result is an array of arrays.
-// The first array is the names, and the second array is the types.
-// They are guaranteed to be the same length; hence, setting `length` to the length
-// of the first array within the result.
-constprocessReaddirResult=(args)=>(args.context.withFileTypes ? handleDirents(args) : handleFilePaths(args));
-
-functionhandleDirents({ result, currentPath, context }){
-const{0: names,1: types}=result;
-const{ length }=names;
-
-for(leti=0;i<length;i++){
-// Avoid excluding symlinks, as they are not directories.
-// Refs: https://github.com/nodejs/node/issues/52663
-constfullPath=pathModule.join(currentPath,names[i]);
-constdirent=getDirent(currentPath,names[i],types[i]);
-ArrayPrototypePush(context.readdirResults,dirent);
-
-if(dirent.isDirectory()||binding.internalModuleStat(fullPath)===1){
-ArrayPrototypePush(context.pathsQueue,fullPath);
-}
+binding.readdir(path,options.encoding,true,req);
 }
-}
-
-functionhandleFilePaths({ result, currentPath, context }){
-for(leti=0;i<result.length;i++){
-constresultPath=pathModule.join(currentPath,result[i]);
-constrelativeResultPath=pathModule.relative(context.basePath,resultPath);
-conststat=binding.internalModuleStat(resultPath);
-ArrayPrototypePush(context.readdirResults,relativeResultPath);
 
-if(stat===1){
-ArrayPrototypePush(context.pathsQueue,resultPath);
-}
-}
+read(context.dirs[i],context.prefixes[i++]);
 }
 
 /**
@@ -1846,35 +1851,20 @@ function handleFilePaths({ result, currentPath, context }) {
 functionreaddirSyncRecursive(basePath,options){
 constcontext={
 withFileTypes: Boolean(options.withFileTypes),
-encoding: options.encoding,
- basePath,
-readdirResults: [],
-pathsQueue: [basePath],
+results: [],
+dirs: [basePath],
+prefixes: [''],
 };
 
-functionread(path){
-constreaddirResult=binding.readdir(
-path,
-context.encoding,
-context.withFileTypes,
-);
-
-if(readdirResult===undefined){
-return;
+for(leti=0;i<context.dirs.length;i++){
+constdir=context.dirs[i];
+constresult=binding.readdir(dir,options.encoding,true);
+if(result!==undefined){
+collectRecursiveReaddirResult(dir,context.prefixes[i],result,context);
 }
-
-processReaddirResult({
-result: readdirResult,
-currentPath: path,
- context,
-});
-}
-
-for(leti=0;i<context.pathsQueue.length;i++){
-read(context.pathsQueue[i]);
 }
 
-returncontext.readdirResults;
+returncontext.results;
 }
 
 /**

lib/internal/fs/promises.js

@@ -32,6 +32,9 @@ const {
 O_WRONLY,
 S_IFMT,
 S_IFREG,
+UV_DIRENT_DIR,
+UV_DIRENT_LINK,
+UV_DIRENT_UNKNOWN,
 }=constants;
 
 constbinding=internalBinding('fs');
@@ -63,6 +66,7 @@ const {
  kWriteFileMaxChunkSize,
 },
  copyObject,
+ getDirent,
  getDirents,
  getOptions,
  getStatFsFromBinding,
@@ -1638,73 +1642,37 @@ async function mkdir(path, options) {
 }
 
 asyncfunctionreaddirRecursive(originalPath,options){
+constwithFileTypes=!!options.withFileTypes;
+constreaddirWithTypes=(path)=>PromisePrototypeThen(
+binding.readdir(path,options.encoding,true,kUsePromises),
+undefined,
+handleErrorFromBinding,
+);
 constresult=[];
-constqueue=[
-[
-originalPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-originalPath,
-options.encoding,
-!!options.withFileTypes,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-],
-];
-
-
-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(constdirentofgetDirents(path,readdir)){
+constqueue=[[originalPath,'',awaitreaddirWithTypes(originalPath)]];
+
+while(queue.length>0){
+// If we want to implement BFS make this a `shift` call instead of `pop`
+const{0: path,1: prefix,2: {0: names,1: types}}=ArrayPrototypePop(queue);
+for(leti=0;i<names.length;i++){
+constname=names[i];
+constrelative=prefix==='' ? name : `${prefix}${pathModule.sep}${name}`;
+letisDirectory;
+if(withFileTypes){
+constdirent=getDirent(path,name,types[i]);
 ArrayPrototypePush(result,dirent);
-if(dirent.isDirectory()){
-constdirentPath=pathModule.join(path,dirent.name);
-ArrayPrototypePush(queue,[
-direntPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-direntPath,
-options.encoding,
-true,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-]);
-}
+isDirectory=dirent.isDirectory();
+}else{
+ArrayPrototypePush(result,relative);
+// Entries that are, or may be, symbolic links to directories are followed.
+consttype=types[i];
+isDirectory=type===UV_DIRENT_DIR||
+((type===UV_DIRENT_LINK||type===UV_DIRENT_UNKNOWN)&&
+binding.internalModuleStat(pathModule.join(path,name))===1);
 }
-}
-}else{
-while(queue.length>0){
-const{0: path,1: readdir}=ArrayPrototypePop(queue);
-for(constentofreaddir){
-constdirentPath=pathModule.join(path,ent);
-conststat=binding.internalModuleStat(direntPath);
-ArrayPrototypePush(
-result,
-pathModule.relative(originalPath,direntPath),
-);
-if(stat===1){
-ArrayPrototypePush(queue,[
-direntPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-direntPath,
-options.encoding,
-false,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-]);
-}
+if(isDirectory){
+constdirentPath=pathModule.join(path,name);
+ArrayPrototypePush(queue,[direntPath,relative,awaitreaddirWithTypes(direntPath)]);
 }
 }
 }

test/known_issues/test-fs-readdir-recursive-with-buffer.js

@@ -12,4 +12,4 @@ const { readdir } = require('node:fs');
 const{ join }=require('node:path');
 
 consttestDirPath=join(__dirname,'..','..');
-readdir(Buffer.from(testDirPath),{recursive: true},common.mustCall());
+readdir(Buffer.from(testDirPath),{recursive: true},common.mustSucceed());

benchmark/fs/bench-readdir.js

@@ -8,16 +8,18 @@ const bench = common.createBenchmark(main, {
 n: [10],
 dir: ['lib','test/parallel'],
 withFileTypes: ['true','false'],
+recursive: ['true','false'],
 });
 
-functionmain({ n, dir, withFileTypes }){
+functionmain({ n, dir, withFileTypes, recursive}){
 withFileTypes=withFileTypes==='true';
+recursive=recursive==='true';
 constfullPath=path.resolve(__dirname,'../../',dir);
 bench.start();
 (functionr(cntr){
 if(cntr--<=0)
 returnbench.end(n);
-fs.readdir(fullPath,{ withFileTypes },()=>{
+fs.readdir(fullPath,{ withFileTypes, recursive},()=>{
 r(cntr);
 });
 }(n));

benchmark/fs/bench-readdirSync.js

@@ -8,15 +8,17 @@ const bench = common.createBenchmark(main, {
 n: [10],
 dir: ['lib','test/parallel'],
 withFileTypes: ['true','false'],
+recursive: ['true','false'],
 });
 
 
-functionmain({ n, dir, withFileTypes }){
+functionmain({ n, dir, withFileTypes, recursive}){
 withFileTypes=withFileTypes==='true';
+recursive=recursive==='true';
 constfullPath=path.resolve(__dirname,'../../',dir);
 bench.start();
 for(leti=0;i<n;i++){
-fs.readdirSync(fullPath,{ withFileTypes });
+fs.readdirSync(fullPath,{ withFileTypes, recursive});
 }
 bench.end(n);
 }

lib/fs.js

@@ -57,6 +57,9 @@ const {
 F_OK,
 O_WRONLY,
 O_SYMLINK,
+UV_DIRENT_DIR,
+UV_DIRENT_LINK,
+UV_DIRENT_UNKNOWN,
 }=constants;
 
 constpathModule=require('path');
@@ -1739,6 +1742,43 @@ function mkdirSync(path, options) {
 }
 }
 
+/**
+ * Appends one directory's entries to `context.results` and the subdirectories
+ * still to visit to `context.dirs` (with the prefix their entries get in
+ * string results in `context.prefixes`). `result` is a `binding.readdir()`
+ * result with file types, so only symbolic links and entries of unknown type
+ * need a stat() to find out whether they lead to a directory.
+ * @param {string} dir
+ * @param {string} prefix
+ * @param {[string[], number[]]} result
+ * @param {{ withFileTypes: boolean, results: (string | Dirent)[], dirs: string[], prefixes: string[] }} context
+ */
+functioncollectRecursiveReaddirResult(dir,prefix,{0: names,1: types},context){
+const{ length }=names;
+for(leti=0;i<length;i++){
+constname=names[i];
+constrelative=prefix==='' ? name : `${prefix}${pathModule.sep}${name}`;
+letisDirectory;
+if(context.withFileTypes){
+constdirent=getDirent(dir,name,types[i]);
+ArrayPrototypePush(context.results,dirent);
+// Follow symbolic links to directories, see https://github.com/nodejs/node/issues/52663
+isDirectory=dirent.isDirectory()||
+(dirent.isSymbolicLink()&&binding.internalModuleStat(pathModule.join(dir,name))===1);
+}else{
+ArrayPrototypePush(context.results,relative);
+consttype=types[i];
+isDirectory=type===UV_DIRENT_DIR||
+((type===UV_DIRENT_LINK||type===UV_DIRENT_UNKNOWN)&&
+binding.internalModuleStat(pathModule.join(dir,name))===1);
+}
+if(isDirectory){
+ArrayPrototypePush(context.dirs,pathModule.join(dir,name));
+ArrayPrototypePush(context.prefixes,relative);
+}
+}
+}
+
 /*
  * An recursive algorithm for reading the entire contents of the `basePath` directory.
  * This function does not validate `basePath` as a directory. It is passed directly to
@@ -1754,15 +1794,20 @@ function mkdirSync(path, options) {
 functionreaddirRecursive(basePath,options,callback){
 constcontext={
 withFileTypes: Boolean(options.withFileTypes),
-encoding: options.encoding,
- basePath,
-readdirResults: [],
-pathsQueue: [basePath],
+results: [],
+dirs: [basePath],
+prefixes: [''],
 };
 
 leti=0;
 
-functionread(path){
+/**
+ * Reads one directory from `context.dirs` and then moves on to the next
+ * one, or calls back once none are left.
+ * @param {string} path
+ * @param {string} prefix path of this directory relative to `basePath`
+ */
+functionread(path,prefix){
 constreq=newFSReqCallback();
 req.oncomplete=(err,result)=>{
 if(err){
@@ -1771,68 +1816,28 @@ function readdirRecursive(basePath, options, callback) {
 }
 
 if(result===undefined){
-callback(null,context.readdirResults);
+callback(null,context.results);
 return;
 }
 
-processReaddirResult({
- result,
-currentPath: path,
- context,
-});
+try{
+collectRecursiveReaddirResult(path,prefix,result,context);
+}catch(err){
+callback(err);
+return;
+}
 
-if(i<context.pathsQueue.length){
-read(context.pathsQueue[i++]);
+if(i<context.dirs.length){
+read(context.dirs[i],context.prefixes[i++]);
 }else{
-callback(null,context.readdirResults);
+callback(null,context.results);
 }
 };
 
-binding.readdir(
-path,
-context.encoding,
-context.withFileTypes,
-req,
-);
-}
-
-read(context.pathsQueue[i++]);
-}
-
-// Calling `readdir` with `withFileTypes=true`, the result is an array of arrays.
-// The first array is the names, and the second array is the types.
-// They are guaranteed to be the same length; hence, setting `length` to the length
-// of the first array within the result.
-constprocessReaddirResult=(args)=>(args.context.withFileTypes ? handleDirents(args) : handleFilePaths(args));
-
-functionhandleDirents({ result, currentPath, context }){
-const{0: names,1: types}=result;
-const{ length }=names;
-
-for(leti=0;i<length;i++){
-// Avoid excluding symlinks, as they are not directories.
-// Refs: https://github.com/nodejs/node/issues/52663
-constfullPath=pathModule.join(currentPath,names[i]);
-constdirent=getDirent(currentPath,names[i],types[i]);
-ArrayPrototypePush(context.readdirResults,dirent);
-
-if(dirent.isDirectory()||binding.internalModuleStat(fullPath)===1){
-ArrayPrototypePush(context.pathsQueue,fullPath);
-}
+binding.readdir(path,options.encoding,true,req);
 }
-}
-
-functionhandleFilePaths({ result, currentPath, context }){
-for(leti=0;i<result.length;i++){
-constresultPath=pathModule.join(currentPath,result[i]);
-constrelativeResultPath=pathModule.relative(context.basePath,resultPath);
-conststat=binding.internalModuleStat(resultPath);
-ArrayPrototypePush(context.readdirResults,relativeResultPath);
 
-if(stat===1){
-ArrayPrototypePush(context.pathsQueue,resultPath);
-}
-}
+read(context.dirs[i],context.prefixes[i++]);
 }
 
 /**
@@ -1846,35 +1851,20 @@ function handleFilePaths({ result, currentPath, context }) {
 functionreaddirSyncRecursive(basePath,options){
 constcontext={
 withFileTypes: Boolean(options.withFileTypes),
-encoding: options.encoding,
- basePath,
-readdirResults: [],
-pathsQueue: [basePath],
+results: [],
+dirs: [basePath],
+prefixes: [''],
 };
 
-functionread(path){
-constreaddirResult=binding.readdir(
-path,
-context.encoding,
-context.withFileTypes,
-);
-
-if(readdirResult===undefined){
-return;
+for(leti=0;i<context.dirs.length;i++){
+constdir=context.dirs[i];
+constresult=binding.readdir(dir,options.encoding,true);
+if(result!==undefined){
+collectRecursiveReaddirResult(dir,context.prefixes[i],result,context);
 }
-
-processReaddirResult({
-result: readdirResult,
-currentPath: path,
- context,
-});
-}
-
-for(leti=0;i<context.pathsQueue.length;i++){
-read(context.pathsQueue[i]);
 }
 
-returncontext.readdirResults;
+returncontext.results;
 }
 
 /**

lib/internal/fs/promises.js

@@ -32,6 +32,9 @@ const {
 O_WRONLY,
 S_IFMT,
 S_IFREG,
+UV_DIRENT_DIR,
+UV_DIRENT_LINK,
+UV_DIRENT_UNKNOWN,
 }=constants;
 
 constbinding=internalBinding('fs');
@@ -63,6 +66,7 @@ const {
  kWriteFileMaxChunkSize,
 },
  copyObject,
+ getDirent,
  getDirents,
  getOptions,
  getStatFsFromBinding,
@@ -1638,73 +1642,37 @@ async function mkdir(path, options) {
 }
 
 asyncfunctionreaddirRecursive(originalPath,options){
+constwithFileTypes=!!options.withFileTypes;
+constreaddirWithTypes=(path)=>PromisePrototypeThen(
+binding.readdir(path,options.encoding,true,kUsePromises),
+undefined,
+handleErrorFromBinding,
+);
 constresult=[];
-constqueue=[
-[
-originalPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-originalPath,
-options.encoding,
-!!options.withFileTypes,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-],
-];
-
-
-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(constdirentofgetDirents(path,readdir)){
+constqueue=[[originalPath,'',awaitreaddirWithTypes(originalPath)]];
+
+while(queue.length>0){
+// If we want to implement BFS make this a `shift` call instead of `pop`
+const{0: path,1: prefix,2: {0: names,1: types}}=ArrayPrototypePop(queue);
+for(leti=0;i<names.length;i++){
+constname=names[i];
+constrelative=prefix==='' ? name : `${prefix}${pathModule.sep}${name}`;
+letisDirectory;
+if(withFileTypes){
+constdirent=getDirent(path,name,types[i]);
 ArrayPrototypePush(result,dirent);
-if(dirent.isDirectory()){
-constdirentPath=pathModule.join(path,dirent.name);
-ArrayPrototypePush(queue,[
-direntPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-direntPath,
-options.encoding,
-true,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-]);
-}
+isDirectory=dirent.isDirectory();
+}else{
+ArrayPrototypePush(result,relative);
+// Entries that are, or may be, symbolic links to directories are followed.
+consttype=types[i];
+isDirectory=type===UV_DIRENT_DIR||
+((type===UV_DIRENT_LINK||type===UV_DIRENT_UNKNOWN)&&
+binding.internalModuleStat(pathModule.join(path,name))===1);
 }
-}
-}else{
-while(queue.length>0){
-const{0: path,1: readdir}=ArrayPrototypePop(queue);
-for(constentofreaddir){
-constdirentPath=pathModule.join(path,ent);
-conststat=binding.internalModuleStat(direntPath);
-ArrayPrototypePush(
-result,
-pathModule.relative(originalPath,direntPath),
-);
-if(stat===1){
-ArrayPrototypePush(queue,[
-direntPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-direntPath,
-options.encoding,
-false,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-]);
-}
+if(isDirectory){
+constdirentPath=pathModule.join(path,name);
+ArrayPrototypePush(queue,[direntPath,relative,awaitreaddirWithTypes(direntPath)]);
 }
 }
 }

test/known_issues/test-fs-readdir-recursive-with-buffer.js

@@ -12,4 +12,4 @@ const { readdir } = require('node:fs');
 const{ join }=require('node:path');
 
 consttestDirPath=join(__dirname,'..','..');
-readdir(Buffer.from(testDirPath),{recursive: true},common.mustCall());
+readdir(Buffer.from(testDirPath),{recursive: true},common.mustSucceed());

benchmark/fs/bench-readdir.js

@@ -8,16 +8,18 @@ const bench = common.createBenchmark(main, {
 n: [10],
 dir: ['lib','test/parallel'],
 withFileTypes: ['true','false'],
+recursive: ['true','false'],
 });
 
-functionmain({ n, dir, withFileTypes }){
+functionmain({ n, dir, withFileTypes, recursive}){
 withFileTypes=withFileTypes==='true';
+recursive=recursive==='true';
 constfullPath=path.resolve(__dirname,'../../',dir);
 bench.start();
 (functionr(cntr){
 if(cntr--<=0)
 returnbench.end(n);
-fs.readdir(fullPath,{ withFileTypes },()=>{
+fs.readdir(fullPath,{ withFileTypes, recursive},()=>{
 r(cntr);
 });
 }(n));

benchmark/fs/bench-readdirSync.js

@@ -8,15 +8,17 @@ const bench = common.createBenchmark(main, {
 n: [10],
 dir: ['lib','test/parallel'],
 withFileTypes: ['true','false'],
+recursive: ['true','false'],
 });
 
 
-functionmain({ n, dir, withFileTypes }){
+functionmain({ n, dir, withFileTypes, recursive}){
 withFileTypes=withFileTypes==='true';
+recursive=recursive==='true';
 constfullPath=path.resolve(__dirname,'../../',dir);
 bench.start();
 for(leti=0;i<n;i++){
-fs.readdirSync(fullPath,{ withFileTypes });
+fs.readdirSync(fullPath,{ withFileTypes, recursive});
 }
 bench.end(n);
 }

lib/fs.js

@@ -57,6 +57,9 @@ const {
 F_OK,
 O_WRONLY,
 O_SYMLINK,
+UV_DIRENT_DIR,
+UV_DIRENT_LINK,
+UV_DIRENT_UNKNOWN,
 }=constants;
 
 constpathModule=require('path');
@@ -1739,6 +1742,43 @@ function mkdirSync(path, options) {
 }
 }
 
+/**
+ * Appends one directory's entries to `context.results` and the subdirectories
+ * still to visit to `context.dirs` (with the prefix their entries get in
+ * string results in `context.prefixes`). `result` is a `binding.readdir()`
+ * result with file types, so only symbolic links and entries of unknown type
+ * need a stat() to find out whether they lead to a directory.
+ * @param {string} dir
+ * @param {string} prefix
+ * @param {[string[], number[]]} result
+ * @param {{ withFileTypes: boolean, results: (string | Dirent)[], dirs: string[], prefixes: string[] }} context
+ */
+functioncollectRecursiveReaddirResult(dir,prefix,{0: names,1: types},context){
+const{ length }=names;
+for(leti=0;i<length;i++){
+constname=names[i];
+constrelative=prefix==='' ? name : `${prefix}${pathModule.sep}${name}`;
+letisDirectory;
+if(context.withFileTypes){
+constdirent=getDirent(dir,name,types[i]);
+ArrayPrototypePush(context.results,dirent);
+// Follow symbolic links to directories, see https://github.com/nodejs/node/issues/52663
+isDirectory=dirent.isDirectory()||
+(dirent.isSymbolicLink()&&binding.internalModuleStat(pathModule.join(dir,name))===1);
+}else{
+ArrayPrototypePush(context.results,relative);
+consttype=types[i];
+isDirectory=type===UV_DIRENT_DIR||
+((type===UV_DIRENT_LINK||type===UV_DIRENT_UNKNOWN)&&
+binding.internalModuleStat(pathModule.join(dir,name))===1);
+}
+if(isDirectory){
+ArrayPrototypePush(context.dirs,pathModule.join(dir,name));
+ArrayPrototypePush(context.prefixes,relative);
+}
+}
+}
+
 /*
  * An recursive algorithm for reading the entire contents of the `basePath` directory.
  * This function does not validate `basePath` as a directory. It is passed directly to
@@ -1754,15 +1794,20 @@ function mkdirSync(path, options) {
 functionreaddirRecursive(basePath,options,callback){
 constcontext={
 withFileTypes: Boolean(options.withFileTypes),
-encoding: options.encoding,
- basePath,
-readdirResults: [],
-pathsQueue: [basePath],
+results: [],
+dirs: [basePath],
+prefixes: [''],
 };
 
 leti=0;
 
-functionread(path){
+/**
+ * Reads one directory from `context.dirs` and then moves on to the next
+ * one, or calls back once none are left.
+ * @param {string} path
+ * @param {string} prefix path of this directory relative to `basePath`
+ */
+functionread(path,prefix){
 constreq=newFSReqCallback();
 req.oncomplete=(err,result)=>{
 if(err){
@@ -1771,68 +1816,28 @@ function readdirRecursive(basePath, options, callback) {
 }
 
 if(result===undefined){
-callback(null,context.readdirResults);
+callback(null,context.results);
 return;
 }
 
-processReaddirResult({
- result,
-currentPath: path,
- context,
-});
+try{
+collectRecursiveReaddirResult(path,prefix,result,context);
+}catch(err){
+callback(err);
+return;
+}
 
-if(i<context.pathsQueue.length){
-read(context.pathsQueue[i++]);
+if(i<context.dirs.length){
+read(context.dirs[i],context.prefixes[i++]);
 }else{
-callback(null,context.readdirResults);
+callback(null,context.results);
 }
 };
 
-binding.readdir(
-path,
-context.encoding,
-context.withFileTypes,
-req,
-);
-}
-
-read(context.pathsQueue[i++]);
-}
-
-// Calling `readdir` with `withFileTypes=true`, the result is an array of arrays.
-// The first array is the names, and the second array is the types.
-// They are guaranteed to be the same length; hence, setting `length` to the length
-// of the first array within the result.
-constprocessReaddirResult=(args)=>(args.context.withFileTypes ? handleDirents(args) : handleFilePaths(args));
-
-functionhandleDirents({ result, currentPath, context }){
-const{0: names,1: types}=result;
-const{ length }=names;
-
-for(leti=0;i<length;i++){
-// Avoid excluding symlinks, as they are not directories.
-// Refs: https://github.com/nodejs/node/issues/52663
-constfullPath=pathModule.join(currentPath,names[i]);
-constdirent=getDirent(currentPath,names[i],types[i]);
-ArrayPrototypePush(context.readdirResults,dirent);
-
-if(dirent.isDirectory()||binding.internalModuleStat(fullPath)===1){
-ArrayPrototypePush(context.pathsQueue,fullPath);
-}
+binding.readdir(path,options.encoding,true,req);
 }
-}
-
-functionhandleFilePaths({ result, currentPath, context }){
-for(leti=0;i<result.length;i++){
-constresultPath=pathModule.join(currentPath,result[i]);
-constrelativeResultPath=pathModule.relative(context.basePath,resultPath);
-conststat=binding.internalModuleStat(resultPath);
-ArrayPrototypePush(context.readdirResults,relativeResultPath);
 
-if(stat===1){
-ArrayPrototypePush(context.pathsQueue,resultPath);
-}
-}
+read(context.dirs[i],context.prefixes[i++]);
 }
 
 /**
@@ -1846,35 +1851,20 @@ function handleFilePaths({ result, currentPath, context }) {
 functionreaddirSyncRecursive(basePath,options){
 constcontext={
 withFileTypes: Boolean(options.withFileTypes),
-encoding: options.encoding,
- basePath,
-readdirResults: [],
-pathsQueue: [basePath],
+results: [],
+dirs: [basePath],
+prefixes: [''],
 };
 
-functionread(path){
-constreaddirResult=binding.readdir(
-path,
-context.encoding,
-context.withFileTypes,
-);
-
-if(readdirResult===undefined){
-return;
+for(leti=0;i<context.dirs.length;i++){
+constdir=context.dirs[i];
+constresult=binding.readdir(dir,options.encoding,true);
+if(result!==undefined){
+collectRecursiveReaddirResult(dir,context.prefixes[i],result,context);
 }
-
-processReaddirResult({
-result: readdirResult,
-currentPath: path,
- context,
-});
-}
-
-for(leti=0;i<context.pathsQueue.length;i++){
-read(context.pathsQueue[i]);
 }
 
-returncontext.readdirResults;
+returncontext.results;
 }
 
 /**

lib/internal/fs/promises.js

@@ -32,6 +32,9 @@ const {
 O_WRONLY,
 S_IFMT,
 S_IFREG,
+UV_DIRENT_DIR,
+UV_DIRENT_LINK,
+UV_DIRENT_UNKNOWN,
 }=constants;
 
 constbinding=internalBinding('fs');
@@ -63,6 +66,7 @@ const {
  kWriteFileMaxChunkSize,
 },
  copyObject,
+ getDirent,
  getDirents,
  getOptions,
  getStatFsFromBinding,
@@ -1638,73 +1642,37 @@ async function mkdir(path, options) {
 }
 
 asyncfunctionreaddirRecursive(originalPath,options){
+constwithFileTypes=!!options.withFileTypes;
+constreaddirWithTypes=(path)=>PromisePrototypeThen(
+binding.readdir(path,options.encoding,true,kUsePromises),
+undefined,
+handleErrorFromBinding,
+);
 constresult=[];
-constqueue=[
-[
-originalPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-originalPath,
-options.encoding,
-!!options.withFileTypes,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-],
-];
-
-
-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(constdirentofgetDirents(path,readdir)){
+constqueue=[[originalPath,'',awaitreaddirWithTypes(originalPath)]];
+
+while(queue.length>0){
+// If we want to implement BFS make this a `shift` call instead of `pop`
+const{0: path,1: prefix,2: {0: names,1: types}}=ArrayPrototypePop(queue);
+for(leti=0;i<names.length;i++){
+constname=names[i];
+constrelative=prefix==='' ? name : `${prefix}${pathModule.sep}${name}`;
+letisDirectory;
+if(withFileTypes){
+constdirent=getDirent(path,name,types[i]);
 ArrayPrototypePush(result,dirent);
-if(dirent.isDirectory()){
-constdirentPath=pathModule.join(path,dirent.name);
-ArrayPrototypePush(queue,[
-direntPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-direntPath,
-options.encoding,
-true,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-]);
-}
+isDirectory=dirent.isDirectory();
+}else{
+ArrayPrototypePush(result,relative);
+// Entries that are, or may be, symbolic links to directories are followed.
+consttype=types[i];
+isDirectory=type===UV_DIRENT_DIR||
+((type===UV_DIRENT_LINK||type===UV_DIRENT_UNKNOWN)&&
+binding.internalModuleStat(pathModule.join(path,name))===1);
 }
-}
-}else{
-while(queue.length>0){
-const{0: path,1: readdir}=ArrayPrototypePop(queue);
-for(constentofreaddir){
-constdirentPath=pathModule.join(path,ent);
-conststat=binding.internalModuleStat(direntPath);
-ArrayPrototypePush(
-result,
-pathModule.relative(originalPath,direntPath),
-);
-if(stat===1){
-ArrayPrototypePush(queue,[
-direntPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-direntPath,
-options.encoding,
-false,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-]);
-}
+if(isDirectory){
+constdirentPath=pathModule.join(path,name);
+ArrayPrototypePush(queue,[direntPath,relative,awaitreaddirWithTypes(direntPath)]);
 }
 }
 }

test/known_issues/test-fs-readdir-recursive-with-buffer.js

@@ -12,4 +12,4 @@ const { readdir } = require('node:fs');
 const{ join }=require('node:path');
 
 consttestDirPath=join(__dirname,'..','..');
-readdir(Buffer.from(testDirPath),{recursive: true},common.mustCall());
+readdir(Buffer.from(testDirPath),{recursive: true},common.mustSucceed());

benchmark/fs/bench-readdir.js

@@ -8,16 +8,18 @@ const bench = common.createBenchmark(main, {
 n: [10],
 dir: ['lib','test/parallel'],
 withFileTypes: ['true','false'],
+recursive: ['true','false'],
 });
 
-functionmain({ n, dir, withFileTypes }){
+functionmain({ n, dir, withFileTypes, recursive}){
 withFileTypes=withFileTypes==='true';
+recursive=recursive==='true';
 constfullPath=path.resolve(__dirname,'../../',dir);
 bench.start();
 (functionr(cntr){
 if(cntr--<=0)
 returnbench.end(n);
-fs.readdir(fullPath,{ withFileTypes },()=>{
+fs.readdir(fullPath,{ withFileTypes, recursive},()=>{
 r(cntr);
 });
 }(n));

benchmark/fs/bench-readdirSync.js

@@ -8,15 +8,17 @@ const bench = common.createBenchmark(main, {
 n: [10],
 dir: ['lib','test/parallel'],
 withFileTypes: ['true','false'],
+recursive: ['true','false'],
 });
 
 
-functionmain({ n, dir, withFileTypes }){
+functionmain({ n, dir, withFileTypes, recursive}){
 withFileTypes=withFileTypes==='true';
+recursive=recursive==='true';
 constfullPath=path.resolve(__dirname,'../../',dir);
 bench.start();
 for(leti=0;i<n;i++){
-fs.readdirSync(fullPath,{ withFileTypes });
+fs.readdirSync(fullPath,{ withFileTypes, recursive});
 }
 bench.end(n);
 }

lib/fs.js

@@ -57,6 +57,9 @@ const {
 F_OK,
 O_WRONLY,
 O_SYMLINK,
+UV_DIRENT_DIR,
+UV_DIRENT_LINK,
+UV_DIRENT_UNKNOWN,
 }=constants;
 
 constpathModule=require('path');
@@ -1739,6 +1742,43 @@ function mkdirSync(path, options) {
 }
 }
 
+/**
+ * Appends one directory's entries to `context.results` and the subdirectories
+ * still to visit to `context.dirs` (with the prefix their entries get in
+ * string results in `context.prefixes`). `result` is a `binding.readdir()`
+ * result with file types, so only symbolic links and entries of unknown type
+ * need a stat() to find out whether they lead to a directory.
+ * @param {string} dir
+ * @param {string} prefix
+ * @param {[string[], number[]]} result
+ * @param {{ withFileTypes: boolean, results: (string | Dirent)[], dirs: string[], prefixes: string[] }} context
+ */
+functioncollectRecursiveReaddirResult(dir,prefix,{0: names,1: types},context){
+const{ length }=names;
+for(leti=0;i<length;i++){
+constname=names[i];
+constrelative=prefix==='' ? name : `${prefix}${pathModule.sep}${name}`;
+letisDirectory;
+if(context.withFileTypes){
+constdirent=getDirent(dir,name,types[i]);
+ArrayPrototypePush(context.results,dirent);
+// Follow symbolic links to directories, see https://github.com/nodejs/node/issues/52663
+isDirectory=dirent.isDirectory()||
+(dirent.isSymbolicLink()&&binding.internalModuleStat(pathModule.join(dir,name))===1);
+}else{
+ArrayPrototypePush(context.results,relative);
+consttype=types[i];
+isDirectory=type===UV_DIRENT_DIR||
+((type===UV_DIRENT_LINK||type===UV_DIRENT_UNKNOWN)&&
+binding.internalModuleStat(pathModule.join(dir,name))===1);
+}
+if(isDirectory){
+ArrayPrototypePush(context.dirs,pathModule.join(dir,name));
+ArrayPrototypePush(context.prefixes,relative);
+}
+}
+}
+
 /*
  * An recursive algorithm for reading the entire contents of the `basePath` directory.
  * This function does not validate `basePath` as a directory. It is passed directly to
@@ -1754,15 +1794,20 @@ function mkdirSync(path, options) {
 functionreaddirRecursive(basePath,options,callback){
 constcontext={
 withFileTypes: Boolean(options.withFileTypes),
-encoding: options.encoding,
- basePath,
-readdirResults: [],
-pathsQueue: [basePath],
+results: [],
+dirs: [basePath],
+prefixes: [''],
 };
 
 leti=0;
 
-functionread(path){
+/**
+ * Reads one directory from `context.dirs` and then moves on to the next
+ * one, or calls back once none are left.
+ * @param {string} path
+ * @param {string} prefix path of this directory relative to `basePath`
+ */
+functionread(path,prefix){
 constreq=newFSReqCallback();
 req.oncomplete=(err,result)=>{
 if(err){
@@ -1771,68 +1816,28 @@ function readdirRecursive(basePath, options, callback) {
 }
 
 if(result===undefined){
-callback(null,context.readdirResults);
+callback(null,context.results);
 return;
 }
 
-processReaddirResult({
- result,
-currentPath: path,
- context,
-});
+try{
+collectRecursiveReaddirResult(path,prefix,result,context);
+}catch(err){
+callback(err);
+return;
+}
 
-if(i<context.pathsQueue.length){
-read(context.pathsQueue[i++]);
+if(i<context.dirs.length){
+read(context.dirs[i],context.prefixes[i++]);
 }else{
-callback(null,context.readdirResults);
+callback(null,context.results);
 }
 };
 
-binding.readdir(
-path,
-context.encoding,
-context.withFileTypes,
-req,
-);
-}
-
-read(context.pathsQueue[i++]);
-}
-
-// Calling `readdir` with `withFileTypes=true`, the result is an array of arrays.
-// The first array is the names, and the second array is the types.
-// They are guaranteed to be the same length; hence, setting `length` to the length
-// of the first array within the result.
-constprocessReaddirResult=(args)=>(args.context.withFileTypes ? handleDirents(args) : handleFilePaths(args));
-
-functionhandleDirents({ result, currentPath, context }){
-const{0: names,1: types}=result;
-const{ length }=names;
-
-for(leti=0;i<length;i++){
-// Avoid excluding symlinks, as they are not directories.
-// Refs: https://github.com/nodejs/node/issues/52663
-constfullPath=pathModule.join(currentPath,names[i]);
-constdirent=getDirent(currentPath,names[i],types[i]);
-ArrayPrototypePush(context.readdirResults,dirent);
-
-if(dirent.isDirectory()||binding.internalModuleStat(fullPath)===1){
-ArrayPrototypePush(context.pathsQueue,fullPath);
-}
+binding.readdir(path,options.encoding,true,req);
 }
-}
-
-functionhandleFilePaths({ result, currentPath, context }){
-for(leti=0;i<result.length;i++){
-constresultPath=pathModule.join(currentPath,result[i]);
-constrelativeResultPath=pathModule.relative(context.basePath,resultPath);
-conststat=binding.internalModuleStat(resultPath);
-ArrayPrototypePush(context.readdirResults,relativeResultPath);
 
-if(stat===1){
-ArrayPrototypePush(context.pathsQueue,resultPath);
-}
-}
+read(context.dirs[i],context.prefixes[i++]);
 }
 
 /**
@@ -1846,35 +1851,20 @@ function handleFilePaths({ result, currentPath, context }) {
 functionreaddirSyncRecursive(basePath,options){
 constcontext={
 withFileTypes: Boolean(options.withFileTypes),
-encoding: options.encoding,
- basePath,
-readdirResults: [],
-pathsQueue: [basePath],
+results: [],
+dirs: [basePath],
+prefixes: [''],
 };
 
-functionread(path){
-constreaddirResult=binding.readdir(
-path,
-context.encoding,
-context.withFileTypes,
-);
-
-if(readdirResult===undefined){
-return;
+for(leti=0;i<context.dirs.length;i++){
+constdir=context.dirs[i];
+constresult=binding.readdir(dir,options.encoding,true);
+if(result!==undefined){
+collectRecursiveReaddirResult(dir,context.prefixes[i],result,context);
 }
-
-processReaddirResult({
-result: readdirResult,
-currentPath: path,
- context,
-});
-}
-
-for(leti=0;i<context.pathsQueue.length;i++){
-read(context.pathsQueue[i]);
 }
 
-returncontext.readdirResults;
+returncontext.results;
 }
 
 /**

lib/internal/fs/promises.js

@@ -32,6 +32,9 @@ const {
 O_WRONLY,
 S_IFMT,
 S_IFREG,
+UV_DIRENT_DIR,
+UV_DIRENT_LINK,
+UV_DIRENT_UNKNOWN,
 }=constants;
 
 constbinding=internalBinding('fs');
@@ -63,6 +66,7 @@ const {
  kWriteFileMaxChunkSize,
 },
  copyObject,
+ getDirent,
  getDirents,
  getOptions,
  getStatFsFromBinding,
@@ -1638,73 +1642,37 @@ async function mkdir(path, options) {
 }
 
 asyncfunctionreaddirRecursive(originalPath,options){
+constwithFileTypes=!!options.withFileTypes;
+constreaddirWithTypes=(path)=>PromisePrototypeThen(
+binding.readdir(path,options.encoding,true,kUsePromises),
+undefined,
+handleErrorFromBinding,
+);
 constresult=[];
-constqueue=[
-[
-originalPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-originalPath,
-options.encoding,
-!!options.withFileTypes,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-],
-];
-
-
-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(constdirentofgetDirents(path,readdir)){
+constqueue=[[originalPath,'',awaitreaddirWithTypes(originalPath)]];
+
+while(queue.length>0){
+// If we want to implement BFS make this a `shift` call instead of `pop`
+const{0: path,1: prefix,2: {0: names,1: types}}=ArrayPrototypePop(queue);
+for(leti=0;i<names.length;i++){
+constname=names[i];
+constrelative=prefix==='' ? name : `${prefix}${pathModule.sep}${name}`;
+letisDirectory;
+if(withFileTypes){
+constdirent=getDirent(path,name,types[i]);
 ArrayPrototypePush(result,dirent);
-if(dirent.isDirectory()){
-constdirentPath=pathModule.join(path,dirent.name);
-ArrayPrototypePush(queue,[
-direntPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-direntPath,
-options.encoding,
-true,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-]);
-}
+isDirectory=dirent.isDirectory();
+}else{
+ArrayPrototypePush(result,relative);
+// Entries that are, or may be, symbolic links to directories are followed.
+consttype=types[i];
+isDirectory=type===UV_DIRENT_DIR||
+((type===UV_DIRENT_LINK||type===UV_DIRENT_UNKNOWN)&&
+binding.internalModuleStat(pathModule.join(path,name))===1);
 }
-}
-}else{
-while(queue.length>0){
-const{0: path,1: readdir}=ArrayPrototypePop(queue);
-for(constentofreaddir){
-constdirentPath=pathModule.join(path,ent);
-conststat=binding.internalModuleStat(direntPath);
-ArrayPrototypePush(
-result,
-pathModule.relative(originalPath,direntPath),
-);
-if(stat===1){
-ArrayPrototypePush(queue,[
-direntPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-direntPath,
-options.encoding,
-false,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-]);
-}
+if(isDirectory){
+constdirentPath=pathModule.join(path,name);
+ArrayPrototypePush(queue,[direntPath,relative,awaitreaddirWithTypes(direntPath)]);
 }
 }
 }

test/known_issues/test-fs-readdir-recursive-with-buffer.js

@@ -12,4 +12,4 @@ const { readdir } = require('node:fs');
 const{ join }=require('node:path');
 
 consttestDirPath=join(__dirname,'..','..');
-readdir(Buffer.from(testDirPath),{recursive: true},common.mustCall());
+readdir(Buffer.from(testDirPath),{recursive: true},common.mustSucceed());

benchmark/fs/bench-readdir.js

@@ -8,16 +8,18 @@ const bench = common.createBenchmark(main, {
 n: [10],
 dir: ['lib','test/parallel'],
 withFileTypes: ['true','false'],
+recursive: ['true','false'],
 });
 
-functionmain({ n, dir, withFileTypes }){
+functionmain({ n, dir, withFileTypes, recursive}){
 withFileTypes=withFileTypes==='true';
+recursive=recursive==='true';
 constfullPath=path.resolve(__dirname,'../../',dir);
 bench.start();
 (functionr(cntr){
 if(cntr--<=0)
 returnbench.end(n);
-fs.readdir(fullPath,{ withFileTypes },()=>{
+fs.readdir(fullPath,{ withFileTypes, recursive},()=>{
 r(cntr);
 });
 }(n));

benchmark/fs/bench-readdirSync.js

@@ -8,15 +8,17 @@ const bench = common.createBenchmark(main, {
 n: [10],
 dir: ['lib','test/parallel'],
 withFileTypes: ['true','false'],
+recursive: ['true','false'],
 });
 
 
-functionmain({ n, dir, withFileTypes }){
+functionmain({ n, dir, withFileTypes, recursive}){
 withFileTypes=withFileTypes==='true';
+recursive=recursive==='true';
 constfullPath=path.resolve(__dirname,'../../',dir);
 bench.start();
 for(leti=0;i<n;i++){
-fs.readdirSync(fullPath,{ withFileTypes });
+fs.readdirSync(fullPath,{ withFileTypes, recursive});
 }
 bench.end(n);
 }

lib/fs.js

@@ -57,6 +57,9 @@ const {
 F_OK,
 O_WRONLY,
 O_SYMLINK,
+UV_DIRENT_DIR,
+UV_DIRENT_LINK,
+UV_DIRENT_UNKNOWN,
 }=constants;
 
 constpathModule=require('path');
@@ -1739,6 +1742,43 @@ function mkdirSync(path, options) {
 }
 }
 
+/**
+ * Appends one directory's entries to `context.results` and the subdirectories
+ * still to visit to `context.dirs` (with the prefix their entries get in
+ * string results in `context.prefixes`). `result` is a `binding.readdir()`
+ * result with file types, so only symbolic links and entries of unknown type
+ * need a stat() to find out whether they lead to a directory.
+ * @param {string} dir
+ * @param {string} prefix
+ * @param {[string[], number[]]} result
+ * @param {{ withFileTypes: boolean, results: (string | Dirent)[], dirs: string[], prefixes: string[] }} context
+ */
+functioncollectRecursiveReaddirResult(dir,prefix,{0: names,1: types},context){
+const{ length }=names;
+for(leti=0;i<length;i++){
+constname=names[i];
+constrelative=prefix==='' ? name : `${prefix}${pathModule.sep}${name}`;
+letisDirectory;
+if(context.withFileTypes){
+constdirent=getDirent(dir,name,types[i]);
+ArrayPrototypePush(context.results,dirent);
+// Follow symbolic links to directories, see https://github.com/nodejs/node/issues/52663
+isDirectory=dirent.isDirectory()||
+(dirent.isSymbolicLink()&&binding.internalModuleStat(pathModule.join(dir,name))===1);
+}else{
+ArrayPrototypePush(context.results,relative);
+consttype=types[i];
+isDirectory=type===UV_DIRENT_DIR||
+((type===UV_DIRENT_LINK||type===UV_DIRENT_UNKNOWN)&&
+binding.internalModuleStat(pathModule.join(dir,name))===1);
+}
+if(isDirectory){
+ArrayPrototypePush(context.dirs,pathModule.join(dir,name));
+ArrayPrototypePush(context.prefixes,relative);
+}
+}
+}
+
 /*
  * An recursive algorithm for reading the entire contents of the `basePath` directory.
  * This function does not validate `basePath` as a directory. It is passed directly to
@@ -1754,15 +1794,20 @@ function mkdirSync(path, options) {
 functionreaddirRecursive(basePath,options,callback){
 constcontext={
 withFileTypes: Boolean(options.withFileTypes),
-encoding: options.encoding,
- basePath,
-readdirResults: [],
-pathsQueue: [basePath],
+results: [],
+dirs: [basePath],
+prefixes: [''],
 };
 
 leti=0;
 
-functionread(path){
+/**
+ * Reads one directory from `context.dirs` and then moves on to the next
+ * one, or calls back once none are left.
+ * @param {string} path
+ * @param {string} prefix path of this directory relative to `basePath`
+ */
+functionread(path,prefix){
 constreq=newFSReqCallback();
 req.oncomplete=(err,result)=>{
 if(err){
@@ -1771,68 +1816,28 @@ function readdirRecursive(basePath, options, callback) {
 }
 
 if(result===undefined){
-callback(null,context.readdirResults);
+callback(null,context.results);
 return;
 }
 
-processReaddirResult({
- result,
-currentPath: path,
- context,
-});
+try{
+collectRecursiveReaddirResult(path,prefix,result,context);
+}catch(err){
+callback(err);
+return;
+}
 
-if(i<context.pathsQueue.length){
-read(context.pathsQueue[i++]);
+if(i<context.dirs.length){
+read(context.dirs[i],context.prefixes[i++]);
 }else{
-callback(null,context.readdirResults);
+callback(null,context.results);
 }
 };
 
-binding.readdir(
-path,
-context.encoding,
-context.withFileTypes,
-req,
-);
-}
-
-read(context.pathsQueue[i++]);
-}
-
-// Calling `readdir` with `withFileTypes=true`, the result is an array of arrays.
-// The first array is the names, and the second array is the types.
-// They are guaranteed to be the same length; hence, setting `length` to the length
-// of the first array within the result.
-constprocessReaddirResult=(args)=>(args.context.withFileTypes ? handleDirents(args) : handleFilePaths(args));
-
-functionhandleDirents({ result, currentPath, context }){
-const{0: names,1: types}=result;
-const{ length }=names;
-
-for(leti=0;i<length;i++){
-// Avoid excluding symlinks, as they are not directories.
-// Refs: https://github.com/nodejs/node/issues/52663
-constfullPath=pathModule.join(currentPath,names[i]);
-constdirent=getDirent(currentPath,names[i],types[i]);
-ArrayPrototypePush(context.readdirResults,dirent);
-
-if(dirent.isDirectory()||binding.internalModuleStat(fullPath)===1){
-ArrayPrototypePush(context.pathsQueue,fullPath);
-}
+binding.readdir(path,options.encoding,true,req);
 }
-}
-
-functionhandleFilePaths({ result, currentPath, context }){
-for(leti=0;i<result.length;i++){
-constresultPath=pathModule.join(currentPath,result[i]);
-constrelativeResultPath=pathModule.relative(context.basePath,resultPath);
-conststat=binding.internalModuleStat(resultPath);
-ArrayPrototypePush(context.readdirResults,relativeResultPath);
 
-if(stat===1){
-ArrayPrototypePush(context.pathsQueue,resultPath);
-}
-}
+read(context.dirs[i],context.prefixes[i++]);
 }
 
 /**
@@ -1846,35 +1851,20 @@ function handleFilePaths({ result, currentPath, context }) {
 functionreaddirSyncRecursive(basePath,options){
 constcontext={
 withFileTypes: Boolean(options.withFileTypes),
-encoding: options.encoding,
- basePath,
-readdirResults: [],
-pathsQueue: [basePath],
+results: [],
+dirs: [basePath],
+prefixes: [''],
 };
 
-functionread(path){
-constreaddirResult=binding.readdir(
-path,
-context.encoding,
-context.withFileTypes,
-);
-
-if(readdirResult===undefined){
-return;
+for(leti=0;i<context.dirs.length;i++){
+constdir=context.dirs[i];
+constresult=binding.readdir(dir,options.encoding,true);
+if(result!==undefined){
+collectRecursiveReaddirResult(dir,context.prefixes[i],result,context);
 }
-
-processReaddirResult({
-result: readdirResult,
-currentPath: path,
- context,
-});
-}
-
-for(leti=0;i<context.pathsQueue.length;i++){
-read(context.pathsQueue[i]);
 }
 
-returncontext.readdirResults;
+returncontext.results;
 }
 
 /**

lib/internal/fs/promises.js

@@ -32,6 +32,9 @@ const {
 O_WRONLY,
 S_IFMT,
 S_IFREG,
+UV_DIRENT_DIR,
+UV_DIRENT_LINK,
+UV_DIRENT_UNKNOWN,
 }=constants;
 
 constbinding=internalBinding('fs');
@@ -63,6 +66,7 @@ const {
  kWriteFileMaxChunkSize,
 },
  copyObject,
+ getDirent,
  getDirents,
  getOptions,
  getStatFsFromBinding,
@@ -1638,73 +1642,37 @@ async function mkdir(path, options) {
 }
 
 asyncfunctionreaddirRecursive(originalPath,options){
+constwithFileTypes=!!options.withFileTypes;
+constreaddirWithTypes=(path)=>PromisePrototypeThen(
+binding.readdir(path,options.encoding,true,kUsePromises),
+undefined,
+handleErrorFromBinding,
+);
 constresult=[];
-constqueue=[
-[
-originalPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-originalPath,
-options.encoding,
-!!options.withFileTypes,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-],
-];
-
-
-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(constdirentofgetDirents(path,readdir)){
+constqueue=[[originalPath,'',awaitreaddirWithTypes(originalPath)]];
+
+while(queue.length>0){
+// If we want to implement BFS make this a `shift` call instead of `pop`
+const{0: path,1: prefix,2: {0: names,1: types}}=ArrayPrototypePop(queue);
+for(leti=0;i<names.length;i++){
+constname=names[i];
+constrelative=prefix==='' ? name : `${prefix}${pathModule.sep}${name}`;
+letisDirectory;
+if(withFileTypes){
+constdirent=getDirent(path,name,types[i]);
 ArrayPrototypePush(result,dirent);
-if(dirent.isDirectory()){
-constdirentPath=pathModule.join(path,dirent.name);
-ArrayPrototypePush(queue,[
-direntPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-direntPath,
-options.encoding,
-true,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-]);
-}
+isDirectory=dirent.isDirectory();
+}else{
+ArrayPrototypePush(result,relative);
+// Entries that are, or may be, symbolic links to directories are followed.
+consttype=types[i];
+isDirectory=type===UV_DIRENT_DIR||
+((type===UV_DIRENT_LINK||type===UV_DIRENT_UNKNOWN)&&
+binding.internalModuleStat(pathModule.join(path,name))===1);
 }
-}
-}else{
-while(queue.length>0){
-const{0: path,1: readdir}=ArrayPrototypePop(queue);
-for(constentofreaddir){
-constdirentPath=pathModule.join(path,ent);
-conststat=binding.internalModuleStat(direntPath);
-ArrayPrototypePush(
-result,
-pathModule.relative(originalPath,direntPath),
-);
-if(stat===1){
-ArrayPrototypePush(queue,[
-direntPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-direntPath,
-options.encoding,
-false,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-]);
-}
+if(isDirectory){
+constdirentPath=pathModule.join(path,name);
+ArrayPrototypePush(queue,[direntPath,relative,awaitreaddirWithTypes(direntPath)]);
 }
 }
 }

test/known_issues/test-fs-readdir-recursive-with-buffer.js

@@ -12,4 +12,4 @@ const { readdir } = require('node:fs');
 const{ join }=require('node:path');
 
 consttestDirPath=join(__dirname,'..','..');
-readdir(Buffer.from(testDirPath),{recursive: true},common.mustCall());
+readdir(Buffer.from(testDirPath),{recursive: true},common.mustSucceed());

benchmark/fs/bench-readdir.js

@@ -8,16 +8,18 @@ const bench = common.createBenchmark(main, {
 n: [10],
 dir: ['lib','test/parallel'],
 withFileTypes: ['true','false'],
+recursive: ['true','false'],
 });
 
-functionmain({ n, dir, withFileTypes }){
+functionmain({ n, dir, withFileTypes, recursive}){
 withFileTypes=withFileTypes==='true';
+recursive=recursive==='true';
 constfullPath=path.resolve(__dirname,'../../',dir);
 bench.start();
 (functionr(cntr){
 if(cntr--<=0)
 returnbench.end(n);
-fs.readdir(fullPath,{ withFileTypes },()=>{
+fs.readdir(fullPath,{ withFileTypes, recursive},()=>{
 r(cntr);
 });
 }(n));

benchmark/fs/bench-readdirSync.js

@@ -8,15 +8,17 @@ const bench = common.createBenchmark(main, {
 n: [10],
 dir: ['lib','test/parallel'],
 withFileTypes: ['true','false'],
+recursive: ['true','false'],
 });
 
 
-functionmain({ n, dir, withFileTypes }){
+functionmain({ n, dir, withFileTypes, recursive}){
 withFileTypes=withFileTypes==='true';
+recursive=recursive==='true';
 constfullPath=path.resolve(__dirname,'../../',dir);
 bench.start();
 for(leti=0;i<n;i++){
-fs.readdirSync(fullPath,{ withFileTypes });
+fs.readdirSync(fullPath,{ withFileTypes, recursive});
 }
 bench.end(n);
 }

lib/fs.js

@@ -57,6 +57,9 @@ const {
 F_OK,
 O_WRONLY,
 O_SYMLINK,
+UV_DIRENT_DIR,
+UV_DIRENT_LINK,
+UV_DIRENT_UNKNOWN,
 }=constants;
 
 constpathModule=require('path');
@@ -1739,6 +1742,43 @@ function mkdirSync(path, options) {
 }
 }
 
+/**
+ * Appends one directory's entries to `context.results` and the subdirectories
+ * still to visit to `context.dirs` (with the prefix their entries get in
+ * string results in `context.prefixes`). `result` is a `binding.readdir()`
+ * result with file types, so only symbolic links and entries of unknown type
+ * need a stat() to find out whether they lead to a directory.
+ * @param {string} dir
+ * @param {string} prefix
+ * @param {[string[], number[]]} result
+ * @param {{ withFileTypes: boolean, results: (string | Dirent)[], dirs: string[], prefixes: string[] }} context
+ */
+functioncollectRecursiveReaddirResult(dir,prefix,{0: names,1: types},context){
+const{ length }=names;
+for(leti=0;i<length;i++){
+constname=names[i];
+constrelative=prefix==='' ? name : `${prefix}${pathModule.sep}${name}`;
+letisDirectory;
+if(context.withFileTypes){
+constdirent=getDirent(dir,name,types[i]);
+ArrayPrototypePush(context.results,dirent);
+// Follow symbolic links to directories, see https://github.com/nodejs/node/issues/52663
+isDirectory=dirent.isDirectory()||
+(dirent.isSymbolicLink()&&binding.internalModuleStat(pathModule.join(dir,name))===1);
+}else{
+ArrayPrototypePush(context.results,relative);
+consttype=types[i];
+isDirectory=type===UV_DIRENT_DIR||
+((type===UV_DIRENT_LINK||type===UV_DIRENT_UNKNOWN)&&
+binding.internalModuleStat(pathModule.join(dir,name))===1);
+}
+if(isDirectory){
+ArrayPrototypePush(context.dirs,pathModule.join(dir,name));
+ArrayPrototypePush(context.prefixes,relative);
+}
+}
+}
+
 /*
  * An recursive algorithm for reading the entire contents of the `basePath` directory.
  * This function does not validate `basePath` as a directory. It is passed directly to
@@ -1754,15 +1794,20 @@ function mkdirSync(path, options) {
 functionreaddirRecursive(basePath,options,callback){
 constcontext={
 withFileTypes: Boolean(options.withFileTypes),
-encoding: options.encoding,
- basePath,
-readdirResults: [],
-pathsQueue: [basePath],
+results: [],
+dirs: [basePath],
+prefixes: [''],
 };
 
 leti=0;
 
-functionread(path){
+/**
+ * Reads one directory from `context.dirs` and then moves on to the next
+ * one, or calls back once none are left.
+ * @param {string} path
+ * @param {string} prefix path of this directory relative to `basePath`
+ */
+functionread(path,prefix){
 constreq=newFSReqCallback();
 req.oncomplete=(err,result)=>{
 if(err){
@@ -1771,68 +1816,28 @@ function readdirRecursive(basePath, options, callback) {
 }
 
 if(result===undefined){
-callback(null,context.readdirResults);
+callback(null,context.results);
 return;
 }
 
-processReaddirResult({
- result,
-currentPath: path,
- context,
-});
+try{
+collectRecursiveReaddirResult(path,prefix,result,context);
+}catch(err){
+callback(err);
+return;
+}
 
-if(i<context.pathsQueue.length){
-read(context.pathsQueue[i++]);
+if(i<context.dirs.length){
+read(context.dirs[i],context.prefixes[i++]);
 }else{
-callback(null,context.readdirResults);
+callback(null,context.results);
 }
 };
 
-binding.readdir(
-path,
-context.encoding,
-context.withFileTypes,
-req,
-);
-}
-
-read(context.pathsQueue[i++]);
-}
-
-// Calling `readdir` with `withFileTypes=true`, the result is an array of arrays.
-// The first array is the names, and the second array is the types.
-// They are guaranteed to be the same length; hence, setting `length` to the length
-// of the first array within the result.
-constprocessReaddirResult=(args)=>(args.context.withFileTypes ? handleDirents(args) : handleFilePaths(args));
-
-functionhandleDirents({ result, currentPath, context }){
-const{0: names,1: types}=result;
-const{ length }=names;
-
-for(leti=0;i<length;i++){
-// Avoid excluding symlinks, as they are not directories.
-// Refs: https://github.com/nodejs/node/issues/52663
-constfullPath=pathModule.join(currentPath,names[i]);
-constdirent=getDirent(currentPath,names[i],types[i]);
-ArrayPrototypePush(context.readdirResults,dirent);
-
-if(dirent.isDirectory()||binding.internalModuleStat(fullPath)===1){
-ArrayPrototypePush(context.pathsQueue,fullPath);
-}
+binding.readdir(path,options.encoding,true,req);
 }
-}
-
-functionhandleFilePaths({ result, currentPath, context }){
-for(leti=0;i<result.length;i++){
-constresultPath=pathModule.join(currentPath,result[i]);
-constrelativeResultPath=pathModule.relative(context.basePath,resultPath);
-conststat=binding.internalModuleStat(resultPath);
-ArrayPrototypePush(context.readdirResults,relativeResultPath);
 
-if(stat===1){
-ArrayPrototypePush(context.pathsQueue,resultPath);
-}
-}
+read(context.dirs[i],context.prefixes[i++]);
 }
 
 /**
@@ -1846,35 +1851,20 @@ function handleFilePaths({ result, currentPath, context }) {
 functionreaddirSyncRecursive(basePath,options){
 constcontext={
 withFileTypes: Boolean(options.withFileTypes),
-encoding: options.encoding,
- basePath,
-readdirResults: [],
-pathsQueue: [basePath],
+results: [],
+dirs: [basePath],
+prefixes: [''],
 };
 
-functionread(path){
-constreaddirResult=binding.readdir(
-path,
-context.encoding,
-context.withFileTypes,
-);
-
-if(readdirResult===undefined){
-return;
+for(leti=0;i<context.dirs.length;i++){
+constdir=context.dirs[i];
+constresult=binding.readdir(dir,options.encoding,true);
+if(result!==undefined){
+collectRecursiveReaddirResult(dir,context.prefixes[i],result,context);
 }
-
-processReaddirResult({
-result: readdirResult,
-currentPath: path,
- context,
-});
-}
-
-for(leti=0;i<context.pathsQueue.length;i++){
-read(context.pathsQueue[i]);
 }
 
-returncontext.readdirResults;
+returncontext.results;
 }
 
 /**

lib/internal/fs/promises.js

@@ -32,6 +32,9 @@ const {
 O_WRONLY,
 S_IFMT,
 S_IFREG,
+UV_DIRENT_DIR,
+UV_DIRENT_LINK,
+UV_DIRENT_UNKNOWN,
 }=constants;
 
 constbinding=internalBinding('fs');
@@ -63,6 +66,7 @@ const {
  kWriteFileMaxChunkSize,
 },
  copyObject,
+ getDirent,
  getDirents,
  getOptions,
  getStatFsFromBinding,
@@ -1638,73 +1642,37 @@ async function mkdir(path, options) {
 }
 
 asyncfunctionreaddirRecursive(originalPath,options){
+constwithFileTypes=!!options.withFileTypes;
+constreaddirWithTypes=(path)=>PromisePrototypeThen(
+binding.readdir(path,options.encoding,true,kUsePromises),
+undefined,
+handleErrorFromBinding,
+);
 constresult=[];
-constqueue=[
-[
-originalPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-originalPath,
-options.encoding,
-!!options.withFileTypes,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-],
-];
-
-
-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(constdirentofgetDirents(path,readdir)){
+constqueue=[[originalPath,'',awaitreaddirWithTypes(originalPath)]];
+
+while(queue.length>0){
+// If we want to implement BFS make this a `shift` call instead of `pop`
+const{0: path,1: prefix,2: {0: names,1: types}}=ArrayPrototypePop(queue);
+for(leti=0;i<names.length;i++){
+constname=names[i];
+constrelative=prefix==='' ? name : `${prefix}${pathModule.sep}${name}`;
+letisDirectory;
+if(withFileTypes){
+constdirent=getDirent(path,name,types[i]);
 ArrayPrototypePush(result,dirent);
-if(dirent.isDirectory()){
-constdirentPath=pathModule.join(path,dirent.name);
-ArrayPrototypePush(queue,[
-direntPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-direntPath,
-options.encoding,
-true,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-]);
-}
+isDirectory=dirent.isDirectory();
+}else{
+ArrayPrototypePush(result,relative);
+// Entries that are, or may be, symbolic links to directories are followed.
+consttype=types[i];
+isDirectory=type===UV_DIRENT_DIR||
+((type===UV_DIRENT_LINK||type===UV_DIRENT_UNKNOWN)&&
+binding.internalModuleStat(pathModule.join(path,name))===1);
 }
-}
-}else{
-while(queue.length>0){
-const{0: path,1: readdir}=ArrayPrototypePop(queue);
-for(constentofreaddir){
-constdirentPath=pathModule.join(path,ent);
-conststat=binding.internalModuleStat(direntPath);
-ArrayPrototypePush(
-result,
-pathModule.relative(originalPath,direntPath),
-);
-if(stat===1){
-ArrayPrototypePush(queue,[
-direntPath,
-awaitPromisePrototypeThen(
-binding.readdir(
-direntPath,
-options.encoding,
-false,
-kUsePromises,
-),
-undefined,
-handleErrorFromBinding,
-),
-]);
-}
+if(isDirectory){
+constdirentPath=pathModule.join(path,name);
+ArrayPrototypePush(queue,[direntPath,relative,awaitreaddirWithTypes(direntPath)]);
 }
 }
 }

test/known_issues/test-fs-readdir-recursive-with-buffer.js

@@ -12,4 +12,4 @@ const { readdir } = require('node:fs');
 const{ join }=require('node:path');
 
 consttestDirPath=join(__dirname,'..','..');
-readdir(Buffer.from(testDirPath),{recursive: true},common.mustCall());
+readdir(Buffer.from(testDirPath),{recursive: true},common.mustSucceed());