diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 5919af4658eaad..514e31e2bc68f4 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -4104,6 +4104,52 @@ The `node:_http_agent`, `node:_http_client`, `node:_http_common`, `node:_http_in `node:_http_outgoing` and `node:_http_server` modules are deprecated as they should be considered an internal nodejs implementation rather than a public facing API, use `node:http` instead. +### DEP0200: Closing fs.Dir on garbage collection + + + +Type: Documentation-only + +Allowing a [`fs.Dir`][] object to be closed on garbage collection is +deprecated. In the future, doing so might result in a thrown error that will +terminate the process. + +Please ensure that all `fs.Dir` objects are explicitly closed using +`Dir.prototype.close()` or `using` keyword: + +```mjs +import { opendir } from 'node:fs/promises'; + +{ + await using dir = await opendir('/async/disposable/directory'); +} // Closed by dir[Symbol.asyncDispose]() + +{ + using dir = await opendir('/sync/disposable/directory'); +} // Closed by dir[Symbol.dispose]() + +{ + const dir = await opendir('/unconditionally/iterated/directory'); + for await (const entry of dir) { + // process an entry + } // Closed by iterator +} + +{ + let dir; + try { + dir = await opendir('/legacy/closeable/directory'); + } finally { + await dir?.close(); + } +} +``` + [DEP0142]: #dep0142-repl_builtinlibs [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf [RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3 @@ -4159,6 +4205,7 @@ an internal nodejs implementation rather than a public facing API, use `node:htt [`ecdh.setPublicKey()`]: crypto.md#ecdhsetpublickeypublickey-encoding [`emitter.listenerCount(eventName)`]: events.md#emitterlistenercounteventname-listener [`events.listenerCount(emitter, eventName)`]: events.md#eventslistenercountemitter-eventname +[`fs.Dir`]: fs.md#class-fsdir [`fs.FileHandle`]: fs.md#class-filehandle [`fs.access()`]: fs.md#fsaccesspath-mode-callback [`fs.appendFile()`]: fs.md#fsappendfilepath-data-options-callback