doc: undocumented magic: async iterator over fs.Dir will call dir.close() on iteration end

[ZYinMD]

📗 API Reference Docs Problem

• Version: ✍️v14.10.1

• Platform: ✍️Linux 4.19.104-microsoft-standard deps: update openssl to 1.0.1j #1 SMP Wed Feb 19 06:37:35 UTC 2020 x86_64 x86_64 x86_64 GNU/Linux

• Subsystem: ✍️
  fs

Location

Section of the site where the content exists

Affected URL(s):

https://nodejs.org/api/fs.html#fs_class_fs_dir

Description

I'm trying the fs.Dir class which was added since node v12.12:

// hello-world.js
const fs = require('fs');

(async function () {
  const dir = await fs.promises.opendir(__dirname);
  for await (const dirent of dir) {
    console.log('name:', dirent.name, 'isDir:', dirent.isDirectory());
  }
  return dir.close();
})();

$ node hello-world.js

It works as expected, but in the end when calling dir.close(), it throws (node:3218) UnhandledPromiseRejectionWarning: Error [ERR_DIR_CLOSED]: Directory handle was closed at Dir.close (internal/fs/dir.js:161:13).

After asking on stackoverflow, with the help of others, I found that the async iterator will auto close the dir after iteration is over, so I don't need to (and cannot) clean up with dir.close() myself. This can be seen in the source code here.

This magic is probably good for many developers, but it also throws for those who are careful to code correctly, so I think it should be mentioned in the doc.

---

• I would like to work on this issue and
  submit a pull request.