explainer/spec: Sync inputs must await each item

Fixes #9. See also #7.

Author: js-choi

README.md

@@ -75,7 +75,20 @@ will also reject with that error.)
 `thisArg` is an optional value with which to call `mapfn`
 (or `undefined` by default).
 
-Like `Array.from`, `Array.fromAsync` is a **generic factory method**.
+Like `for await`, when `Array.fromAsync` receives a **sync-iterable object**
+(and that object is not async iterable),
+then it creates a sync iterator for that object and adds its items to an array.
+When **any yielded item is a promise**, then that promise will **block** the iteration
+until it **resolves** to a value (in which case that value is what is added to the array)
+or until it **rejects** with an error (in which case
+the promise returned by `Array.fromAsync` itself will reject with that error).
+
+Like `Array.from`, `Array.fromAsync` also works on non-iterable **array-like objects**
+(i.e., objects with a length property and indexed elements).
+As with sync-iterable objects, any element that is a promise must settle first,
+and the value to which it resolves (if any) will be what is added to the resulting array.
+
+Also like `Array.from`, `Array.fromAsync` is a **generic factory method**.
 It does not require that its `this` value be the `Array` constructor,
 and it can be transferred to or inherited by any other constructors
 that may be called with a single numeric argument.

spec.html

@@ -48,59 +48,109 @@ <h1><ins>Array.fromAsync ( _asyncItems_ [ , _mapfn_ [ , _thisArg_ ] ] )</ins></h
             1. Else,
               1. If IsCallable(_mapfn_) is *false*, throw a *TypeError* exception.
               1. Let _mapping_ be *true*.
-            1. Let _usingAsyncOrSyncIterator_ be ? GetMethod(_asyncItems_, @@asyncIterator).
-            1. If _usingAsyncOrSyncIterator_ is *undefined*, let _usingAsyncOrSyncIterator_ be ? GetMethod(_asyncItems_, @@iterator).
-            1. If _usingAsyncOrSyncIterator_ 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 _iteratorRecord_ be ? GetIterator(_asyncItems_, ~async~, _usingAsyncOrSyncIterator_).
+            1. Let _usingAsyncIterator_ be ? GetMethod(_asyncItems_, @@asyncIterator).
+            1. Else,
+              1. Let _usingSyncIterator_ be ? GetMethod(_asyncItems_, @@iterator).
+              1. If _usingSyncIterator_ is *undefined*, set _usingIterator_ to CreateArrayIterator(_asyncItems_, ~value~).
+            1. If IsConstructor(_C_) is *true*, then
+              1. Let _A_ be ? Construct(_C_).
+            1. Else,
+              1. Let _A_ be ! ArrayCreate(0).
+            1. If _usingAsyncIterator_ is not *undefined*, then
+              1. Let _iteratorRecord_ be ? GetIterator(_asyncItems_, ~async~, _usingAsyncIterator_).
+            1. Else,
+              1. Let _iteratorRecord_ be ? CreateAsyncFromSyncIterator(GetIterator(_asyncItems_, ~sync~, _usingSyncIterator_)).
+            1. Let _k_ be 0.
+            1. Repeat,
+              1. If _k_ &ge; 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 _next_ be ? Await(IteratorStep(_iteratorRecord_)).
+              1. If _next_ is *false*, then
+                1. Perform ? Set(_A_, *"length"*, 𝔽(_k_), *true*).
+                1. Return _A_.
+              1. Let _nextValue_ be ? IteratorValue(_next_).
+              1. If _mapping_ is *true*, then
+                1. Let _mappedValue_ be Call(_mapfn_, _thisArg_, &laquo; _nextValue_, 𝔽(_k_) &raquo;).
+                1. IfAbruptCloseAsyncIterator(_iteratorRecord_, _mappedValue_).
+                1. Let _mappedValue_ to Await(_mappedValue_).
+                1. IfAbruptCloseAsyncIterator(_iteratorRecord_, _mappedValue_).
+                1. Set _mappedValue_ to _mappedValue_.[[Value]].
+              1. Else, let _mappedValue_ be _nextValue_.
+              1. Let _defineStatus_ be CreateDataPropertyOrThrow(_A_, _Pk_, _mappedValue_).
+              1. If _defineStatus_ is an abrupt completion, return ? AsyncIteratorClose(_iteratorRecord_, _defineStatus_).
+              1. Set _k_ to _k_ + 1.
+          1. Perform AsyncFunctionStart(promiseCapability, _fromAsyncClosure_).
+          1. Return Completion { [[Type]]: ~return~, [[Value]]: _promiseCapability_.[[Promise]], [[Target]]: ~empty~ }.
+        </emu-alg>
+        <emu-note>
+          <p>The `fromAsync` function 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>
+  </emu-clause>
+
+  <emu-clause id="sec-typedarray-objects">
+    <h1>TypedArray Objects</h1>
+
+    <emu-clause id="sec-properties-of-the-%typedarray%-intrinsic-object">
+      <h1>Properties of the %TypedArray% Intrinsic Object</h1>
+
+      <emu-clause id="sec-%typedarray%.fromAsync">
+        <h1><ins>%TypedArray%.fromAsync ( _source_ [ , _mapfn_ [ , _thisArg_ ] ] )</ins></h1>
+
+        <emu-note type=editor>
+          <p>This section is a wholly new subsection of the <a
+          href=https://tc39.es/ecma262/#sec-properties-of-the-%typedarray%-intrinsic-object>original
+          Properties of the %TypedArray% Intrinsic Object clause</a>, to be inserted before the <a
+          href=https://tc39.es/ecma262/#sec-%typedarray%.from>%TypedArray%.from
+          clause</a>.</p>
+        </emu-note>
+
+        <p>When the `fromAsync` method is called, the following steps are taken:</p>
+        <emu-alg>
+          1. Let _C_ be the *this* value.
+          1. Let _promiseCapability_ be ! NewPromiseCapability(%Promise%).
+          1. Let _fromAsyncClosure_ be a new Abstract Closure with no parameters that captures _C_ and _mapfn_ and performs the following steps when called:
+            1. If IsConstructor(_C_) is *false*, throw a *TypeError* exception.
+            1. If _mapfn_ is *undefined*, let _mapping_ be *false*.
+            1. Else,
+              1. If IsCallable(_mapfn_) is *false*, throw a *TypeError* exception.
+              1. Let _mapping_ be *true*.
+            1. Let _usingIterator_ be ? GetMethod(_source_, @@iterator).
+            1. If _usingIterator_ is not *undefined*, then
+              1. Let _values_ be ? IterableToList(_source_, _usingIterator_).
+              1. Let _len_ be the number of elements in _values_.
+              1. Let _targetObj_ be ? TypedArrayCreate(_C_, &laquo; 𝔽(_len_) &raquo;).
               1. Let _k_ be 0.
-              1. Repeat,
-                1. If _k_ &ge; 2<sup>53</sup> - 1, then
-                  1. Let _error_ be ThrowCompletion(a newly created *TypeError* object).
-                  1. Return ? AsyncIteratorClose(_iteratorRecord_, _error_).
+              1. Repeat, while _k_ &lt; _len_,
                 1. Let _Pk_ be ! ToString(𝔽(_k_)).
-                1. Let _next_ be ? Await(IteratorStep(_iteratorRecord_)).
-                1. If _next_ is *false*, then
-                  1. Perform ? Set(_A_, *"length"*, 𝔽(_k_), *true*).
-                  1. Return _A_.
-                1. Let _nextValue_ be ? IteratorValue(_next_).
+                1. Let _kValue_ be the first element of _values_ and remove that element from _values_.
                 1. If _mapping_ is *true*, then
-                  1. Let _mappedValue_ be Call(_mapfn_, _thisArg_, &laquo; _nextValue_, 𝔽(_k_) &raquo;).
-                  1. IfAbruptCloseAsyncIterator(_iteratorRecord_, _mappedValue_).
-                  1. Let _mappedValue_ to Await(_mappedValue_).
-                  1. IfAbruptCloseAsyncIterator(_iteratorRecord_, _mappedValue_).
-                  1. Set _mappedValue_ to _mappedValue_.[[Value]].
-                1. Else, let _mappedValue_ be _nextValue_.
-                1. Let _defineStatus_ be CreateDataPropertyOrThrow(_A_, _Pk_, _mappedValue_).
-                1. If _defineStatus_ is an abrupt completion, return ? AsyncIteratorClose(_iteratorRecord_, _defineStatus_).
+                  1. Let _mappedValue_ be ? Call(_mapfn_, _thisArg_, &laquo; _kValue_, 𝔽(_k_) &raquo;).
+                1. Else, let _mappedValue_ be _kValue_.
+                1. Perform ? Set(_targetObj_, _Pk_, _mappedValue_, *true*).
                 1. Set _k_ to _k_ + 1.
-            1. NOTE: _items_ is not an AsyncIterable or Iterable so assume it is an array-like object.
-            1. Let _arrayLike_ be ! ToObject(_items_).
+              1. Assert: _values_ is now an empty List.
+              1. Return _targetObj_.
+            1. NOTE: _source_ is not an Iterable so assume it is already an array-like object.
+            1. Let _arrayLike_ be ! ToObject(_source_).
             1. Let _len_ be ? LengthOfArrayLike(_arrayLike_).
-            1. If IsConstructor(_C_) is *true*, then
-              1. Let _A_ be ? Construct(_C_, &laquo; 𝔽(_len_) &raquo;).
-            1. Else,
-              1. Let _A_ be ? ArrayCreate(_len_).
+            1. Let _targetObj_ be ? TypedArrayCreate(_C_, &laquo; 𝔽(_len_) &raquo;).
             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. If _mapping_ is *true*, then
                 1. Let _mappedValue_ be ? Call(_mapfn_, _thisArg_, &laquo; _kValue_, 𝔽(_k_) &raquo;).
               1. Else, let _mappedValue_ be _kValue_.
-              1. Perform ? CreateDataPropertyOrThrow(_A_, _Pk_, _mappedValue_).
+              1. Perform ? Set(_targetObj_, _Pk_, _mappedValue_, *true*).
               1. Set _k_ to _k_ + 1.
-            1. Perform ? Set(_A_, *"length"*, 𝔽(_len_), *true*).
-            1. Return _A_.
+            1. Return _targetObj_.
           1. Perform AsyncFunctionStart(promiseCapability, _fromAsyncClosure_).
           1. Return Completion { [[Type]]: ~return~, [[Value]]: _promiseCapability_.[[Promise]], [[Target]]: ~empty~ }.
         </emu-alg>
-        <emu-note>
-          <p>The `fromAsync` function 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>
   </emu-clause>