Generators and Iterators

The iterator protocol is a simple contract: an object is an iterator if it has a next() method, and calling that method returns an object shaped like { value, done }. value is the next item in the sequence, and done is a boolean that becomes true once there's nothing left to produce. That's the entire contract — no special class or built-in type is required, just an object with the right method shape.

The iterable protocol builds on top of the iterator protocol: an object is iterable if it has a method at the special key Symbol.iterator, and calling that method returns an iterator (an object matching the shape above). Being iterable is what makes an object usable with for...of, the spread operator (...), destructuring, and Array.from().

You can make any object work with for...of by giving it a Symbol.iterator method that returns an iterator. This is exactly how you would implement a custom collection type — a linked list, a range, or a queue — that you want to feel like a first-class part of the language.

Writing the iterator protocol by hand every time is tedious. A generator function — declared with function* and using yield inside — does the same job with far less boilerplate. Calling a generator function does not run its body immediately; instead it returns a generator object, which is both an iterator and an iterable. Each call to .next() runs the function until it hits a yield, pauses there, and returns that yielded value.

The defining feature of a generator is that execution truly pauses at each yield and picks back up exactly where it left off on the next call to .next() — including any local variables and loop state. This makes generators well suited for representing sequences that are computed lazily, one step at a time, rather than all at once.

yield is a two-way street: not only does it produce a value out of the generator, but whatever you pass to the next .next() call becomes the result of that yield expression inside the generator body. This lets a generator receive input from the outside world at each pause point, not just emit values.

Generators are a natural fit for infinite sequences, since values are only computed as they are requested. You can safely define a generator that never runs out, and simply stop pulling values from it whenever you have enough.