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
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 millionAsync 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
Powered by Rune AI
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.
Previous
Preventing Memory Leaks with JS WeakMaps Guide
18 min read · advanced
Next
Handling Async Flows with JS Generator Functions
18 min read · advanced
More in this topic
OffscreenCanvas API in JS for UI Performance
Master the OffscreenCanvas API to offload rendering from the main thread. Covers worker-based 2D and WebGL rendering, animation loops inside workers, bitmap transfer, double buffering, chart rendering pipelines, image processing, and performance measurement strategies.
Advanced Web Workers for High Performance JS
Master Web Workers for truly parallel JavaScript execution. Covers dedicated and shared workers, structured cloning, transferable objects, SharedArrayBuffer with Atomics, worker pools, task scheduling, Comlink RPC patterns, module workers, and performance profiling strategies.
JavaScript Macros and Abstract Code Generation
Master JavaScript code generation techniques for compile-time and runtime metaprogramming. Covers AST manipulation, Babel plugin authorship, tagged template literals as macros, code generation pipelines, source-to-source transformation, compile-time evaluation, and safe eval alternatives.