ECMAScript® 2021 Language Specification

Draft ECMA-262 / March 6, 2021

7.4 Operations on Iterator Objects

See Common Iteration Interfaces (27.1).

7.4.1 GetIterator ( obj [ , hint [ , method ] ] )

The abstract operation GetIterator takes argument obj and optional arguments hint and method. It performs the following steps when called:

  1. If hint is not present, set hint to sync.
  2. Assert: hint is either sync or async.
  3. If method is not present, then
    1. If hint is async, then
      1. Set method to ? GetMethod(obj, @@asyncIterator).
      2. If method is undefined, then
        1. Let syncMethod be ? GetMethod(obj, @@iterator).
        2. Let syncIteratorRecord be ? GetIterator(obj, sync, syncMethod).
        3. Return ! CreateAsyncFromSyncIterator(syncIteratorRecord).
    2. Otherwise, set method to ? GetMethod(obj, @@iterator).
  4. Let iterator be ? Call(method, obj).
  5. If Type(iterator) is not Object, throw a TypeError exception.
  6. Let nextMethod be ? GetV(iterator, "next").
  7. Let iteratorRecord be the Record { [[Iterator]]: iterator, [[NextMethod]]: nextMethod, [[Done]]: false }.
  8. Return iteratorRecord.

7.4.2 IteratorNext ( iteratorRecord [ , value ] )

The abstract operation IteratorNext takes argument iteratorRecord and optional argument value. It performs the following steps when called:

  1. If value is not present, then
    1. Let result be ? Call(iteratorRecord.[[NextMethod]], iteratorRecord.[[Iterator]]).
  2. Else,
    1. Let result be ? Call(iteratorRecord.[[NextMethod]], iteratorRecord.[[Iterator]], « value »).
  3. If Type(result) is not Object, throw a TypeError exception.
  4. Return result.

7.4.3 IteratorComplete ( iterResult )

The abstract operation IteratorComplete takes argument iterResult. It performs the following steps when called:

  1. Assert: Type(iterResult) is Object.
  2. Return ! ToBoolean(? Get(iterResult, "done")).

7.4.4 IteratorValue ( iterResult )

The abstract operation IteratorValue takes argument iterResult. It performs the following steps when called:

  1. Assert: Type(iterResult) is Object.
  2. Return ? Get(iterResult, "value").

7.4.5 IteratorStep ( iteratorRecord )

The abstract operation IteratorStep takes argument iteratorRecord. It requests the next value from iteratorRecord.[[Iterator]] by calling iteratorRecord.[[NextMethod]] and returns either false indicating that the iterator has reached its end or the IteratorResult object if a next value is available. It performs the following steps when called:

  1. Let result be ? IteratorNext(iteratorRecord).
  2. Let done be ? IteratorComplete(result).
  3. If done is true, return false.
  4. Return result.

7.4.6 IteratorClose ( iteratorRecord, completion )

The abstract operation IteratorClose takes arguments iteratorRecord and completion. It is used to notify an iterator that it should perform any actions it would normally perform when it has reached its completed state. It performs the following steps when called:

  1. Assert: Type(iteratorRecord.[[Iterator]]) is Object.
  2. Assert: completion is a Completion Record.
  3. Let iterator be iteratorRecord.[[Iterator]].
  4. Let innerResult be GetMethod(iterator, "return").
  5. If innerResult.[[Type]] is normal, then
    1. Let return be innerResult.[[Value]].
    2. If return is undefined, return Completion(completion).
    3. Set innerResult to Call(return, iterator).
  6. If completion.[[Type]] is throw, return Completion(completion).
  7. If innerResult.[[Type]] is throw, return Completion(innerResult).
  8. If Type(innerResult.[[Value]]) is not Object, throw a TypeError exception.
  9. Return Completion(completion).

7.4.7 AsyncIteratorClose ( iteratorRecord, completion )

The abstract operation AsyncIteratorClose takes arguments iteratorRecord and completion. It is used to notify an async iterator that it should perform any actions it would normally perform when it has reached its completed state. It performs the following steps when called:

  1. Assert: Type(iteratorRecord.[[Iterator]]) is Object.
  2. Assert: completion is a Completion Record.
  3. Let iterator be iteratorRecord.[[Iterator]].
  4. Let innerResult be GetMethod(iterator, "return").
  5. If innerResult.[[Type]] is normal, then
    1. Let return be innerResult.[[Value]].
    2. If return is undefined, return Completion(completion).
    3. Set innerResult to Call(return, iterator).
    4. If innerResult.[[Type]] is normal, set innerResult to Await(innerResult.[[Value]]).
  6. If completion.[[Type]] is throw, return Completion(completion).
  7. If innerResult.[[Type]] is throw, return Completion(innerResult).
  8. If Type(innerResult.[[Value]]) is not Object, throw a TypeError exception.
  9. Return Completion(completion).

7.4.8 CreateIterResultObject ( value, done )

The abstract operation CreateIterResultObject takes arguments value and done. It creates an object that supports the IteratorResult interface. It performs the following steps when called:

  1. Assert: Type(done) is Boolean.
  2. Let obj be ! OrdinaryObjectCreate(%Object.prototype%).
  3. Perform ! CreateDataPropertyOrThrow(obj, "value", value).
  4. Perform ! CreateDataPropertyOrThrow(obj, "done", done).
  5. Return obj.

7.4.9 CreateListIteratorRecord ( list )

The abstract operation CreateListIteratorRecord takes argument list. It creates an Iterator (27.1.1.2) object record whose next method returns the successive elements of list. It performs the following steps when called:

  1. Let closure be a new Abstract Closure with no parameters that captures list and performs the following steps when called:
    1. For each element E of list, do
      1. Perform ? Yield(E).
    2. Return undefined.
  2. Let iterator be ! CreateIteratorFromClosure(closure, empty, %IteratorPrototype%).
  3. Return Record { [[Iterator]]: iterator, [[NextMethod]]: %GeneratorFunction.prototype.prototype.next%, [[Done]]: false }.
 Note

The list iterator object is never directly accessible to ECMAScript code.

7.4.10 IterableToList ( items [ , method ] )

The abstract operation IterableToList takes argument items and optional argument method. It performs the following steps when called:

  1. If method is present, then
    1. Let iteratorRecord be ? GetIterator(items, sync, method).
  2. Else,
    1. Let iteratorRecord be ? GetIterator(items, sync).
  3. Let values be a new empty List.
  4. Let next be true.
  5. Repeat, while next is not false,
    1. Set next to ? IteratorStep(iteratorRecord).
    2. If next is not false, then
      1. Let nextValue be ? IteratorValue(next).
      2. Append nextValue to the end of the List values.
  6. Return values.