JavaScript iterators and generators

The iterable and iterator protocols, for…of, and generator next, return, and closure behavior, without the later Iterator helper methods.

An iterable object has a Symbol.iterator method that returns an iterator. An iterator has a next() method that returns an object with value and done. for…of uses that protocol. Arrays, strings, Map, and Set are iterables; those collection pages are not repeated here.

A generator function (function*) produces an iterator. This page covers next, return, early completion of for…of, and values closed over by the generator. It does not use the later Iterator helper methods such as map or take, even when a given engine implements them. Examples were checked in Node.js 22 and are not browser tests.

Examples were checked in Node.js 22, which implements these ECMAScript built-ins. See the MDN documentation for the complete API.

JavaScript tutorial and API overview →

API index

APISummary
Symbol.iterator and Iterator.nextAn iterable returns an iterator from Symbol.iterator. next() yields { value, done }. for…of may call return() on early exit.
Generator next and returnnext resumes a generator. return completes it and runs finally. for…of break also closes the generator. Yielded objects share the closed-over binding.

Iterable protocol and for…of

obj[Symbol.iterator]() should return an iterator. iterator.next() returns { value, done }. When done is true, value may be undefined, which JSON.stringify omits.

for…of calls Symbol.iterator, then next() until done is true. If the loop exits early, for…of calls iterator.return() when that method exists, which is how generators run finally blocks on break.

Symbol.iterator and Iterator.next

iterable[Symbol.iterator]()
iterator.next()
iterator.return?.(value)

An iterable returns an iterator from Symbol.iterator. next() yields { value, done }. for…of may call return() on early exit.

ParameterDescription
valueOptional completion value passed to return() or as the result of a finished iterator.

Returns: next and return return an iterator result object with a done boolean and a value.

  • This page does not call Iterator helper methods. Array, Map, and Set iteration stay on those pages.
javascript
const list = [10, 20];
const it = list[Symbol.iterator]();
console.log(JSON.stringify(it.next()));
console.log(JSON.stringify(it.next()));
const last = it.next();
console.log(last.value, last.done);

Expected output

{"value":10,"done":false}
{"value":20,"done":false}
undefined true

Related: Generators, Symbol, Array, Map and Set, Official iteration protocols

MDN documentation →

Generators: next, return, and closures

function* body pauses at yield. next() resumes until the next yield or the end of the function. next(arg) supplies arg as the result of the current yield expression. That argument is ignored on the first next() call, which only starts the generator.

return(value) completes the generator, runs finally, and returns { value, done: true }. Breaking out of for…of has the same cleanup effect when the iterator implements return.

A generator closes over bindings in its scope. If it yields an object, later mutations of that object are visible when the generator reads the same binding again.

Generator next and return

function* name() { yield value; }
generator.next(arg)
generator.return(value)

next resumes a generator. return completes it and runs finally. for…of break also closes the generator. Yielded objects share the closed-over binding.

ParameterDescription
argPassed to next after the first call, and received as the result of the previous yield.
valueThe completion value for return(), used as the result’s value when the generator finishes.

Returns: An iterator result object. After return or a completed function, done is true.

javascript
function* count() {
  try {
    yield 1;
    yield 2;
    yield 3;
  } finally {
    console.log("cleanup");
  }
}
const g = count();
console.log(g.next().value);
console.log(JSON.stringify(g.return(99)));
for (const value of count()) {
  console.log(value);
  break;
}

function* share() {
  const box = { n: 1 };
  yield box;
  yield box.n;
}
const s = share();
const first = s.next().value;
first.n = 8;
console.log(s.next().value);

function* feed() {
  const x = yield 1;
  yield x + 10;
}
const f = feed();
console.log(f.next().value);
console.log(f.next(5).value);

Expected output

1
cleanup
{"value":99,"done":true}
1
cleanup
8
1
15

Related: Iterator protocol, Official function*

MDN documentation →