Alternative API Proposal

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.

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.

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' })
})

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.

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

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.

Try Inverted API

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);
});

@jasnell

@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.

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.

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.
  })
}

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

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.

@jridgewell

Cc. @jridgewell

Navigation Menu

Repository navigation

Alternative API Proposal #105

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Alternative API Proposal #105

Description

Activity

Qard commented on Oct 10, 2024

martinheidegger commented on Oct 10, 2024

Qard commented on Oct 10, 2024

martinheidegger commented on Oct 11, 2024

martinheidegger commented on Oct 11, 2024

jasnell commented on Dec 3, 2024

martinheidegger commented on Dec 3, 2024

Flarna commented on Dec 3, 2024

martinheidegger commented on Dec 3, 2024

jasnell commented on Dec 3, 2024

martinheidegger commented on Dec 3, 2024

martinheidegger commented on Nov 15, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions