Iterators & the Iteration Protocol

"The three chief virtues of a programmer are: Laziness, Impatience and Hubris." — Larry Wall

Parts I–III took you through the language itself, the engine that runs it, and the asynchronous machinery that keeps it responsive. Part IV is about something you do in almost every function you write: iterate over data and transform it. And it opens with the quiet contract that makes half of modern JavaScript's syntax work. When you write for (const x of thing), or [...thing], or const [a, b] = thing, you are not using magic reserved for arrays — you are speaking a protocol that any object can implement. Learn the protocol once and a dozen features stop being special cases and become the same idea. Interviewers know this, which is why "make this object work with for...of" is such a revealing question.

Core Concepts

There are two protocols, and they interlock. Keep them separate in your head and everything else falls into place.

The iterable protocol: an object is iterable if it has a method under the special key Symbol.iterator. Calling that method returns an iterator. Symbol.iterator is a well-known symbol — a unique, unforgeable key — so it never clashes with your own property names.

The iterator protocol: an iterator is any object with a next() method. Each call to next() returns a result object { value, done }. While there's more to produce, done is false and value holds the next item. When the sequence is exhausted, next() returns { value: undefined, done: true }, and by convention stays that way forever after.

That's the whole machine. An iterable knows how to produce an iterator; the iterator produces values one at a time and announces when it's finished.

Driving an iterator by hand

Every consumer you'll meet is really just calling next() in a loop. Do it manually once and the abstraction dissolves. (We print the fields directly so the output is exact regardless of how a console formats objects — but each next() genuinely returns an object shaped { value, done }.)

Notice the array itself is not the iterator — letters[Symbol.iterator]() hands you a separate cursor. The array is the iterable; the cursor is the iterator.

What the built-ins give you for free

Many built-in types ship a [Symbol.iterator] already. That single fact is why they all cooperate with the same syntax. Plain objects ({}) are the notable exception — they are not iterable.

What actually consumes iterables

None of these features special-case arrays. Under the hood, each one calls [Symbol.iterator]() and then drains the iterator with next():

• for...of loops
• spread into an array or call: [...it], fn(...it)
• array/Set/Map destructuring: const [first, second] = it
• Array.from(it), new Set(it), new Map(it)
• Promise.all, Promise.race, Promise.allSettled, Promise.any
• yield* delegation inside a generator

So when you make your own object iterable, all of that lights up at once — for free.

Writing a custom iterable by hand

Here's the pay-off. Let's make a range(start, end) object that produces the numbers from start up to (but not including) end. We give it a [Symbol.iterator]() method that returns a fresh iterator each time — an object with a next():

Because [Symbol.iterator]() returns a new iterator (with its own current) on every call, range(1, 5) is reusable — you can loop it, spread it, and destructure it independently. That is exactly how the built-ins behave.

Lazy, one value at a time — and infinite sequences

An iterator computes each value on demand, only when next() is called. Nothing forces it to hold the whole sequence in memory, and nothing forces it to be finite. Here is an infinite iterator of the natural numbers — legal precisely because values are produced lazily:

naturals() would loop forever, yet it costs almost nothing: at any instant only one number exists. Laziness is what lets you model unbounded streams — lines from a file, pages from an API, ticks of a clock — without ever "materialising" them.

The one-shot gotcha

An iterator is a cursor, and a cursor only moves forward. Once fully consumed it is exhausted — draining it again yields nothing. This bites people who spread the same live iterator twice:

The array nums is still full — it's the iterator it that got used up. This is also why an object that returns this from [Symbol.iterator]() (like naturals above) can only be looped once. Reusable iterables dodge this by returning a brand-new iterator each time, which is exactly what range did.

Common Mistakes

• Confusing for...in with for...of. for...in walks enumerable keys (and inherited ones); for...of walks values of an iterable. Using for...in on an array is a classic, subtle bug.
• Expecting plain objects to be iterable. for (const x of {a: 1}) throws — objects have no [Symbol.iterator]. Iterate Object.keys/values/entries(obj) instead (those return arrays, which are iterable).
• Reusing an exhausted iterator. After a full for...of or spread, a raw iterator is spent. Get a fresh one from the iterable for a second pass.
• Returning this from [Symbol.iterator]() when you need reusability. That makes the object its own iterator — fine for one-shot streams, but it can only be traversed once.
• Forgetting to signal done. An iterator whose next() never returns { done: true } will hang any for...of, spread, or Promise.all that consumes it — an infinite loop with no break.
• Assuming string length equals character count. Strings iterate by code point, but .length counts UTF-16 units, so '👋'.length is 2 while [...'👋'].length is 1.

Interview Corner

Chapter Summary

• Two protocols interlock: an iterable has [Symbol.iterator]() returning an iterator; an iterator has next() returning { value, done }.
• Iteration ends when next() returns done: true, and a spent iterator stays spent — it's a forward-only cursor.
• Array, String, Map, Set, arguments, and NodeList are iterable out of the box; plain objects are not.
• for...of, spread, destructuring, Array.from, new Set/Map, and Promise.all all consume iterables by calling [Symbol.iterator]() under the hood.
• You make any object iterable by hand — a [Symbol.iterator]() returning an object with next() — but it's verbose and easy to get subtly wrong.
• Iterators are lazy: one value at a time, computed on demand, which makes infinite sequences legal and huge ones cheap.
• Return a fresh iterator each call for reusability; return this for a single-use stream.

Editorial reflection — the iteration protocol is a small idea with an outsized reach: one method name, one result shape, and suddenly arrays, strings, maps, sets, DOM lists, and anything you dream up all speak the same language to the same syntax. That is what good abstractions do — they don't add features, they remove special cases. Learn to see the protocol beneath the syntax, and for...of stops being a loop you memorised and becomes a contract you can extend.