Skip to content

Commit 714dc5d

Browse files
lluisemperlluisemper
authored
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é <[email protected]>
1 parent ede6d6a commit 714dc5d

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
@@ -1188,6 +1188,10 @@ changes:
11881188
Calls `filehandle.close()` and returns a promise that fulfills when the
11891189
filehandle is closed.
11901190
1191+
This method enables the filehandle to be used with [`await using`][], which
1192+
will automatically close the file when the scope exits. For more information,
1193+
see the [MDN documentation on `using` statements][`using`].
1194+
11911195
### `fsPromises.access(path[, mode])`
11921196
11931197
<!-- YAML
@@ -1672,10 +1676,11 @@ directory cannot be deleted, disposal will throw an error. The object has an
16721676
async `remove()` method which will perform the same task.
16731677
16741678
Both this function and the disposal function on the resulting object are
1675-
async, so it should be used with `await` + `await using` as in
1679+
async, so it should be used with `await` + [`await using`][] as in
16761680
`await using dir = await fsPromises.mkdtempDisposable('prefix')`.
16771681
1678-
<!-- TODO: link MDN docs for disposables once https://github.com/mdn/content/pull/38027 lands -->
1682+
See the [MDN documentation on `using` statements][`using`] for more information about
1683+
explicit resource management.
16791684
16801685
For detailed information, see the documentation of [`fsPromises.mkdtemp()`][].
16811686
@@ -6430,12 +6435,13 @@ removed if it still exists. If the directory cannot be deleted, disposal will
64306435
throw an error. The object has a `remove()` method which will perform the same
64316436
task.
64326437
6433-
<!-- TODO: link MDN docs for disposables once https://github.com/mdn/content/pull/38027 lands -->
6438+
See the [MDN documentation on `using` statements][`using`] for more information about
6439+
explicit resource management.
64346440
64356441
For detailed information, see the documentation of [`fs.mkdtemp()`][].
64366442
64376443
There is no callback-based version of this API because it is designed for use
6438-
with the `using` syntax.
6444+
with the [`using`][] syntax.
64396445
64406446
The optional `options` argument can be a string specifying an encoding, or an
64416447
object with an `encoding` property specifying the character encoding to use.
@@ -7307,6 +7313,10 @@ changes:
73077313
Calls `dir.close()` if the directory handle is open, and returns a promise that
73087314
fulfills when disposal is complete.
73097315
7316+
This method enables the directory to be used with [`await using`][], which
7317+
will automatically close the directory when the scope exits. For more
7318+
information, see the [MDN documentation on `using` statements][`using`].
7319+
73107320
#### `dir[Symbol.dispose]()`
73117321
73127322
<!-- YAML
@@ -7322,6 +7332,10 @@ changes:
73227332
Calls `dir.closeSync()` if the directory handle is open, and returns
73237333
`undefined`.
73247334
7335+
This method enables the directory to be used with [`using`][], which
7336+
will automatically close the directory when the scope exits. For more
7337+
information, see the [MDN documentation on `using` statements][`using`].
7338+
73257339
### Class: `fs.Dirent`
73267340
73277341
<!-- YAML
@@ -8458,6 +8472,10 @@ the `data` argument must be a {Buffer}.
84588472
84598473
Calls `utf8Stream.destroy()`.
84608474
8475+
This method enables the stream to be used with [`using`][], which
8476+
will automatically destroy the stream when the scope exits. For more
8477+
information, see the [MDN documentation on `using` statements][`using`].
8478+
84618479
### Class: `fs.WriteStream`
84628480
84638481
<!-- YAML
@@ -9274,6 +9292,7 @@ the file contents.
92749292
[`Number.MAX_SAFE_INTEGER`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER
92759293
[`ReadDirectoryChangesW`]: https://docs.microsoft.com/en-us/windows/desktop/api/winbase/nf-winbase-readdirectorychangesw
92769294
[`UV_THREADPOOL_SIZE`]: cli.md#uv_threadpool_sizesize
9295+
[`await using`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/await_using
92779296
[`event ports`]: https://illumos.org/man/port_create
92789297
[`filehandle.createReadStream()`]: #filehandlecreatereadstreamoptions
92799298
[`filehandle.createWriteStream()`]: #filehandlecreatewritestreamoptions
@@ -9333,6 +9352,7 @@ the file contents.
93339352
[`stream/iter pipeTo()`]: stream_iter.md#pipetosource-transforms-writer-options
93349353
[`stream/iter pull()`]: stream_iter.md#pullsource-transforms-options
93359354
[`stream/iter pullSync()`]: stream_iter.md#pullsyncsource-transforms
9355+
[`using`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using
93369356
[`util.promisify()`]: util.md#utilpromisifyoriginal
93379357
[bigints]: https://tc39.github.io/proposal-bigint
93389358
[caveats]: #caveats

0 commit comments

Comments
 (0)