From 69a25e2b5f9d773c73e2806f6b875df73e9c1188 Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Sat, 5 Apr 2025 13:28:51 -0700
Subject: [PATCH 1/2] lib: add defaultValue and name options to
 AsyncLocalStorage

The upcoming `AsyncContext` specification adds a default value and name
to async storage variables. This adds the same to `AsyncLocalStorage`
to promote closer alignment with the pending spec.

```js
const als = new AsyncLocalStorage({
  name: 'foo',
  defaultValue: 123,
});

console.log(als.name);  // 'foo'
console.log(als.getStore());  // 123
```

Refs: https://github.com/tc39/proposal-async-context/blob/master/spec.html
---
 doc/api/async_context.md                      | 19 ++++++++-
 .../async_context_frame.js                    | 33 ++++++++++++++-
 .../async_local_storage/async_hooks.js        | 30 +++++++++++++-
 .../test-als-defaultvalue-original.js         | 40 +++++++++++++++++++
 test/parallel/test-als-defaultvalue.js        | 40 +++++++++++++++++++
 5 files changed, 159 insertions(+), 3 deletions(-)
 create mode 100644 test/parallel/test-als-defaultvalue-original.js
 create mode 100644 test/parallel/test-als-defaultvalue.js

diff --git a/doc/api/async_context.md b/doc/api/async_context.md
index c7aaac3dbc438f..e8c58eae962ebf 100644
--- a/doc/api/async_context.md
+++ b/doc/api/async_context.md
@@ -116,13 +116,16 @@ Each instance of `AsyncLocalStorage` maintains an independent storage context.
 Multiple instances can safely exist simultaneously without risk of interfering
 with each other's data.
 
-### `new AsyncLocalStorage()`
+### `new AsyncLocalStorage([options])`
 
 <!-- YAML
 added:
  - v13.10.0
  - v12.17.0
 changes:
+ - version: REPLACEME
+   pr-url: https://github.com/nodejs/node/pull/00000
+   description: Add `defaultValue` and `name` options.
  - version:
     - v19.7.0
     - v18.16.0
@@ -135,6 +138,10 @@ changes:
    description: Add option onPropagate.
 -->
 
+* `options` {Object}
+  * `defaultValue` {any} The default value to be used when no store is provided.
+  * `name` {string} A name for the `AsyncLocalStorage` value.
+
 Creates a new instance of `AsyncLocalStorage`. Store is only provided within a
 `run()` call or after an `enterWith()` call.
 
@@ -286,6 +293,16 @@ emitter.emit('my-event');
 asyncLocalStorage.getStore(); // Returns the same object
 ```
 
+### `asyncLocalStorage.name`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* {string}
+
+The name of the `AsyncLocalStorage` instance if provided.
+
 ### `asyncLocalStorage.run(store, callback[, ...args])`
 
 <!-- YAML
diff --git a/lib/internal/async_local_storage/async_context_frame.js b/lib/internal/async_local_storage/async_context_frame.js
index 72e1edf57ef0fe..13b769a4642aa1 100644
--- a/lib/internal/async_local_storage/async_context_frame.js
+++ b/lib/internal/async_local_storage/async_context_frame.js
@@ -4,10 +4,37 @@ const {
   ReflectApply,
 } = primordials;
 
+const {
+  validateObject,
+} = require('internal/validators');
+
 const AsyncContextFrame = require('internal/async_context_frame');
 const { AsyncResource } = require('async_hooks');
 
 class AsyncLocalStorage {
+  #defaultValue = undefined;
+  #name = undefined;
+
+  /**
+   * @typedef {object} AsyncLocalStorageOptions
+   * @property {any} [defaultValue] - The default value to use when no value is set.
+   * @property {string} [name] - The name of the storage.
+   */
+  /**
+   * @param {AsyncLocalStorageOptions} [options]
+   */
+  constructor(options = {}) {
+    validateObject(options, 'options');
+    this.#defaultValue = options.defaultValue;
+
+    if (options.name !== undefined) {
+      this.#name = `${options.name}`;
+    }
+  }
+
+  /** @type {string} */
+  get name() { return this.#name || ''; }
+
   static bind(fn) {
     return AsyncResource.bind(fn);
   }
@@ -40,7 +67,11 @@ class AsyncLocalStorage {
   }
 
   getStore() {
-    return AsyncContextFrame.current()?.get(this);
+    const frame = AsyncContextFrame.current();
+    if (!frame?.has(this)) {
+      return this.#defaultValue;
+    }
+    return frame?.get(this);
   }
 }
 
diff --git a/lib/internal/async_local_storage/async_hooks.js b/lib/internal/async_local_storage/async_hooks.js
index 519dd37e6156c5..0ed423f5932ed7 100644
--- a/lib/internal/async_local_storage/async_hooks.js
+++ b/lib/internal/async_local_storage/async_hooks.js
@@ -9,6 +9,10 @@ const {
   Symbol,
 } = primordials;
 
+const {
+  validateObject,
+} = require('internal/validators');
+
 const {
   AsyncResource,
   createHook,
@@ -27,11 +31,31 @@ const storageHook = createHook({
 });
 
 class AsyncLocalStorage {
-  constructor() {
+  #defaultValue = undefined;
+  #name = undefined;
+
+  /**
+   * @typedef {object} AsyncLocalStorageOptions
+   * @property {any} [defaultValue] - The default value to use when no value is set.
+   * @property {string} [name] - The name of the storage.
+   */
+  /**
+   * @param {AsyncLocalStorageOptions} [options]
+   */
+  constructor(options = {}) {
     this.kResourceStore = Symbol('kResourceStore');
     this.enabled = false;
+    validateObject(options, 'options');
+    this.#defaultValue = options.defaultValue;
+
+    if (options.name !== undefined) {
+      this.#name = `${options.name}`;
+    }
   }
 
+  /** @type {string} */
+  get name() { return this.#name || ''; }
+
   static bind(fn) {
     return AsyncResource.bind(fn);
   }
@@ -109,8 +133,12 @@ class AsyncLocalStorage {
   getStore() {
     if (this.enabled) {
       const resource = executionAsyncResource();
+      if (!(this.kResourceStore in resource)) {
+        return this.#defaultValue;
+      }
       return resource[this.kResourceStore];
     }
+    return this.#defaultValue;
   }
 }
 
diff --git a/test/parallel/test-als-defaultvalue-original.js b/test/parallel/test-als-defaultvalue-original.js
new file mode 100644
index 00000000000000..7ea5ec0eab45c2
--- /dev/null
+++ b/test/parallel/test-als-defaultvalue-original.js
@@ -0,0 +1,40 @@
+// Flags: --no-async-context-frame
+'use strict';
+
+require('../common');
+
+const {
+  AsyncLocalStorage,
+} = require('async_hooks');
+
+const {
+  strictEqual,
+  throws,
+} = require('assert');
+
+// ============================================================================
+// The defaultValue option
+const als1 = new AsyncLocalStorage();
+strictEqual(als1.getStore(), undefined, 'value should be undefined');
+
+const als2 = new AsyncLocalStorage({ defaultValue: 'default' });
+strictEqual(als2.getStore(), 'default', 'value should be "default"');
+
+const als3 = new AsyncLocalStorage({ defaultValue: 42 });
+strictEqual(als3.getStore(), 42, 'value should be 42');
+
+const als4 = new AsyncLocalStorage({ defaultValue: null });
+strictEqual(als4.getStore(), null, 'value should be null');
+
+throws(() => new AsyncLocalStorage(null), {
+  code: 'ERR_INVALID_ARG_TYPE',
+});
+
+// ============================================================================
+// The name option
+
+const als5 = new AsyncLocalStorage({ name: 'test' });
+strictEqual(als5.name, 'test');
+
+const als6 = new AsyncLocalStorage();
+strictEqual(als6.name, '');
diff --git a/test/parallel/test-als-defaultvalue.js b/test/parallel/test-als-defaultvalue.js
new file mode 100644
index 00000000000000..0e905104f27c6b
--- /dev/null
+++ b/test/parallel/test-als-defaultvalue.js
@@ -0,0 +1,40 @@
+// Flags: --async-context-frame
+'use strict';
+
+require('../common');
+
+const {
+  AsyncLocalStorage,
+} = require('async_hooks');
+
+const {
+  strictEqual,
+  throws,
+} = require('assert');
+
+// ============================================================================
+// The defaultValue option
+const als1 = new AsyncLocalStorage();
+strictEqual(als1.getStore(), undefined, 'value should be undefined');
+
+const als2 = new AsyncLocalStorage({ defaultValue: 'default' });
+strictEqual(als2.getStore(), 'default', 'value should be "default"');
+
+const als3 = new AsyncLocalStorage({ defaultValue: 42 });
+strictEqual(als3.getStore(), 42, 'value should be 42');
+
+const als4 = new AsyncLocalStorage({ defaultValue: null });
+strictEqual(als4.getStore(), null, 'value should be null');
+
+throws(() => new AsyncLocalStorage(null), {
+  code: 'ERR_INVALID_ARG_TYPE',
+});
+
+// ============================================================================
+// The name option
+
+const als5 = new AsyncLocalStorage({ name: 'test' });
+strictEqual(als5.name, 'test');
+
+const als6 = new AsyncLocalStorage();
+strictEqual(als6.name, '');

From 90db9114ed9e85a876f4389f1a58333b2d779cfd Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Mon, 7 Apr 2025 08:01:51 -0700
Subject: [PATCH 2/2] Update doc/api/async_context.md

Co-authored-by: Chengzhong Wu <legendecas@gmail.com>
---
 doc/api/async_context.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/api/async_context.md b/doc/api/async_context.md
index e8c58eae962ebf..520c572860649a 100644
--- a/doc/api/async_context.md
+++ b/doc/api/async_context.md
@@ -124,7 +124,7 @@ added:
  - v12.17.0
 changes:
  - version: REPLACEME
-   pr-url: https://github.com/nodejs/node/pull/00000
+   pr-url: https://github.com/nodejs/node/pull/57766
    description: Add `defaultValue` and `name` options.
  - version:
     - v19.7.0