Flatten nested iterables

An iterator hands out values one at a time: each call to its next() method returns an object like { value: 1, done: false }, until one says done: true. for...of, spread, and destructuring all read values by calling next(). Often the code reading stops before the end, such as a loop that breaks once it finds what it wanted. Closing the iterator means telling it that no more values will be asked for, so it can clean up: stop a timer, close a connection, release a lock. The iteration protocol, the shape every iterator follows, has an optional method for that: return().

It's like telling a waiter you've had enough before the last course: the kitchen stops cooking for you and clears up, instead of keeping your table laid all night.

function* lines() {
  console.log("open");
  try {
    yield "first";
    yield "second";
    yield "third";
  } finally {
    console.log("close"); // runs however the generator ends
  }
}
 
for (const line of lines()) {
  console.log(line);
  if (line === "second") break;
}
// logs open, first, second, close: break called return(), which ran the finally block
 
const [first] = lines();
// logs open, close: destructuring read one value, then closed the generator
 
const manual = lines();
manual.next();            // logs open; { value: "first", done: false }
// nothing closes manual for you: it stays paused at its first yield
manual.return("stopped"); // logs close; { value: "stopped", done: true }
manual.next();            // { value: undefined, done: true }

On a generator, return() resumes it at the yield where it's paused, as if that yield were a return statement. The generator ends there, but its finally blocks run on the way out, so cleanup written in a finally happens however the generator stops. A generator that hasn't started, because next() was never called, finishes at once: its body never runs, so it has nothing to clean up. Calling return() on a generator that has already finished changes nothing.

return() is optional. Array, string, Map, and Set iterators don't have one, since they hold nothing that needs releasing: [1, 2][Symbol.iterator]().return is undefined. So code that closes an iterator calls return() only when it exists. Generators, sync and async, always have one, and an iterator you write by hand can have one too.

You rely on closing whenever a generator holds something open: a loop over it can break early, and the generator still tidies up. Code that reads from an iterator and stops before the end is expected to do what for...of does, and close it.

Lazy evaluation means working out a value only when something asks for it. The opposite, eager evaluation, does all the work up front. Array methods are eager: numbers.map(double) calls double on every element at once, and builds the whole new array before the next line runs. A generator is lazy, or pull-based: the code that reads it pulls each value when it wants one. Until then, the generator does nothing; asked for a value, it works out that one value and pauses again.

Think of a café that makes each coffee when it's ordered, next to one that makes a hundred at opening time. The first never wastes a cup and can keep serving all day. The second has everything ready, but pours away whatever nobody orders.

// Eager: squares every number before looking for one over 10
const numbers = Array.from({ length: 1_000_000 }, (_, i) => i + 1);
numbers.map((n) => n * n).find((n) => n > 10); // 16, after 1,000,000 squarings
 
// Lazy: squares a number only when the loop asks for the next one
function* squares() {
  for (let n = 1; ; n++) {
    console.log("squaring", n);
    yield n * n;
  }
}
 
const sequence = squares(); // logs nothing: no square has been asked for yet
for (const square of sequence) {
  if (square > 10) break;
}
// logs squaring 1, squaring 2, squaring 3, squaring 4, then stops at 16

squares never ends: its loop has no condition. As an array, it could never be built. As a generator, it's fine, because the loop reading it decides how many values to take.

Those last rows are the costs. A lazy sequence doesn't know how long it is until it has been read to the end, which for an endless one is never. A generator object can be read only once: spread it to the end, and spreading it again gives [], so to read the values again you call the generator function for a new one. And work happens later than the code that sets it up: calling squares() ran none of its body, so its logging, and any error it throws, comes only when a value is pulled, maybe far from where the sequence was created.

You meet laziness in generators, in the iterator helpers built into current browsers and Node, such as map, filter, and take on iterators, which pass values along one at a time, and in streams, which handle data a chunk at a time instead of all at once. The same idea, putting work off until it's needed, is behind loading="lazy" on images and React.lazy for loading a component's code.