Generators

Functions that can pause

A normal function runs from start to end in one go. You call it, and it keeps running until it returns a value or throws an error. A generator function is different. It can stop in the middle, hand you a value, and wait. Later you tell it to go on, and it carries on from the exact place where it stopped.

The keyword that hands out a value and pauses is yield. The method that says "go on" is next(). While the function waits, it keeps all its local variables, so nothing is lost.

Generators build on the last lesson, the iteration protocols. There you wrote a next() method by hand, and it gave back objects like { value, done }. A generator makes that next() method for you. You write normal code with loops and yield, and JavaScript makes the results. The object you get also works with for...of, spread (...), and destructuring.

In this lesson you will:

• Step through a generator, one line at a time.
• Send commands to a live generator with buttons.
• Use yield* to hand out the values of another array or generator.
• Safely take a few values from a list that never ends.

To write a generator, put a star after the word function, like this: function*. Inside it, use yield to hand out a value.

Here is the surprising part: calling a generator function runs none of its code. It only gives you a generator object. The code starts on the first next() call, and it runs until the first yield.

The three cards below show the three steps. They use the story example that you'll step through soon.

1function* makeTea() {2  console.log("body ran");3  yield "tea";4}5 6const cup = makeTea();7console.log("created");

Lines 1 to 4 write a generator called makeTea. Line 2 would print body ran. Line 6 calls makeTea() and keeps the generator object in cup. But line 2 does not run, because nobody called next(). Line 7 prints created, and that is the only output.

This is useful when the work inside should wait until someone really asks for a value.

1function* colors() {2  yield "red";3  yield "blue";4}5 6const list = colors();7console.log(JSON.stringify(list.next()));8console.log(JSON.stringify(list.next()));9console.log(JSON.stringify(list.next()));

Lines 7, 8, and 9 call list.next() three times. JSON.stringify turns each result into text, so you can see its two properties:

• value is the value handed out by yield.
• done is false while the generator is paused at a yield, and true once its code has finished.

The first call prints {"value":"red","done":false}. The second prints {"value":"blue","done":false}. The third call finds no more yield, so it prints {"done":true}. Its value is undefined, and JSON.stringify leaves out properties that are undefined.

When you call next() yourself, check done to know when to stop.

Next, step through a longer example called story. Each step shows one line running. The steps were recorded from real JavaScript, but this is not a view inside the JavaScript engine. The "Running in" row shows where the code is right now: in the main script, or inside the generator.

You can also change the last command, on line 20, to see three endings: go on as normal, finish early, or throw an error into the generator.

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 more details are worth knowing.

First, next() can take a value, like next("hi"). That value becomes the result of the paused yield. But on the first call, no yield has paused yet, so the value has nowhere to go. JavaScript ignores it. Sending values into a generator gets its own lesson later: Generators for control flow.

Second, a generator's local variables are not shared with the rest of the program. They belong to that one paused generator object. It's like the local variables of a normal function call, which you saw in the Execution contexts lesson.

1function* reply() {2  const answer = yield "ready";3  console.log("answer: " + answer);4}5 6const task = reply();7console.log(JSON.stringify(task.next("ignored")));8console.log(JSON.stringify(task.next("accepted")));

Line 2 says const answer = yield "ready". The yield hands out ready and pauses. When the generator goes on, the value sent with next() is stored in answer.

Line 7 calls next("ignored"). The code runs to the yield, and line 7 prints {"value":"ready","done":false}. The word ignored is dropped, because no yield was paused yet.

Line 8 calls next("accepted"). Now the paused yield receives accepted, so line 3 prints answer: accepted. Then the code ends, and line 8 prints {"done":true}.

A generator object is both an iterator and an iterable. You met both words in the last lesson:

• An iterator has a next() method that gives one result at a time.
• An iterable has a [Symbol.iterator]() method, so for...of and spread can loop over it.

A generator object has both methods. Its [Symbol.iterator]() method simply gives back the object itself. So for a generator object called it, it[Symbol.iterator]() === it is true.

The table below compares a generator object with an array. Read each row as a question, then the answer for each one.

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

Line 6 makes a generator object called list. Line 7 calls list.next() once and gets red. Line 8 spreads a brand-new generator object from colors(), so it gets both colors. Line 9 spreads list, the object from line 6.

Line 9 surprises many people. It prints only ["blue"]. list already gave out red on line 7, so the spread starts from where list paused, not from the beginning. To start again, call the generator function again to get a fresh object.

1function* chores() {2  yield "wash";3  yield "read";4}5 6const today = chores();7console.log([...today].join(", "));8console.log([...today].join(", ") || "nothing left");

Line 6 makes one generator object, today. Line 7 spreads it and prints wash, read. That uses it up. Line 8 spreads the same object again. It has no values left, so join gives an empty string, and the || "nothing left" part prints nothing left instead.

If some code may need the values again, keep the generator function and call it again for a fresh object.

In the playground below, you send commands to one live generator. Each button calls a method on the same object, so the order you press them in matters. Reset makes a new object. You'll learn about return() and throw() in the next section, but you can try them now.

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 normal "go on" command. A generator object has two more methods. Both act on a generator that is paused at a yield:

• return(value) tells the generator to finish now. It gives back { value, done: true }. If the generator paused inside a try that has a finally block, the finally code still runs first. A yield inside that finally block could even pause it once more before it finishes.
• throw(error) throws the error at the paused yield, as if that line had thrown it. A try...catch around that yield can catch it. If the generator has not started yet, there is no paused yield, so the error is thrown straight back to the code that called throw().

Both methods work well with the try, catch & finally rules you already know. Put clean-up code, like closing a connection, in a finally block. Then it runs even when a loop stops early.

1function* makeReceipt() {2  yield "item";3  return "total";4}5 6const receipt = makeReceipt();7console.log(JSON.stringify(receipt.next()));8console.log(JSON.stringify(receipt.next()));9console.log([...receipt]);

Line 2 yields item, and line 3 returns total. Line 7 prints the first result, with done: false. Line 8 prints total with done: true. Line 9 spreads what is left and prints an empty array, [].

for...of and spread only collect values from yield. They stop at done: true, so they never see a generator's final return value.

1function* openConnection() {2  try {3    yield "connected";4  } finally {5    console.log("closed");6  }7}8 9const connection = openConnection();10console.log(connection.next().value);11console.log(JSON.stringify(connection.return("stopped")));

Line 10 calls next(). The code runs to the yield on line 3 and pauses inside the try. Line 10 prints connected.

Line 11 calls return("stopped"). The generator finishes from that paused yield, but first its finally block runs and prints closed. Then line 11 prints the result: {"value":"stopped","done":true}.

1function* safeTask() {2  try {3    yield "waiting";4  } catch (error) {5    yield "recovered: " + error.message;6  }7}8 9const task = safeTask();10console.log(task.next().value);11console.log(task.throw(new Error("retry" )).value);

Line 10 calls next(), and the generator pauses at the yield on line 3. Line 10 prints waiting.

Line 11 calls throw() with an error whose message is retry. The error is thrown at the paused yield on line 3, so the catch on line 4 catches it. Line 5 yields recovered: retry, and line 11 prints that value.

yield* (yield with a star) means: "hand out every value from this other iterable, one at a time, and then carry on here." Passing the work to another iterable like this is called delegation. It works with any iterable: arrays, strings, sets, your own iterables, and other generators.

When the other iterable is a generator, there is one more thing. That generator's return value becomes the result of the yield* expression, so you can save it in a variable.

1function* names() {2  yield* ["Asha", "Ben"];3  yield "done";4}5 6console.log([...names()].join(", "));

Line 2 uses yield* on the array ["Asha", "Ben"]. It hands out Asha, then Ben. Then line 3 yields done. So line 6 prints Asha, Ben, done.

An array has no return value, so here the yield* expression just gives undefined.

The playground below has two examples:

• Story team: a generator saves another generator's return value and then yields it.
• Flatten arrays: yield* is used inside a function that calls itself.

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 flatten example uses the same idea as the Recursion lesson. Each nested array gets its own flatten call. yield* passes the values from the deeper call out to the code that loops over the result.

A generator makes each value only when someone asks for it. This is called being lazy. Because of this, a generator can describe an infinite sequence: a list of values that never ends. An array could never store one. Some examples: IDs, timestamps, retry attempts, Fibonacci numbers, pages from a long search, or events as they happen.

The rule is simple. An endless generator is safe only when the code that asks for values stops asking.

The take helper in the playground does that stopping. take(ids(), 3) asks ids() for three values, hands them out, and then 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. Use one when:

• the values come one after another, over time,
• building the whole array first would waste memory or work, or
• a function that calls itself (recursion) needs to pass results back out as it finds them.

1function* makeIds(start) {2  let id = start;3  while (true) {4    yield "order-" + id;5    id += 1;6  }7}8 9function* take(iterable, limit) {10  let count = 0;11  for (const value of iterable) {12    if (count === limit) return;13    count += 1;14    yield value;15  }16}17 18console.log([...take(makeIds(100), 3)].join(", "));

Line 1 starts makeIds, a generator that makes IDs. Line 2 keeps the next number in a local variable, id. The loop on line 3 never ends. Each time round, line 4 yields one ID, and line 5 adds 1.

Line 18 uses take to keep only three IDs, so it prints order-100, order-101, order-102. This take is written with for...of. When a value arrives after the limit, line 12 returns. That ends the for...of loop, and the loop closes the endless ID maker.

1function* pageResults(pages) {2  for (const page of pages) {3    console.log("request page");4    yield* page;5  }6}7 8function* take(iterable, limit) {9  let count = 0;10  for (const value of iterable) {11    if (count === limit) return;12    count += 1;13    yield value;14  }15}16 17const pages = [["Asha", "Ben"], ["Chen", "Di"]];18console.log([...take(pageResults(pages), 3)].join(", "));

pageResults loops over the pages. Line 3 prints request page; it stands in for asking a server for the next page. Line 4 uses yield* to hand out that page's names one by one, without first joining all the pages into one big array.

Line 18 asks for three names. The first page gives Asha and Ben. Then the second page is requested, and Chen is the third name. So the output is two request page lines, then Asha, Ben, Chen. The name Di is never printed.

1function* trafficLight() {2  let light = "red";3  while (true) {4    yield light;5    light = light === "red" ? "green" : light === "green" ? "yellow" : "red";6  }7}8 9const lights = trafficLight();10console.log(lights.next().value);11console.log(lights.next().value);12console.log(lights.next().value);13console.log(lights.next().value);

A state machine is something that is always in one state, and has rules for moving to the next one. A traffic light is a good example: red, then green, then yellow, then red again.

Line 2 starts with light set to red. Line 4 yields the current color and pauses. When next() is called again, line 5 picks the next color. Because light is kept between pauses, lines 10 to 13 print red, green, yellow, and red. This code only describes the order of the colors. It does not control a real traffic light.

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(", "));

Lines 1 to 5 list three orders. Lines 7 to 11 write paidOrderIds. Line 8 loops over the orders, and line 9 yields an order's id only if it is paid. Line 13 prints 1, 3.

For a short array that is already in memory, orders.filter(...).map(...) works just as well. The generator version helps when orders arrive one page at a time, or when the code that asks may stop after the first match.

Other places where generators show up:

• Splitting text into words: yield one word at a time.
• Walking a tree, like folders or a menu: yield each file, folder, or menu item as you find it.
• Making test data: yield as many test cases as the test needs.
• Chains of steps: combine filter, map, and take without making a new array between each step.

Common mix-ups

The table below compares the three commands you can send to a generator. Read each row as: "when I call this, where does the generator carry on, and what do I get back?"

Try each exercise before you open the hints. The first ones ask you to predict the output. The later ones ask you to write and fix generators.

function* letters() {
  yield "A";
  yield "B";
}

const it = letters();
console.log(it.next().value);
console.log(it.next().done);
console.log(it.next().done);

function* odds(limit) {
  // yield 1, 3, 5 up to limit
}

console.log([...odds(5)].join(","));

function* odds(limit) {
  for (let n = 1; n <= limit; n += 2) {
    yield n;
  }
}

console.log([...odds(5)].join(","));

function* ids() {
  let id = 1;
  while (true) yield id++;
}

console.log([...ids()].slice(0, 3));

function* ids() {
  let id = 1;
  while (true) yield id++;
}

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

console.log([...take(ids(), 3)].join(","));

function* one() {
  yield "x";
  return "done";
}
function* two() {
  const message = yield* one();
  yield message;
}
console.log([...two()].join("|"));

function* matchingTasks(tasks, tag) {
  for (const task of tasks) {
    if (task.tags.includes(tag)) {
      yield task.title;
    }
  }
}

Pick an answer, then read the explanation for every choice. The wrong choices show common mistakes with generators.

Key takeaways

• function* makes a generator function. Calling it gives you a generator object and runs none of its code.
• Each next() runs the code until the next yield, a return, or an error.
• A generator object is both an iterator and an iterable, so it works with for...of and spread. It works only once.
• return() finishes early and still runs finally. throw() throws an error at the paused yield.
• yield* hands out every value from another iterable. With a generator, it also gives back that generator's return value.
• An endless generator is safe only when something like take stops asking for values.

Up next: Iterator helpers. They give any iterator lazy map, filter, take, and more.