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: nodejs/node-v0.x-archive#388
Refs: nodejs/node#583
Refs: libuv/libuv#2057

PR-URL: nodejs/node#29349
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: David Carlier <[email protected]>

lib/internal/fs/promises.js

@@ -512,33 +512,29 @@ async function readFile(path, options) {
 }
 
 module.exports = {
-  exports: {
-    access,
-    copyFile,
-    open,
-    opendir: promisify(opendir),
-    rename,
-    truncate,
-    rmdir,
-    mkdir,
-    readdir,
-    readlink,
-    symlink,
-    lstat,
-    stat,
-    link,
-    unlink,
-    chmod,
-    lchmod,
-    lchown,
-    chown,
-    utimes,
-    realpath,
-    mkdtemp,
-    writeFile,
-    appendFile,
-    readFile,
-  },
-
-  FileHandle
+  access,
+  copyFile,
+  open,
+  opendir: promisify(opendir),
+  rename,
+  truncate,
+  rmdir,
+  mkdir,
+  readdir,
+  readlink,
+  symlink,
+  lstat,
+  stat,
+  link,
+  unlink,
+  chmod,
+  lchmod,
+  lchown,
+  chown,
+  utimes,
+  realpath,
+  mkdtemp,
+  writeFile,
+  appendFile,
+  readFile
 };