iteration.html

<emu-clause id="sec-common-iteration-interfaces">
  <h1>Common Iteration Interfaces</h1>

  <emu-clause id="sec-asynciterable-interface">
    <h1><ins>The <i>AsyncIterable</i> Interface</ins></h1>
    <p>The <i>AsyncIterable</i> interface includes the properties described in <emu-xref href="#table-async-iterable"></emu-xref>:</p>
    <emu-table id="table-async-iterable" caption="<i>AsyncIterable</i> Interface Required Properties">
      <table>
        <tbody>
        <tr>
          <th>Property</th>
          <th>Value</th>
          <th>Requirements</th>
        </tr>
        <tr>
          <td>`@@asyncIterator`</td>
          <td>A function that returns an <i>AsyncIterator</i> object.</td>
          <td>The returned object must conform to the <i>AsyncIterator</i> interface.</td>
        </tr>
        </tbody>
      </table>
    </emu-table>
  </emu-clause>

  <emu-clause id="sec-asynciterator-interface">
    <h1><ins>The <i>AsyncIterator</i> Interface</ins></h1>
    <p>An object that implements the <i>AsyncIterator</i> interface must include the properties in <emu-xref href="#table-async-iterator-required"></emu-xref>. Such objects may also implement the properties in <emu-xref href="#table-async-iterator-optional"></emu-xref>.</p>
    <emu-table id="table-async-iterator-required" caption="<i>AsyncIterator</i> Interface Required Properties">
      <table>
        <tbody>
        <tr>
          <th>Property</th>
          <th>Value</th>
          <th>Requirements</th>
        </tr>
        <tr>
          <td>`next`</td>
          <td>A function that returns a promise for an <i>IteratorResult</i> object.</td>
          <td>
            <p>The returned promise, when fulfilled, must fulfill with an object which conforms to the <i>IteratorResult</i> interface. If a previous call to the `next` method of an <i>AsyncIterator</i> has returned a promise for an <i>IteratorResult</i> object whose `done` property is *true*, then all subsequent calls to the `next` method of that object should also return a promise for an <i>IteratorResult</i> object whose `done` property is *true*. However, this requirement is not enforced.</p>

            <p>Additionally, the <i>IteratorResult</i> object that serves as a fulfillment value should have a `value` property whose value is not a promise (or "thenable"). However, this requirement is also not enforced.</p>
          </td>
        </tr>
        </tbody>
      </table>
    </emu-table>
    <emu-note>
      <p>Arguments may be passed to the next function but their interpretation and validity is dependent upon the target <i>AsyncIterator</i>. The `for`-`await`-`of` statement and other common users of <em>AsyncIterators</em> do not pass any arguments, so <i>AsyncIterator</i> objects that expect to be used in such a manner must be prepared to deal with being called with no arguments.</p>
    </emu-note>
    <emu-table id="table-async-iterator-optional" caption="<i>AsyncIterator</i> Interface Optional Properties">
      <table>
        <tbody>
        <tr>
          <th>Property</th>
          <th>Value</th>
          <th>Requirements</th>
        </tr>
        <tr>
          <td>`return`</td>
          <td>A function that returns a promise for an <i>IteratorResult</i> object.</td>
          <td>
            <p>The returned promise, when fulfilled, must fulfill with an object which conforms to the <i>IteratorResult</i> interface. Invoking this method notifies the <i>AsyncIterator</i> object that the caller does not intend to make any more `next` method calls to the <i>AsyncIterator</i>. The returned promise will fulfill with an <i>IteratorResult</i> object which will typically have a `done` property whose value is *true*, and a `value` property with the value passed as the argument of the `return` method. However, this requirement is not enforced.</p>

            <p>Additionally, the <i>IteratorResult</i> object that serves as a fulfillment value should have a `value` property whose value is not a promise (or "thenable"). If the argument value is used in the typical manner, then if it is a rejected promise, a promise rejected with the same reason should be returned; if it is a fulfilled promise, then its fulfillment value should be used as the `value` property of the returned promise's <i>IteratorResult</i> object fulfillment value. However, these requirements are also not enforced.</p>
          </td>
        </tr>
        <tr>
          <td>`throw`</td>
          <td>A function that returns a promise for an <i>IteratorResult</i> object.</td>
          <td>
            <p>The returned promise, when fulfilled, must fulfill with an object which conforms to the <i>IteratorResult</i> interface. Invoking this method notifies the <i>AsyncIterator</i> 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.</p>

            <p>If the returned promise is fulfilled, the <i>IteratorResult</i> fulfillment value will typically have a `done` property whose value is *true*. Additionally, it should have a `value` property whose value is not a promise (or "thenable"), but this requirement is not enforced.</p>
          </td>
        </tr>
        </tbody>
      </table>
    </emu-table>
    <emu-note>
      <p>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.</p>
    </emu-note>

    <emu-clause id="sec-async-iterator-value-unwrap-functions">
      <h1>Async Iterator Value Unwrap Functions</h1>

      <p>An async iterator value unwrap function is an anonymous built-in function that is used when processing the `value` field of an <i>IteratorResult</i> object, in order to wait for its value if it is a promise and re-package the result in a new "unwrapped" <i>IteratorResult</i> object. Each async iterator value unwrap function has a [[Done]] internal slot.</p>

      <p>When an async iterator unwrap function _F_ is called with argument _value_, the following steps are taken:</p>

      <emu-alg>
        1. Return ! CreateIterResultObject(_value_, _F_.[[Done]]).
      </emu-alg>
    </emu-clause>
  </emu-clause>
</emu-clause>

<emu-clause id="sec-asynciteratorprototype">
  <h1><ins>The %AsyncIteratorPrototype% Object</ins></h1>
  <p>The value of the [[Prototype]] internal slot of the <dfn>%AsyncIteratorPrototype%</dfn> object is the intrinsic object %ObjectPrototype%. The %AsyncIteratorPrototype% object is an ordinary object. The initial value of the [[Extensible]] internal slot of the %AsyncIteratorPrototype% object is *true*.</p>
  <emu-note>
    <p>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.</p>
  </emu-note>

  <emu-clause id="sec-asynciteratorprototype-asynciterator">
    <h1>%AsyncIteratorPrototype% [ @@asyncIterator ] ( )</h1>
    <p>The following steps are taken:</p>
    <emu-alg>
      1. Return the *this* value.
    </emu-alg>
    <p>The value of the `name` property of this function is `"[Symbol.asyncIterator]"`.</p>
  </emu-clause>
</emu-clause>

<emu-clause id="sec-async-from-sync-iterator-objects">
  <h1><ins>Async-from-Sync Iterator Objects</ins></h1>
  <p>An Async-from-Sync Iterator object is an async iterator that adapts a specific synchronous iterator. There is not a named constructor for Async-from-Sync Iterator objects. Instead, Async-from-Sync iterator objects are created by the @@asyncIterator method of synchronous iterator objects.</p>

  <emu-clause id="sec-createasyncfromsynciterator" aoid="CreateAsyncFromSyncIterator">
    <h1>CreateAsyncFromSyncIterator(_syncIterator_) Abstract Operation</h1>
    <p>The abstract operation CreateAsyncFromSyncIterator is used to create an async iterator from a synchronous iterator. It performs the following steps:</p>
    <emu-alg>
      1. If Type(_syncIterator_) is not Object, throw a *TypeError* exception.
      1. Let _asyncIterator_ be ! ObjectCreate(%AsyncFromSyncIteratorPrototype%, &laquo; [[SyncIterator]] &raquo;).
      1. Set _asyncIterator_.[[SyncIterator]] to _syncIterator_.
      1. Return _asyncIterator_.
    </emu-alg>
  </emu-clause>

  <emu-clause id="sec-%asyncfromsynciteratorprototype%-object">
    <h1>The %AsyncFromSyncIteratorPrototype% Object</h1>
    <p>All Async-from-Sync Iterator Objects inherit properties from the <dfn>%AsyncFromSyncIteratorPrototype%</dfn> intrinsic object. The %AsyncFromSyncIteratorPrototype% object is an ordinary object and its [[Prototype]] internal slot is the %AsyncIteratorPrototype% intrinsic object. In addition, %AsyncFromSyncIteratorPrototype% has the following properties:</p>

    <emu-clause id="sec-%asyncfromsynciteratorprototype%.next">
      <h1>%AsyncFromSyncIteratorPrototype%.next ( _value_ )</h1>
      <emu-alg>
        1. Let _O_ be the *this* value.
        1. Let _promiseCapability_ be ! NewPromiseCapability(%Promise%).
        1. If Type(_O_) is not Object, or if _O_ does not have a [[SyncIterator]] internal slot, then
          1. Let _badIteratorError_ be a new *TypeError* exception.
          1. Perform ! Call(_promiseCapability_.[[Reject]], *undefined*, &laquo; _badIteratorError_ &raquo;).
          1. Return _promiseCapability_.[[Promise]].
        1. Let _syncIterator_ be _O_.[[SyncIterator]].
        1. Let _nextResult_ be IteratorNext(_syncIterator_, _value_).
        1. IfAbruptRejectPromise(_nextResult_, _promiseCapability_).
        1. Let _value_ be IteratorValue(_nextResult_).
        1. IfAbruptRejectPromise(_value_, _promiseCapability_).
        1. Let _done_ be IteratorComplete(_nextResult_).
        1. IfAbruptRejectPromise(_value_, _promiseCapability_).
        1. Let _valueWrapperCapability_ be ! NewPromiseCapability(%Promise%).
        1. Perform ! Call(_valueWrapperCapability_.[[Resolve]], *undefined*, &laquo; _value_ &raquo;).
        1. Let _onFulfilled_ be a new built-in function object as defined in <emu-xref href="#sec-async-iterator-value-unwrap-functions" title></emu-xref>.
        1. Set _onFulfilled_.[[Done]] to _done_.
        1. Perform ! PerformPromiseThen(_valueWrapperCapability_.[[Promise]], _onFulfilled_, *undefined*, _promiseCapability_).
        1. Return _promiseCapability_.
      </emu-alg>
    </emu-clause>

    <emu-clause id="sec-%asyncfromsynciteratorprototype%.throw">
      <h1>%AsyncFromSyncIteratorPrototype%.throw ( _value_ )</h1>

      `%AsyncFromSyncIteratorPrototype%.throw` is a distinct function that implements the same algorithm as `%AsyncFromSyncIteratorPrototype%.next` as defined in <emu-xref href="#sec-%asyncfromsynciteratorprototype%.next"></emu-xref>.
    </emu-clause>

    <emu-clause id="sec-%asyncfromsynciteratorprototype%.return">
      <h1>%AsyncFromSyncIteratorPrototype%.return ( _value_ )</h1>

      `%AsyncFromSyncIteratorPrototype%.return` is a distinct function that implements the same algorithm as `%AsyncFromSyncIteratorPrototype%.next` as defined in <emu-xref href="#sec-%asyncfromsynciteratorprototype%.next"></emu-xref>.
    </emu-clause>

    <emu-clause id="sec-%asyncfromsynciteratorprototype%-@@tostringtag">
      <h1>%AsyncFromSyncIteratorPrototype% [ @@toStringTag ]</h1>
      <p>The initial value of the @@toStringTag property is the String value `"Async-from-Sync Iterator"`.</p>
      <p>This property has the attributes { [[Writable]]: *false*, [[Enumerable]]: *false*, [[Configurable]]: *true* }.</p>
    </emu-clause>
  </emu-clause>

  <emu-clause id="sec-properties-of-async-from-sync-iterator-instances">
    <h1>Properties of Async-from-Sync Iterator Instances</h1>
    <p>Async-from-Sync Iterator instances are ordinary objects that inherit properties from the %AsyncFromSyncIteratorPrototype% intrinsic object. Async-from-Sync Iterator instances are initially created with the internal slots listed in <emu-xref href="#table-async-from-sync-iterator-internal-slots"></emu-xref>.</p>
    <emu-table id="table-async-from-sync-iterator-internal-slots" caption="Internal Slots of Async-from-Sync Iterator Instances">
      <table>
        <thead>
        <tr>
          <th>
            Internal Slot
          </th>
          <th>
            Description
          </th>
        </tr>
        </thead>
        <tbody>
        <tr>
          <td>
            [[SyncIterator]]
          </td>
          <td>
            The original synchronous iterator which is being adapted.
          </td>
        </tr>
        </tbody>
      </table>
    </emu-table>
  </emu-clause>
</emu-clause>