For comparison, .NET has two ways of doing something similar:

AsyncLocal<T> (https://learn.microsoft.com/en-us/dotnet/api/system.threading.asynclocal-1?view=net-7.0) has a .Value property (analogous to Node's AsyncLocalStorage.getStore() and .enterWith(store)

ExecutionContext (https://learn.microsoft.com/en-us/dotnet/api/system.threading.executioncontext.run?view=netframework-4.8) has .Run() (analogous to Node's AsyncLocalStorage.run()) and can be used with LogicalCallContext (https://learn.microsoft.com/en-us/dotnet/api/system.runtime.remoting.messaging.logicalcallcontext.getdata?view=netframework-4.8) to get and set values associated with the logical call flow. It also has a Dispose, which is analogous to Node's .disable().

In addition, ExecutionContext allows you to capture the current context, copy it into a new context, and suppress and restore the context across async invocations (using AsyncFlowControl).

I don't disagree with its utility, but It's still a convenience method. You could achieve the same in userland with only .run() and .get():

function wrap(ctx, cb) {
  const store = ctx.get();
  return () => ctx.run(store, cb);
}

If you have multiple AsyncContext objects, you might end up with:

const ctx1 = new AsyncContext();
const ctx2 = new AsyncContext();

function foo() {
  ctx1.run({ id: 1 }, bar);
}

function bar() {
  ctx1.run({ id: 2 }, baz);
}

function baz() {
  ctx1.get(); // { id: 1 }
  ctx2.get(); // { id: 2 } 
}

While in .NET you might do:

var local1 = new AsyncLocal<number>();
var local2 = new AsyncLocal<number>();

void Foo() {
  var context = ExecutionContext.CreateCopy();
  ExecutionContext.Run(context, () => {
    local1.Value = 1;
    Bar();
  });
}

void Bar() {
  local2.Value = 2;
  Baz();
}

void Baz() { ... }

From what I surmise, the purpose of .wrap is to address two specific needs:

1. To capture the current logical call context (i.e., all global async context values)
2. To, at some point in the future, use that captured context to execute a callback.

.wrap() does that by combining those two operations into a single operation. This is fine if you want to wrap a single callback, but is less convenient if you want to capture all contexts and pass it to different callbacks:

const callWithContext = AsyncContext.wrap((cb, ...args) => cb(...args));
callWithContext(f);
callWithContext(g);

vs. something like:

const context = AsyncContext.capture();

// with a `.run` method on the captured context...
context.run(f);
context.run(g);

// or with a static method
AsyncContext.runWithContext(context, f);
AsyncContext.runWithContext(context, g);

And if AsyncContext ever does become mutable (i.e., via .enterWith), you might want to be able to clone the global context so that async context mutations are local to the logical call:

const ctx = new AsyncContext();
ctx.run(1, main);

function main() {
  const captured = AsyncContext.capture();
  const copied = AsyncContext.copyContext();

  AsyncContext.runWithContext(captured, foo);
  AsyncContext.runWithContext(copied, bar);

  console.log(ctx.get()); // 2 (bar's mutation acted on a copy)
}

function foo() {
  console.log(ctx.get()); // 1
  ctx.set(2);
}

function bar() {
  console.log(ctx.get()); // 1 (due to copy)
  ctx.set(3);
}

Also, without .enterWith, you could not easily emulate something like AsyncLocal in user code:

// with AsyncLocalStorage
class AsyncLocal {
  #context = new AsyncLocalStorage();
  get value() { return this.#context.getStore(); }
  set value(v) { this.#context.enterWith(v); }
}

const loc = new AsyncLocal();
loc.value = 1;
loc.value; // 1

// with AsyncContext
class AsyncLocal {
  #context = new AsyncContext();
  get value() { return this.#context.value; }
  set value(v) { this.#context.value = v; }
  enable(cb) {
    return this.#context.run({ value: undefined }, cb);
  }
}

const loc = new AsyncLocal();
loc.value = 1; // ReferenceError

// need to establish context first
loc.enable(() => {
  loc.value = 1;
  loc.value; // 1
});

Tennent's Correspondence Principle (aka. "Tennent's Principle of Correspondence"): http://techscursion.com/2012/02/tennent-correspondence-principle.html

In plenary its often used to describe anything that changes the context of an expression such that the expression can no longer be evaluated in the same way, which is a bit of an more expanded definition than the actual principle. The issue I'm concerned with is as follows:

Lets say you start with an async generator:

class C {
async function* foo() {
  await a();
  yield b();
  await c();
}

Now I need to

Now I need to introduce an async context for b() and c():

const ctx = new AsyncContext();
class C {
  async * foo() {
    await a();
    ctx.run(value, () => {
      yield b(); // syntax error, arrow function is not a generator
      await this.c(); // syntax error, arrow function is not async
    });
  }
}

I can make that an async arrow:

const ctx = new AsyncContext();
class C {
  async * foo() {
    await a();
    await ctx.run(value, async () => {
      yield b(); // syntax error, arrow function is not a generator
      await this.c(); // ok
    });
  }
}

But that won't work with yield.

I can make it an async generator:

const ctx = new AsyncContext();
class C {
  async * foo() {
    await a();
    ctx.run(value, async function *() {
      yield b(); // ok
      await this.c(); // reference error, this is undefined
    });
  }
}

But that won't work with the this binding.

vs. an enterWith:

const ctx = new AsyncContext();
class C {
  async * foo() {
    await a();
    ctx.enterWith(value);
    try {
      yield b();
      await this.c();
    }
    finally {
      ctx.disable();
    }
  }
}

And that could be potentially even more convenient with using declarations:

const ctx = new AsyncContext();
class C {
  async * foo() {
    await a();
    using _ = ctx.enterWith(value); // assumes disposable return value...
    yield b();
    await this.c();
  }
}

A .wrap() method makes it easy to wrap a single callback in a captured execution context, but harder to reuse that context for multiple callbacks without incurring the overhead of an additional function wrapper for each callback.

A .capture() method, and an associated .run(globalContext, cb) method make it easy to reuse a context with multiple functions without incurring the overhead of a function wrapper.

Either can be composed with the other, however:

// emulate `capture` if you only have `wrap()`:

function capture() {
    return AsyncContext.wrap((cb, ...args) => cb(...args));
}

// wrap a single callback
const wrapped = AsyncContext.wrap(cb);
setImmediate(() => {
    wrapped();
});

// capture context and use with multiple functions
const context = capture();
setImmediate(() => {
    context(foo);
    context(bar);
});

// emulate `wrap` if you only have `capture()`:

// assumes `AsyncContext.capture()` produces `(cb, ...args) => any`
function wrap(cb) {
    const context = AsyncContext.capture();
    return (...args) => context(cb, ...args);
}

// wrap a single callback
const wrapped = wrap(cb);
setImmediate(() => {
    wrapped();
});

// capture context and use with multiple functions
const context = AsyncContext.capture();
setImmediate(() => {
    context(foo);
    context(bar);
});

I'd argue its a bit more obvious to a developer that they can do the following to wrap:

const context = AsyncContext.capture();
return () => context(f);

vs. the more opaque syntax needed to emulate context():

const context = AsyncContext.wrap((cb, ...args) => cb(...args));
context(f);

const suppressed = AsyncContext.wrap((cb, …args) => cb(…args));

context.run(1, () => {
  suppressed(() => {
    context.get() === undefined;
  });
});

Something like SuppressFlow() would also work well with using declarations, i.e.:

const ctx = new AsyncContext();
ctx.run(1, foo);

async function foo() {
  console.log(ctx.get()); // 1
  {
    using flow = AsyncContext.suppressFlow();
    console.log(ctx.get()); // undefined
  }
  console.log(ctx.get()); // 1
}

I'd really like to be able to have a simple AsyncLocal primitive, or even an @AsyncLocal decorator (not unlike a potential @ThreadLocal decorator that could someday exist for shared structs):

class HttpServer {
  @AsyncLocal
  accessor currentRequest;
  ...
}

But that wouldn't work without the ability attach an async context to the current execution context without needing to go through a .run call.

If we were to support mutable contexts, it would either

• allow one function to replace the context for sibling calls (which I think is what Mark is objecting to)
• push a context onto the stack (but then it's not obvious where we would pop with deep integration with the host's actual call stack)

• allow one function to replace the context for sibling calls (which I think is what Mark is objecting to)

In a mutable context world, you would use .copyContext() to clone the global context to avoid mutations in siblings.

So based on that, here's a rough example:

const local = new AsyncLocal();
local.value = 1;
await foo(); 

// mutation of local doesn't change the snapshot seen by the `await` in foo
local.value = 2; 

await bar();

function foo() {
  console.log(local.value); // 1

  // takes snapshot of current async execution context
  // restores snapshot when `await` resumes
  await Promise.resolve(); 

  console.log(local.value); // 1
}

function bar() {
  console.log(local.value); // 2

  // takes snapshot of current async execution context
  // restores snapshot when `await` resumes
  await Promise.resolve(); 

  console.log(local.value); // 2
}

So in .NET, you can do:

LogicalCallContext.SetData("foo", 1);
var context = ExecutionContext.Capture();

ExecutionContext.Run(context, () => {
  Console.WriteLine(LogicalCallContext.GetData("foo")); // 1
  LogicalCallContext.SetData("foo", 2);
});

Console.WriteLine(LogicalCallContext.GetData("foo")); // 2

Since the context is mutable.

Since AsyncLocal does snapshotting, its very useful for fork/join operations like this:

const local = new AsyncLocal();
local.value = 1;
await Promise.all(operations.map(async (op) => {
  await op.execute(); // where op.execute reads or writes local.value
}));

Where each op.execute() gets a copy of the state, such that any state mutations don't affect other parallel tasks.

I'll simplify my thoughts:

• new AsyncContext() is great.
• AsyncContext.prototype.run() is great.
• AsyncContext.prototype.get() is great.
• The capability introduced by AsyncContext.wrap() is necessary, but has some ergonomics issues I have concerns about.
• The minimal API for AsyncContext means some other useful primitives like an AsyncLocal can't be modeled in userland. However, its likely it would need to be introduced as a built-in anyways if we wanted anything like snapshotting capabilities such that the value is associated with control flow.
• A way to suppress and restore the global context is necessary, and I'm not convinced the approach of a "call to AsyncContext.wrap() at the top level" is sufficiently ergonomic.

Imagine the current execution context as an ImmutableMap. Adding or replacing entries in the map copies the map.
So:

const ctx1 = new AsyncContext();
const ctx2 = new AsyncContext();
const ctx3 = new AsyncContext();

// execution context: {}
ctx1.run("a", () => {
  // execution context: { [ctx1]: "a" }
  ctx2.run("b", () => {
    // execution context: { [ctx1]: "a", [ctx2]: "b" }
  });
  ctx3.run("c", () => {
    // execution context: { [ctx1]: "a", [ctx3]: "c" }
  });
});

let __storage__ = new Map();
class AsyncContext {
  // Pushes a new state, and pops it when done
  run(val, cb) {
    let prev = __storage__;
    try {
      this.set(val);
      return cb();
    } finally {
      __storage__ = prev;
    }
  }

  // Mutates the current state
  set(val) {
    const next = new Map(__storage__);
    next.set(this, val);
    __storage__ = next;
  }
}

Imagine there was an internal ExecutionContext object that had an immutable dictionary of AsyncContext->value entries. What an AsyncLocal would need is a second immutable dictionary on that object:

// internal implementation details...
class ExecutionContext {
  #asyncContextValues;
  #asyncLocalValues;
  constructor(asyncContextValues, asyncLocalValues) {
    this.#asyncContextValues = asyncContextValues;
    this.#asyncLocalValues = asyncLocalValues;
  }

  static get current() {
    return %GetCurrentExecutionContext();
  }

  static set current(value) {
    %SetCurrentExecutionContext(value);
  }

  static create() {
    return new ExecutionContext(new ImmutableMap(), new ImmutableMap());
  }

  copy() {
    return new ExecutionContext(this.#asyncContextValues, this.#asyncLocalValues);
  }

  getContext(key) {
    return this.#asyncContextValues.get(key);
  }

  getLocal(key) {
    return this.#asyncLocalValues.get(key);
  }

  setLocal(key, value) {
    this.#asyncLocalValues = this.#asyncLocalValues.set(key, value);
  }

  runWithContext(asyncContext, value, callback, args) {
    const context = new ExecutionContext(this.#asyncContextValues.set(asyncContext, value), this.#asyncLocalValues);
    return %RunWithContext(context, callback, args);
  }
}

// global scope would have a root context
ExecutionContext.current = ExecutionContext.create();

// public
class AsyncContext {
  run(value, callback, ...args) {
    return ExecutionContext.current.runWithContext(this, value, callback, args);
  }

  get() {
    return ExecutionContext.current.getContext(this);
  }

  static wrap(cb) {
    const captured = ExecutionContext.current;
    return (...args) => {
      const current = ExecutionContext.current;
      try {
        ExecutionContext.captured = captured;
        return cb(...args);
      }
      finally {
        ExecutionContext.current = current;
      }
    }
  }
}

// public
class AsyncLocal {
  get value() { return ExecutionContext.current.getLocal(this); }
  set value(v) { ExecutionContext.current.setLocal(this, v); }
}

// and `await f()` is translated to something like:

const result = Promise.resolve(f());
result.[[ExecutionContext]] = ExecutionContext.current.copy(); // used for continuations
await result;

An await would just preserve the pointer to the AsyncContext entries, but get an independent reference to the AsyncLocal entries. Mutating the asyncLocalValues reference wouldn't affect snapshots taken during await.