Generators for control flow

A generator is a program you can pause

You already know that a generator can give you values one at a time. In this lesson you use the same pause-and-continue trick for control flow. Control flow means the order in which code runs. Here it answers three questions:

• Which piece of code runs next?
• What value does a paused line get when it starts again?
• What cleanup runs when the caller stops early?

A quick reminder of the basics. A generator function is written with function*. Calling it does not run its body. It gives you an iterator: an object with a next() method. Each next() call runs the body up to the next yield and pauses there. It gives back a small object, { value, done }.

The new part is this: the caller can also send a value back in to the paused yield. The caller is the code that calls next().

You will start with a tiny conversation. Then you will build a promise runner, stop a generator early, let tasks take turns, and step through a list of states. The goal is not to replace async/await. The goal is to see what a paused program can do.

The code yield "question" does two jobs:

1. It sends "question" out to the caller, and the generator pauses.
2. Later the caller runs next(answer). The generator starts again, and the whole yield "question" part now stands for answer.

The first next() call is different. It only starts the body. The generator is not paused at a yield yet, so there is nowhere for a value to go. That is why the first call's argument, next("ignored"), is thrown away. Step through the code below and change the answers to see this.

1function* interview() {2  const name = yield "What is your name?";3  const color = yield "Hi " + name + ", favorite color?";4  return name + " likes " + color;5}6const chat = interview();Run7console.log(chat.next("ignored").value);8console.log(chat.next("Ada").value);9console.log(chat.next("blue").value);

A generator has two more methods that start it again from the paused yield:

• throw(error) raises an error at the paused yield. A try/catch inside the generator can catch it.
• return(value) asks the generator to finish now. Any finally block still runs on the way out.

1function* checkout() {2  try {3    const address = yield "address?";4    return "ship to " + address;5  } catch (error) {6    return "ask again";7  }8}9 10const order = checkout();11console.log(order.next().value);12console.log(order.throw(new Error("missing")));13 14const secondOrder = checkout();15secondOrder.next();16console.log(secondOrder.return("cancelled"));

Line 12 sends an error into the paused yield. The generator catches it and returns "ask again". Line 16 stops a second generator before it gets an address. So it gives back { value: "cancelled", done: true }.

Both methods are requests from the caller. The generator can catch the error, and its finally block can run cleanup. Neither method rewinds the body or starts it over.

A promise is a value that arrives later. It fulfills when the value arrives, or rejects when something goes wrong. Before async/await existed, libraries such as co used generators to make promise code read from top to bottom. It worked like this:

1. The generator yields a promise and pauses.
2. A small function called a runner waits for that promise.
3. If the promise fulfills, the runner calls next(result). The paused yield gets the result.
4. If the promise rejects, the runner calls throw(error). The error appears at the paused yield.

The runner in the lab below follows three rules:

• It starts the generator with next().
• It wraps each yielded value in Promise.resolve(...). That turns any value into a promise, so the runner can always wait the same way.
• When the promise is done, it calls exactly one method: next(value) if the promise fulfilled, or throw(error) if it rejected.

1function run(genFn) {2  const it = genFn();3  function step(method, value) {4    const result = it[method](value);5    if (result.done) return Promise.resolve(result.value);6    return Promise.resolve(result.value).then(7      (value) => step("next", value),8      (error) => step("throw", error)9    );10  }11  return step("next");12}13 14function* loadProfile() {15  const user = yield getUser();16  const posts = yield getPosts(user.id);17  return user.name + " has " + posts.length + " posts";18}

1async function loadProfile() {2  const user = await getUser();3  const posts = await getPosts(user.id);4  return user.name + " has " + posts.length + " posts";5}

The steps happen one after another. The second request must wait for the first, because the generator needs user.id to ask for the posts. If two requests don't need each other, run them together with Promise.all inside an async function instead.

Today, async/await does this job for you. The language itself pauses the function, waits for the promise, and lets you use a normal try/catch. That code is easier to read, debug, and check for type errors. So in everyday app code, use async & await.

The generator runner is still worth learning. It shows each handoff clearly: pause, wait, send the value back, go on. Some libraries also still need a caller that controls each step.

A generator may hold something that must be closed when you are done with it. Examples are a file reader, a lock, or a subscription to updates. Put the closing code in a finally block. The generator runs that finally block when the caller stops early, in either of two ways:

• The caller calls return() on the generator.
• A for...of loop over the generator ends with break.

Good cleanup finishes right away, without pausing. For example, it removes a subscription, resets a flag, or closes a reader before the caller's code goes on. Then stopping early always works the same way, even if the caller never calls next() again.

1function* readResource() {2  try {3    console.log("open");4    yield "chunk 1";5    yield "chunk 2";6  } finally {7    console.log("close start");8    yield "paused in cleanup";9    console.log("closed");10  }11}

This uses the same finally you met in try, catch & finally. The new part is that the caller can ask the generator to stop early.

A for...of loop uses the values the generator yields. It ignores the generator's final return value. When the loop ends with break, JavaScript first closes the generator by calling its return() method. That is why finally runs. Readers and subscriptions that you can cancel depend on this rule.

A coroutine is a piece of code that takes turns with other pieces of code. It decides for itself when to pause and let another one run. With generators, each task runs until it reaches a yield. Then a scheduler, the code that picks who goes next, can start a different task.

1function* saveInPieces() {2  yield "save title";3  yield "save body";4  return "saved";5}6 7const task = saveInPieces();8console.log(task.next().value);9console.log(task.next().value);10console.log(task.next());

The first two calls print "save title" and "save body". The third call prints { value: "saved", done: true }. The generator has finished, so it gives its return value instead of another turn.

A task that takes turns must pause at good places. Yielding after each small piece of work lets the scheduler switch tasks often. But a long loop between two yields still freezes the page until that loop ends. Generators never stop your code in the middle for you.

The lab below uses a queue: a list where you take from the front and add to the back. The picture shows one turn.

1function* task(name, count) {2  for (let i = 1; i <= count; i++) {3    yield name + " step " + i;4  }5}6 7const tasks = [task("paint", 2), task("cook", 3), task("music", 2)];8while (tasks.length > 0) {9  const current = tasks.shift();10  const result = current.next();11  if (!result.done) tasks.push(current);12}

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

The tasks do not run at the same time. Only one runs at a time, and they take turns. This is a clear way to write step-by-step work: animation scripts, parsers that read text piece by piece, or teaching tools that pause at named points.

Don't mix up this small queue with the browser's event loop. The browser runs timers, clicks, and screen updates around your code by itself. A generator scheduler runs only when your own code calls next(). Once a slow step has started, the scheduler can't make the page respond until that step ends.

Generators as state machines

A state is the stage something is in right now. A state machine moves through a fixed list of states, one step at a time. A traffic light is one: green, yellow, red, then green again. A generator fits this well:

• Each yield is one state.
• Each next() call moves one step forward.
• The generator remembers which state it is in, so you don't need a variable for it.

1function* orderState() {2  yield "cart";3  yield "paid";4  yield "shipped";5}6 7const order = orderState();8console.log(order.next().value);9console.log(order.next().value);10console.log(order.next().value);

Lines 8 to 10 print cart, paid, and shipped, in that order. The generator remembers where the order is. It does not check any rules, though. A real shop still needs code that decides whether the payment is allowed.

Use this pattern when the states always come in the same order and the caller decides when to move on. Use a state machine library or a switch on the current state when you need more: branches, saving the state, or many separate states at once.

The table compares a generator with a runner and an async function. Read each row as a question, then compare the two answers.

Generators are great for custom loops, step-by-step replays, tasks that take turns, and small state machines. Code that waits for promises usually belongs in an async function today.

The generator above does not guard its steps. A real state machine may refuse shipped before paid, save the current state, or pick between two next states. The generator gives you a readable order of steps. The shop's rules still belong in your app code.

You will meet generator control flow in libraries, test tools, parsers, animation demos, and job interviews. The skill is not to turn every function into a generator. The skill is to spot when a pause point makes the code easier to follow.

On a website, a generator can give you one page of results at a time, replay the steps of a long form, or drive a teaching demo. It is a poor fit for plain data formatting. A hand-written promise runner is usually a poor fit for new app code, too.

Common misconceptions

Pick an answer before you look. Then read every explanation. The wrong answers are common generator mistakes.

Key takeaways

• next(value) sends value into the paused yield. The first call's argument is thrown away.
• throw(error) raises an error at the paused yield. return(value) finishes the generator, and finally blocks still run.
• A promise runner waits for each promise, then calls next(result) or throw(error). Modern code usually uses async/await instead.
• Coroutines take turns: each task runs until it reaches its own yield.
• Generators help with custom loops, step-by-step replays, state machines, and small schedulers. They are not for every function.

Up next: Why modules?