doc: stabilize AsyncLocalStorage methods

[vdeturckheim]

Mark AsyncLocalStorage#enterWith and AsyncLocalStorage#disable as stable

Following discussions with @mcollina , I don't remember fully why these two methods are now stable.

They might be confusing for the end user to know which context they are in but now that async context tracking is more well known, I don't think this is so much of a big problem?

[Flarna]

As far as I remember it was not marked as stable for following reasons:

• enterWith was seen as "dangerous", prone to result in leaks
• The TC39 proposal for AsyncContext doesn't include them for the same reason
• CloudFlare Worker didn't add them for the same reason (@jasnell please correct me if I'm wrong)

Having these APIs stable and getting native JS support for AsyncContext without it would likely result in adoption problems.

[Flarna]

I think we should mention the version when it was moved from experimental to stable in the YAML section above.
see e.g. AsyncLocalStorage.snapshot() as reference.

[mcollina]

We can't remove them either because they are needed for the instrumentation/apm use case as well as many frameworks. You can see examples in: nodejs/standards-positions#2 (comment).

We should mark those as stable, or remove them entirely if an alternative can be identified.

[vdeturckheim]

Thanks for the context @Flarna !
Do you think that documentation warnings would be enough in 2025 to let the user know they need to worry about leaks?

It is indeed dangerous, but I agree with @mcollina 's point here, it's needed or we should look for an alternative.

[Flarna]

Sorry, my intention was not to block this. I was in favor of a simple set API from beginning but that time there was a lot push back.

I guess the best extension to run would be via using (Refs: tc39/proposal-async-context#60)

What I still don't like is the name - enterWith(newCtx) sounds like a matching exit() fits but actually needed is a enterWith(prevCtx). But well, renaming this was already too late a few years ago (see #45373).

Another question: Any reason why AsyncLocalStorage.exit() is kept experimental?
The current AsyncContextFrame based implemenation is just a wrapper around run(undefined, ...).
The previous, resource based implemenation is a bit different as it first disables and afterward enabled ALS. Maybe calling disable() followed by enterWith() would do the job.
Or is that an API we should actually removed?

While writing this I remembered that disable() acts different between current and previous implemenation (refs: #48528 (comment)) which indicates stability is not that good.

[vdeturckheim]

Sorry, my intention was not to block this.

No worries, I did not read it this way, also, I opened this PR to re-open the discussion!

I like the idea of using using here tbh, seems to be an elegant solution.

cc @legendecas

[legendecas]

using support on AsyncContext just reached to stage 1 at https://github.com/tc39/proposal-async-context-disposable.

Comparing to run, enterWith has to be used with care, either due to how it is implemented with lazy-initialization (#53037), or due to its semantics with async function before first await like:

asyncfunctionfoo(){als.enterWith(newValue);await0;}

If enterWith is promoted to stable, I think it'd be better to initialize AsyncLocalStorage eagerly to fix issues like #53037. To kick off the work, I submitted #58029.

It's fair to say that an experimental API has been used a lot and it should be promote to stable, but it should also be documented in which case it will break as caveats.

---

That's been said, I think AsyncLocalStorage.prototype.disable() should be separated from this PR. It's use cases are not the same with enterWith and I think it is more error proven to cause more issues like #53037.

[jasnell]

I'm not against graduating these to stable but I would suggest perhaps moving these APIs immediately to the Legacy status and we should likely better document the potential issues inherent in their use.

And as a side note, we likely need to align AsyncLocalStorage use of explicit resource management to align with the work being done on the AsyncContext proposal.

[mcollina]

I would not mark enterWith() as legacy as long as there isn't a viable alternative.

[vdeturckheim]

I'll wait for using to be available and start to play with it to see if it works in this case. Let's keep it open until then

[vdeturckheim]

I just pushed a draft commit showing how we could use explicit ressource management

With this commit, the code:

import{AsyncLocalStorage}from'async_hooks';import{setTimeout}from'timers/promises';constctx=newAsyncLocalStorage()constf1=asyncfunction(){usingc=ctx.unNamedMethod({f: 1});console.log(ctx.getStore());awaitsetTimeout(5000);console.log(ctx.getStore());}constf2=asyncfunction(){usingc=ctx.unNamedMethod({f: 2});console.log(ctx.getStore());awaitsetTimeout(2000);console.log(ctx.getStore());}f1();f2();

displays

{ f: 1 }
{ f: 2 }
{ f: 2 }
Stop propagating store { f: 2 }
{ f: 1 }
Stop propagating store { f: 1 }

@legendecas@mcollina@Flarna wdyt?

[vdeturckheim]

closing in favor of #58104

[codecov]

Codecov Report

Attention: Patch coverage is 18.18182% with 18 lines in your changes missing coverage. Please review.

Project coverage is 90.12%. Comparing base (4454d09) to head (0fcb0d3).
Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
...nternal/async_local_storage/async_context_frame.js	18.18%	9 Missing ⚠️
lib/internal/async_local_storage/async_hooks.js	18.18%	9 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #58019 +/- ##
==========================================
- Coverage 90.12% 90.12% -0.01% 
==========================================
Files 629 629 Lines 186628 186650 +22 Branches 36622 36623 +1 ==========================================
+ Hits 168206 168219 +13 - Misses 11216 11233 +17 + Partials 7206 7198 -8 

Files with missing lines	Coverage Δ
...nternal/async_local_storage/async_context_frame.js	90.32% <18.18%> (-9.68%)	⬇️
lib/internal/async_local_storage/async_hooks.js	92.40% <18.18%> (-5.56%)	⬇️

... and 25 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.