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

40274027

an 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