Alternative API Proposal

[martinheidegger]

With two variables to set at the same time the code seems to easily become very unwieldy.

const a = AsyncContext.Variable()
const b = AsyncContext.Variable()

a.run('x', async () => {
   b.run('y', async () => {
      console.log([a.get(), b.get()])
   }
})

in Python if you use a context, you can specify more than one value at a time. However, since the run function is defined on the Variable, there is no easy way to work around this.

I am wondering if a different, inverted API couldn't prove both more flexible and better readable?

const a = Symbol('a')
const b = Symbol('b')
const { run, get } = AsyncContext

run({ [a]: 'x', [b]: 'y' }, async () => {
    console.log([get(a), get(b)])
})

Note: this proposal could possible address the issue in #76 by allowing the internals to use a Object instead of a Map to store.

[Qard]

If we detach the scoping mechanism from the setting mechanism, as I have described in other previous conversations about AsyncContext, we would not have this problem.

const a = new AsyncContext()
const b = new AsyncContext()

AsyncContext.scope(() => {
  a.set('foo')
  b.set('bar')
})

This is essentially what already happens internally anyway that it has to first create and enter a scope before it can set the value, but the API as it is designed at present requires that every set comes with a new scope rather than being able to share or reuse scopes. The current design also results in rather poor ergonomics for async-await code, which this design resolves too.

[martinheidegger]

Thank you for highlight the other discussions. My problem with the scope example would be that the context variables are assumed to be set within the "scope" at any given time causing possibly confusing behavior:

const a = new AsyncContext.Variable()

function test() {
  if (a.get() === 'foo') {
     //...
  }
}

function bar() {
  a.set('baz')
}

AsyncContext.scope(() => {
  a.set('foo')
  test()
  bar()
  test()
})

However, I don't try to weigh in on the single-swoop or detached definition approach here and rather mean try to reduce the API surface and at the same time make declaration easier. For the detached scope definition I could analogously imagine:

const a = Symbol('a')
const b = Symbol('b')

AsyncContext.scope(() => {
   AsyncContext.set({ [a]: 'foo', [b]: 'bar' })
})

[Qard]

You can avoid that issue by just wrapping the calls in more scopes, if you want to contain their changes. It's somewhat correct that linear code like that would behave that way though--you can think of context as being a lot like a global, but only within a particular scope. Changes will appear to any related code, so long as it originates in that scope.

[martinheidegger]

Note: I updated the API proposal in the initial post to use Symbols instead of a Map

[martinheidegger]

Extending the proposal I would also think that it might make sense to add it as function to Snapshot

const asyncVar = Symbol('asyncVar')
const snapshot = AsyncContext.Snapshot()
let value;
value = snapshot.run(() => AsyncContext.get(asyncVar))
// Equal to the line above
value = snapshot.get(asyncVar)

that way a unnecessary workaround could be avoided.

[jasnell]

For cases where someone might use multiple like that, it would likely just be cleaner to use a single AsyncContext.Variable with a compound value... so instead of...

const a = AsyncContext.Variable()
const b = AsyncContext.Variable()

a.run('x', async () => {
   b.run('y', async () => {
      console.log([a.get(), b.get()])
   }
})

It would be...

const var = AsyncContext.Variable();

var.run({ a: 'x', b: 'y' }, () => {
  const { a, b } = var.get();
  console.log(a, b);
});

[martinheidegger]

@jasnell that is under the assumption that multiple can be grouped, I would assume that they are from different subsystems to be configured at the same time.

[Flarna]

If you combine two independent stores into one they always propagate together and are activated/deactivated together. This might be not intended in all cases.
Mutating a part of this combined store to reflect this difference results in side effects that different propagation chains are effected as well.

But I wonder about the use case to have more AsyncContext.Variable() instances in hand from different subsystems. I would expect these instances are internals of these subsystem and should not leak to a global place.

[martinheidegger]

With the proposed API it is up to the user to define multiple at once or a single one. You can nest it like the current API.

The variables can be private but they can also be exposed and likely will be exposed by some libraries. Setting the values for the libraries in an overarching context.

I imagine something like:

import { Request, Response } from 'server/symbol'
import { Trace } from 'system-logger/symbol'

function handleRequest(req, res) {
  const controller = new AbortController()
  // etc.
  AsyncContext.run({
     [Request]: req,
     [Response]: res,
     [Trace]: crypto.randomUUID(),
     [AbortController.context]: controller.signal
  }, async () => {
     /// etc.
  })
}

[jasnell]

If we're going for something like that then I would almost prefer a Map-like model for AsyncContext... perhaps something like...

const as1 = AsyncContext.Variable();
const as2 = AsyncContext.Variable();
const ctx = AsyncContext.Map();
ctx.set(as1, 1);  // set the values explicitly
ctx.set(as2, 2);

const snapshot = ctx.snapshot();

Then the snapshot can be used as any other AsyncContext.Snapshot

Essentially, the AsyncContext.Map would allow fine grained control over what context is actually propagated in the snapshot rather than taking everything in the current

[martinheidegger]

The main reason why I opened this proposal is for readability reasons, to make it more natural to use and to reduce the amount of specification introduced. Adding a Map to the AsyncContext would look something like this:

import { Request, Response } from 'server/symbol'
import { Trace } from 'system-logger/symbol'

function handleRequest(req, res) {
  const controller = new AbortController()
  // etc.
  const ctx = new AsyncContext.Map([ // assuming the constructor is somewhat like the Map constructor
    [Request, req],
    [Response, res],
    [Trace, crypto.randomUUID()],
    [AbortController.context, controller.signal],
  ])
  ctx.snapshot().run(async () => {
     // etc.
  })
}

To me this is a lot more uncomfortable to write and deal with and overall the complexity feels a lot higher as well.

Sidenote: The snapshot() is probably superfluous.

[martinheidegger]

Cc. @jridgewell