From 09cb6ad7e0a9007abe9eb75814e5a112416c65b1 Mon Sep 17 00:00:00 2001
From: Stephen Belanger <admin@stephenbelanger.com>
Date: Wed, 4 Feb 2026 19:03:40 +0800
Subject: [PATCH] async_hooks: add using scopes to AsyncLocalStorage

Adds support for using scope = storage.withScope(data) to do
the equivalent of a storage.run(data, fn) with using syntax.
This enables avoiding unnecessary closures.
---
 doc/api/async_context.md                      |  95 ++++++++++
 .../async_context_frame.js                    |   6 +
 .../async_local_storage/async_hooks.js        |   6 +
 lib/internal/async_local_storage/run_scope.js |  27 +++
 .../test-async-local-storage-run-scope.js     | 165 ++++++++++++++++++
 tools/doc/type-parser.mjs                     |   1 +
 6 files changed, 300 insertions(+)
 create mode 100644 lib/internal/async_local_storage/run_scope.js
 create mode 100644 test/parallel/test-async-local-storage-run-scope.js

diff --git a/doc/api/async_context.md b/doc/api/async_context.md
index dd3b6a834ec950..a3d551f99269fe 100644
--- a/doc/api/async_context.md
+++ b/doc/api/async_context.md
@@ -386,6 +386,83 @@ try {
 }
 ```
 
+### `asyncLocalStorage.withScope(store)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+* `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,
@@ -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
@@ -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
diff --git a/lib/internal/async_local_storage/async_context_frame.js b/lib/internal/async_local_storage/async_context_frame.js
index 518e955379ac54..8390ba92cbe848 100644
--- a/lib/internal/async_local_storage/async_context_frame.js
+++ b/lib/internal/async_local_storage/async_context_frame.js
@@ -12,6 +12,8 @@ const {
 const AsyncContextFrame = require('internal/async_context_frame');
 const { AsyncResource } = require('async_hooks');
 
+const RunScope = require('internal/async_local_storage/run_scope');
+
 class AsyncLocalStorage {
   #defaultValue = undefined;
   #name = undefined;
@@ -77,6 +79,10 @@ class AsyncLocalStorage {
     }
     return frame?.get(this);
   }
+
+  withScope(store) {
+    return new RunScope(this, store);
+  }
 }
 
 module.exports = AsyncLocalStorage;
diff --git a/lib/internal/async_local_storage/async_hooks.js b/lib/internal/async_local_storage/async_hooks.js
index d227549412bf61..552092d89bf305 100644
--- a/lib/internal/async_local_storage/async_hooks.js
+++ b/lib/internal/async_local_storage/async_hooks.js
@@ -19,6 +19,8 @@ const {
   executionAsyncResource,
 } = require('async_hooks');
 
+const RunScope = require('internal/async_local_storage/run_scope');
+
 const storageList = [];
 const storageHook = createHook({
   init(asyncId, type, triggerAsyncId, resource) {
@@ -142,6 +144,10 @@ class AsyncLocalStorage {
     }
     return this.#defaultValue;
   }
+
+  withScope(store) {
+    return new RunScope(this, store);
+  }
 }
 
 module.exports = AsyncLocalStorage;
diff --git a/lib/internal/async_local_storage/run_scope.js b/lib/internal/async_local_storage/run_scope.js
new file mode 100644
index 00000000000000..a2d024fc23d027
--- /dev/null
+++ b/lib/internal/async_local_storage/run_scope.js
@@ -0,0 +1,27 @@
+'use strict';
+
+const {
+  SymbolDispose,
+} = primordials;
+
+class RunScope {
+  #storage;
+  #previousStore;
+  #disposed = false;
+
+  constructor(storage, store) {
+    this.#storage = storage;
+    this.#previousStore = storage.getStore();
+    storage.enterWith(store);
+  }
+
+  [SymbolDispose]() {
+    if (this.#disposed) {
+      return;
+    }
+    this.#disposed = true;
+    this.#storage.enterWith(this.#previousStore);
+  }
+}
+
+module.exports = RunScope;
diff --git a/test/parallel/test-async-local-storage-run-scope.js b/test/parallel/test-async-local-storage-run-scope.js
new file mode 100644
index 00000000000000..e9f06147dc3b77
--- /dev/null
+++ b/test/parallel/test-async-local-storage-run-scope.js
@@ -0,0 +1,165 @@
+/* eslint-disable no-unused-vars */
+'use strict';
+require('../common');
+const assert = require('node:assert');
+const { AsyncLocalStorage } = require('node:async_hooks');
+
+// Test basic RunScope with using
+{
+  const storage = new AsyncLocalStorage();
+
+  assert.strictEqual(storage.getStore(), undefined);
+
+  {
+    using scope = storage.withScope('test');
+    assert.strictEqual(storage.getStore(), 'test');
+  }
+
+  // Store should be restored to undefined
+  assert.strictEqual(storage.getStore(), undefined);
+}
+
+// Test RunScope restores previous value
+{
+  const storage = new AsyncLocalStorage();
+
+  storage.enterWith('initial');
+  assert.strictEqual(storage.getStore(), 'initial');
+
+  {
+    using scope = storage.withScope('scoped');
+    assert.strictEqual(storage.getStore(), 'scoped');
+  }
+
+  // Should restore to previous value
+  assert.strictEqual(storage.getStore(), 'initial');
+}
+
+// Test nested RunScope
+{
+  const storage = new AsyncLocalStorage();
+  const storeValues = [];
+
+  {
+    using outer = storage.withScope('outer');
+    storeValues.push(storage.getStore());
+
+    {
+      using inner = storage.withScope('inner');
+      storeValues.push(storage.getStore());
+    }
+
+    // Should restore to outer
+    storeValues.push(storage.getStore());
+  }
+
+  // Should restore to undefined
+  storeValues.push(storage.getStore());
+
+  assert.deepStrictEqual(storeValues, ['outer', 'inner', 'outer', undefined]);
+}
+
+// Test RunScope with error during usage
+{
+  const storage = new AsyncLocalStorage();
+
+  storage.enterWith('before');
+
+  const testError = new Error('test');
+
+  assert.throws(() => {
+    using scope = storage.withScope('during');
+    assert.strictEqual(storage.getStore(), 'during');
+    throw testError;
+  }, testError);
+
+  // Store should be restored even after error
+  assert.strictEqual(storage.getStore(), 'before');
+}
+
+// Test idempotent disposal
+{
+  const storage = new AsyncLocalStorage();
+
+  const scope = storage.withScope('test');
+  assert.strictEqual(storage.getStore(), 'test');
+
+  // Dispose via Symbol.dispose
+  scope[Symbol.dispose]();
+  assert.strictEqual(storage.getStore(), undefined);
+
+  // Double dispose should be idempotent
+  scope[Symbol.dispose]();
+  assert.strictEqual(storage.getStore(), undefined);
+}
+
+// Test RunScope with defaultValue
+{
+  const storage = new AsyncLocalStorage({ defaultValue: 'default' });
+
+  assert.strictEqual(storage.getStore(), 'default');
+
+  {
+    using scope = storage.withScope('custom');
+    assert.strictEqual(storage.getStore(), 'custom');
+  }
+
+  // Should restore to default
+  assert.strictEqual(storage.getStore(), 'default');
+}
+
+// Test deeply nested RunScope
+{
+  const storage = new AsyncLocalStorage();
+
+  {
+    using s1 = storage.withScope(1);
+    assert.strictEqual(storage.getStore(), 1);
+
+    {
+      using s2 = storage.withScope(2);
+      assert.strictEqual(storage.getStore(), 2);
+
+      {
+        using s3 = storage.withScope(3);
+        assert.strictEqual(storage.getStore(), 3);
+
+        {
+          using s4 = storage.withScope(4);
+          assert.strictEqual(storage.getStore(), 4);
+        }
+
+        assert.strictEqual(storage.getStore(), 3);
+      }
+
+      assert.strictEqual(storage.getStore(), 2);
+    }
+
+    assert.strictEqual(storage.getStore(), 1);
+  }
+
+  assert.strictEqual(storage.getStore(), undefined);
+}
+
+// Test RunScope with multiple storages
+{
+  const storage1 = new AsyncLocalStorage();
+  const storage2 = new AsyncLocalStorage();
+
+  {
+    using scope1 = storage1.withScope('A');
+
+    {
+      using scope2 = storage2.withScope('B');
+
+      assert.strictEqual(storage1.getStore(), 'A');
+      assert.strictEqual(storage2.getStore(), 'B');
+    }
+
+    assert.strictEqual(storage1.getStore(), 'A');
+    assert.strictEqual(storage2.getStore(), undefined);
+  }
+
+  assert.strictEqual(storage1.getStore(), undefined);
+  assert.strictEqual(storage2.getStore(), undefined);
+}
diff --git a/tools/doc/type-parser.mjs b/tools/doc/type-parser.mjs
index db85a64e33a903..0e2b5578f0c3d9 100644
--- a/tools/doc/type-parser.mjs
+++ b/tools/doc/type-parser.mjs
@@ -65,6 +65,7 @@ const customTypesMap = {
     'https://tc39.github.io/ecma262/#sec-module-namespace-exotic-objects',
 
   'AsyncLocalStorage': 'async_context.html#class-asynclocalstorage',
+  'RunScope': 'async_context.html#class-runscope',
 
   'AsyncHook': 'async_hooks.html#async_hookscreatehookoptions',
   'AsyncResource': 'async_hooks.html#class-asyncresource',