GitHub - tc39/proposal-async-context: Async Context for JavaScript (original) (raw)

Async Context for JavaScript

Status: Stage 2

Champions:

Discuss with the group and join the bi-weekly via #tc39-async-contextmatrix room (Matrix Guide).

Motivation

When writing synchronous JavaScript code, a reasonable expectation from developers is that values are consistently available over the life of the synchronous execution. These values may be passed explicitly (i.e., as parameters to the function or some nested function, or as a closed over variable), or implicitly (extracted from the call stack, e.g., outside the scope as a external object that the function or nested function has access to).

function program() { const value = { key: 123 };

// Explicitly pass the value to function via parameters. // The value is available for the full execution of the function. explicit(value);

// Explicitly captured by the closure. // The value is available for as long as the closure exists. const closure = () => { assert.equal(value.key, 123); };

// Implicitly propagated via shared reference to an external variable. // The value is available as long as the shared reference is set. // In this case, for as long as the synchronous execution of the // try-finally code. try { shared = value; implicit(); } finally { shared = undefined; } }

function explicit(value) { assert.equal(value.key, 123); }

let shared; function implicit() { assert.equal(shared.key, 123); }

program();

Async/await syntax improved in ergonomics of writing asynchronous JS. It allows developers to think of asynchronous code in terms of synchronous code. The behavior of the event loop executing the code remains the same as in a promise chain. However, passing code through the event loop loses implicit information from the call site because we end up replacing the call stack. In the case of async/await syntax, the loss of implicit call site information becomes invisible due to the visual similarity to synchronous code -- the only indicator of a barrier is the await keyword. As a result, code that "just works" in synchronous JS has unexpected behavior in asynchronous JS while appearing almost exactly the same.

function program() { const value = { key: 123 };

// Implicitly propagated via shared reference to an external variable. // The value is only available only for the synchronous execution of // the try-finally code. try { shared = value; implicit(); } finally { shared = undefined; } }

let shared; async function implicit() { // The shared reference is still set to the correct value. assert.equal(shared.key, 123);

await 1;

// After awaiting, the shared reference has been reset to undefined. // We've lost access to our original value. assert.throws(() => { assert.equal(shared.key, 123); }); }

program();

The above problem existed already in promise callback-style code, but the introduction of async/await syntax has aggravated it by making the stack replacement almost undetectable. This problem is not generally solvable with user land code alone. For instance, if the call stack has already been replaced by the time the function is called, that function will never have a chance to capture the shared reference.

function program() { const value = { key: 123 };

// Implicitly propagated via shared reference to an external variable. // The value is only available only for the synchronous execution of // the try-finally code. try { shared = value; setTimeout(implicit, 0); } finally { shared = undefined; } }

let shared; function implicit() { // By the time this code is executed, the shared reference has already // been reset. There is no way for implicit to solve this because // because the bug is caused (accidentally) by the program function. assert.throws(() => { assert.equal(shared.key, 123); }); }

program();

Furthermore, the async/await syntax bypasses the userland Promises and makes it impossible for existing tools like Zone.js thatinstrumentsthe Promise to work with it without transpilation.

This proposal introduces a general mechanism by which lost implicit call site information can be captured and used across transitions through the event loop, while allowing the developer to write async code largely as they do in cases without implicit information. The goal is to reduce the mental burden currently required for special handling async code in such cases.

Summary

This proposal introduces APIs to propagate a value through asynchronous code, such as a promise continuation or async callbacks.

Compared to the Prior Arts, this proposal identifies the following features as non-goals:

  1. Async tasks scheduling and interception.
  2. Error handling & bubbling through async stacks.

Proposed Solution

AsyncContext is designed as a value store for context propagation across logically-connected sync/async code execution.

namespace AsyncContext { class Variable { constructor(options: AsyncVariableOptions); get name(): string; get(): T | undefined; run(value: T, fn: (...args: any[])=> R, ...args: any[]): R; } interface AsyncVariableOptions { name?: string; defaultValue?: T; }

class Snapshot { constructor(); run(fn: (...args: any[]) => R, ...args: any[]): R; static wrap<T, R>(fn: (this: T, ...args: any[]) => R): (this: T, ...args: any[]) => R; } }

AsyncContext.Variable

Variable is a container for a value that is associated with the current execution flow. The value is propagated through async execution flows, and can be snapshot and restored with Snapshot.

Variable.prototype.run() and Variable.prototype.get() sets and gets the current value of an async execution flow.

const asyncVar = new AsyncContext.Variable();

// Sets the current value to 'top', and executes the main function. asyncVar.run("top", main);

function main() { // AsyncContext.Variable is maintained through other platform queueing. setTimeout(() => { console.log(asyncVar.get()); // => 'top'

asyncVar.run("A", () => {
  console.log(asyncVar.get()); // => 'A'

  setTimeout(() => {
    console.log(asyncVar.get()); // => 'A'
  }, randomTimeout());
});

}, randomTimeout());

// AsyncContext.Variable runs can be nested. asyncVar.run("B", () => { console.log(asyncVar.get()); // => 'B'

setTimeout(() => {
  console.log(asyncVar.get()); // => 'B'
}, randomTimeout());

});

// AsyncContext.Variable was restored after the previous run. console.log(asyncVar.get()); // => 'top' }

function randomTimeout() { return Math.random() * 1000; }

Tip

There have been long detailed discussions on the dynamic scoping ofAsyncContext.Variable. Checkout SCOPING.md for more details.

Hosts are expected to use the infrastructure in this proposal to allow tracking not only asynchronous callstacks, but other ways to schedule jobs on the event loop (such as setTimeout) to maximize the value of these use cases. We describe the needed integration with web platform APIs in the web integration document.

A detailed example of use cases can be found in theUse Cases and Frameworks documents.

AsyncContext.Snapshot

AsyncContext.Snapshot is an advanced API that allows opaquely capturing the current values of all Variables, and execute a function at a later time as if those values were still the current values.

Snapshot is useful for implementing APIs that logically "schedule" a callback, so the callback will be called with the context that it logically belongs to, regardless of the context under which it actually runs:

let queue = [];

export function enqueueCallback(cb: () => void) { // Each callback is stored with the context at which it was enqueued. const snapshot = new AsyncContext.Snapshot(); queue.push(() => snapshot.run(cb)); }

runWhenIdle(() => { // All callbacks in the queue would be run with the current context if they // hadn't been wrapped. for (const cb of queue) { cb(); } queue = []; });

Most web developers, even those interacting with AsyncContext.Variable directly, are not expected to ever need to reach out to AsyncContext.Snapshot.

Tip

A detailed explanation of why AsyncContext.Snapshot is a requirement can be found in SNAPSHOT.md.

Note that even with AsyncContext.Snapshot, you can only access the value associated with a AsyncContext.Variable instance if you have access to that instance. There is no way to iterate through the entries or the AsyncContext.Variables in the snapshot.

const asyncVar = new AsyncContext.Variable();

let snapshot asyncVar.run("A", () => { // Captures the state of all AsyncContext.Variable's at this moment. snapshot = new AsyncContext.Snapshot(); });

asyncVar.run("B", () => { console.log(asyncVar.get()); // => 'B'

// The snapshot will restore all AsyncContext.Variable to their snapshot // state and invoke the wrapped function. We pass a function which it will // invoke. snapshot.run(() => { // Despite being lexically nested inside 'B', the snapshot restored us to // to the snapshot 'A' state. console.log(asyncVar.get()); // => 'A' }); });

AsyncContext.Snapshot.wrap

AsyncContext.Snapshot.wrap is a helper which captures the current values of allVariables and returns a wrapped function. When invoked, this wrapped function restores the state of all Variables and executes the inner function.

const asyncVar = new AsyncContext.Variable();

function fn() { return asyncVar.get(); }

let wrappedFn; asyncVar.run("A", () => { // Captures the state of all AsyncContext.Variable's at this moment, returning // wrapped closure that restores that state. wrappedFn = AsyncContext.Snapshot.wrap(fn) });

console.log(fn()); // => undefined console.log(wrappedFn()); // => 'A'

You can think of this as a more convenient version of Snapshot, where only a single function needs to be wrapped. It also serves as a convenient way for consumers of libraries that don't support AsyncContext to ensure that function is executed in the correct execution context.

// User code that uses a legacy library const asyncVar = new AsyncContext.Variable();

function fn() { return asyncVar.get(); }

asyncVar.run("A", () => { defer(fn); // setTimeout schedules during "A" context. }) asyncVar.run("B", () => { defer(fn); // setTimeout is not called, fn will still see "A" context. }) asyncVar.run("C", () => { const wrapped = AsyncContext.Snapshot.wrap(fn); defer(wrapped); // wrapped callback captures "C" context. })

// Some legacy library that queues multiple callbacks per macrotick // Because the setTimeout is called a single time per queue batch, // all callbacks will be invoked with that context regardless of // whatever context is active during the call to defer. const queue = []; function defer(callback) { if (queue.length === 0) setTimeout(processQueue, 1); queue.push(callback); } function processQueue() { for (const cb of queue) { cb(); } queue.length = 0; }

Examples

Determine the initiator of a task

Application monitoring tools like OpenTelemetry save their tracing spans in theAsyncContext.Variable and retrieve the span when they need to determine what started this chain of interaction.

These libraries can not intrude the developer APIs for seamless monitoring. The tracing span doesn't need to be manually passing around by usercodes.

// tracer.js

const asyncVar = new AsyncContext.Variable(); export function run(cb) { // (a) const span = { startTime: Date.now(), traceId: randomUUID(), spanId: randomUUID(), }; asyncVar.run(span, cb); }

export function end() { // (b) const span = asyncVar.get(); span?.endTime = Date.now(); }

// my-app.js import * as tracer from "./tracer.js";

button.onclick = (e) => { // (1) tracer.run(() => { fetch("https://example.com").then((res) => { // (2)

  return processBody(res.body).then((data) => {
    // (3)

    const dialog = html`<dialog>
      Here's some cool data: ${data} <button>OK, cool</button>
    </dialog>`;
    dialog.show();

    tracer.end();
  });
});

}); };

In the example above, run and end don't share same lexical scope with actual code functions, and they are capable of async reentrance thus capable of concurrent multi-tracking.

Transitive task attribution

User tasks can be scheduled with attributions. With AsyncContext.Variable, task attributions are propagated in the async task flow and sub-tasks can be scheduled with the same priority.

const scheduler = { asyncVar: new AsyncContext.Variable(), postTask(task, options) { // In practice, the task execution may be deferred. // Here we simply run the task immediately. return this.asyncVar.run({ priority: options.priority }, task); }, currentTask() { return this.asyncVar.get() ?? { priority: "default" }; }, };

const res = await scheduler.postTask(task, { priority: "background" }); console.log(res);

async function task() { // Fetch remains background priority by referring to scheduler.currentTask(). const resp = await fetch("/hello"); const text = await resp.text();

scheduler.currentTask(); // => { priority: 'background' } return doStuffs(text); }

async function doStuffs(text) { // Some async calculation... return text; }

User-land queues

User-land queues can be implemented with AsyncContext.Snapshot to propagate the values of all AsyncContext.Variables without access to any of them. This allows the user-land queue to be implemented in a way that is decoupled from consumers of AsyncContext.Variable.

// The scheduler doesn't access to any AsyncContext.Variable. const scheduler = { queue: [], postTask(task) { // Each callback is stored with the context at which it was enqueued. const snapshot = new AsyncContext.Snapshot(); queue.push(() => snapshot.run(task)); }, runWhenIdle() { // All callbacks in the queue would be run with the current context if they // hadn't been wrapped. for (const cb of this.queue) { cb(); } this.queue = []; } };

function userAction() { scheduler.postTask(function userTask() { console.log(traceContext.get()); }); }

// Tracing libraries can use AsyncContext.Variable to store tracing contexts. const traceContext = new AsyncContext.Variable(); traceContext.run("trace-id-a", userAction); traceContext.run("trace-id-b", userAction);

scheduler.runWhenIdle(); // The userTask will be run with the trace context it was enqueued with. // => 'trace-id-a' // => 'trace-id-b'

FAQ

Are there any prior arts?

Please checkout prior-arts.md for more details.

Why take a function in run?

The Variable.prototype.run and Snapshot.prototype.run methods take a function to execute because it ensures async context variables will always contain consistent values in a given execution flow. Any modification must be taken in a sub-graph of an async execution flow, and can not affect their parent or sibling scopes.

const asyncVar = new AsyncContext.Variable(); asyncVar.run("A", async () => { asyncVar.get(); // => 'A'

// ...arbitrary synchronous codes. // ...or await-ed asynchronous calls.

// The value can not be modified at this point. asyncVar.get(); // => 'A' });

This increases the integrity of async context variables, and makes them easier to reason about where a value of an async variable comes from.

How does AsyncContext interact with built-in schedulers?

Any time a scheduler (such as setTimeout, addEventListener, orPromise.prototype.then) runs a user-provided callback, it must choose which snapshot to run it in. While userland schedulers are free to make any choice here, this proposal adopts a convention that built-in schedulers will always run callbacks in the snapshot that was active when the callback was passed to the built-in (i.e. at "registration time"). This is equivalent to what would happen if the user explicitly called AsyncContext.Snapshot.wrap on all callbacks before passing them.

This choice is the most consistent with the function-scoped structure that results from run taking a function, and is also the most clearly-defined option among the possible alternatives. For instance, many event listeners may be initiated either programmatically or through user interaction; in the former case there may be a more recently relevant snapshot available, but it's inconsistent across different types of events or even different instances of the same type of event. On the other hand, passing a callback to a built-in function happens at a very clearly defined time.

Another advantage of registration-time snapshotting is that it is expected to reduce the amount of intervention required to opt out of the default snapshot. Because AsyncContext is a subtle feature, it's not reasonable to expect every web developer to build a complete understanding of its nuances. Moreover, it's important that library users should not need to be aware of the nature of the variables that library implementations are implicitly passing around. It would be harmful if common practices emerged that developers felt they needed to wrap their callbacks before passing them anywhere. The primary means to have a function run in a different snapshot is to call Snapshot.wrap, but this will be idempotent when passing callbacks to built-ins, making it both less likely for this common practice to begin in the first place, and also less harmful when it does happen unnecessarily.

What if I need access to the snapshot from a more recent cause?

The downside to registration-time snapshotting is that it's impossible to opt_out_ of the snapshot restoration to access whatever the snapshot would have been before it was restored. Use cases where this snapshot is more relevant include

As explained above, the alternative snapshot choices are much more specific to the individual use case, but they can be made available through side channels. For instance, web specifications could include that certain event types will expose an originSnapshot property (actual name to be determined) on the event object containing the active AsyncContext.Snapshot from a specific point in time that initiated the event.

Providing these additional snapshots through side channels has several benefits over switching to them by default, or via a generalized "previous snapshot" mechanism: