fs: introduce `opendir()` and `fs.Dir`

This adds long-requested methods for asynchronously interacting and
iterating through directory entries by using `uv_fs_opendir`,
`uv_fs_readdir`, and `uv_fs_closedir`.

`fs.opendir()` and friends return an `fs.Dir`, which contains methods
for doing reads and cleanup. `fs.Dir` also has the async iterator
symbol exposed.

The `read()` method and friends only return `fs.Dirent`s for this API.
Having a entry type or doing a `stat` call is deemed to be necessary in
the majority of cases, so just returning dirents seems like the logical
choice for a new api.

Reading when there are no more entries returns `null` instead of a
dirent. However the async iterator hides that (and does automatic
cleanup).

The code lives in separate files from the rest of fs, this is done
partially to prevent over-pollution of those (already very large)
files, but also in the case of js allows loading into `fsPromises`.

Due to async_hooks, this introduces a new handle type of `DIRHANDLE`.

This PR does not attempt to make complete optimization of
this feature. Notable future improvements include:
- Moving promise work into C++ land like FileHandle.
- Possibly adding `readv()` to do multi-entry directory reads.
- Aliasing `fs.readdir` to `fs.scandir` and doing a deprecation.

Refs: https://github.com/nodejs/node-v0.x-archive/issues/388
Refs: https://github.com/nodejs/node/issues/583
Refs: https://github.com/libuv/libuv/pull/2057

PR-URL: https://github.com/nodejs/node/pull/29349
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: David Carlier <devnexen@gmail.com>

1 files changed, 3 insertions, 0 deletions

diff --git a/node.gyp b/node.gyp
index 31d10b7444..ced6fbc954 100644
--- a/node.gyp
+++ b/node.gyp
@@ -121,6 +121,7 @@
       'lib/internal/fixed_queue.js',
       'lib/internal/freelist.js',
       'lib/internal/freeze_intrinsics.js',
+      'lib/internal/fs/dir.js',
       'lib/internal/fs/promises.js',
       'lib/internal/fs/read_file_context.js',
       'lib/internal/fs/rimraf.js',
@@ -526,6 +527,7 @@
         'src/node_constants.cc',
         'src/node_contextify.cc',
         'src/node_credentials.cc',
+        'src/node_dir.cc',
         'src/node_domain.cc',
         'src/node_env_var.cc',
         'src/node_errors.cc',
@@ -606,6 +608,7 @@
         'src/node_constants.h',
         'src/node_context_data.h',
         'src/node_contextify.h',
+        'src/node_dir.h',
         'src/node_errors.h',
         'src/node_file.h',
         'src/node_http2.h',