explainer/spec: Sync inputs must await each item

Fixes #9. See also #7.

Author: js-choi

README.md

@@ -72,7 +72,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,14 +48,17 @@ <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. Let _usingIterator_ be ? GetMethod(_asyncItems_, @@asyncIterator).
+            1. If _usingIterator_ is *undefined*, then
+              1. Set _usingIterator_ to ? GetMethod(_asyncItems_, @@iterator).
+              1. If _usingIterator_ is *undefined*, set _usingIterator_ to CreateArrayIterator(_asyncItems_, ~value~).
+              1. Set _usingIterator_ to CreateAsyncFromSyncIterator(_usingIterator_).
             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 _iteratorRecord_ be ? GetIterator(_asyncItems_, ~async~, _usingIterator_).
               1. Let _k_ be 0.
               1. Repeat,
                 1. If _k_ &ge; 2<sup>53</sup> - 1, then
@@ -77,30 +80,76 @@ <h1><ins>Array.fromAsync ( _asyncItems_ [ , _mapfn_ [ , _thisArg_ ] ] )</ins></h
                 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. NOTE: _items_ is not an AsyncIterable or Iterable so assume it is an array-like object.
-            1. Let _arrayLike_ be ! ToObject(_items_).
-            1. Let _len_ be ? LengthOfArrayLike(_arrayLike_).
-            1. If IsConstructor(_C_) is *true*, then
-              1. Let _A_ be ? Construct(_C_, &laquo; 𝔽(_len_) &raquo;).
+          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. Let _A_ be ? ArrayCreate(_len_).
+              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, while _k_ &lt; _len_,
+                1. Let _Pk_ be ! ToString(𝔽(_k_)).
+                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; _kValue_, 𝔽(_k_) &raquo;).
+                1. Else, let _mappedValue_ be _kValue_.
+                1. Perform ? Set(_targetObj_, _Pk_, _mappedValue_, *true*).
+                1. Set _k_ to _k_ + 1.
+              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. 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>