From f1b79828bc4215365ee31e3fd052c1937426f1e4 Mon Sep 17 00:00:00 2001
From: flakey5 <73616808+flakey5@users.noreply.github.com>
Date: Fri, 27 Jan 2023 17:12:00 -0800
Subject: [PATCH] lib: add AsyncLocalStorage.bind() and .snapshot()
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PR-URL: https://github.com/nodejs/node/pull/46387
Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Gerhard Stöbich <deb2001-github@yahoo.de>
---
 doc/api/async_context.md                      | 50 +++++++++++++++++++
 lib/async_hooks.js                            |  8 +++
 .../parallel/test-async-local-storage-bind.js | 17 +++++++
 .../test-async-local-storage-snapshot.js      | 16 ++++++
 4 files changed, 91 insertions(+)
 create mode 100644 test/parallel/test-async-local-storage-bind.js
 create mode 100644 test/parallel/test-async-local-storage-snapshot.js

diff --git a/doc/api/async_context.md b/doc/api/async_context.md
index 85507cfadc8f1a..ed2de575e92106 100644
--- a/doc/api/async_context.md
+++ b/doc/api/async_context.md
@@ -134,6 +134,56 @@ changes:
 Creates a new instance of `AsyncLocalStorage`. Store is only provided within a
 `run()` call or after an `enterWith()` call.
 
+### Static method: `AsyncLocalStorage.bind(fn)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+* `fn` {Function} The function to bind to the current execution context.
+* Returns: {Function} A new function that calls `fn` within the captured
+  execution context.
+
+Binds the given function to the current execution context.
+
+### Static method: `AsyncLocalStorage.snapshot()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+* Returns: {Function} A new function with the signature
+  `(fn: (...args) : R, ...args) : R`.
+
+Captures the current execution context and returns a function that accepts a
+function as an argument. Whenever the returned function is called, it
+calls the function passed to it within the captured context.
+
+```js
+const asyncLocalStorage = new AsyncLocalStorage();
+const runInAsyncScope = asyncLocalStorage.run(123, () => asyncLocalStorage.snapshot());
+const result = asyncLocalStorage.run(321, () => runInAsyncScope(() => asyncLocalStorage.getStore()));
+console.log(result);  // returns 123
+```
+
+AsyncLocalStorage.snapshot() can replace the use of AsyncResource for simple
+async context tracking purposes, for example:
+
+```js
+class Foo {
+  #runInAsyncScope = AsyncLocalStorage.snapshot();
+
+  get() { return this.#runInAsyncScope(() => asyncLocalStorage.getStore()); }
+}
+
+const foo = asyncLocalStorage.run(123, () => new Foo());
+console.log(asyncLocalStorage.run(321, () => foo.get())); // returns 123
+```
+
 ### `asyncLocalStorage.disable()`
 
 <!-- YAML
diff --git a/lib/async_hooks.js b/lib/async_hooks.js
index 525b69acbfc652..43fc6ad74da8b2 100644
--- a/lib/async_hooks.js
+++ b/lib/async_hooks.js
@@ -279,6 +279,14 @@ class AsyncLocalStorage {
     this.enabled = false;
   }
 
+  static bind(fn) {
+    return AsyncResource.bind(fn);
+  }
+
+  static snapshot() {
+    return AsyncLocalStorage.bind((cb, ...args) => cb(...args));
+  }
+
   disable() {
     if (this.enabled) {
       this.enabled = false;
diff --git a/test/parallel/test-async-local-storage-bind.js b/test/parallel/test-async-local-storage-bind.js
new file mode 100644
index 00000000000000..d8d4c4599826f9
--- /dev/null
+++ b/test/parallel/test-async-local-storage-bind.js
@@ -0,0 +1,17 @@
+'use strict';
+
+const common = require('../common');
+const assert = require('assert');
+const { AsyncLocalStorage } = require('async_hooks');
+
+[1, false, '', {}, []].forEach((i) => {
+  assert.throws(() => AsyncLocalStorage.bind(i), {
+    code: 'ERR_INVALID_ARG_TYPE'
+  });
+});
+
+const fn = common.mustCall(AsyncLocalStorage.bind(() => 123));
+assert.strictEqual(fn(), 123);
+
+const fn2 = AsyncLocalStorage.bind(common.mustCall((arg) => assert.strictEqual(arg, 'test')));
+fn2('test');
diff --git a/test/parallel/test-async-local-storage-snapshot.js b/test/parallel/test-async-local-storage-snapshot.js
new file mode 100644
index 00000000000000..63e47ba3ce0ac0
--- /dev/null
+++ b/test/parallel/test-async-local-storage-snapshot.js
@@ -0,0 +1,16 @@
+'use strict';
+
+const common = require('../common');
+const { strictEqual } = require('assert');
+const { AsyncLocalStorage } = require('async_hooks');
+
+const asyncLocalStorage = new AsyncLocalStorage();
+const runInAsyncScope =
+  asyncLocalStorage.run(123, common.mustCall(() => AsyncLocalStorage.snapshot()));
+const result =
+  asyncLocalStorage.run(321, common.mustCall(() => {
+    return runInAsyncScope(() => {
+      return asyncLocalStorage.getStore();
+    });
+  }));
+strictEqual(result, 123);