Skip to content

Commit 964e108

Browse files
js-choijs-choi
committed
explainer/spec: Sync inputs must await each item
Fixes #9. See also #7.
1 parent c096610 commit 964e108

File tree

2 files changed

+101
-38
lines changed

2 files changed

+101
-38
lines changed

Diff for: ‎README.md

+14-1
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,20 @@ will also reject with that error.)
7575
`thisArg` is an optional value with which to call `mapfn`
7676
(or `undefined` by default).
7777

78-
Like `Array.from`, `Array.fromAsync` is a **generic factory method**.
78+
Like `for await`, when `Array.fromAsync` receives a **sync-iterable object**
79+
(and that object is not async iterable),
80+
then it creates a sync iterator for that object and adds its items to an array.
81+
When **any yielded item is a promise**, then that promise will **block** the iteration
82+
until it **resolves** to a value (in which case that value is what is added to the array)
83+
or until it **rejects** with an error (in which case
84+
the promise returned by `Array.fromAsync` itself will reject with that error).
85+
86+
Like `Array.from`, `Array.fromAsync` also works on non-iterable **array-like objects**
87+
(i.e., objects with a length property and indexed elements).
88+
As with sync-iterable objects, any element that is a promise must settle first,
89+
and the value to which it resolves (if any) will be what is added to the resulting array.
90+
91+
Also like `Array.from`, `Array.fromAsync` is a **generic factory method**.
7992
It does not require that its `this` value be the `Array` constructor,
8093
and it can be transferred to or inherited by any other constructors
8194
that may be called with a single numeric argument.

Diff for: ‎spec.html

+87-37
Original file line numberDiff line numberDiff line change
@@ -48,59 +48,109 @@ <h1><ins>Array.fromAsync ( _asyncItems_ [ , _mapfn_ [ , _thisArg_ ] ] )</ins></h
4848
1. Else,
4949
1. If IsCallable(_mapfn_) is *false*, throw a *TypeError* exception.
5050
1. Let _mapping_ be *true*.
51-
1. Let _usingAsyncOrSyncIterator_ be ? GetMethod(_asyncItems_, @@asyncIterator).
52-
1. If _usingAsyncOrSyncIterator_ is *undefined*, let _usingAsyncOrSyncIterator_ be ? GetMethod(_asyncItems_, @@iterator).
53-
1. If _usingAsyncOrSyncIterator_ is not *undefined*, then
54-
1. If IsConstructor(_C_) is *true*, then
55-
1. Let _A_ be ? Construct(_C_).
56-
1. Else,
57-
1. Let _A_ be ! ArrayCreate(0).
58-
1. Let _iteratorRecord_ be ? GetIterator(_asyncItems_, ~async~, _usingAsyncOrSyncIterator_).
51+
1. Let _usingAsyncIterator_ be ? GetMethod(_asyncItems_, @@asyncIterator).
52+
1. Else,
53+
1. Let _usingSyncIterator_ be ? GetMethod(_asyncItems_, @@iterator).
54+
1. If _usingSyncIterator_ is *undefined*, set _usingIterator_ to CreateArrayIterator(_asyncItems_, ~value~).
55+
1. If IsConstructor(_C_) is *true*, then
56+
1. Let _A_ be ? Construct(_C_).
57+
1. Else,
58+
1. Let _A_ be ! ArrayCreate(0).
59+
1. If _usingAsyncIterator_ is not *undefined*, then
60+
1. Let _iteratorRecord_ be ? GetIterator(_asyncItems_, ~async~, _usingAsyncIterator_).
61+
1. Else,
62+
1. Let _iteratorRecord_ be ? CreateAsyncFromSyncIterator(GetIterator(_asyncItems_, ~sync~, _usingSyncIterator_)).
63+
1. Let _k_ be 0.
64+
1. Repeat,
65+
1. If _k_ &ge; 2<sup>53</sup> - 1, then
66+
1. Let _error_ be ThrowCompletion(a newly created *TypeError* object).
67+
1. Return ? AsyncIteratorClose(_iteratorRecord_, _error_).
68+
1. Let _Pk_ be ! ToString(𝔽(_k_)).
69+
1. Let _next_ be ? Await(IteratorStep(_iteratorRecord_)).
70+
1. If _next_ is *false*, then
71+
1. Perform ? Set(_A_, *"length"*, 𝔽(_k_), *true*).
72+
1. Return _A_.
73+
1. Let _nextValue_ be ? IteratorValue(_next_).
74+
1. If _mapping_ is *true*, then
75+
1. Let _mappedValue_ be Call(_mapfn_, _thisArg_, &laquo; _nextValue_, 𝔽(_k_) &raquo;).
76+
1. IfAbruptCloseAsyncIterator(_iteratorRecord_, _mappedValue_).
77+
1. Let _mappedValue_ to Await(_mappedValue_).
78+
1. IfAbruptCloseAsyncIterator(_iteratorRecord_, _mappedValue_).
79+
1. Set _mappedValue_ to _mappedValue_.[[Value]].
80+
1. Else, let _mappedValue_ be _nextValue_.
81+
1. Let _defineStatus_ be CreateDataPropertyOrThrow(_A_, _Pk_, _mappedValue_).
82+
1. If _defineStatus_ is an abrupt completion, return ? AsyncIteratorClose(_iteratorRecord_, _defineStatus_).
83+
1. Set _k_ to _k_ + 1.
84+
1. Perform AsyncFunctionStart(promiseCapability, _fromAsyncClosure_).
85+
1. Return Completion { [[Type]]: ~return~, [[Value]]: _promiseCapability_.[[Promise]], [[Target]]: ~empty~ }.
86+
</emu-alg>
87+
<emu-note>
88+
<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>
89+
</emu-note>
90+
</emu-clause>
91+
</emu-clause>
92+
</emu-clause>
93+
94+
<emu-clause id="sec-typedarray-objects">
95+
<h1>TypedArray Objects</h1>
96+
97+
<emu-clause id="sec-properties-of-the-%typedarray%-intrinsic-object">
98+
<h1>Properties of the %TypedArray% Intrinsic Object</h1>
99+
100+
<emu-clause id="sec-%typedarray%.fromAsync">
101+
<h1><ins>%TypedArray%.fromAsync ( _source_ [ , _mapfn_ [ , _thisArg_ ] ] )</ins></h1>
102+
103+
<emu-note type=editor>
104+
<p>This section is a wholly new subsection of the <a
105+
href=https://tc39.es/ecma262/#sec-properties-of-the-%typedarray%-intrinsic-object>original
106+
Properties of the %TypedArray% Intrinsic Object clause</a>, to be inserted before the <a
107+
href=https://tc39.es/ecma262/#sec-%typedarray%.from>%TypedArray%.from
108+
clause</a>.</p>
109+
</emu-note>
110+
111+
<p>When the `fromAsync` method is called, the following steps are taken:</p>
112+
<emu-alg>
113+
1. Let _C_ be the *this* value.
114+
1. Let _promiseCapability_ be ! NewPromiseCapability(%Promise%).
115+
1. Let _fromAsyncClosure_ be a new Abstract Closure with no parameters that captures _C_ and _mapfn_ and performs the following steps when called:
116+
1. If IsConstructor(_C_) is *false*, throw a *TypeError* exception.
117+
1. If _mapfn_ is *undefined*, let _mapping_ be *false*.
118+
1. Else,
119+
1. If IsCallable(_mapfn_) is *false*, throw a *TypeError* exception.
120+
1. Let _mapping_ be *true*.
121+
1. Let _usingIterator_ be ? GetMethod(_source_, @@iterator).
122+
1. If _usingIterator_ is not *undefined*, then
123+
1. Let _values_ be ? IterableToList(_source_, _usingIterator_).
124+
1. Let _len_ be the number of elements in _values_.
125+
1. Let _targetObj_ be ? TypedArrayCreate(_C_, &laquo; 𝔽(_len_) &raquo;).
59126
1. Let _k_ be 0.
60-
1. Repeat,
61-
1. If _k_ &ge; 2<sup>53</sup> - 1, then
62-
1. Let _error_ be ThrowCompletion(a newly created *TypeError* object).
63-
1. Return ? AsyncIteratorClose(_iteratorRecord_, _error_).
127+
1. Repeat, while _k_ &lt; _len_,
64128
1. Let _Pk_ be ! ToString(𝔽(_k_)).
65-
1. Let _next_ be ? Await(IteratorStep(_iteratorRecord_)).
66-
1. If _next_ is *false*, then
67-
1. Perform ? Set(_A_, *"length"*, 𝔽(_k_), *true*).
68-
1. Return _A_.
69-
1. Let _nextValue_ be ? IteratorValue(_next_).
129+
1. Let _kValue_ be the first element of _values_ and remove that element from _values_.
70130
1. If _mapping_ is *true*, then
71-
1. Let _mappedValue_ be Call(_mapfn_, _thisArg_, &laquo; _nextValue_, 𝔽(_k_) &raquo;).
72-
1. IfAbruptCloseAsyncIterator(_iteratorRecord_, _mappedValue_).
73-
1. Let _mappedValue_ to Await(_mappedValue_).
74-
1. IfAbruptCloseAsyncIterator(_iteratorRecord_, _mappedValue_).
75-
1. Set _mappedValue_ to _mappedValue_.[[Value]].
76-
1. Else, let _mappedValue_ be _nextValue_.
77-
1. Let _defineStatus_ be CreateDataPropertyOrThrow(_A_, _Pk_, _mappedValue_).
78-
1. If _defineStatus_ is an abrupt completion, return ? AsyncIteratorClose(_iteratorRecord_, _defineStatus_).
131+
1. Let _mappedValue_ be ? Call(_mapfn_, _thisArg_, &laquo; _kValue_, 𝔽(_k_) &raquo;).
132+
1. Else, let _mappedValue_ be _kValue_.
133+
1. Perform ? Set(_targetObj_, _Pk_, _mappedValue_, *true*).
79134
1. Set _k_ to _k_ + 1.
80-
1. NOTE: _items_ is not an AsyncIterable or Iterable so assume it is an array-like object.
81-
1. Let _arrayLike_ be ! ToObject(_items_).
135+
1. Assert: _values_ is now an empty List.
136+
1. Return _targetObj_.
137+
1. NOTE: _source_ is not an Iterable so assume it is already an array-like object.
138+
1. Let _arrayLike_ be ! ToObject(_source_).
82139
1. Let _len_ be ? LengthOfArrayLike(_arrayLike_).
83-
1. If IsConstructor(_C_) is *true*, then
84-
1. Let _A_ be ? Construct(_C_, &laquo; 𝔽(_len_) &raquo;).
85-
1. Else,
86-
1. Let _A_ be ? ArrayCreate(_len_).
140+
1. Let _targetObj_ be ? TypedArrayCreate(_C_, &laquo; 𝔽(_len_) &raquo;).
87141
1. Let _k_ be 0.
88142
1. Repeat, while _k_ &lt; _len_,
89143
1. Let _Pk_ be ! ToString(𝔽(_k_)).
90144
1. Let _kValue_ be ? Get(_arrayLike_, _Pk_).
91145
1. If _mapping_ is *true*, then
92146
1. Let _mappedValue_ be ? Call(_mapfn_, _thisArg_, &laquo; _kValue_, 𝔽(_k_) &raquo;).
93147
1. Else, let _mappedValue_ be _kValue_.
94-
1. Perform ? CreateDataPropertyOrThrow(_A_, _Pk_, _mappedValue_).
148+
1. Perform ? Set(_targetObj_, _Pk_, _mappedValue_, *true*).
95149
1. Set _k_ to _k_ + 1.
96-
1. Perform ? Set(_A_, *"length"*, 𝔽(_len_), *true*).
97-
1. Return _A_.
150+
1. Return _targetObj_.
98151
1. Perform AsyncFunctionStart(promiseCapability, _fromAsyncClosure_).
99152
1. Return Completion { [[Type]]: ~return~, [[Value]]: _promiseCapability_.[[Promise]], [[Target]]: ~empty~ }.
100153
</emu-alg>
101-
<emu-note>
102-
<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>
103-
</emu-note>
104154
</emu-clause>
105155
</emu-clause>
106156
</emu-clause>

0 commit comments

Comments
 (0)