JavaScript Generators Deep Dive Full Guide

Master JavaScript generators for lazy evaluation, coroutines, and async control flow. Covers generator functions, yield expressions, iterator protocol, delegation with yield*, infinite sequences, two-way communication, async generators, cancellation patterns, and real-world pipeline architectures.

JavaScriptadvanced

RuneHub Team

March 5, 2026

19 min read

RuneHub Team

Mar 5, 2026

19 min read

Generator functions produce iterators that pause and resume execution at yield points. They enable lazy evaluation, two-way communication between caller and generator, and elegant async control flow patterns that fundamentally change how you structure JavaScript programs.

For related async patterns, see Call Stack vs Task Queue vs Microtask Queue.

Generator Function Basics

javascript

// Generator functions are declared with function*
function* countUp(start = 0) {
  let current = start;
  while (true) {
    yield current;
    current++;
  }
}
 
// Calling a generator function returns a generator object (iterator)
const counter = countUp(1);
 
// .next() resumes execution until the next yield
console.log(counter.next()); // { value: 1, done: false }
console.log(counter.next()); // { value: 2, done: false }
console.log(counter.next()); // { value: 3, done: false }
 
// Generators are lazy: values are computed only when requested
// This infinite generator uses constant memory
 
// FINITE GENERATORS
function* range(start, end, step = 1) {
  for (let i = start; i < end; i += step) {
    yield i;
  }
  // Implicit return undefined -> { value: undefined, done: true }
}
 
const nums = range(0, 5);
console.log([...nums]); // [0, 1, 2, 3, 4]
 
// RETURN VALUE
function* withReturn() {
  yield 1;
  yield 2;
  return 3; // return value appears in the final { value: 3, done: true }
}
 
const gen = withReturn();
console.log(gen.next()); // { value: 1, done: false }
console.log(gen.next()); // { value: 2, done: false }
console.log(gen.next()); // { value: 3, done: true }
console.log(gen.next()); // { value: undefined, done: true }
 
// NOTE: Spread and for...of ignore the return value
console.log([...withReturn()]); // [1, 2] (NOT [1, 2, 3])
 
for (const val of withReturn()) {
  console.log(val); // 1, 2 (NOT 3)
}
 
// GENERATOR EXPRESSIONS (not standalone, but as methods)
const obj = {
  *items() {
    yield "a";
    yield "b";
    yield "c";
  }
};
 
console.log([...obj.items()]); // ["a", "b", "c"]
 
// CLASS GENERATORS
class Collection {
  #data;
 
  constructor(...items) {
    this.#data = items;
  }
 
  *[Symbol.iterator]() {
    for (const item of this.#data) {
      yield item;
    }
  }
 
  *reversed() {
    for (let i = this.#data.length - 1; i >= 0; i--) {
      yield this.#data[i];
    }
  }
 
  *filter(predicate) {
    for (const item of this.#data) {
      if (predicate(item)) yield item;
    }
  }
}
 
const coll = new Collection(10, 20, 30, 40, 50);
console.log([...coll]);                        // [10, 20, 30, 40, 50]
console.log([...coll.reversed()]);             // [50, 40, 30, 20, 10]
console.log([...coll.filter(x => x > 25)]);   // [30, 40, 50]

Two-Way Communication

javascript

// yield is an EXPRESSION: it receives the value passed to .next()
// The first .next() call starts the generator; its argument is discarded
 
function* calculator() {
  let result = 0;
 
  while (true) {
    const input = yield result; // yield current result, receive next input
 
    if (input === null) break;
 
    if (typeof input === "number") {
      result += input;
    } else if (typeof input === "object") {
      switch (input.op) {
        case "add": result += input.value; break;
        case "sub": result -= input.value; break;
        case "mul": result *= input.value; break;
        case "div": result /= input.value; break;
        case "reset": result = 0; break;
      }
    }
  }
 
  return result;
}
 
const calc = calculator();
calc.next();                                // Start generator
console.log(calc.next(10).value);           // 10
console.log(calc.next(5).value);            // 15
console.log(calc.next({ op: "mul", value: 2 }).value);  // 30
console.log(calc.next({ op: "sub", value: 8 }).value);  // 22
console.log(calc.next(null));               // { value: 22, done: true }
 
// .return() FORCES generator to finish
function* controlled() {
  try {
    yield 1;
    yield 2;
    yield 3;
  } finally {
    console.log("Cleanup executed");
  }
}
 
const ctrl = controlled();
console.log(ctrl.next());    // { value: 1, done: false }
console.log(ctrl.return(99)); // "Cleanup executed" -> { value: 99, done: true }
console.log(ctrl.next());    // { value: undefined, done: true }
 
// .throw() INJECTS an error into the generator
function* resilient() {
  let attempts = 0;
  while (true) {
    try {
      const value = yield `attempt ${attempts}`;
      console.log(`Received: ${value}`);
      attempts++;
    } catch (err) {
      console.log(`Error caught inside generator: ${err.message}`);
      attempts++;
    }
  }
}
 
const res = resilient();
res.next();                              // Start
res.next("data1");                       // "Received: data1"
res.throw(new Error("network failure")); // "Error caught inside generator: network failure"
res.next("data2");                       // "Received: data2"

Delegation with yield*

javascript

// yield* delegates to another iterable or generator
 
function* innerA() {
  yield 1;
  yield 2;
  return "a-done"; // Return value is the result of yield*
}
 
function* innerB() {
  yield 3;
  yield 4;
  return "b-done";
}
 
function* outer() {
  const resultA = yield* innerA();
  console.log(`Inner A returned: ${resultA}`); // "a-done"
 
  const resultB = yield* innerB();
  console.log(`Inner B returned: ${resultB}`); // "b-done"
 
  yield 5;
}
 
console.log([...outer()]); // [1, 2, 3, 4, 5]
 
// DELEGATING TO ANY ITERABLE
function* withArrays() {
  yield* [10, 20, 30];    // Array
  yield* "hello";          // String -> individual characters
  yield* new Set([40, 50]); // Set
}
 
console.log([...withArrays()]); // [10, 20, 30, "h", "e", "l", "l", "o", 40, 50]
 
// RECURSIVE GENERATOR (tree traversal)
class TreeNode {
  constructor(value, children = []) {
    this.value = value;
    this.children = children;
  }
 
  *[Symbol.iterator]() {
    yield this.value;
    for (const child of this.children) {
      yield* child; // Recursively delegate to child iterators
    }
  }
}
 
const tree = new TreeNode("root", [
  new TreeNode("a", [
    new TreeNode("a1"),
    new TreeNode("a2")
  ]),
  new TreeNode("b", [
    new TreeNode("b1"),
    new TreeNode("b2", [
      new TreeNode("b2x")
    ])
  ])
]);
 
console.log([...tree]); // ["root", "a", "a1", "a2", "b", "b1", "b2", "b2x"]
 
// FLATTEN WITH YIELD*
function* flatten(arr, depth = Infinity) {
  for (const item of arr) {
    if (Array.isArray(item) && depth > 0) {
      yield* flatten(item, depth - 1);
    } else {
      yield item;
    }
  }
}
 
const nested = [1, [2, [3, [4, [5]]]]];
console.log([...flatten(nested)]);       // [1, 2, 3, 4, 5]
console.log([...flatten(nested, 1)]);    // [1, 2, [3, [4, [5]]]]
console.log([...flatten(nested, 2)]);    // [1, 2, 3, [4, [5]]]

Lazy Evaluation Pipelines

javascript

// Generators enable lazy pipelines that process one element at a time
// No intermediate arrays are created
 
function* map(iterable, fn) {
  for (const item of iterable) {
    yield fn(item);
  }
}
 
function* filter(iterable, predicate) {
  for (const item of iterable) {
    if (predicate(item)) yield item;
  }
}
 
function* take(iterable, n) {
  let count = 0;
  for (const item of iterable) {
    if (count >= n) return;
    yield item;
    count++;
  }
}
 
function* skip(iterable, n) {
  let count = 0;
  for (const item of iterable) {
    if (count >= n) {
      yield item;
    }
    count++;
  }
}
 
function* chunk(iterable, size) {
  let batch = [];
  for (const item of iterable) {
    batch.push(item);
    if (batch.length === size) {
      yield batch;
      batch = [];
    }
  }
  if (batch.length > 0) yield batch;
}
 
// Composing a lazy pipeline
function* naturals() {
  let n = 1;
  while (true) yield n++;
}
 
// Find the first 5 squares of even numbers greater than 10
const result = take(
  map(
    filter(
      filter(
        naturals(),
        n => n > 10      // Greater than 10
      ),
      n => n % 2 === 0   // Even
    ),
    n => n * n            // Square
  ),
  5                       // Take only 5
);
 
console.log([...result]); // [144, 196, 256, 324, 400]
// Only computed 12, 14, 16, 18, 20 (not all naturals)
 
// FLUENT PIPELINE API
class LazyPipeline {
  #source;
 
  constructor(iterable) {
    this.#source = iterable;
  }
 
  static from(iterable) {
    return new LazyPipeline(iterable);
  }
 
  static range(start, end) {
    return new LazyPipeline(function* () {
      for (let i = start; i < end; i++) yield i;
    }());
  }
 
  map(fn) {
    const source = this.#source;
    return new LazyPipeline(function* () {
      for (const item of source) yield fn(item);
    }());
  }
 
  filter(predicate) {
    const source = this.#source;
    return new LazyPipeline(function* () {
      for (const item of source) {
        if (predicate(item)) yield item;
      }
    }());
  }
 
  take(n) {
    const source = this.#source;
    return new LazyPipeline(function* () {
      let count = 0;
      for (const item of source) {
        if (count >= n) return;
        yield item;
        count++;
      }
    }());
  }
 
  toArray() {
    return [...this.#source];
  }
 
  reduce(fn, initial) {
    let acc = initial;
    for (const item of this.#source) {
      acc = fn(acc, item);
    }
    return acc;
  }
 
  *[Symbol.iterator]() {
    yield* this.#source;
  }
}
 
const pipeline = LazyPipeline.range(1, 1000000)
  .filter(n => n % 3 === 0)
  .map(n => n * 2)
  .take(5)
  .toArray();
 
console.log(pipeline); // [6, 12, 18, 24, 30]
// Processes only 5 elements, not 1 million

Async Generators

javascript

// async function* combines generators with async/await
// Yields promises that resolve one at a time
 
async function* fetchPages(baseUrl, maxPages = 10) {
  let page = 1;
  let hasMore = true;
 
  while (hasMore && page <= maxPages) {
    // Simulated fetch
    const response = await simulateFetch(`${baseUrl}?page=${page}`);
    const data = response;
 
    yield data.items;
 
    hasMore = data.hasNextPage;
    page++;
  }
}
 
function simulateFetch(url) {
  const page = parseInt(url.split("page=")[1]);
  return Promise.resolve({
    items: Array.from({ length: 3 }, (_, i) => ({
      id: (page - 1) * 3 + i + 1,
      title: `Item ${(page - 1) * 3 + i + 1}`
    })),
    hasNextPage: page < 4
  });
}
 
// Consuming with for await...of
async function getAllItems() {
  const items = [];
  for await (const pageItems of fetchPages("https://api.example.com/items")) {
    items.push(...pageItems);
    console.log(`Fetched ${items.length} items so far`);
  }
  return items;
}
 
// ASYNC GENERATOR PIPELINE
async function* asyncMap(asyncIterable, fn) {
  for await (const item of asyncIterable) {
    yield fn(item);
  }
}
 
async function* asyncFilter(asyncIterable, predicate) {
  for await (const item of asyncIterable) {
    if (await predicate(item)) {
      yield item;
    }
  }
}
 
async function* asyncFlatMap(asyncIterable, fn) {
  for await (const item of asyncIterable) {
    const result = fn(item);
    if (result[Symbol.iterator] || result[Symbol.asyncIterator]) {
      yield* result;
    } else {
      yield result;
    }
  }
}
 
// REAL-TIME EVENT STREAM
async function* eventStream(source, eventType) {
  const queue = [];
  let resolve = null;
 
  const handler = (event) => {
    if (resolve) {
      const r = resolve;
      resolve = null;
      r(event);
    } else {
      queue.push(event);
    }
  };
 
  source.on(eventType, handler);
 
  try {
    while (true) {
      if (queue.length > 0) {
        yield queue.shift();
      } else {
        yield await new Promise(r => { resolve = r; });
      }
    }
  } finally {
    source.off(eventType, handler);
  }
}
 
// RATE-LIMITED ASYNC GENERATOR
async function* rateLimited(asyncIterable, intervalMs) {
  let lastYield = 0;
 
  for await (const item of asyncIterable) {
    const now = Date.now();
    const elapsed = now - lastYield;
 
    if (elapsed < intervalMs) {
      await new Promise(r => setTimeout(r, intervalMs - elapsed));
    }
 
    yield item;
    lastYield = Date.now();
  }
}

State Machines with Generators

javascript

// Generators naturally model state machines
// Each yield point is a state transition
 
function* trafficLight() {
  while (true) {
    yield { state: "green", duration: 30000 };
    yield { state: "yellow", duration: 5000 };
    yield { state: "red", duration: 25000 };
  }
}
 
// COMPLEX STATE MACHINE: HTTP REQUEST LIFECYCLE
function* httpRequestLifecycle() {
  // State: IDLE
  const config = yield { state: "idle", message: "Waiting for request" };
 
  // State: PREPARING
  yield { state: "preparing", message: `Preparing ${config.method} ${config.url}` };
 
  // State: CONNECTING
  yield { state: "connecting", message: "Establishing connection" };
 
  // State: SENDING
  yield { state: "sending", message: "Sending request body" };
 
  // State: WAITING
  const response = yield { state: "waiting", message: "Awaiting response" };
 
  if (response.status >= 400) {
    // State: ERROR
    yield { state: "error", message: `Error: ${response.status}`, response };
    return { success: false, response };
  }
 
  // State: RECEIVING
  yield { state: "receiving", message: "Receiving response body" };
 
  // State: COMPLETE
  yield { state: "complete", message: "Request complete", response };
 
  return { success: true, response };
}
 
const req = httpRequestLifecycle();
 
console.log(req.next());     // idle
console.log(req.next({ method: "POST", url: "/api/data" })); // preparing
console.log(req.next());     // connecting
console.log(req.next());     // sending
console.log(req.next());     // waiting
console.log(req.next({ status: 200, body: { id: 1 } })); // receiving
console.log(req.next());     // complete
 
// MIDDLEWARE PIPELINE WITH GENERATORS
function* middleware(context) {
  // Auth middleware
  console.log("Auth: checking token");
  if (!context.token) {
    return { error: "Unauthorized" };
  }
  yield; // Pass to next middleware
 
  // Logging middleware
  console.log(`Log: ${context.method} ${context.path}`);
  yield;
 
  // Rate limit middleware
  console.log("Rate limit: checking");
  yield;
 
  // Handler
  console.log("Handler: processing request");
  return { status: 200, body: "OK" };
}
 
function runMiddleware(gen) {
  let result = gen.next();
  while (!result.done) {
    result = gen.next();
  }
  return result.value;
}
 
const ctx = { method: "GET", path: "/api/users", token: "abc123" };
const response = runMiddleware(middleware(ctx));
console.log(response); // { status: 200, body: "OK" }

Feature	Regular Function	Generator Function	Async Generator
Declaration	`function f()`	`function* f()`	`async function* f()`
Return type	Value	Generator object	Async generator object
Pause/Resume	No	Yes (yield)	Yes (yield + await)
Iterable	No	Yes (Symbol.iterator)	Yes (Symbol.asyncIterator)
Lazy	No	Yes	Yes
Two-way data	No	Yes (.next(val))	Yes (.next(val))
Cancellable	N/A	Yes (.return())	Yes (.return())
Error injection	N/A	Yes (.throw())	Yes (.throw())
Consumption	Direct call	for...of / .next()	for await...of / .next()

Rune AI

Key Insights

Generator functions produce iterators that pause at yield and resume on .next(), enabling lazy computation without loading entire datasets into memory: This is fundamental for processing large or infinite sequences efficiently
Two-way communication via yield expressions and .next(value) enables coroutine patterns like calculators, state machines, and middleware pipelines: The first .next() argument is always discarded since the generator has not yet reached a yield point
yield delegates to inner generators or iterables, forwarding .next(), .throw(), and .return() transparently*: The return value of yield* is the inner generator's return value, not its yielded values
Async generators combine await and yield for lazy async iteration over streams, paginated APIs, and real-time events: Consume them with for await...of loops and use finally blocks for cleanup
Lazy pipelines composed from generator utilities (map, filter, take, chunk) process elements one at a time without creating intermediate arrays: This enables efficient processing of datasets that would not fit in memory

Frequently Asked Questions

When should I use generators instead of arrays?

Use generators when working with large or infinite data sets, when you want lazy evaluation (compute values on demand), or when you need to model sequential processes with pause/resume semantics. If your data fits comfortably in memory and you need random access, arrays are simpler. Generators shine when you need to process millions of records without loading them all into memory, when you need to pipeline transformations without creating intermediate arrays, or when you need to model stateful processes like protocol parsers or state machines.

How do generators differ from async/await?

Generators pause execution at `yield` and resume when `.next()` is called by external code. The caller controls when execution resumes. Async functions pause at `await` and resume automatically when the awaited promise resolves. The runtime controls when execution resumes. Generators are synchronous and pull-based (caller pulls values). Async generators combine both: they can `await` promises and `yield` values, enabling lazy async iteration. Historically, generators were used to implement async/await before it was a language feature (via libraries like co).

Can generators replace RxJS or other reactive libraries?

sync generators can handle many use cases that previously required reactive libraries: event streams, data pipelines, backpressure, and rate limiting. However, reactive libraries provide richer operators (combineLatest, switchMap, debounceTime) and handle multiple concurrent streams elegantly. Generators are inherently sequential (one value at a time), while reactive streams can merge and combine multiple sources. For simple streaming data processing, async generators are sufficient. For complex event composition with multiple sources, reactive libraries remain more expressive.

What happens to generator cleanup if I break out of a for...of loop?

When you break out of a for...of loop or use return inside the loop body, the engine automatically calls `.return()` on the generator. This triggers any `finally` blocks inside the generator, allowing cleanup code to execute. This is why you should always put cleanup logic (closing files, releasing connections, removing event listeners) in `finally` blocks within generators. If you consume a generator manually with `.next()` calls and stop early, you should call `.return()` explicitly to trigger cleanup.

How does yield* interact with .throw() and .return()?

When you use `yield*` to delegate to another generator, `.throw()` and `.return()` are forwarded to the inner generator. If the inner generator handles the thrown error (with try/catch), execution continues in the inner generator. If the inner generator does not handle the error, it propagates back to the outer generator. Similarly, `.return()` is forwarded to the inner generator, triggering its `finally` blocks before the outer generator resumes. This makes `yield*` a transparent delegation mechanism that preserves the full generator protocol.

Conclusion

Generators provide lazy evaluation, two-way communication, and elegant control flow through pausable functions. They transform complex iteration, state machines, and data pipelines into readable sequential code. For memory-safe data association used alongside generators, see JavaScript WeakMap and WeakSet Complete Guide. For the runtime execution model that generators operate within, explore Understanding libuv and JS Asynchronous I/O.

JavaScript Generators Deep Dive Full Guide

Generator Function Basics

Two-Way Communication

Delegation with yield*

Lazy Evaluation Pipelines

Async Generators

State Machines with Generators

Rune AI

Frequently Asked Questions

When should I use generators instead of arrays?

How do generators differ from async/await?

Can generators replace RxJS or other reactive libraries?

What happens to generator cleanup if I break out of a for...of loop?

How does yield* interact with .throw() and .return()?

Conclusion

Tags

More in this topic

OffscreenCanvas API in JS for UI Performance

Advanced Web Workers for High Performance JS

JavaScript Macros and Abstract Code Generation

Stay Updated