Iterators & Generators

The iteration protocol, custom iterables, generator functions, and lazy sequences in JavaScript.

What it is, in plain English: An iterator is any object with a next() method that returns {value, done} pairs. An iterable is any object that has a [Symbol.iterator]() method returning an iterator. Arrays, strings, Maps, Sets, and NodeLists are all iterables — that's why for...of works on them. A generator function (function*) is a special function that can pause mid-execution with yield, producing one value at a time. Generators are the easiest way to create custom iterables.

Where this bites you

Leaving a for...of loop early, with break, return or a thrown error, doesn't just stop the loop. It calls the iterator's return() method, and for a generator that means "finished for good". So if you pass the same generator to a helper like take() twice, the second call gets nothing, because the first call's break already closed it.

function* naturals(start = 0) {
  let n = start;
  while (true) {
    yield n++;
  }
}

function take(n, iterable) {
  const result = [];
  for (const val of iterable) {
    result.push(val);
    if (result.length >= n) break;     // break also CLOSES the generator
  }
  return result;
}

const ids = naturals(1);
console.log(take(3, ids));   // first page
console.log(take(3, ids));   // second page?
// [ 1, 2, 3 ]
// []

Iterators, iterables, and generator functions

You've used for...of loops to iterate over arrays and strings. But how does JavaScript know how to loop over them? The answer is the iteration protocol — a contract that any object can implement to become "loopable." Generator functions make implementing this contract easy.

The iteration protocol

An object is iterable if it has a [Symbol.iterator]() method that returns an iterator — an object with a next() method that returns { value, done } pairs.

// Arrays are built-in iterables:
const arr = [10, 20, 30];

// for...of uses the iterator protocol under the hood:
for (const n of arr) {
  console.log(n);   // 10, 20, 30
}

// You can call the protocol manually:
const iter = arr[Symbol.iterator]();
console.log(iter.next());  // { value: 10, done: false }
console.log(iter.next());  // { value: 20, done: false }
console.log(iter.next());  // { value: 30, done: false }
console.log(iter.next());  // { value: undefined, done: true }

Strings, Maps, Sets, NodeLists, and arguments objects are all built-in iterables. That's why for...of, spread (...), destructuring, and Array.from() all work on them.

Generator functions — the easy way to make iterables

Writing the iterator protocol by hand is verbose. Generator functions (function*) do it for you. A generator can yield a value and then pause — it resumes on the next .next() call.

// function* marks a generator function
function* countdown(from) {
  while (from > 0) {
    yield from;   // ← pause here, return 'from', wait for next .next()
    from--;
  }
  yield "Go!";
}

// A generator is automatically an iterable:
for (const value of countdown(3)) {
  console.log(value);  // 3, 2, 1, Go!
}

// Spread works too:
console.log([...countdown(3)]);  // [3, 2, 1, "Go!"]

A range generator — the most useful first generator

// Python has range(). JS doesn't — but you can write it:
function* range(start, end, step = 1) {
  for (let i = start; i <= end; i += step) {
    yield i;
  }
}

for (const n of range(1, 5)) {
  console.log(n);  // 1, 2, 3, 4, 5
}

console.log([...range(0, 10, 2)]);  // [0, 2, 4, 6, 8, 10]

// Works in destructuring:
const [first, second, third] = range(10, 50, 10);
console.log(first, second, third);  // 10 20 30

Infinite generators — safe because they're lazy

Generators produce values on demand — they don't calculate everything upfront. This makes infinite sequences safe (as long as you stop asking eventually):

// Infinite sequence — never ends, but that's fine:
function* naturals(start = 0) {
  let n = start;
  while (true) {
    yield n++;
  }
}

// Only take what you need:
function take(n, iterable) {
  const result = [];
  for (const val of iterable) {
    result.push(val);
    if (result.length >= n) break;
  }
  return result;
}

console.log(take(5, naturals()));      // [0, 1, 2, 3, 4]
console.log(take(5, naturals(100)));   // [100, 101, 102, 103, 104]

The take() above is fine when every call gets a fresh generator, as in take(5, naturals()). To keep pulling from the same generator, call next() yourself instead of looping with for...of. Calling next() never closes the generator, so the next call carries on where this one stopped:

function take(n, iterator) {
  const result = [];
  while (result.length < n) {
    const { value, done } = iterator.next();   // pull values without closing it
    if (done) break;
    result.push(value);
  }
  return result;
}

const ids = naturals(1);
console.log(take(3, ids));
console.log(take(3, ids));
// [ 1, 2, 3 ]
// [ 4, 5, 6 ]

Making your own iterable object

// Add [Symbol.iterator] to any object to make it iterable:
class NumberRange {
  constructor(start, end) {
    this.start = start;
    this.end   = end;
  }

  [Symbol.iterator]() {
    let current = this.start;
    const end   = this.end;
    return {
      next() {
        if (current <= end) {
          return { value: current++, done: false };
        }
        return { value: undefined, done: true };
      }
    };
  }
}

const nums = new NumberRange(1, 5);
console.log([...nums]);   // [1, 2, 3, 4, 5]

for (const n of nums) {
  console.log(n);  // 1, 2, 3, 4, 5
}

// Can iterate multiple times — each call to [Symbol.iterator]() creates a fresh iterator:
console.log([...nums]);   // [1, 2, 3, 4, 5] — works again

Try It Yourself

// Iterators — any object with a .next() method
function makeCounter(start, end) {
  let current = start;
  return {
    next() {
      if (current <= end) {
        return { value: current++, done: false };
      }
      return { value: undefined, done: true };
    }
  };
}

// Generators — function* with yield (much simpler to write)
function* range(start, end, step = 1) {
  for (let i = start; i <= end; i += step) {
    yield i;   // pause here, return i, resume on next .next() call
  }
}

// for...of uses the iterator protocol automatically
for (const n of range(1, 5)) {
  process?.stdout?.write(n + " ") || console.log(n);
}
console.log(); // newline

// Spread works too — materialize into an array
console.log([...range(0, 10, 2)]); // [0, 2, 4, 6, 8, 10]

// Infinite generator — only produces values on demand
function* naturals(start = 1) {
  let n = start;
  while (true) {
    yield n++;
  }
}

function take(n, iterable) {
  const result = [];
  for (const value of iterable) {
    result.push(value);
    if (result.length >= n) break;
  }
  return result;
}

console.log(take(5, naturals())); // [1, 2, 3, 4, 5] — safe, doesn't run forever

Two-way communication, delegating with yield*, and async generators

Sending values back into a generator

Generators are two-way channels — you can send values back in via next(value). The sent value becomes the result of the yield expression:

function* calculator() {
  let total = 0;
  while (true) {
    const input = yield total;   // pause; 'input' = value sent to .next()
    if (input === null) break;
    total += input;
  }
  return total;
}

const calc = calculator();
calc.next();         // start the generator (runs to first yield)
calc.next(10);       // sends 10 in; total = 10
calc.next(20);       // sends 20 in; total = 30
const { value } = calc.next(null);  // stops, returns final total
console.log(value);  // 30

yield* — delegating to another iterable

function* inner() {
  yield "a";
  yield "b";
}

function* outer() {
  yield 1;
  yield* inner();   // delegate — yield all values from inner()
  yield* [2, 3];    // yield* works with any iterable
  yield 4;
}

console.log([...outer()]);  // [1, "a", "b", 2, 3, 4]

// Useful for flattening nested iterables:
function* flatten(iterable, depth = Infinity) {
  for (const item of iterable) {
    if (depth > 0 && typeof item[Symbol.iterator] === "function" && typeof item !== "string") {
      yield* flatten(item, depth - 1);
    } else {
      yield item;
    }
  }
}

console.log([...flatten([1, [2, [3, [4]]]])]);  // [1, 2, 3, 4]

Async generators and for await...of

// Async generator — yields Promises; for await...of handles the awaiting:
async function* paginate(url, pageSize = 10) {
  let page = 1;
  while (true) {
    const res  = await fetch(`${url}?page=${page}&limit=${pageSize}`);
    const data = await res.json();
    if (data.length === 0) return;
    yield data;
    page++;
  }
}

// Process each page of results without loading all pages into memory first:
for await (const page of paginate("/api/items")) {
  page.forEach(item => console.log(item.name));
  // Each page is processed before the next fetch begins
}

Generator-based state machines

// A traffic light state machine:
function* trafficLight() {
  while (true) {
    yield "green";   // go
    yield "yellow";  // slow down
    yield "red";     // stop
  }
}

const light = trafficLight();
console.log(light.next().value);  // "green"
console.log(light.next().value);  // "yellow"
console.log(light.next().value);  // "red"
console.log(light.next().value);  // "green" — cycles forever

Generator internals, the GeneratorState slot, and coroutines

Generator execution model (ECMA-262 §27.5)

A generator function, when called, does not execute its body. Instead it creates a Generator object with internal slots: [[GeneratorState]] (one of "suspended-start", "suspended-yield", "executing", "completed") and [[GeneratorContext]] (the saved execution context — the entire call stack frame, including locals and the program counter position). Each next() call:

Pushes [[GeneratorContext]] back onto the execution context stack
Sets [[GeneratorState]] to "executing"
Resumes execution from the saved PC
When the next yield is hit: saves the context, sets state to "suspended-yield", returns { value: yielded, done: false }
When return or the function end is reached: sets state to "completed", returns { value: returnValue, done: true }

Generator as coroutine

Generators are symmetric coroutines — control passes between the caller and the generator via yield/next. This is how early async libraries (co, redux-saga) worked before async/await: the scheduler called gen.next(resolvedValue) whenever a Promise resolved, making async code look synchronous inside the generator body.

// The original async/await polyfill pattern (generators + Promises):
function run(genFn) {
  const gen = genFn();
  function step({ value, done }) {
    if (done) return Promise.resolve(value);
    return Promise.resolve(value).then(
      resolved => step(gen.next(resolved)),
      error    => step(gen.throw(error))
    );
  }
  return step(gen.next());
}

// This is what async/await desugars to under the hood:
run(function* () {
  const data = yield fetch("/api/data").then(r => r.json());
  console.log(data);
});

Iterator helpers (TC39 Stage 4, ES2025)

// Iterator.prototype now has map, filter, take, drop, flatMap, reduce, toArray:
const result = Iterator.from([1,2,3,4,5,6,7,8,9,10])
  .filter(n => n % 2 === 0)   // lazy — no intermediate array
  .map(n => n ** 2)
  .take(3)
  .toArray();

console.log(result);  // [4, 16, 36]
// Without toArray(), the chain is lazy — no work done until consumed

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.