async_hooks: add use() method to AsyncLocalStorage

[bengl]

This provides a way to use the using syntax (when available) to manage AsyncLocalStorage contexts, as an alternative to run().

[codecov]

Codecov Report

❌ Patch coverage is 87.75510% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.21%. Comparing base (102d8cf) to head (b0bc07a).
⚠️ Report is 2036 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/async_local_storage/async_hooks.js	80.64%	6 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #58104 +/- ##
=======================================
Coverage 90.20% 90.21% =======================================
Files 630 630 Lines 186446 186495 +49 Branches 36622 36629 +7 =======================================
+ Hits 168189 168246 +57 - Misses 11051 11058 +7 + Partials 7206 7191 -15 

Files with missing lines	Coverage Δ
...nternal/async_local_storage/async_context_frame.js	100.00% <100.00%> (ø)
lib/internal/async_local_storage/async_hooks.js	94.94% <80.64%> (-3.02%)	⬇️

... and 28 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Failed to start CI

 ⚠ No approving reviews found
✘ Refusing to run CI on potentially unsafe PR

https://github.com/nodejs/node/actions/runs/14782552537

[legendecas]

Like #52065, i think this does not work with an async function before the first await that the value will leak out the async function scope. This will need a patch to make V8 CPED aware of async function scopes as well.

asyncfunctionfoo(){usingvalue=als.use(newValue);await0;}foo()// no awaital's.getStore()// value changed.

[Flarna]

Is it intended to be added as stable ?
Otherwise add > Stability: 1 - Experimental here.

[Flarna]

I think it's not the previous context. It's that one seen at the time use() was called.
If use and the matching dispose are called in right order this is the same but if they are called in different order it's not.

e.g. a cast like this (condensed, in real world this would be distributed at independent locations):

const{ AsyncLocalStorage }=require("node:async_hooks");constals1=newAsyncLocalStorage();constals2=newAsyncLocalStorage();constd1=als1.use(store1);constd2=als2.use(store2);constd3=als1.use(store3);als1.getStore();// Returns store3als2.getStore();// Returns store2d1[Symbol.dispose]();als1.getStore();// Returns undefinedals2.getStore();// Returns undefinedd2[Symbol.dispose]();als1.getStore();// Returns store1als2.getStore();// Returns undefinedd3[Symbol.dispose]();als1.getStore();// Returns store1als2.getStore();// Returns store2

Likely a user problem and once using is a thing harder to do.
But I think it should be clear documented what happens or avoid such cases.

In special that one ALS user might effect others is critical in my opinion.

Note that only the AsyncContextFrame variant shows side effects to all ALS users.

[jasnell]

I think if folks are manually calling Symbol.dispose they're rather on their own at that point. It's a bit unfortunate that the ERM model gives them that ability but there's only do much we can do.

[jasnell]

That said, we'll want to be sure that this works as expected when using DisposableStack when that is available.

[Flarna]

I fully agree once using keyword is a thing. But until this is true users have to do it manually.

[Flarna]

I notices that the side effect to other ALS instances is not bound to wrong usage of dispose:

constd1=als1.use("store1");als2.enterWith("store2");console.log(als1.getStore());// store1console.log(als2.getStore());// store2d1[Symbol.dispose]();console.log(als1.getStore());// undefinedconsole.log(als2.getStore());// undefined, but should be store2

[Flarna]

I noticed that this global side effect is not new in the AsyncContextFrame variant. See #58149.

[bengl]

use() is intended to roughly mimic run(), and since that's been changed in #58149 to isolate the storage instances, I'll do that here as well in the next rev.

[Flarna]

I guess by capturing/restoring only the owned store instead the complete frame the side effects to other ALS users could be avoided.

[legendecas]

Agreed, an operation on an AsyncLocalStorage should not affect other instances. For reference: tc39/proposal-async-context-disposable#2

[jasnell]

Should be marked as experimental but otherwise lgtm

[Flarna]

using works meanwhile on main (see #58154) therefore this should be updated accordingly.

[vdeturckheim]

🤦 -> closing #58019 in favor of this

[vdeturckheim]

🫶 this

[bengl]

@legendecas

Like #52065, i think this does not work with an async function before the first await that the value will leak out the async function scope. This will need a patch to make V8 CPED aware of async function scopes as well.

Do you see that as a blocker? Or would it just be fine to document this limitation for now?

[legendecas]

Do you see that as a blocker? Or would it just be fine to document this limitation for now?

I would not see it as a blocker on this particular PR. It would be great to have this PR landed with this API marked as an experimental (1.1 Active development) API and with the limitation documented as a caveat. I think to promote this to stable, we'll need this semantic as a blocker.

[mcollina]

lgtm

[Flarna]

as there are already approvals but there are still important todos I clearly mark it so to avoid accidental merging.

[devsnek]

I never got around to merging this but I have a fix for the CPED issue: https://chromium-review.googlesource.com/c/v8/v8/+/6020635

[BridgeAR]

@devsnek do you think you could find some time to pick it up again and finish that? :)

[bengl]

Closing in favour of #61674