Skip to content

diagnostics_channel: add WindowChannel and scopes #61680

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Qard wants to merge 2 commits into
base: main
Choose a base branch
from
Open

diagnostics_channel: add WindowChannel and scopes #61680

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
09cb6ad
async_hooks: add using scopes to AsyncLocalStorage
Qard Feb 4, 2026
1018c57
diagnostics_channel: add WindowChannel and scopes
Qard Feb 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 95 additions & 0 deletions doc/api/async_context.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -386,6 +386,83 @@ try {
}
```

### `asyncLocalStorage.withScope(store)`

<!-- YAML
added: REPLACEME
-->

> Stability: 1 - Experimental
Copy link
Member

@RafaelGSS RafaelGSS Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
> Stability: 1 - Experimental
> Stability: 1 - Experimental

Perhaps 1.1 Active Development instead?


* `store` {any}
* Returns: {RunScope}

Creates a disposable scope that enters the given store and automatically
restores the previous store value when the scope is disposed. This method is
designed to work with JavaScript's explicit resource management (`using` syntax).

Example:

```mjs
import { AsyncLocalStorage } from 'node:async_hooks';

const asyncLocalStorage = new AsyncLocalStorage();

{
using scope = asyncLocalStorage.withScope('my-store');
console.log(asyncLocalStorage.getStore()); // Prints: my-store
}

console.log(asyncLocalStorage.getStore()); // Prints: undefined
```

```cjs
const { AsyncLocalStorage } = require('node:async_hooks');

const asyncLocalStorage = new AsyncLocalStorage();

{
using scope = asyncLocalStorage.withScope('my-store');
console.log(asyncLocalStorage.getStore()); // Prints: my-store
}

console.log(asyncLocalStorage.getStore()); // Prints: undefined
```

The `withScope()` method is particularly useful for managing context in
synchronous code where you want to ensure the previous store value is restored
when exiting a block, even if an error is thrown.

```mjs
import { AsyncLocalStorage } from 'node:async_hooks';

const asyncLocalStorage = new AsyncLocalStorage();

try {
using scope = asyncLocalStorage.withScope('my-store');
console.log(asyncLocalStorage.getStore()); // Prints: my-store
throw new Error('test');
} catch (e) {
// Store is automatically restored even after error
console.log(asyncLocalStorage.getStore()); // Prints: undefined
}
```

```cjs
const { AsyncLocalStorage } = require('node:async_hooks');

const asyncLocalStorage = new AsyncLocalStorage();

try {
using scope = asyncLocalStorage.withScope('my-store');
console.log(asyncLocalStorage.getStore()); // Prints: my-store
throw new Error('test');
} catch (e) {
// Store is automatically restored even after error
console.log(asyncLocalStorage.getStore()); // Prints: undefined
}
```

### Usage with `async/await`

If, within an async function, only one `await` call is to run within a context,
Expand Down Expand Up @@ -420,6 +497,22 @@ of `asyncLocalStorage.getStore()` after the calls you suspect are responsible
for the loss. When the code logs `undefined`, the last callback called is
probably responsible for the context loss.

## Class: `RunScope`

<!-- YAML
added: REPLACEME
-->

> Stability: 1 - Experimental

A disposable scope returned by [`asyncLocalStorage.withScope()`][] that
automatically restores the previous store value when disposed. This class
implements the [Explicit Resource Management][] protocol and is designed to work
with JavaScript's `using` syntax.

The scope automatically restores the previous store value when the `using` block
exits, whether through normal completion or by throwing an error.

## Class: `AsyncResource`

<!-- YAML
Expand Down Expand Up @@ -905,8 +998,10 @@ const server = createServer((req, res) => {
}).listen(3000);
```

[Explicit Resource Management]: https://github.com/tc39/proposal-explicit-resource-management
[`AsyncResource`]: #class-asyncresource
[`EventEmitter`]: events.md#class-eventemitter
[`Stream`]: stream.md#stream
[`Worker`]: worker_threads.md#class-worker
[`asyncLocalStorage.withScope()`]: #asynclocalstoragewithscopestore
[`util.promisify()`]: util.md#utilpromisifyoriginal
Loading
Loading