Useful Cheatsheets
Build / Code / JavaScript

JavaScript Iterators

Understand iterables, the iteration protocol, generators, and async iteration with for await...of.

TL;DR

  1. Expose a next method returning value and done properties.
  2. Implement Symbol.iterator to make custom objects natively iterable.
  3. Use generator functions to construct custom iterables efficiently.
Jump to section

What Iterators Are

    Iterator definition

    Provides a next method returning value and done flags.

    const arr = [10, 20];
const it = arr[Symbol.iterator]();
it.next(); // { value: 10, done: false }
    Iteration state

    Tracks progress dynamically, returning done: true when complete.

    it.next(); // { value: 20, done: false }
it.next(); // { value: undefined, done: true }
    Underlying support

    Powers loops, spreads, and destructuring operations implicitly.

    const [x, y] = [10, 20]; // uses iterator

Iteration Protocol and Built-in Iterables

    Custom iterables

    Implements Symbol.iterator to make objects work with for-of.

    const obj = {
  data: [1, 2, 3],
  [Symbol.iterator]() {
    let i = 0;
    return { next: () => ({ value: this.data[i], done: i++ >= this.data.length }) };
  }
};
for (const n of obj) console.log(n);
    Required structures

    Demands the standard iterator method shape to match engine interfaces.

    // Iterator returns: { next() { ... } }
    Standard collections

    Provides native iteration for strings, arrays, sets, and maps.

    for (const char of "Hi!") console.log(char);
for (const val of new Set([1, 2])) console.log(val);
    Map entries

    Iterates over key-value pairs using array destructuring syntax.

    const map = new Map([['a', 1]]);
for (const [k, v] of map) console.log(k, v);
    DOM NodeLists

    Supports for-of iteration on elements retrieved from DOM queries.

    const divs = document.querySelectorAll("div");
for (const div of divs) console.log(div);

Generators

    Generator functions

    Pauses function execution using the yield keyword.

    function* greet() {
  const name = yield "name?";
  yield `Hello, ${name}!`;
}
const g = greet();
g.next().value; // "name?"
g.next("Ada").value; // "Hello, Ada!"
    Generator delegation

    Delegates execution to nested iterables using the yield* operator.

    function* combine() {
  yield* [1, 2];
  yield* ['a', 'b'];
}
console.log([...combine()]); // [1, 2, 'a', 'b']

Async Generator Functions

    async function*

    Yield awaited values one at a time, over time.

    async function* pages(url) {
  for (let n = url; n; ) {
    const p = await (await fetch(n)).json();
    yield p.items;
    n = p.nextUrl;
  }
}
    yield pauses

    Each yield pauses until the next next() call.

    async function* ticker() {
  yield 1;
  yield 2;
}
const t = ticker();
await t.next(); // { value: 1, done: false }
    Error propagation

    A thrown error surfaces where you consume it.

    async function* risky() {
  yield 1;
  throw new Error('boom');
}
try {
  for await (const v of risky()) console.log(v);
} catch (e) {
  console.log(e.message); // 1, then boom
}

The for await...of Loop

    for await...of

    Consume an async iterable with for await...of, awaiting each value automatically.

    async function run() {
  for await (const items of
    fetchPages('/api/items')) {
    console.log(items);
  }
}
    Waits per iteration

    The loop body only runs once the currently yielded promise resolves.

    async function* slowNums() {
  yield 1;
  await new Promise(r => setTimeout(r, 100));
  yield 2;
}
for await (const n of slowNums()) {
  console.log(Date.now(), n);
}
    Scope restriction

    for await...of only works inside an async function or a module's top level.

    async function readAll(stream) {
  for await (const chunk of stream) {
    process(chunk);
  }
}

Tips

  1. Use generator functions to implement the iteration contract automatically without manual state tracking.
  2. Delegate execution to nested iterables using yield* to simplify generator loop declarations.

Warnings

  1. Remember that exhausted iterators cannot be reused without obtaining a fresh iterator instance.
  2. Convert plain objects using Object.entries() before attempting loop iteration over them.

In Practice

FAQ