Skip to content

Normative: Add Array.fromAsync #3581

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 11 commits into
base: add-builtin-async-function-objects
Choose a base branch
from
Open

Normative: Add Array.fromAsync #3581

Changes from 5 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
a545cb8
Editorial: support built-in async functions
michaelficarra Oct 24, 2022
b4c45be
Normative: Add Array.fromAsync
js-choi May 1, 2025
1b2d5bb
Editorial: Make Array.fromAsync's esid lowercase
js-choi May 21, 2025
09d4b3b
accept review feedback
michaelficarra May 22, 2025
09fe8d1
Editorial: Change Array.from/fromAsync from "method"s to "function"s
js-choi May 22, 2025
b4438b9
Editorial: Change Array.fromAsync asyncItems note
js-choi May 28, 2025
a55e882
Editorial: Simplify branching
js-choi May 28, 2025
fc28be7
Editorial: Explicitly mark Array.fromAsync as async; rename asyncItem…
js-choi May 28, 2025
680ba54
Editorial: Fix typo in Array.fromAsync behavior
js-choi May 28, 2025
8462af1
Editorial: Fix indentation formatting in Array.fromAsync behavior
js-choi May 28, 2025
aa83416
Merge branch 'add-builtin-async-function-objects' into add-array-from…
js-choi May 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
152 changes: 148 additions & 4 deletions spec.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7393,6 +7393,20 @@ <h1>
</emu-alg>
</emu-clause>

<emu-clause id="sec-ifabruptcloseasynciterator" aoid="IfAbruptCloseAsyncIterator">
<h1>IfAbruptCloseAsyncIterator ( _value_, _iteratorRecord_ )</h1>
<p>IfAbruptCloseAsyncIterator is a shorthand for a sequence of algorithm steps that use an Iterator Record. An algorithm step of the form:</p>
<emu-alg>
1. IfAbruptCloseAsyncIterator(_value_, _iteratorRecord_).
</emu-alg>
<p>means the same thing as:</p>
<emu-alg>
1. Assert: _value_ is a Completion Record.
1. If _value_ is an abrupt completion, return ? AsyncIteratorClose(_iteratorRecord_, _value_).
1. Else, set _value_ to ! _value_.
</emu-alg>
</emu-clause>

<emu-clause id="sec-createiterresultobject" type="abstract operation">
<h1>
CreateIteratorResultObject (
Expand Down Expand Up @@ -13991,8 +14005,8 @@ <h1>Built-in Function Objects</h1>
<li>[[InitialName]], a String that is the initial name of the function. It is used by <emu-xref href="#sec-function.prototype.tostring"></emu-xref>.</li>
</ul>
<p>The initial value of a built-in function object's [[Prototype]] internal slot is %Function.prototype%, unless otherwise specified.</p>
<p>A built-in function object must have a [[Call]] internal method that conforms to the definition in <emu-xref href="#sec-built-in-function-objects-call-thisargument-argumentslist"></emu-xref>.</p>
<p>A built-in function object has a [[Construct]] internal method if and only if it is described as a “constructor”, or some algorithm in this specification explicitly sets its [[Construct]] internal method. Such a [[Construct]] internal method must conform to the definition in <emu-xref href="#sec-built-in-function-objects-construct-argumentslist-newtarget"></emu-xref>.</p>
<p>A built-in function object must have a [[Call]] internal method that, unless otherwise specified, conforms to the definition in <emu-xref href="#sec-built-in-function-objects-call-thisargument-argumentslist"></emu-xref>.</p>
<p>A built-in function object has a [[Construct]] internal method if and only if it is described as a “constructor”, or some algorithm in this specification explicitly sets its [[Construct]] internal method. Unless otherwise specified, such a [[Construct]] internal method must conform to the definition in <emu-xref href="#sec-built-in-function-objects-construct-argumentslist-newtarget"></emu-xref>.</p>
<p>An implementation may provide additional built-in function objects that are not defined in this specification.</p>

<emu-clause id="sec-built-in-function-objects-call-thisargument-argumentslist" type="internal method">
Expand Down Expand Up @@ -14081,7 +14095,10 @@ <h1>
1. If _prototype_ is not present, set _prototype_ to _realm_.[[Intrinsics]].[[%Function.prototype%]].
1. Let _internalSlotsList_ be a List containing the names of all the internal slots that <emu-xref href="#sec-built-in-function-objects"></emu-xref> requires for the built-in function object that is about to be created.
1. Append to _internalSlotsList_ the elements of _additionalInternalSlotsList_.
1. Let _func_ be a new built-in function object that, when called, performs the action described by _behaviour_ using the provided arguments as the values of the corresponding parameters specified by _behaviour_. The new function object has internal slots whose names are the elements of _internalSlotsList_, and an [[InitialName]] internal slot.
1. If _behaviour_ is described as async, then
1. Let _func_ be a new built-in async function object that, when called, performs the action described by _behaviour_ using the provided arguments as the values of the corresponding parameters specified by _behaviour_. The new function object has internal slots whose names are the elements of _internalSlotsList_, and an [[InitialName]] internal slot.
1. Else,
1. Let _func_ be a new built-in function object that, when called, performs the action described by _behaviour_ using the provided arguments as the values of the corresponding parameters specified by _behaviour_. The new function object has internal slots whose names are the elements of _internalSlotsList_, and an [[InitialName]] internal slot.
1. Set _func_.[[Prototype]] to _prototype_.
1. Set _func_.[[Extensible]] to *true*.
1. Set _func_.[[Realm]] to _realm_.
Expand All @@ -14097,6 +14114,57 @@ <h1>
</emu-clause>
</emu-clause>

<emu-clause id="sec-built-in-async-function-objects">
<h1>Built-in Async Function Objects</h1>
<p><dfn variants="built-in async function object,built-in async function objects">Built-in async function objects</dfn> are built-in function objects that provide [[Call]] and [[Construct]] internal methods that conform to the following definitions:</p>

<emu-clause id="sec-built-in-async-function-objects-call" type="internal method">
<h1>
[[Call]] (
_thisArgument_: an ECMAScript language value,
_argumentsList_: a List of ECMAScript language values,
): a normal completion containing a Promise
</h1>
<dl class="header">
<dt>for</dt>
<dd>a built-in async function object _F_</dd>
</dl>
<emu-alg>
1. Let _callerContext_ be the running execution context.
1. If _callerContext_ is not already suspended, suspend _callerContext_.
1. Let _calleeContext_ be a new execution context.
1. Set the Function of _calleeContext_ to _F_.
1. Let _calleeRealm_ be _F_.[[Realm]].
1. Set the Realm of _calleeContext_ to _calleeRealm_.
1. Set the ScriptOrModule of _calleeContext_ to *null*.
1. Perform any necessary implementation-defined initialization of _calleeContext_.
1. Push _calleeContext_ onto the execution context stack; _calleeContext_ is now the running execution context.
1. Let _promiseCapability_ be ! NewPromiseCapability(%Promise%).
1. Let _resultsClosure_ be a new Abstract Closure with no parameters that captures _F_, _thisArgument_, and _argumentsList_ and performs the following steps when called:
1. Return the Completion Record that is the result of evaluating _F_ in a manner that conforms to the specification of _F_. _thisArgument_ is the *this* value, _argumentsList_ provides the named parameters, and the NewTarget value is *undefined*.
1. Perform AsyncFunctionStart(_promiseCapability_, _resultsClosure_).
1. Remove _calleeContext_ from the execution context stack and restore _callerContext_ as the running execution context.
1. Return _promiseCapability_.[[Promise]].
</emu-alg>
</emu-clause>

<emu-clause id="sec-built-in-async-function-objects-construct" type="internal method">
<h1>
[[Construct]] (
_argumentsList_: a List of ECMAScript language values,
_newTarget_: a constructor,
): either a normal completion containing an Object or a throw completion
</h1>
<dl class="header">
<dt>for</dt>
<dd>a built-in async function object _F_</dd>
</dl>
<emu-alg>
1. Throw a *TypeError* exception.
</emu-alg>
</emu-clause>
</emu-clause>

<emu-clause id="sec-built-in-exotic-object-internal-methods-and-slots">
<h1>Built-in Exotic Object Internal Methods and Slots</h1>
<p>This specification defines several kinds of built-in exotic objects. These objects generally behave similar to ordinary objects except for a few specific situations. The following exotic objects use the ordinary object internal methods except where it is explicitly specified otherwise below:</p>
Expand Down Expand Up @@ -39731,7 +39799,7 @@ <h1>Properties of the Array Constructor</h1>

<emu-clause id="sec-array.from">
<h1>Array.from ( _items_ [ , _mapper_ [ , _thisArg_ ] ] )</h1>
<p>This method performs the following steps when called:</p>
<p>This function performs the following steps when called:</p>
<emu-alg>
1. Let _C_ be the *this* value.
1. If _mapper_ is *undefined*, then
Expand Down Expand Up @@ -39789,6 +39857,82 @@ <h1>Array.from ( _items_ [ , _mapper_ [ , _thisArg_ ] ] )</h1>
</emu-note>
</emu-clause>

<emu-clause id="sec-array.fromasync">
<h1>Array.fromAsync ( _asyncItems_ [ , _mapper_ [ , _thisArg_ ] ] )</h1>

<p>This function performs the following steps when called:</p>
<emu-alg>
1. Let _C_ be the *this* value.
1. If _mapper_ is *undefined*, then
1. Let _mapping_ be *false*.
1. Else,
1. If IsCallable(_mapper_) is *false*, throw a *TypeError* exception.
1. Let _mapping_ be *true*.
1. Let _usingAsyncIterator_ be ? GetMethod(_asyncItems_, %Symbol.asyncIterator%).
1. If _usingAsyncIterator_ is *undefined*, then
1. Let _usingSyncIterator_ be ? GetMethod(_asyncItems_, %Symbol.iterator%).
1. Let _iteratorRecord_ be *undefined*.
1. If _usingAsyncIterator_ is not *undefined*, then
1. Set _iteratorRecord_ to ? GetIteratorFromMethod(_asyncItems_, _usingAsyncIterator_).
1. Else if _usingSyncIterator_ is not *undefined*, then
1. Set _iteratorRecord_ to CreateAsyncFromSyncIterator(? GetIteratorFromMethod(_asyncItems_, _usingSyncIterator_)).
1. If _iteratorRecord_ is not *undefined*, then
1. If IsConstructor(_C_) is *true*, then
1. Let _A_ be ? Construct(_C_).
1. Else,
1. Let _A_ be ! ArrayCreate(0).
1. Let _k_ be 0.
1. Repeat,
1. If _k_ ≥ 2<sup>53</sup> - 1, then
1. Let _error_ be ThrowCompletion(a newly created *TypeError* object).
1. Return ? AsyncIteratorClose(_iteratorRecord_, _error_).
1. Let _Pk_ be ! ToString(𝔽(_k_)).
1. Let _nextResult_ be ? Call(_iteratorRecord_.[[NextMethod]], _iteratorRecord_.[[Iterator]]).
1. Set _nextResult_ to ? Await(_nextResult_).
1. If _nextResult_ is not an Object, throw a *TypeError* exception.
1. Let _done_ be ? IteratorComplete(_nextResult_).
1. If _done_ is *true*, then
1. Perform ? Set(_A_, *"length"*, 𝔽(_k_), *true*).
1. Return _A_.
1. Let _nextValue_ be ? IteratorValue(_nextResult_).
1. If _mapping_ is *true*, then
1. Let _mappedValue_ be Completion(Call(_mapper_, _thisArg_, « _nextValue_, 𝔽(_k_) »)).
1. IfAbruptCloseAsyncIterator(_mappedValue_, _iteratorRecord_).
1. Set _mappedValue_ to Completion(Await(_mappedValue_)).
1. IfAbruptCloseAsyncIterator(_mappedValue_, _iteratorRecord_).
1. Else,
1. Let _mappedValue_ be _nextValue_.
1. Let _defineStatus_ be Completion(CreateDataPropertyOrThrow(_A_, _Pk_, _mappedValue_)).
1. IfAbruptCloseAsyncIterator(_defineStatus_, _iteratorRecord_).
1. Set _k_ to _k_ + 1.
1. Else,
1. NOTE: _asyncItems_ is neither async iterable nor iterable so assume it is an array-like object.
1. Let _arrayLike_ be ! ToObject(_asyncItems_).
1. Let _len_ be ? LengthOfArrayLike(_arrayLike_).
1. If IsConstructor(_C_) is *true*, then
1. Let _A_ be ? Construct(_C_, « 𝔽(_len_) »).
1. Else,
1. Let _A_ be ? ArrayCreate(_len_).
1. Let _k_ be 0.
1. Repeat, while _k_ &lt; _len_,
1. Let _Pk_ be ! ToString(𝔽(_k_)).
1. Let _kValue_ be ? Get(_arrayLike_, _Pk_).
1. Set _kValue_ to ? Await(_kValue_).
1. If _mapping_ is *true*, then
1. Let _mappedValue_ be ? Call(_mapper_, _thisArg_, « _kValue_, 𝔽(_k_) »).
1. Set _mappedValue_ to ? Await(_mappedValue_).
1. Else,
1. Let _mappedValue_ be _kValue_.
1. Perform ? CreateDataPropertyOrThrow(_A_, _Pk_, _mappedValue_).
1. Set _k_ to _k_ + 1.
1. Perform ? Set(_A_, *"length"*, 𝔽(_len_), *true*).
1. Return _A_.
</emu-alg>
<emu-note>
<p>This method is an intentionally generic factory method; it does not require that its *this* value be the Array constructor. Therefore it can be transferred to or inherited by any other constructors that may be called with a single numeric argument.</p>
</emu-note>
</emu-clause>

<emu-clause id="sec-array.isarray">
<h1>Array.isArray ( _arg_ )</h1>
<p>This function performs the following steps when called:</p>
Expand Down
Loading