Status: Stage 2
Champions:
- Andreu Botella (@andreubotella)
- Chengzhong Wu (@legendecas)
- Justin Ridgewell (@jridgewell)
Discuss with the group and join the bi-weekly via #tc39-async-context matrix room (Matrix Guide).
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 that
instruments
the 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.
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:
- Async tasks scheduling and interception.
- Error handling & bubbling through async stacks.
AsyncContext is designed as a value store for context propagation across
logically-connected sync/async code execution.
namespace AsyncContext {
class Variable<T> {
constructor(options: AsyncVariableOptions<T>);
get name(): string;
get(): T | undefined;
run<R>(value: T, fn: (...args: any[])=> R, ...args: any[]): R;
}
interface AsyncVariableOptions<T> {
name?: string;
defaultValue?: T;
}
class Snapshot {
constructor();
run<R>(fn: (...args: any[]) => R, ...args: any[]): R;
static wrap<T, R>(fn: (this: T, ...args: any[]) => R): (this: T, ...args: any[]) => R;
}
}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;
}Note: There are controversial thought on the dynamic scoping and
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.
A detailed example of use cases can be found in the Use cases document.
Snapshot allows you to opaquely capture the current values of all Variables
and execute a function at a later time as if those values were still the
current values (a snapshot and restore).
Note that even with Snapshot, you can only access the value associated with
a Variable instance if you have access to that instance.
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'
});
});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 = [];
});A detailed explanation of why AsyncContext.Snapshot is a requirement can be
found in SNAPSHOT.md.
AsyncContext.Snapshot.wrap is a helper which captures the current values of all
Variables 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;
}Application monitoring tools like OpenTelemetry save their tracing spans in the
AsyncContext.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.
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 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'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.
Any time a scheduler (such as setTimeout, addEventListener, or
Promise.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.
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
- programmatically-dispatched events whose handlers are installed at application initialization time
- unhandled rejection handlers are a specific example of the above
- tracing execution flow, where one task "follows from" a sibling task
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:
- different types of schedulers may have a variety of potential origination points, whose scope can be matched precisely with a well-specified side channel
- access via a known side channel avoids loss of idempotency when callbacks are wrapped multiple times (whereas a "previous snapshot" would becomes much less clear)
- no single wrapper method for developers to build bad habits around
Zones proposed a Zone object, which has the following API:
class Zone {
constructor({ name, parent });
name;
get parent();
fork({ name });
run(callback);
wrap(callback);
static get current();
}The concept of the current zone, reified as Zone.current, is crucial. Both
run and wrap are designed to manage running the current zone:
z.run(callback)will set the current zone tozfor the duration ofcallback, resetting it to its previous value afterward. This is how you "enter" a zone.z.wrap(callback)produces a new function that essentially performsz.run(callback)(passing along arguments and this, of course).
The current zone is the async context that propagates with all our operations.
In our above example, sites (1) through (6) would all have the same value of
Zone.current. If a developer had done something like:
const loadZone = Zone.current.fork({ name: "loading zone" });
window.onload = loadZone.wrap(e => { ... });then at all those sites, Zone.current would be equal to loadZone.
Domain's global central active domain can be consumed by multiple endpoints and
be exchanged in any time with synchronous operation (domain.enter()). Since it
is possible that some third party module changed active domain on the fly and
application owner may unaware of such change, this can introduce unexpected
implicit behavior and made domain diagnosis hard.
Check out Domain Module Postmortem for more details.
This is what the proposal evolved from. async_hooks in Node.js enabled async
resources tracking for APM vendors. On which Node.js also implemented
AsyncLocalStorage.
Frameworks can schedule tasks with their own userland queues. In such case, the stack trace originated from the framework scheduling logic tells only part of the story.
Error: Call stack
at someTask (example.js)
at loop (framework.js)The Chrome Async Stack Tagging API introduces a new console method named
console.createTask(). The API signature is as follows:
interface Console {
createTask(name: string): Task;
}
interface Task {
run<T>(f: () => T): T;
}console.createTask() snapshots the call stack into a Task record. And each
Task.run() restores the saved call stack and append it to newly generated call
stacks.
Error: Call stack
at someTask (example.js)
at loop (framework.js) // <- Task.run
at async someTask // <- Async stack appended
at schedule (framework.js) // <- console.createTask
at businessLogic (example.js)