Skip to content

Commit 181bd05

Browse files
puzpuzpuzdanielleadams
authored andcommitted
doc: improve ALS.enterWith and exit descriptions
PR-URL: #36705 Refs: #36683 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Gerhard Stöbich <[email protected]> Reviewed-By: Rich Trott <[email protected]>
1 parent 9eff709 commit 181bd05

File tree

1 file changed

+15
-10
lines changed

1 file changed

+15
-10
lines changed

doc/api/async_hooks.md

+15-10
Original file line numberDiff line numberDiff line change
@@ -1000,7 +1000,7 @@ added:
10001000
-->
10011001

10021002
Creates a new instance of `AsyncLocalStorage`. Store is only provided within a
1003-
`run` method call.
1003+
`run` or after `enterWith` method call.
10041004

10051005
### `asyncLocalStorage.disable()`
10061006
<!-- YAML
@@ -1011,7 +1011,7 @@ added:
10111011

10121012
This method disables the instance of `AsyncLocalStorage`. All subsequent calls
10131013
to `asyncLocalStorage.getStore()` will return `undefined` until
1014-
`asyncLocalStorage.run()` is called again.
1014+
`asyncLocalStorage.run()` or `asyncLocalStorage.enterWith()` is called again.
10151015

10161016
When calling `asyncLocalStorage.disable()`, all current contexts linked to the
10171017
instance will be exited.
@@ -1035,7 +1035,8 @@ added:
10351035

10361036
This method returns the current store.
10371037
If this method is called outside of an asynchronous context initialized by
1038-
calling `asyncLocalStorage.run`, it will return `undefined`.
1038+
calling `asyncLocalStorage.run()` or `asyncLocalStorage.enterWith()`, it will
1039+
return `undefined`.
10391040

10401041
### `asyncLocalStorage.enterWith(store)`
10411042
<!-- YAML
@@ -1046,14 +1047,15 @@ added:
10461047

10471048
* `store` {any}
10481049

1049-
Calling `asyncLocalStorage.enterWith(store)` will transition into the context
1050-
for the remainder of the current synchronous execution and will persist
1051-
through any following asynchronous calls.
1050+
This method transitions into the context for the remainder of the current
1051+
synchronous execution and then persists the store through any following
1052+
asynchronous calls.
10521053

10531054
Example:
10541055

10551056
```js
10561057
const store = { id: 1 };
1058+
// Replaces previous store with the given store object
10571059
asyncLocalStorage.enterWith(store);
10581060
asyncLocalStorage.getStore(); // Returns the store object
10591061
someAsyncOperation(() => {
@@ -1064,7 +1066,9 @@ someAsyncOperation(() => {
10641066
This transition will continue for the _entire_ synchronous execution.
10651067
This means that if, for example, the context is entered within an event
10661068
handler subsequent event handlers will also run within that context unless
1067-
specifically bound to another context with an `AsyncResource`.
1069+
specifically bound to another context with an `AsyncResource`. That is why
1070+
`run` should be preferred over `enterWith` unless there are strong reasons
1071+
to use the latter method.
10681072

10691073
```js
10701074
const store = { id: 1 };
@@ -1130,14 +1134,15 @@ added:
11301134

11311135
This methods runs a function synchronously outside of a context and return its
11321136
return value. The store is not accessible within the callback function or
1133-
the asynchronous operations created within the callback.
1137+
the asynchronous operations created within the callback, i.e. any `getStore`
1138+
call done within the callback function will always return `undefined`.
11341139

11351140
Optionally, arguments can be passed to the function. They will be passed to
11361141
the callback function.
11371142

11381143
If the callback function throws an error, it will be thrown by `exit` too.
1139-
The stacktrace will not be impacted by this call and
1140-
the context will be re-entered.
1144+
The stacktrace will not be impacted by this call and the context will be
1145+
re-entered.
11411146

11421147
Example:
11431148

0 commit comments

Comments
 (0)