Skip to content

Commit a836720

Browse files
lluisemperaduh95
authored andcommitted
doc: add MDN links for explicit resource management in fs
Add cross-references to MDN documentation for `using` and `await using` statements in the fs module documentation. Remove TODO comment waiting for MDN documentation availability. Fixes: #59556 PR-URL: #59557 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>
1 parent 70dedef commit a836720

1 file changed

Lines changed: 24 additions & 4 deletions

File tree

doc/api/fs.md

Lines changed: 24 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1183,6 +1183,10 @@ changes:
11831183
Calls `filehandle.close()` and returns a promise that fulfills when the
11841184
filehandle is closed.
11851185
1186+
This method enables the filehandle to be used with [`await using`][], which
1187+
will automatically close the file when the scope exits. For more information,
1188+
see the [MDN documentation on `using` statements][`using`].
1189+
11861190
### `fsPromises.access(path[, mode])`
11871191
11881192
<!-- YAML
@@ -1665,10 +1669,11 @@ directory cannot be deleted, disposal will throw an error. The object has an
16651669
async `remove()` method which will perform the same task.
16661670
16671671
Both this function and the disposal function on the resulting object are
1668-
async, so it should be used with `await` + `await using` as in
1672+
async, so it should be used with `await` + [`await using`][] as in
16691673
`await using dir = await fsPromises.mkdtempDisposable('prefix')`.
16701674
1671-
<!-- TODO: link MDN docs for disposables once https://github.com/mdn/content/pull/38027 lands -->
1675+
See the [MDN documentation on `using` statements][`using`] for more information about
1676+
explicit resource management.
16721677
16731678
For detailed information, see the documentation of [`fsPromises.mkdtemp()`][].
16741679
@@ -6417,12 +6422,13 @@ removed if it still exists. If the directory cannot be deleted, disposal will
64176422
throw an error. The object has a `remove()` method which will perform the same
64186423
task.
64196424
6420-
<!-- TODO: link MDN docs for disposables once https://github.com/mdn/content/pull/38027 lands -->
6425+
See the [MDN documentation on `using` statements][`using`] for more information about
6426+
explicit resource management.
64216427
64226428
For detailed information, see the documentation of [`fs.mkdtemp()`][].
64236429
64246430
There is no callback-based version of this API because it is designed for use
6425-
with the `using` syntax.
6431+
with the [`using`][] syntax.
64266432
64276433
The optional `options` argument can be a string specifying an encoding, or an
64286434
object with an `encoding` property specifying the character encoding to use.
@@ -7294,6 +7300,10 @@ changes:
72947300
Calls `dir.close()` if the directory handle is open, and returns a promise that
72957301
fulfills when disposal is complete.
72967302
7303+
This method enables the directory to be used with [`await using`][], which
7304+
will automatically close the directory when the scope exits. For more
7305+
information, see the [MDN documentation on `using` statements][`using`].
7306+
72977307
#### `dir[Symbol.dispose]()`
72987308
72997309
<!-- YAML
@@ -7309,6 +7319,10 @@ changes:
73097319
Calls `dir.closeSync()` if the directory handle is open, and returns
73107320
`undefined`.
73117321
7322+
This method enables the directory to be used with [`using`][], which
7323+
will automatically close the directory when the scope exits. For more
7324+
information, see the [MDN documentation on `using` statements][`using`].
7325+
73127326
### Class: `fs.Dirent`
73137327
73147328
<!-- YAML
@@ -8443,6 +8457,10 @@ the `data` argument must be a {Buffer}.
84438457
84448458
Calls `utf8Stream.destroy()`.
84458459
8460+
This method enables the stream to be used with [`using`][], which
8461+
will automatically destroy the stream when the scope exits. For more
8462+
information, see the [MDN documentation on `using` statements][`using`].
8463+
84468464
### Class: `fs.WriteStream`
84478465
84488466
<!-- YAML
@@ -9259,6 +9277,7 @@ the file contents.
92599277
[`Number.MAX_SAFE_INTEGER`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER
92609278
[`ReadDirectoryChangesW`]: https://docs.microsoft.com/en-us/windows/desktop/api/winbase/nf-winbase-readdirectorychangesw
92619279
[`UV_THREADPOOL_SIZE`]: cli.md#uv_threadpool_sizesize
9280+
[`await using`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/await_using
92629281
[`event ports`]: https://illumos.org/man/port_create
92639282
[`filehandle.createReadStream()`]: #filehandlecreatereadstreamoptions
92649283
[`filehandle.createWriteStream()`]: #filehandlecreatewritestreamoptions
@@ -9318,6 +9337,7 @@ the file contents.
93189337
[`stream/iter pipeTo()`]: stream_iter.md#pipetosource-transforms-writer-options
93199338
[`stream/iter pull()`]: stream_iter.md#pullsource-transforms-options
93209339
[`stream/iter pullSync()`]: stream_iter.md#pullsyncsource-transforms
9340+
[`using`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using
93219341
[`util.promisify()`]: util.md#utilpromisifyoriginal
93229342
[bigints]: https://tc39.github.io/proposal-bigint
93239343
[caveats]: #caveats

0 commit comments

Comments
 (0)