27.1 Iteration
27.1.1 Common Iteration Interfaces
An interface is a set of property keys whose associated values match a specific specification. Any object that provides all the properties as described by an interface's specification conforms to that interface. An interface is not represented by a distinct object. There may be many separately implemented objects that conform to any interface. An individual object may conform to multiple interfaces.
27.1.1.1 The Iterable Interface
The Iterable interface includes the property described in
Property | Value | Requirements |
---|---|---|
@@iterator
|
A function that returns an Iterator object. | The returned object must conform to the Iterator interface. |
27.1.1.2 The Iterator Interface
An object that implements the Iterator interface must include the property in
Property | Value | Requirements |
---|---|---|
|
A function that returns an IteratorResult object. |
The returned object must conform to the IteratorResult interface. If a previous call to the next method of an Iterator has returned an IteratorResult object whose next method of that object should also return an IteratorResult object whose |
Arguments may be passed to the next
function but their interpretation and validity is dependent upon the target Iterator. The for-of statement and other common users of Iterators do not pass any arguments, so Iterator objects that expect to be used in such a manner must be prepared to deal with being called with no arguments.
Property | Value | Requirements |
---|---|---|
|
A function that returns an IteratorResult object. |
The returned object must conform to the IteratorResult interface. Invoking this method notifies the Iterator object that the caller does not intend to make any more next method calls to the Iterator. The returned IteratorResult object will typically have a return method. However, this requirement is not enforced.
|
|
A function that returns an IteratorResult object. |
The returned object must conform to the IteratorResult interface. Invoking this method notifies the Iterator object that the caller has detected an error condition. The argument may be used to identify the error condition and typically will be an exception object. A typical response is to throw the value passed as the argument. If the method does not throw , the returned IteratorResult object will typically have a |
Typically callers of these methods should check for their existence before invoking them. Certain ECMAScript language features including for
-of
, yield*
, and array destructuring call these methods after performing an existence check. Most ECMAScript library functions that accept Iterable objects as arguments also conditionally call them.
27.1.1.3 The AsyncIterable Interface
The AsyncIterable interface includes the properties described in
Property | Value | Requirements |
---|---|---|
@@asyncIterator |
A function that returns an AsyncIterator object. | The returned object must conform to the AsyncIterator interface. |
27.1.1.4 The AsyncIterator Interface
An object that implements the AsyncIterator interface must include the properties in
Property | Value | Requirements |
---|---|---|
A function that returns a promise for an IteratorResult object. |
The returned promise, when fulfilled, must fulfill with an object which conforms to the IteratorResult interface. If a previous call to the Additionally, the IteratorResult object that serves as a fulfillment value should have a |
Arguments may be passed to the next
function but their interpretation and validity is dependent upon the target AsyncIterator. The for
-await
-of
statement and other common users of AsyncIterators do not pass any arguments, so AsyncIterator objects that expect to be used in such a manner must be prepared to deal with being called with no arguments.
Property | Value | Requirements |
---|---|---|
A function that returns a promise for an IteratorResult object. |
The returned promise, when fulfilled, must fulfill with an object which conforms to the IteratorResult interface. Invoking this method notifies the AsyncIterator object that the caller does not intend to make any more Additionally, the IteratorResult object that serves as a fulfillment value should have a |
|
A function that returns a promise for an IteratorResult object. |
The returned promise, when fulfilled, must fulfill with an object which conforms to the IteratorResult interface. Invoking this method notifies the AsyncIterator object that the caller has detected an error condition. The argument may be used to identify the error condition and typically will be an exception object. A typical response is to return a rejected promise which rejects with the value passed as the argument. If the returned promise is fulfilled, the IteratorResult fulfillment value will typically have a |
Typically callers of these methods should check for their existence before invoking them. Certain ECMAScript language features including for
-await
-of
and yield*
call these methods after performing an existence check.
27.1.1.5 The IteratorResult Interface
The IteratorResult interface includes the properties listed in
Property | Value | Requirements |
---|---|---|
|
Either |
This is the result status of an iterator next method call. If the end of the iterator was reached |
|
Any |
If done is |
27.1.2 The %IteratorPrototype% Object
The %IteratorPrototype% object:
- has a [[Prototype]] internal slot whose value is
%Object.prototype% . - is an
ordinary object .
All objects defined in this specification that implement the Iterator interface also inherit from %IteratorPrototype%. ECMAScript code may also define objects that inherit from %IteratorPrototype%. The %IteratorPrototype% object provides a place where additional methods that are applicable to all iterator objects may be added.
The following expression is one way that ECMAScript code can access the %IteratorPrototype% object:
Object.getPrototypeOf(Object.getPrototypeOf([][Symbol.iterator]()))
27.1.2.1 %IteratorPrototype% [ @@iterator ] ( )
The following steps are taken:
- Return the
this value.
The value of the
27.1.3 The %AsyncIteratorPrototype% Object
The %AsyncIteratorPrototype% object:
- has a [[Prototype]] internal slot whose value is
%Object.prototype% . - is an
ordinary object .
All objects defined in this specification that implement the AsyncIterator interface also inherit from %AsyncIteratorPrototype%. ECMAScript code may also define objects that inherit from %AsyncIteratorPrototype%. The %AsyncIteratorPrototype% object provides a place where additional methods that are applicable to all async iterator objects may be added.
27.1.3.1 %AsyncIteratorPrototype% [ @@asyncIterator ] ( )
The following steps are taken:
- Return the
this value.
The value of the
27.1.4 Async-from-Sync Iterator Objects
An Async-from-Sync Iterator object is an async iterator that adapts a specific synchronous iterator. There is not a named
27.1.4.1 CreateAsyncFromSyncIterator ( syncIteratorRecord )
The abstract operation CreateAsyncFromSyncIterator takes argument syncIteratorRecord. It is used to create an async iterator
- Let asyncIterator be !
OrdinaryObjectCreate (%AsyncFromSyncIteratorPrototype% , « [[SyncIteratorRecord]] »). - Set asyncIterator.[[SyncIteratorRecord]] to syncIteratorRecord.
- Let nextMethod be !
Get (asyncIterator,"next" ). - Let iteratorRecord be the
Record { [[Iterator]]: asyncIterator, [[NextMethod]]: nextMethod, [[Done]]:false }. - Return iteratorRecord.
27.1.4.2 The %AsyncFromSyncIteratorPrototype% Object
The %AsyncFromSyncIteratorPrototype% object:
- has properties that are inherited by all Async-from-Sync Iterator Objects.
- is an
ordinary object . - has a [[Prototype]] internal slot whose value is
%AsyncIteratorPrototype% . - has the following properties:
27.1.4.2.1 %AsyncFromSyncIteratorPrototype%.next ( [ value ] )
- Let O be the
this value. Assert :Type (O) is Object and O has a [[SyncIteratorRecord]] internal slot.- Let promiseCapability be !
NewPromiseCapability (%Promise% ). - Let syncIteratorRecord be O.[[SyncIteratorRecord]].
- If value is present, then
- Let result be
IteratorNext (syncIteratorRecord, value).
- Let result be
- Else,
- Let result be
IteratorNext (syncIteratorRecord).
- Let result be
IfAbruptRejectPromise (result, promiseCapability).- Return !
AsyncFromSyncIteratorContinuation (result, promiseCapability).
27.1.4.2.2 %AsyncFromSyncIteratorPrototype%.return ( [ value ] )
- Let O be the
this value. Assert :Type (O) is Object and O has a [[SyncIteratorRecord]] internal slot.- Let promiseCapability be !
NewPromiseCapability (%Promise% ). - Let syncIterator be O.[[SyncIteratorRecord]].[[Iterator]].
- Let return be
GetMethod (syncIterator,"return" ). IfAbruptRejectPromise (return, promiseCapability).- If return is
undefined , then- Let iterResult be !
CreateIterResultObject (value,true ). - Perform !
Call (promiseCapability.[[Resolve]],undefined , « iterResult »). - Return promiseCapability.[[Promise]].
- Let iterResult be !
- If value is present, then
- Let result be
Call (return, syncIterator, « value »).
- Let result be
- Else,
- Let result be
Call (return, syncIterator).
- Let result be
IfAbruptRejectPromise (result, promiseCapability).- If
Type (result) is not Object, then- Perform !
Call (promiseCapability.[[Reject]],undefined , « a newly createdTypeError object »). - Return promiseCapability.[[Promise]].
- Perform !
- Return !
AsyncFromSyncIteratorContinuation (result, promiseCapability).
27.1.4.2.3 %AsyncFromSyncIteratorPrototype%.throw ( [ value ] )
- Let O be the
this value. Assert :Type (O) is Object and O has a [[SyncIteratorRecord]] internal slot.- Let promiseCapability be !
NewPromiseCapability (%Promise% ). - Let syncIterator be O.[[SyncIteratorRecord]].[[Iterator]].
- Let throw be
GetMethod (syncIterator,"throw" ). IfAbruptRejectPromise (throw, promiseCapability).- If throw is
undefined , then- Perform !
Call (promiseCapability.[[Reject]],undefined , « value »). - Return promiseCapability.[[Promise]].
- Perform !
- If value is present, then
- Let result be
Call (throw, syncIterator, « value »).
- Let result be
- Else,
- Let result be
Call (throw, syncIterator).
- Let result be
IfAbruptRejectPromise (result, promiseCapability).- If
Type (result) is not Object, then- Perform !
Call (promiseCapability.[[Reject]],undefined , « a newly createdTypeError object »). - Return promiseCapability.[[Promise]].
- Perform !
- Return !
AsyncFromSyncIteratorContinuation (result, promiseCapability).
27.1.4.2.4 Async-from-Sync Iterator Value Unwrap Functions
An async-from-sync iterator value unwrap function is an anonymous built-in function that is used by
When an async-from-sync iterator value unwrap function is called with argument value, the following steps are taken:
- Let F be the
active function object . - Return !
CreateIterResultObject (value, F.[[Done]]).
27.1.4.3 Properties of Async-from-Sync Iterator Instances
Async-from-Sync Iterator instances are ordinary objects that inherit properties from the
Internal Slot | Description |
---|---|
[[SyncIteratorRecord]] |
A |
27.1.4.4 AsyncFromSyncIteratorContinuation ( result, promiseCapability )
The abstract operation AsyncFromSyncIteratorContinuation takes arguments result and promiseCapability (a
- Let done be
IteratorComplete (result). IfAbruptRejectPromise (done, promiseCapability).- Let value be
IteratorValue (result). IfAbruptRejectPromise (value, promiseCapability).- Let valueWrapper be
PromiseResolve (%Promise% , value). IfAbruptRejectPromise (valueWrapper, promiseCapability).- Let steps be the algorithm steps defined in
Async-from-Sync Iterator Value Unwrap Functions . - Let length be the number of non-optional parameters of the function definition in
Async-from-Sync Iterator Value Unwrap Functions . - Let onFulfilled be !
CreateBuiltinFunction (steps, length,"" , « [[Done]] »). - Set onFulfilled.[[Done]] to done.
- Perform !
PerformPromiseThen (valueWrapper, onFulfilled,undefined , promiseCapability). - Return promiseCapability.[[Promise]].