async_hooks: rename AsyncLocalStore#enterWith to set

The name enterWith indicates that there should be a matching exit but
this is not the case. AsyncLocalStore#exit exists but it is not the
opponent of enterWith.

enterWith() is kept as alias and marked as doc only deprecated.

Author: Flarna

benchmark/diagnostics_channel/http.js

@@ -42,7 +42,7 @@ function patch() {
   function wrappedEmit(...args) {
     const [name, req, res] = args;
     if (name === 'request') {
-      als.enterWith({
+      als.set({
         url: req.url,
         start: process.hrtime.bigint()
       });
@@ -72,7 +72,7 @@ function diagnostics_channel() {
   const finish = dc.channel('http.server.response.finish');
 
   function onStart(req) {
-    als.enterWith({
+    als.set({
       url: req.url,
       start: process.hrtime.bigint()
     });

doc/api/async_context.md

@@ -125,7 +125,7 @@ added:
 -->
 
 Creates a new instance of `AsyncLocalStorage`. Store is only provided within a
-`run()` call or after an `enterWith()` call.
+`run()` call or after an `set()` call.
 
 ### `asyncLocalStorage.disable()`
 
@@ -139,7 +139,7 @@ added:
 
 Disables the instance of `AsyncLocalStorage`. All subsequent calls
 to `asyncLocalStorage.getStore()` will return `undefined` until
-`asyncLocalStorage.run()` or `asyncLocalStorage.enterWith()` is called again.
+`asyncLocalStorage.run()` or `asyncLocalStorage.set()` is called again.
 
 When calling `asyncLocalStorage.disable()`, all current contexts linked to the
 instance will be exited.
@@ -164,7 +164,7 @@ added:
 
 Returns the current store.
 If called outside of an asynchronous context initialized by
-calling `asyncLocalStorage.run()` or `asyncLocalStorage.enterWith()`, it
+calling `asyncLocalStorage.run()` or `asyncLocalStorage.set()`, it
 returns `undefined`.
 
 ### `asyncLocalStorage.enterWith(store)`
@@ -173,13 +173,26 @@ returns `undefined`.
 added:
  - v13.11.0
  - v12.17.0
+deprecated:
+ - REPLACEME
+-->
+
+> Stability: 0 - Deprecated: Use [`asyncLocalStorage.set(store)`][]
+
+This is a deprecated alias for [`asyncLocalStorage.set(store)`][].
+
+### `asyncLocalStorage.set(store)`
+
+<!-- YAML
+added:
+ - REPLACEME
 -->
 
 > Stability: 1 - Experimental
 
 * `store` {any}
 
-Transitions into the context for the remainder of the current
+Sets `store` on current execution context for the remainder of the current
 synchronous execution and then persists the store through any following
 asynchronous calls.
 
@@ -188,7 +201,7 @@ Example:
 ```js
 const store = { id: 1 };
 // Replaces previous store with the given store object
-asyncLocalStorage.enterWith(store);
+asyncLocalStorage.set(store);
 asyncLocalStorage.getStore(); // Returns the store object
 someAsyncOperation(() => {
   asyncLocalStorage.getStore(); // Returns the same object
@@ -199,14 +212,14 @@ This transition will continue for the _entire_ synchronous execution.
 This means that if, for example, the context is entered within an event
 handler subsequent event handlers will also run within that context unless
 specifically bound to another context with an `AsyncResource`. That is why
-`run()` should be preferred over `enterWith()` unless there are strong reasons
+`run()` should be preferred over `set()` unless there are strong reasons
 to use the latter method.
 
 ```js
 const store = { id: 1 };
 
 emitter.on('my-event', () => {
-  asyncLocalStorage.enterWith(store);
+  asyncLocalStorage.set(store);
 });
 emitter.on('my-event', () => {
   asyncLocalStorage.getStore(); // Returns the same object
@@ -816,4 +829,5 @@ const server = createServer((req, res) => {
 [`EventEmitter`]: events.md#class-eventemitter
 [`Stream`]: stream.md#stream
 [`Worker`]: worker_threads.md#class-worker
+[`asyncLocalStorage.set(store)`]: #asynclocalstoragesetstore`
 [`util.promisify()`]: util.md#utilpromisifyoriginal

lib/async_hooks.js

@@ -307,7 +307,7 @@ class AsyncLocalStorage {
     }
   }
 
-  enterWith(store) {
+  set(store) {
     this._enable();
     const resource = executionAsyncResource();
     resource[this.kResourceStore] = store;
@@ -353,6 +353,9 @@ class AsyncLocalStorage {
   }
 }
 
+// Create deprecated enterWith alias
+AsyncLocalStorage.prototype.enterWith = AsyncLocalStorage.prototype.set;
+
 // Placing all exports down here because the exported classes won't export
 // otherwise.
 module.exports = {

test/async-hooks/test-async-local-storage-enter-with.js

@@ -5,9 +5,11 @@ const { AsyncLocalStorage } = require('async_hooks');
 
 const asyncLocalStorage = new AsyncLocalStorage();
 
+assert.strictEqual(AsyncLocalStorage.prototype.enterWith, AsyncLocalStorage.prototype.set);
+
 setImmediate(() => {
   const store = { foo: 'bar' };
-  asyncLocalStorage.enterWith(store);
+  asyncLocalStorage.set(store);
 
   assert.strictEqual(asyncLocalStorage.getStore(), store);
   setTimeout(() => {

test/parallel/test-diagnostics-channel-http-server-start.js

@@ -11,7 +11,7 @@ let context;
 
 // Bind requests to an AsyncLocalStorage context
 dc.subscribe('http.server.request.start', common.mustCall((message) => {
-  als.enterWith(message);
+  als.set(message);
   context = message;
 }));