Skip to content
FEE
Frontend Engineering Essentials
Mid Level

[FEE-308] Iterators, Generators & Async Iteration ​

INFO

JavaScript arrays have always been iterable with for loops, but Maps, Sets, custom data structures, and asynchronous data sources needed a universal contract for sequential access. ES2015 introduced the iteration protocols -- Symbol.iterator and the { next() } interface -- giving every data structure a single, composable way to produce values on demand. ES2018 extended this to asynchronous sources with Symbol.asyncIterator and for await...of. Understanding these protocols is essential because they underpin for...of, spread syntax, destructuring, Array.from(), Promise.all(), and the entire Web Streams API.

Context ​

Before ES2015, iterating over different data structures required different mechanisms. Arrays used index-based for loops. Objects used for...in (which enumerates all enumerable properties, including inherited ones). NodeList required converting to an array or using Array.prototype.forEach.call(). There was no uniform way to say "this thing produces a sequence of values."

The iteration protocols solved this by defining two complementary contracts:

  1. The iterable protocol -- an object implements [Symbol.iterator]() to declare that it can produce a sequence.
  2. The iterator protocol -- the returned object has a next() method that returns { value, done }.

Built-in iterables include Array, String, Map, Set, TypedArray, arguments, NodeList, URLSearchParams, FormData, and Headers. Any custom object can become iterable by implementing Symbol.iterator.

ES2015 also introduced generator functions (function*) -- a syntactic shortcut for creating iterators. Generators pause execution at each yield and resume when next() is called, making them ideal for lazy sequences.

ES2018 extended the model to asynchronous data with the async iteration protocol: Symbol.asyncIterator, for await...of, and async function*. This enables pull-based consumption of data that arrives over time -- paginated APIs, streaming responses, file chunks, and WebSocket messages.

Scenario ​

You are building a pagination feature that fetches the next page of results when the user scrolls near the bottom. The current implementation couples the fetching logic, the cursor tracking, and the rendering into a single scroll handler, making it hard to test the fetching logic in isolation. A generator function can model the sequence of pages as a lazy iterator — yielding one page at a time, maintaining cursor state internally, and separating the production of pages from their consumption.

Design Thinking ​

Why JS adopted the iterator protocol ​

The core motivation was uniform interface: one protocol that works for Arrays, Maps, Sets, Strings, TypedArrays, DOM collections, and any custom structure. Before this, every library invented its own traversal API. The iterator protocol lets language constructs -- for...of, spread, destructuring, Array.from(), Promise.all(), Map() constructor -- work with any iterable without knowing its internal structure.

Lazy evaluation was the second motivation. An iterator produces values one at a time, on demand. A range from 1 to 1,000,000 does not need to allocate an array of 1,000,000 elements -- it produces each number only when next() is called. This matters for memory-constrained environments and infinite sequences (Fibonacci, sensor readings, event streams).

Composability was the third goal. Because every iterable conforms to the same protocol, generic utilities -- map, filter, take, zip -- can be written once and work with any source. The TC39 Iterator Helpers proposal (shipping in V8 v12.2+) adds these methods directly to Iterator.prototype.

Pull vs push models ​

Iterators implement a pull model: the consumer decides when to get the next value by calling next(). The producer is passive -- it waits until asked. This gives the consumer full control over backpressure and timing.

The alternative is a push model: the producer decides when to emit values. Callbacks, EventEmitter, and Observables (RxJS) follow this pattern. The producer pushes data whether the consumer is ready or not, requiring buffering or dropping strategies.

The distinction matters for async data:

AspectPull (Iterator)Push (Observable/EventEmitter)
ControlConsumer calls next()Producer emits events
BackpressureBuilt-in (consumer controls pace)Requires explicit handling
Cancellationreturn() on iteratorunsubscribe() / removeListener()
Use casePaginated API, file chunksDOM events, WebSocket messages

Async iterators bridge the two: the consumer pulls with next(), but next() returns a Promise, allowing the producer to resolve it when data is ready. This gives pull-based backpressure with asynchronous delivery.

Web platform iterables ​

The iteration protocol is deeply integrated into the web platform:

  • ReadableStream implements Symbol.asyncIterator (WHATWG Streams spec). You can consume a fetch response body with for await (const chunk of response.body) instead of manually managing readers.
  • URLSearchParams, FormData, and Headers implement Symbol.iterator, yielding [key, value] pairs -- matching Map's iteration behavior.
  • NodeList is iterable, so for (const el of document.querySelectorAll('div')) works without conversion.

Framework streaming patterns ​

Modern frameworks leverage async iteration for streaming server-side rendering:

  • React -- renderToPipeableStream() produces a Node.js readable stream for streaming SSR. React Server Components can be async (returning Promises), and the server streams HTML chunks as components resolve, enabling progressive hydration.
  • Astro Islands -- Astro streams the HTML shell immediately, then streams each island component as it resolves. Non-critical islands can be deferred with client:idle or client:visible, and the streamed HTML includes inline scripts that hydrate each island independently.
  • Next.js -- App Router uses React Suspense boundaries to stream content progressively. Each <Suspense> boundary becomes a streaming chunk. The loading.js convention automatically wraps route segments in Suspense.

These patterns all rely on the same fundamental concept: producing data incrementally (streaming/iteration) rather than buffering everything before sending.

Best Practices ​

Prefer for...of over the manual iterator protocol. SHOULD consume iterables with for...of, spread syntax, or destructuring rather than calling .next() manually. When a for...of loop exits early via break or return, the runtime automatically calls iterator.return() on the iterator, allowing it to release resources held in finally blocks. Manual .next() calls do not trigger this cleanup unless you call .return() explicitly.

Always use try/finally in generators that hold resources. MUST wrap resource acquisition in a generator's try block and place the corresponding release in finally. The finally block runs when the generator completes normally, when it throws, and when generator.return() is called externally — including the call made by for...of on early exit. Without finally, resources such as open connections, file handles, or subscriptions will leak when the consumer breaks early.

Use Symbol.asyncIterator for streaming and push-based data sources. SHOULD implement Symbol.asyncIterator on objects that produce values asynchronously over time — paginated API responses, WebSocket message streams, SSE connections, and ReadableStream wrappers. An async iterable is consumable with for await...of, which provides pull-based backpressure: the producer only advances when the consumer calls next(), preventing unbounded buffering.

Avoid infinite generators without explicit termination conditions for the consumer. SHOULD pair every infinite generator (while (true) { yield ... }) with a consumer-side limit such as break, a take(n) wrapper, or a termination signal. An infinite generator that is never terminated prevents the generator function from being garbage-collected and can accumulate state indefinitely. When an infinite generator is intended, document the termination contract clearly.

Visual ​

The following sequence diagram shows how a consumer interacts with an iterator through the next() protocol:

The consumer drives the interaction. Each call to next() pulls one value. When done is true, the sequence is exhausted. If the consumer breaks out of the loop early, for...of automatically calls iterator.return() (if it exists), giving the iterator a chance to release resources.

Example ​

1. Custom iterable Range class (lazy number production) ​

js
class Range {
  constructor(start, end, step = 1) {
    this.start = start;
    this.end = end;
    this.step = step;
  }

  // Implement the iterable protocol
  [Symbol.iterator]() {
    let current = this.start;
    const { end, step } = this;

    return {
      next() {
        if (current <= end) {
          const value = current;
          current += step;
          return { value, done: false };
        }
        return { value: undefined, done: true };
      },

      // Make the iterator itself iterable (best practice)
      [Symbol.iterator]() {
        return this;
      }
    };
  }
}

// Works with for...of
for (const n of new Range(1, 5)) {
  console.log(n); // 1, 2, 3, 4, 5
}

// Works with spread
const nums = [...new Range(0, 100, 10)]; // [0, 10, 20, ..., 100]

// Works with destructuring
const [first, second, third] = new Range(10, 50, 10);
// first = 10, second = 20, third = 30

// Works with Array.from
const arr = Array.from(new Range(1, 5)); // [1, 2, 3, 4, 5]

2. Generator for Fibonacci (infinite lazy sequence) ​

js
function* fibonacci() {
  let a = 0;
  let b = 1;
  while (true) {
    yield a;
    [a, b] = [b, a + b];
  }
}

// Take only the first 10 values -- the generator never computes more
function take(n, iterable) {
  const result = [];
  for (const value of iterable) {
    result.push(value);
    if (result.length >= n) break; // triggers generator.return()
  }
  return result;
}

console.log(take(10, fibonacci()));
// [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]

// Generator delegation with yield*
function* range(start, end) {
  for (let i = start; i <= end; i++) yield i;
}

function* concatenated() {
  yield* range(1, 3);   // yields 1, 2, 3
  yield* range(10, 12); // yields 10, 11, 12
}

console.log([...concatenated()]); // [1, 2, 3, 10, 11, 12]

// Generators support two-way communication
function* accumulator() {
  let total = 0;
  while (true) {
    const value = yield total; // yield current total, receive next value
    total += value;
  }
}

const acc = accumulator();
acc.next();       // { value: 0, done: false } -- primes the generator
acc.next(10);     // { value: 10, done: false }
acc.next(20);     // { value: 30, done: false }
acc.next(5);      // { value: 35, done: false }

3. Async generator for paginated API with for await...of ​

js
// Async generator: fetches pages on demand (pull-based)
async function* fetchPages(baseUrl) {
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(`${baseUrl}?page=${page}&limit=50`);
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    const data = await response.json();
    yield* data.items; // yield each item individually

    hasMore = data.hasNextPage;
    page++;
  }
}

// Consumer controls the pace -- no unnecessary fetches
async function findUser(name) {
  for await (const user of fetchPages("/api/users")) {
    if (user.name === name) {
      return user; // breaks the loop, stops fetching further pages
    }
  }
  return null;
}

// Streaming response body as async iterable
async function streamResponse(url) {
  const response = await fetch(url);
  const decoder = new TextDecoder();
  let fullText = "";

  // ReadableStream implements Symbol.asyncIterator
  for await (const chunk of response.body) {
    fullText += decoder.decode(chunk, { stream: true });
    updateUI(fullText); // progressive rendering
  }

  fullText += decoder.decode(); // flush remaining bytes
  return fullText;
}

// Async generator with cleanup (try/finally)
async function* watchEvents(url) {
  const eventSource = new EventSource(url);
  const queue = [];
  let resolve;
  let pending = new Promise(r => (resolve = r));

  eventSource.onmessage = (event) => {
    queue.push(JSON.parse(event.data));
    resolve();
    pending = new Promise(r => (resolve = r));
  };

  try {
    while (true) {
      await pending;
      while (queue.length > 0) {
        yield queue.shift();
      }
    }
  } finally {
    // Cleanup runs when consumer breaks or calls return()
    eventSource.close();
  }
}

// Usage: loop automatically calls return() on break
for await (const event of watchEvents("/api/events")) {
  console.log(event);
  if (event.type === "done") break; // triggers finally block
}

Deep Dive ​

Generator delegation with yield* and method propagation ​

yield* delegates iteration to another iterable or generator, forwarding each yielded value to the outer consumer. What is less obvious is that all three generator control methods -- next(), throw(), and return() -- are forwarded through the delegation chain to the innermost generator.

return() propagation: When the outer consumer calls generator.return(value), yield* forwards the return() call to the currently delegated iterator. If that iterator defines return(), it is invoked, which triggers any finally block inside the inner generator. The inner generator closes, and control returns to the outer generator, which then also closes. This means that a break or early return in a for...of loop correctly cleans up resources across all levels of a yield* chain.

throw() propagation: When the consumer calls generator.throw(error), yield* forwards the throw() call to the delegated iterator. If the inner generator has a try/catch at the current yield, it can catch the error and continue. If the inner generator does not handle it, the error propagates back to the outer generator's yield* expression, where the outer generator's try/catch can handle it. If neither handles it, it becomes an unhandled exception.

yield* return value: The expression yield* innerGen() itself evaluates to the return value of the inner generator (the value in { value: ..., done: true } from the inner generator's final return statement). This allows composing pipelines where each generator stage can pass a result to the next.

js
function* inner() {
  yield 1;
  yield 2;
  return "inner done"; // the return value of the inner generator
}

function* outer() {
  const result = yield* inner(); // result === "inner done"
  console.log("inner returned:", result);
  yield 3;
}

console.log([...outer()]); // [1, 2, 3]
// "inner returned: inner done" is logged during iteration

Understanding this propagation model matters when composing generator pipelines that manage resources: a break at the top of the chain correctly threads return() all the way down, triggering finally blocks in every level.

Common Mistakes ​

1. Forgetting generators are lazy -- they do not execute until next() is called ​

js
function* processItems(items) {
  console.log("Generator started!"); // never runs if next() is never called
  for (const item of items) {
    console.log(`Processing ${item}`);
    yield transform(item);
  }
  console.log("Generator finished!");
}

// BAD: assuming the generator runs immediately
const gen = processItems(["a", "b", "c"]);
// Nothing logged! The function body has not executed yet.

// The body runs incrementally as you call next()
gen.next(); // NOW "Generator started!" and "Processing a" are logged
gen.next(); // "Processing b" is logged
// "Processing c" and "Generator finished!" only run if you continue iterating

// FIX: if you need eager execution, use a regular function
// and collect results into an array. Use generators when you
// want lazy, on-demand evaluation.

2. Not calling return() when breaking early (resource leaks) ​

js
// A generator that opens a resource
function* readLines(filePath) {
  const handle = openFile(filePath);
  try {
    let line;
    while ((line = handle.readLine()) !== null) {
      yield line;
    }
  } finally {
    handle.close(); // critical cleanup
    console.log("File handle closed");
  }
}

// GOOD: for...of calls return() automatically on break
for (const line of readLines("/data/log.txt")) {
  if (line.includes("ERROR")) {
    console.log(line);
    break; // for...of calls generator.return() -> finally block runs
  }
}

// BAD: manual iteration without calling return()
const gen = readLines("/data/log.txt");
const first = gen.next(); // file opened, first line read
// If you stop here without calling gen.return(), the finally block
// never runs and the file handle leaks!

// FIX: always use for...of, or call return() manually
gen.return(); // forces the finally block to execute

3. Confusing for...in (keys, includes prototype) with for...of (values, iterator protocol) ​

js
const arr = ["a", "b", "c"];
arr.customProp = "oops";

// for...in: enumerates enumerable property KEYS (including inherited)
for (const key in arr) {
  console.log(key); // "0", "1", "2", "customProp"
  // Strings, not numbers! Includes the custom property.
}

// for...of: consumes the iterable protocol -- yields VALUES
for (const value of arr) {
  console.log(value); // "a", "b", "c"
  // No "customProp" -- only the iterable sequence.
}

// Objects are NOT iterable by default
const obj = { x: 1, y: 2 };
// for (const v of obj) {} // TypeError: obj is not iterable

// FIX: use Object.entries() which returns an iterable
for (const [key, value] of Object.entries(obj)) {
  console.log(key, value); // "x" 1, "y" 2
}

4. Array.from() or spread on huge iterables defeats lazy evaluation ​

js
function* hugeRange(n) {
  for (let i = 0; i < n; i++) yield i;
}

// BAD: materializes 10 million elements into memory
const allNumbers = [...hugeRange(10_000_000)]; // ~80 MB for 10M numbers
const filtered = allNumbers.filter(n => n % 1000 === 0);

// GOOD: stay lazy with generator composition
function* filter(predicate, iterable) {
  for (const value of iterable) {
    if (predicate(value)) yield value;
  }
}

function* take(n, iterable) {
  let count = 0;
  for (const value of iterable) {
    yield value;
    if (++count >= n) return;
  }
}

// Only 10 values ever exist in memory at once
const result = [
  ...take(10, filter(n => n % 1000 === 0, hugeRange(10_000_000)))
];
// [0, 1000, 2000, 3000, 4000, 5000, 6000, 7000, 8000, 9000]

// BETTER (ES2025+): use built-in Iterator Helpers
const result2 = hugeRange(10_000_000)
  .filter(n => n % 1000 === 0)
  .take(10)
  .toArray();

5. Not handling errors in async generators ​

js
async function* fetchStream(url) {
  const response = await fetch(url);
  for await (const chunk of response.body) {
    yield chunk;
  }
}

// BAD: network errors crash the process
async function consume() {
  for await (const chunk of fetchStream("/api/stream")) {
    process(chunk); // if fetch fails or stream errors, unhandled rejection
  }
}

// GOOD: wrap in try/catch, handle both fetch and stream errors
async function consumeSafely() {
  try {
    for await (const chunk of fetchStream("/api/stream")) {
      process(chunk);
    }
  } catch (error) {
    if (error.name === "AbortError") {
      console.log("Stream aborted");
    } else {
      console.error("Stream error:", error);
      // retry logic, fallback, or graceful degradation
    }
  }
}

// You can also throw errors INTO a generator
async function* resilientStream(url, maxRetries = 3) {
  let retries = 0;
  while (retries < maxRetries) {
    try {
      const response = await fetch(url);
      for await (const chunk of response.body) {
        yield chunk;
      }
      return; // stream completed successfully
    } catch (error) {
      retries++;
      if (retries >= maxRetries) throw error;
      await new Promise(r => setTimeout(r, 1000 * retries)); // backoff
    }
  }
}
  • FEE-300 -- JavaScript Core & Runtime Overview: iterators are part of the core language runtime
  • FEE-301 -- Event Loop & Task Queues: async iteration scheduling -- for await...of uses microtasks to resolve each next() Promise
  • FEE-303 -- Prototypes & Inheritance: Symbol.iterator is defined on prototype objects (Array.prototype, Map.prototype, etc.)
  • FEE-307 -- ES Modules & Module Systems: dynamic import() returns a Promise, connecting to async patterns

References ​