fs: extends readdir option 'recursive' to allow a function to limit traversal

Author: prettydiff

doc/api/fs.md

@@ -1304,7 +1304,11 @@ changes:
 * `options` {string|Object}
   * `encoding` {string} **Default:** `'utf8'`
   * `withFileTypes` {boolean} **Default:** `false`
-  * `recursive` {boolean} **Default:** `false`
+  * `recursive` {boolean|Function} **Default:** `false`
+    * `directory` {string} A given directory file system artifact name.
+    * `depth` {integer} The number of steps traversed from the supplied base
+      path.
+    * Returns: {boolean}
 * Returns: {Promise}  Fulfills with an array of the names of the files in
   the directory excluding `'.'` and `'..'`.
 
@@ -1318,6 +1322,12 @@ will be passed as {Buffer} objects.
 If `options.withFileTypes` is set to `true`, the resolved array will contain
 {fs.Dirent} objects.
 
+When passing a function to `options.recursive` the first argument populates
+with the name of a directory, or {fs.Dirent} object if `options.withFileTypes`
+is true, and directory depth relative to the base path as the second argument.
+This function expects to return a boolean which determines the descendant
+directories to traverse.
+
 ```mjs
 import { readdir } from 'node:fs/promises';
 
@@ -3614,7 +3624,11 @@ changes:
 * `options` {string|Object}
   * `encoding` {string} **Default:** `'utf8'`
   * `withFileTypes` {boolean} **Default:** `false`
-  * `recursive` {boolean} **Default:** `false`
+  * `recursive` {boolean|Function} **Default:** `false`
+    * `directory` {string} A given directory file system artifact name.
+    * `depth` {integer} The number of steps traversed from the supplied base
+      path.
+    * Returns: {boolean}
 * `callback` {Function}
   * `err` {Error}
   * `files` {string\[]|Buffer\[]|fs.Dirent\[]}
@@ -3633,6 +3647,12 @@ the filenames returned will be passed as {Buffer} objects.
 If `options.withFileTypes` is set to `true`, the `files` array will contain
 {fs.Dirent} objects.
 
+When passing a function to `options.recursive` the first argument populates
+with the name of a directory, or {fs.Dirent} object if `options.withFileTypes`
+is true, and directory depth relative to the base path as the second argument.
+This function expects to return a boolean which determines the descendant
+directories to traverse.
+
 ### `fs.readFile(path[, options], callback)`
 
 <!-- YAML
@@ -5680,7 +5700,11 @@ changes:
 * `options` {string|Object}
   * `encoding` {string} **Default:** `'utf8'`
   * `withFileTypes` {boolean} **Default:** `false`
-  * `recursive` {boolean} **Default:** `false`
+  * `recursive` {boolean|Function} **Default:** `false`
+    * `directory` {string} A given directory file system artifact name.
+    * `depth` {integer} The number of steps traversed from the supplied base
+      path.
+    * Returns: {boolean}
 * Returns: {string\[]|Buffer\[]|fs.Dirent\[]}
 
 Reads the contents of the directory.
@@ -5695,6 +5719,12 @@ the filenames returned will be passed as {Buffer} objects.
 If `options.withFileTypes` is set to `true`, the result will contain
 {fs.Dirent} objects.
 
+When passing a function to `options.recursive` the first argument populates
+with the name of a directory, or {fs.Dirent} object if `options.withFileTypes`
+is true, and directory depth relative to the base path as the second argument.
+This function expects to return a boolean which determines the descendant
+directories to traverse.
+
 ### `fs.readFileSync(path[, options])`
 
 <!-- YAML

lib/fs.js

@@ -1429,11 +1429,21 @@ function readdirSyncRecursive(basePath, options) {
   const encoding = options.encoding;
 
   const readdirResults = [];
-  const pathsQueue = [basePath];
+  const pathsQueue = [[basePath, 1]];
 
   const ctx = { path: basePath };
-  function read(path) {
+  function read({ 0: path, 1: depth }) {
     ctx.path = path;
+
+    function filterCheck(item, dirEnt) {
+      if (typeof options.recursive !== 'function' ||
+        (dirEnt === true && typeof item.name !== 'string') || (dirEnt === false && typeof item !== 'string')
+      ) {
+        return true;
+      }
+      return options.recursive(item, depth);
+    }
+
     const readdirResult = binding.readdir(
       pathModule.toNamespacedPath(path),
       encoding,
@@ -1452,8 +1462,8 @@ function readdirSyncRecursive(basePath, options) {
       for (let i = 0; i < length; i++) {
         const dirent = getDirent(path, readdirResult[0][i], readdirResult[1][i]);
         ArrayPrototypePush(readdirResults, dirent);
-        if (dirent.isDirectory()) {
-          ArrayPrototypePush(pathsQueue, pathModule.join(dirent.path, dirent.name));
+        if (dirent.isDirectory() && filterCheck(dirent, true)) {
+          ArrayPrototypePush(pathsQueue, [pathModule.join(dirent.path, dirent.name), depth + 1]);
         }
       }
     } else {
@@ -1463,8 +1473,8 @@ function readdirSyncRecursive(basePath, options) {
         const stat = binding.internalModuleStat(resultPath);
         ArrayPrototypePush(readdirResults, relativeResultPath);
         // 1 indicates directory
-        if (stat === 1) {
-          ArrayPrototypePush(pathsQueue, resultPath);
+        if (stat === 1 && filterCheck(readdirResult[i], false)) {
+          ArrayPrototypePush(pathsQueue, [resultPath, depth + 1]);
         }
       }
     }
@@ -1483,6 +1493,7 @@ function readdirSyncRecursive(basePath, options) {
  * @param {string | {
  *   encoding?: string;
  *   withFileTypes?: boolean;
+ *   recursive?: boolean | (name: string | dirent: Dirent, depth: number) => boolean;
  *   }} [options]
  * @param {(
  *   err?: Error,
@@ -1494,9 +1505,6 @@ 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, options));
@@ -1525,16 +1533,13 @@ function readdir(path, options, callback) {
  * @param {string | {
  *   encoding?: string;
  *   withFileTypes?: boolean;
- *   recursive?: boolean;
+ *   recursive?: boolean | (name: string | dirent: Dirent, depth: number) => 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, options);

lib/internal/fs/promises.js

@@ -790,17 +790,17 @@ async function readdirRecursive(originalPath, options) {
         !!options.withFileTypes,
         kUsePromises,
       ),
+      1,
     ],
   ];
 
-
   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);
+      const { 0: path, 1: readdir, 2: depth } = ArrayPrototypePop(queue);
       for (const dirent of getDirents(path, readdir)) {
         ArrayPrototypePush(result, dirent);
-        if (dirent.isDirectory()) {
+        if (dirent.isDirectory() && (typeof options.recursive !== 'function' || options.recursive(dirent, depth))) {
           const direntPath = pathModule.join(path, dirent.name);
           ArrayPrototypePush(queue, [
             direntPath,
@@ -810,21 +810,22 @@ async function readdirRecursive(originalPath, options) {
               true,
               kUsePromises,
             ),
+            depth + 1,
           ]);
         }
       }
     }
   } else {
     while (queue.length > 0) {
-      const { 0: path, 1: readdir } = ArrayPrototypePop(queue);
+      const { 0: path, 1: readdir, 2: depth } = 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) {
+        if (stat === 1 && (typeof options.recursive !== 'function' || options.recursive(ent, depth))) {
           ArrayPrototypePush(queue, [
             direntPath,
             await binding.readdir(
@@ -833,6 +834,7 @@ async function readdirRecursive(originalPath, options) {
               false,
               kUsePromises,
             ),
+            depth + 1,
           ]);
         }
       }