Readd AsyncContext.Snapshot.wrap() helper (#68)

* Add back AsyncContext.wrap()

* Update readme

* Add Wrapped function exotic objects section

* Update wrap length

* Add Realm to wrapper

* Move to Snapshot, simplify spec

* Add "wrapped" to function name

* Explicitly support rest params in Abstract Closures

* Remove CBF change, ecma262 will be updated

* Update example

* Update spec.html

Co-authored-by: Andreu Botella <[email protected]>

* Move to "Properties of X Constructor" clause

---------

Co-authored-by: Andreu Botella <[email protected]>

Author: jridgewell

README.md

@@ -163,23 +163,19 @@ logically-connected sync/async code execution.
 namespace AsyncContext {
   class Variable<T> {
     constructor(options: AsyncVariableOptions<T>);
-
     get name(): string;
-
     run<R>(value: T, fn: (...args: any[])=> R, ...args: any[]): R;
-
     get(): T | undefined;
   }
-
   interface AsyncVariableOptions<T> {
     name?: string;
     defaultValue?: T;
   }
 
   class Snapshot {
     constructor();
-
     run<R>(fn: (...args: any[]) => R, ...args: any[]): R;
+    wrap<T, R>(fn: (this: T, ...args: any[]) => R): (this: T, ...args: any[]) => R;
   }
 }
 ```
@@ -299,6 +295,74 @@ runWhenIdle(() => {
 A detailed explanation of why `AsyncContext.Snapshot` is a requirement can be
 found in [SNAPSHOT.md](./SNAPSHOT.md).
 
+### `AsyncContext.Snapshot.wrap`
+
+`AsyncContext.Snapshot.wrap` is a helper which captures the current values of all
+`Variable`s and returns a wrapped function. When invoked, this wrapped function
+restores the state of all `Variable`s and executes the inner function.
+
+```typescript
+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.
+
+```typescript
+// 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

spec.html

@@ -908,6 +908,28 @@ <h1>AsyncContext.Snapshot.prototype</h1>
         <p>The initial value of `AsyncContext.Snapshot.prototype` is the AsyncContext.Snapshot prototype object.</p>
         <p>This property has the attributes { [[Writable]]: *false*, [[Enumerable]]: *false*, [[Configurable]]: *false* }.</p>
       </emu-clause>
+
+      <emu-clause id="sec-asynccontext-snapshot.wrap">
+        <h1>AsyncContext.Snapshot.wrap ( _fn_ )</h1>
+        <p>This function returns a new function which restores the current value of all AsyncContext.Variable values when being invoked.</p>
+
+        <emu-alg>
+          1. If IsCallable(_fn_) is *false*, throw a *TypeError* exception.
+          1. Let _snapshot_ be AsyncContextSnapshot().
+          1. Let _closure_ be a new Abstract Closure with parameters (..._args_) that captures _fn_ and _snapshot_ and performs the following steps when called:
+            1. Let _thisArgument_ be the *this* value.
+            1. Let _previousContextMapping_ be AsyncContextSwap(_snapshot_).
+            1. Let _result_ be Completion(Call(_fn_, _thisArgument_, _args_)).
+            1. AsyncContextSwap(_previousContextMapping_).
+            1. Return _result_.
+          1. Let _length_ be ? LengthOfArrayLike(_fn_).
+          1. Let _name_ be ? Get(_fn_, *"name"*).
+          1. If _name_ is not a String, set _name_ to the empty String.
+          1. Let _realm_ be the current Realm Record.
+          1. Let _prototype_ be _realm_.[[Intrinsics]].[[%Function.prototype%]].
+          1. Return CreateBuiltinFunction(_closure_, _length_, _name_, &laquo; &raquo;, _realm_, _prototype_, *"wrapped"*).
+        </emu-alg>
+      </emu-clause>
     </emu-clause>
 
     <emu-clause id="sec-properties-of-the-asynccontext-snapshot-prototype-object">