Generators

Functions that can pause

A regular JavaScript function is like a sprint: call it, and it runs until it returns or throws. A generator function is different. It can run for a while, yield a value, pause with all its local variables still in place, and continue later when someone calls next().

Generators sit right on top of the iterator protocol from the previous lesson. A generator object has a next() method that returns { value, done }, and it is also iterable, so it works with for...of, spread, and destructuring. The difference is that you write the iterator as ordinary-looking control flow instead of hand-building a next method.

In this lesson you will step through a real recorded run, command a live generator with buttons, delegate to another generator with yield*, and safely take values from sequences that could go on forever.

The syntax is small: put a star after function, then use yield inside the body. The behavior is the big idea: calling the generator function runs none of the body. It only returns a generator object. The first next() call starts the body and runs until the first yield.

Step through the replay. It was recorded from real JavaScript calls, but it is not an engine debugger. The “Running in” row shows whether we are back in the script or currently inside the generator context. Change the last command to see normal resume, early return, and a thrown problem.

1function* story() {2  console.log("story starts");3  try {4    yield "chapter 1";5    console.log("after first pause");6    yield "chapter 2";7    console.log("after second pause");8    return "the end";9  } catch (error) {10    console.log("caught: " + error.message);11    return "recovered";12  } finally {13    console.log("cleanup");14  }15}16 17const tale = story();Run18console.log("created");19tale.next();20tale.next();

Two details matter for professional code. First, the argument passed to the first next(value) is ignored because no paused yield exists yet to receive it. Sending values back into generators is powerful, but this course saves it for Lesson 31.5. Second, a generator’s local variables are not global state. They live inside that one suspended generator object, similar to the local execution context you saw in the Execution contexts lesson.

A generator object is both an iterator and an iterable. Iterator means it has next(). Iterable means it has Symbol.iterator and can be consumed by for...of. For generator objects, iterator[Symbol.iterator]() === iterator is true.

1function* colors() {2  yield "red";3  yield "blue";4}5 6const list = colors();7console.log(list.next());       // { value: "red", done: false }8console.log([...colors()]);     // ["red", "blue"]9console.log([...list]);         // ["blue"] because red was already consumed

That last line surprises many people. list is the same iterator object you already advanced once, so spreading it starts from its current pause, not from the beginning. If you need a fresh pass, call the generator function again.

1function* task() {2  console.log("start");3  try {4    yield "first";5    console.log("after first");6    yield "second";7  } catch (error) {8    console.log("caught " + error.message);9  } finally {10    console.log("cleanup");11  }12  return "done";13}

next(), return(), and throw()

next() is the ordinary “go on” command. Two other methods let the caller close or interrupt a paused generator:

• return(value) asks the generator to finish. It returns { value, done: true } and runs pending finally blocks. A yield inside finally can pause once more before completion.
• throw(error) throws at the paused yield. A try...catch inside the generator can handle it. If the generator has never started, the throw happens immediately.

These methods make generators good citizens around cleanup. They work well with the try, catch & finally rules you already know: cleanup belongs in finally, even when iteration stops early.

yield* means “yield everything from this iterable before continuing here.” It works with arrays, strings, sets, custom iterables, and other generators. When the delegate is a generator, its final return value becomes the value of the yield* expression.

1function* leaf(name) {2  yield name + ": start";3  yield name + ": end";4  return name + " finished";5}6 7function* storyTeam() {8  yield "host intro";9  const finalLine = yield* leaf("guest");10  yield "host heard " + finalLine;11  return "host finished";12}13 14console.log([...storyTeam()].join(" | "));

The recursive flatten example is the same idea as the Recursion lesson: each nested array gets its own call, and yield* passes values from the deeper call to the outside consumer.

Because generators are lazy, they can describe sequences that would be impossible to store in an array: IDs, timestamps, retry attempts, Fibonacci numbers, pages from a long search, or events from a stream. The rule is simple: an infinite generator is safe only when the consumer stops.

1function* ids() {2  let id = 1;3  while (true) {4    console.log("compute id " + id);5    yield id;6    id += 1;7  }8}9 10function* take(iterable, limit) {11  const iterator = iterable[Symbol.iterator]();12  for (let count = 0; count < limit; count += 1) {13    const result = iterator.next();14    if (result.done) return;15    yield result.value;16  }17}18 19console.log([...take(ids(), 3)].join(", "));

Where you’ll use generators

Generators are not for every loop. Reach for them when a process naturally produces a sequence over time, when building the whole array would waste memory, or when recursion needs to stream results upward.

1const orders = [2  { id: 1, paid: true },3  { id: 2, paid: false },4  { id: 3, paid: true },5];6 7function* paidOrderIds(items) {8  for (const order of items) {9    if (order.paid) yield order.id;10  }11}12 13console.log([...paidOrderIds(orders)].join(", "));

This example is small, but the shape scales. An eager array solution such as orders.filter(...).map(...) is perfectly fine for a short in-memory array. A generator version can be useful when orders arrive one page at a time or when later code may stop after the first match.

• Tokenizing text: yield one token at a time.
• Walking trees: yield each file, folder, or menu item as you find it.
• Generating test data: yield as many cases as the test needs.
• Lazy pipelines: combine filter, map, and take without intermediate arrays.

Misconceptions and edge cases

Pick an answer, then read every explanation. The wrong choices name common generator mistakes.

Key takeaways

• function* creates generator functions; calling one returns a generator object without running the body.
• Each next() resumes until the next yield, return, or thrown error.
• Generator objects are both iterators and iterables, so they work with for...of and spread.
• return() closes early and runs cleanup; throw() throws at the paused yield.
• yield* delegates to another iterable and can receive a generator delegate’s final return value.
• Infinite generators are safe only with a stopping consumer such as take.

Up next: Iterator helpers, lazy map, filter, take, and friends for any iterator.