ECMAScript® 2024 Language Specification

Draft ECMA-262 / February 15, 2024

7.4 Operations on Iterator Objects

See Common Iteration Interfaces (27.1).

7.4.1 Iterator Records

An Iterator Record is a Record value used to encapsulate an Iterator or AsyncIterator along with the next method.

Iterator Records have the fields listed in Table 15.

Table 15: Iterator Record Fields
Field Name Value Meaning
[[Iterator]] an Object An object that conforms to the Iterator or AsyncIterator interface.
[[NextMethod]] an ECMAScript language value The next method of the [[Iterator]] object.
[[Done]] a Boolean Whether the iterator has been closed.

7.4.2 GetIteratorFromMethod ( obj, method )

The abstract operation GetIteratorFromMethod takes arguments obj (an ECMAScript language value) and method (a function object) and returns either a normal completion containing an Iterator Record or a throw completion. It performs the following steps when called:

  1. Let iterator be ? Call(method, obj).
  2. If iterator is not an Object, throw a TypeError exception.
  3. Let nextMethod be ? Get(iterator, "next").
  4. Let iteratorRecord be the Iterator Record { [[Iterator]]: iterator, [[NextMethod]]: nextMethod, [[Done]]: false }.
  5. Return iteratorRecord.

7.4.3 GetIterator ( obj, kind )

The abstract operation GetIterator takes arguments obj (an ECMAScript language value) and kind (sync or async) and returns either a normal completion containing an Iterator Record or a throw completion. It performs the following steps when called:

  1. If kind is async, then
    1. Let method be ? GetMethod(obj, @@asyncIterator).
    2. If method is undefined, then
      1. Let syncMethod be ? GetMethod(obj, @@iterator).
      2. If syncMethod is undefined, throw a TypeError exception.
      3. Let syncIteratorRecord be ? GetIteratorFromMethod(obj, syncMethod).
      4. Return CreateAsyncFromSyncIterator(syncIteratorRecord).
  2. Else,
    1. Let method be ? GetMethod(obj, @@iterator).
  3. If method is undefined, throw a TypeError exception.
  4. Return ? GetIteratorFromMethod(obj, method).

7.4.4 IteratorNext ( iteratorRecord [ , value ] )

The abstract operation IteratorNext takes argument iteratorRecord (an Iterator Record) and optional argument value (an ECMAScript language value) and returns either a normal completion containing an Object or a throw completion. 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 result is not an Object, throw a TypeError exception.
  4. Return result.

7.4.5 IteratorComplete ( iterResult )

The abstract operation IteratorComplete takes argument iterResult (an Object) and returns either a normal completion containing a Boolean or a throw completion. It performs the following steps when called:

  1. Return ToBoolean(? Get(iterResult, "done")).

7.4.6 IteratorValue ( iterResult )

The abstract operation IteratorValue takes argument iterResult (an Object) and returns either a normal completion containing an ECMAScript language value or a throw completion. It performs the following steps when called:

  1. Return ? Get(iterResult, "value").

7.4.7 IteratorStep ( iteratorRecord )

The abstract operation IteratorStep takes argument iteratorRecord (an Iterator Record) and returns either a normal completion containing either an Object or false, or a throw completion. 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.8 IteratorStepValue ( iteratorRecord )

The abstract operation IteratorStepValue takes argument iteratorRecord (an Iterator Record) and returns either a normal completion containing either an ECMAScript language value or done, or a throw completion. It requests the next value from iteratorRecord.[[Iterator]] by calling iteratorRecord.[[NextMethod]] and returns either done indicating that the iterator has reached its end or the value from the IteratorResult object if a next value is available. It performs the following steps when called:

  1. Let result be Completion(IteratorNext(iteratorRecord)).
  2. If result is a throw completion, then
    1. Set iteratorRecord.[[Done]] to true.
    2. Return ? result.
  3. Set result to ! result.
  4. Let done be Completion(IteratorComplete(result)).
  5. If done is a throw completion, then
    1. Set iteratorRecord.[[Done]] to true.
    2. Return ? done.
  6. Set done to ! done.
  7. If done is true, then
    1. Set iteratorRecord.[[Done]] to true.
    2. Return done.
  8. Let value be Completion(Get(result, "value")).
  9. If value is a throw completion, then
    1. Set iteratorRecord.[[Done]] to true.
  10. Return ? value.

7.4.9 IteratorClose ( iteratorRecord, completion )

The abstract operation IteratorClose takes arguments iteratorRecord (an Iterator Record) and completion (a Completion Record) and returns a Completion Record. 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: iteratorRecord.[[Iterator]] is an Object.
  2. Let iterator be iteratorRecord.[[Iterator]].
  3. Let innerResult be Completion(GetMethod(iterator, "return")).
  4. If innerResult is a normal completion, then
    1. Let return be innerResult.[[Value]].
    2. If return is undefined, return ? completion.
    3. Set innerResult to Completion(Call(return, iterator)).
  5. If completion is a throw completion, return ? completion.
  6. If innerResult is a throw completion, return ? innerResult.
  7. If innerResult.[[Value]] is not an Object, throw a TypeError exception.
  8. Return ? completion.

7.4.10 IfAbruptCloseIterator ( value, iteratorRecord )

IfAbruptCloseIterator is a shorthand for a sequence of algorithm steps that use an Iterator Record. An algorithm step of the form:

  1. IfAbruptCloseIterator(value, iteratorRecord).

means the same thing as:

  1. Assert: value is a Completion Record.
  2. If value is an abrupt completion, return ? IteratorClose(iteratorRecord, value).
  3. Else, set value to ! value.

7.4.11 AsyncIteratorClose ( iteratorRecord, completion )

The abstract operation AsyncIteratorClose takes arguments iteratorRecord (an Iterator Record) and completion (a Completion Record) and returns a Completion Record. 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: iteratorRecord.[[Iterator]] is an Object.
  2. Let iterator be iteratorRecord.[[Iterator]].
  3. Let innerResult be Completion(GetMethod(iterator, "return")).
  4. If innerResult is a normal completion, then
    1. Let return be innerResult.[[Value]].
    2. If return is undefined, return ? completion.
    3. Set innerResult to Completion(Call(return, iterator)).
    4. If innerResult is a normal completion, set innerResult to Completion(Await(innerResult.[[Value]])).
  5. If completion is a throw completion, return ? completion.
  6. If innerResult is a throw completion, return ? innerResult.
  7. If innerResult.[[Value]] is not an Object, throw a TypeError exception.
  8. Return ? completion.

7.4.12 CreateIterResultObject ( value, done )

The abstract operation CreateIterResultObject takes arguments value (an ECMAScript language value) and done (a Boolean) and returns an Object that conforms to the IteratorResult interface. It creates an object that conforms to the IteratorResult interface. It performs the following steps when called:

  1. Let obj be OrdinaryObjectCreate(%Object.prototype%).
  2. Perform ! CreateDataPropertyOrThrow(obj, "value", value).
  3. Perform ! CreateDataPropertyOrThrow(obj, "done", done).
  4. Return obj.

7.4.13 CreateListIteratorRecord ( list )

The abstract operation CreateListIteratorRecord takes argument list (a List of ECMAScript language values) and returns an Iterator Record. 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 ? GeneratorYield(CreateIterResultObject(E, false)).
    2. Return NormalCompletion(undefined).
  2. Let iterator be CreateIteratorFromClosure(closure, empty, %IteratorPrototype%).
  3. Return the Iterator Record { [[Iterator]]: iterator, [[NextMethod]]: %GeneratorFunction.prototype.prototype.next%, [[Done]]: false }.
 Note

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

7.4.14 IteratorToList ( iteratorRecord )

The abstract operation IteratorToList takes argument iteratorRecord (an Iterator Record) and returns either a normal completion containing a List of ECMAScript language values or a throw completion. It performs the following steps when called:

  1. Let values be a new empty List.
  2. Repeat,
    1. Let next be ? IteratorStepValue(iteratorRecord).
    2. If next is done, then
      1. Return values.
    3. Append next to values.