Iterators and the iteration protocol

Why learn the protocol?

You have used for…of on arrays, strings, Maps and Sets. How does one loop work on such different things? Each of them follows the same small agreement, the iteration protocol. Once you know it, you can make your own objects work with for…of, spread and destructuring, and you understand generators (next topic) and many library APIs.

Iterator: an object with next()

An iterator is an object with a next() method. Each call returns an object with two properties: value (the next item) and done (true when there are no more items).

const it = ['tea', 'coffee'][Symbol.iterator]();
console.log(it.next()); // { value: 'tea', done: false }
console.log(it.next()); // { value: 'coffee', done: false }
console.log(it.next()); // { value: undefined, done: true }

Iterable: an object that can give an iterator

An iterable is any object with a method stored under the special key Symbol.iterator. That method returns a fresh iterator. Symbol.iterator is a built-in symbol: a unique key that cannot clash with normal string keys.

for (const x of thing) does this: call thing[Symbol.iterator]() to get an iterator, then call next() again and again, giving you each value, until done is true.

Making your own iterable

const range = {
  from: 1,
  to: 5,
  [Symbol.iterator]() {
    let current = this.from;
    const last = this.to;
    return {
      next() {
        return current <= last
          ? { value: current++, done: false }
          : { value: undefined, done: true };
      },
    };
  },
};
console.log([...range]);          // [1, 2, 3, 4, 5]
for (const n of range) console.log(n);
const [first, second] = range;    // 1, 2

Who uses the protocol?

• for…of loops
• Spread in arrays and calls: [...x], Math.max(...x)
• Array destructuring: const [a, b] = x
• Array.from(x), new Map(x), new Set(x), Promise.all(x)

Iterables are lazy

An iterator produces values one at a time, only when asked. That means it can represent a sequence that is huge or even endless, as long as the consumer stops asking. A plain array, in contrast, must hold every element in memory at once.

Iterator helpers

ES2025 added helper methods directly on iterators: map, filter, take, drop, toArray and more, for example map.keys().filter(...).toArray(). They work lazily, item by item. They are in current browsers and Node; check MDN compatibility if you support older ones.