doc: deprecate closing `fs.Dir` on garbage collection · nodejs/node@e4f5716
@@ -4026,6 +4026,52 @@ The `node:_http_agent`, `node:_http_client`, `node:_http_common`, `node:_http_in
40264026`node:_http_outgoing` and `node:_http_server` modules are deprecated as they should be considered
40274027an internal nodejs implementation rather than a public facing API, use `node:http` instead.
402840284029+### DEP0200: Closing fs.Dir on garbage collection
4030+4031+<!-- YAML
4032+changes:
4033+ - version: REPLACEME
4034+ pr-url: https://github.com/nodejs/node/pull/59839
4035+ description: Documentation-only deprecation.
4036+-->
4037+4038+Type: Documentation-only
4039+4040+Allowing a [`fs.Dir`][] object to be closed on garbage collection is
4041+deprecated. In the future, doing so might result in a thrown error that will
4042+terminate the process.
4043+4044+Please ensure that all `fs.Dir` objects are explicitly closed using
4045+`Dir.prototype.close()` or `using` keyword:
4046+4047+```mjs
4048+import { opendir } from 'node:fs/promises';
4049+4050+{
4051+await using dir = await opendir('/async/disposable/directory');
4052+} // Closed by dir[Symbol.asyncDispose]()
4053+4054+{
4055+ using dir = await opendir('/sync/disposable/directory');
4056+} // Closed by dir[Symbol.dispose]()
4057+4058+{
4059+const dir = await opendir('/unconditionally/iterated/directory');
4060+for await (const entry of dir) {
4061+// process an entry
4062+ } // Closed by iterator
4063+}
4064+4065+{
4066+let dir;
4067+try {
4068+ dir = await opendir('/legacy/closeable/directory');
4069+ } finally {
4070+await dir?.close();
4071+ }
4072+}
4073+```
4074+40294075[DEP0142]: #dep0142-repl_builtinlibs
40304076[NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
40314077[RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3
@@ -4083,6 +4129,7 @@ an internal nodejs implementation rather than a public facing API, use `node:htt
40834129[`ecdh.setPublicKey()`]: crypto.md#ecdhsetpublickeypublickey-encoding
40844130[`emitter.listenerCount(eventName)`]: events.md#emitterlistenercounteventname-listener
40854131[`events.listenerCount(emitter, eventName)`]: events.md#eventslistenercountemitter-eventname
4132+[`fs.Dir`]: fs.md#class-fsdir
40864133[`fs.FileHandle`]: fs.md#class-filehandle
40874134[`fs.access()`]: fs.md#fsaccesspath-mode-callback
40884135[`fs.appendFile()`]: fs.md#fsappendfilepath-data-options-callback