What is the problem this feature will solve?

In version 20.1.0 Node introduced new option recursive on fs.readdir. I needed this feature about 8 years ago so I wrote my own library to accomplish it, but I found that it can be exceptionally painful if you execute a recursive option as a boolean from too high in the file system tree.

To solve for in my own library I removed the recursive option and replaced it with an option named depth that takes a number. The floor value of that number determines how many rounds of recursion to apply when walking the file system.

• If the value is less than 1 then I apply full recursion.
• If the value is 1 then I apply no recursion.
• If the value is 2 I gather file system contents of the specified directory and the immediate child directories.
• Greater values then walk each additional descendent depth of the file system per the supplied value.

An example of where this is helpful is applying a depth 2 on Windows from "C:". Will full recursion it will just fail.

What is the feature you are proposing to solve the problem?

I am proposing an option named depth for fs.readdir. I am not sure, but it looks like would be executed at:

https://github.com/nodejs/node/blob/main/lib/fs.js#L1427

Here is how I am calculating depth in my own code: filePath.replace(startItem, "").split(vars.path.sep).length

https://github.com/prettydiff/share-file-systems/blob/master/lib/terminal/commands/library/directory.ts#L409

With a bit of guidance I will happily do the work and submit a pull request. I just need:

1. Am I looking at the correct location in the Node code base?
2. If the current way I solve for this in my own code is less desirable I will write the solution in a different way.
3. I would need guidance to build Node so that I can test that my enhancement works correctly.
4. I would need guidance to supply and execute unit tests however Node executes unit tests.

What alternatives have you considered?

As an alternative I wrote my own solution about 8 years ago.