How async code is compiled down

What compiled down means

Modern JavaScript engines understand async, await, and generators. Very old browsers do not. A transpiler is a tool that rewrites new JavaScript into older JavaScript. The goal is that the program still does the same things, in the same order.

The rewrite cannot skip the waiting. Instead, it writes out each pause in plain code. Each pause needs three things:

• a place to keep the values the function still needs;
• a note that says which step comes next;
• a promise callback that starts the work again when the result arrives. A callback is a function you hand over so other code can call it later.

This lesson follows on from the microtask queue. That lesson showed where promise jobs wait. This lesson shows the extra JavaScript a build tool can write to make pauses work in older browsers.

A generator pauses at yield

Start with a generator, because it shows pausing clearly. A generator is a function that can stop in the middle and carry on later. You write it with a star after the word function: function*. Inside it, yield marks a pause point. There, the function hands back a value and stops.

Calling a generator does not run its body. It gives you a generator object. Each time you call the object's next() method, the body runs up to the next yield and stops again.

1function* makeTea() {2  yield "boil water";3  yield "add tea";4  yield "pour";5}6 7const tea = makeTea();8console.log(tea.next().value);9console.log(tea.next().value);10console.log(tea.next().value);

Line by line:

• Line 1 starts the generator makeTea.
• Lines 2, 3, and 4 each have a yield. Each one is a pause point with one tea step.
• Line 7 calls makeTea(). This makes one generator object, tea. No step runs yet.
• Lines 8, 9, and 10 each call tea.next(). The console prints boil water, add tea, and pour, in that order.

Each call to next() returns a small object, such as { value: "boil water", done: false }. It has two parts:

• value is what the yield handed back.
• done says whether the generator has finished. It stays false until there are no steps left.

Lines 8 to 10 print only the value part.

1function* makeTea() {2  yield "boil water";3  yield "add tea";4  yield "pour";5}6 7const tea = makeTea();Run8console.log(tea.next().value);9console.log(tea.next().value);10console.log(tea.next().value);

Generators as state machines

A state machine is ordinary code that remembers which step it is on. Each time you call it, it looks at the saved step, does that step, and saves the next one. This is a good way to picture a generator, because a generator also has to remember which yield it stopped at.

1function makeTeaMachine() {2  let state = 0;3  return {4    next() {5      switch (state) {6        case 0: state = 1; return { value: "boil water", done: false };7        case 1: state = 2; return { value: "add tea", done: false };8        case 2: state = 3; return { value: "pour", done: false };9        default: return { value: undefined, done: true };10      }11    },12  };13}

Here state is a plain number. A switch picks one branch, one case, by that number. Line by line:

• Line 2 sets state to 0, so the first call starts at the first step.
• The first next() takes line 6. It sets state to 1 and returns boil water.
• The second call takes line 7. It sets state to 2 and returns add tea.
• The third call takes line 8. It sets state to 3 and returns pour.
• A fourth call finds no case for 3. It takes the default branch on line 9 and returns done: true.

This machine is a model for learning. It is not the code inside a real engine; engines store paused functions in their own, faster way. The main point is simple: a function that can pause must save where it stopped. A saved number plus a switch is one way to do that in ordinary JavaScript.

1function makeTeaMachine() {2  let state = 0;Run3  return {4    next() {5      switch (state) {6        case 0: state = 1; return { value: "boil water", done: false };7        case 1: state = 2; return { value: "add tea", done: false };8        case 2: state = 3; return { value: "pour", done: false };9        default: return { value: undefined, done: true };10      }11    },12  };13}

Compare the generator and the machine

Inside, the two versions look different. From the outside, they act the same: each call gives the next tea step. The machine also shows one thing a real generator keeps hidden: its saved state number.

1function* makeTea() {2  yield "boil water";3  yield "add tea";4  yield "pour";5}6 7const tea = makeTea();8console.log(tea.next().value);9console.log(tea.next().value);10console.log(tea.next().value);

1function makeTeaMachine() {2  let state = 0;3  return {4    next() {5      switch (state) {6        case 0: state = 1; return { value: "boil water", done: false };7        case 1: state = 2; return { value: "add tea", done: false };8        case 2: state = 3; return { value: "pour", done: false };9        default: return { value: undefined, done: true };10      }11    },12  };13}

Try these:

• 1 call: both return boil water, and the machine saves state 1.
• 3 calls: both reach pour.
• 4 calls: both return done: true, because no steps are left.
• Reset goes back to 1 call.

The table below compares four kinds of code that can pause. Read each row as: what it is, who starts it again, and what you get back.

A build tool can write its output in different shapes. But every shape must keep the same three facts:

• which step runs next;
• the local variables (variables made inside the function) that later steps still read;
• how to return the next result without running earlier steps again.

Regenerator and async-to-generator

Regenerator is a tool used by Babel, a popular transpiler. Regenerator rewrites a generator into ordinary code. It works like the tea machine: a switch reads a saved step number, often called context.next. It also saves the values that later steps still need.

1// Simplified sketch of Regenerator output. It does not run on its own.2function makeTea(context) {3  while (1) switch (context.next) {4    case 0: context.next = 2; return "boil water";5    case 2: context.next = 4; return "add tea";6    case 4: return context.stop("pour");7  }8}

This sketch is cut down on purpose, and it does not run on its own. Line by line:

• Line 2 starts the rewritten makeTea. It gets a context object that holds the saved step number.
• Line 3 reads the saved step number, context.next, and picks a branch.
• Lines 4 and 5 each save the following step number and return one tea step.
• Line 6 returns the last step, pour, and marks the generator as finished.

Real output does more. It also handles errors, an early return, throw, and loops.

Async-to-generator is the next step. It rewrites an async function into a generator. Each await becomes a yield that hands out a promise. A small helper, called a runner, drives the generator. When a promise is ready, the runner starts the generator again and gives it the promise's value.

1async function makeOrder() {2  console.log("start order");3  const item = await Promise.resolve("tea");4  console.log("serve " + item);5}6 7makeOrder();

Line by line:

• Line 2 prints start order before the pause.
• Line 3 waits for a promise that holds "tea".
• When that promise is ready, line 4 prints serve tea.
• Line 7 calls the function.

The next section builds a small runner that keeps this same order, using a generator.

A tiny async-to-generator runner

The runner can be small, because a promise already knows how to call code later. The runner does three jobs:

• It starts the generator.
• It checks whether the generator has finished.
• If not, it waits for the promise the generator handed out. Then it calls next(value) with that promise's value.

1function run(genFn) {2  const iterator = genFn();3  function advance(method, value) {4    let step;5    try {6      step = iterator[method](value);7    } catch (error) {8      return Promise.reject(error);9    }10    if (step.done) return Promise.resolve(step.value);11    return Promise.resolve(step.value).then(12      value => advance("next", value),13      error => advance("throw", error),14    );15  }16  return advance("next");17}18 19function* makeOrder() {20  console.log("start order");21  const item = yield Promise.resolve("tea");22  console.log("serve " + item);23}24 25run(makeOrder);

Line by line:

• Line 2 calls the generator function. This gives the generator object, iterator.
• Line 3 makes advance, the function that moves the generator one step.
• Line 6 starts the generator again, with either next or throw.
• Line 10: when the generator has finished, the runner finishes its own promise with the final value.
• Lines 11 to 14: when the promise is ready, its value goes back in through next(value). If the promise fails, the error goes back in through throw(error). That way, a try/catch around the original await still works.
• Line 16 makes the first move, with next.
• Lines 19 to 22 are the async function, rewritten as a generator. Line 21 hands out the promise. On a later call, item gets "tea".
• Line 25 starts everything.

The real async function and this runner print the same two lines, in the same order: start order, then serve tea. The lesson's tests run both programs with real promises to check this.

Coroutines keep their local state

A coroutine is a function that can pause and carry on later. While it is paused, it keeps its local variables. The word names what the function does, not a kind of syntax. Both of these are coroutines:

• A generator. You drive it by calling next().
• An async function. Promises drive it: it carries on when the promise it waits for is ready.

1function* countOrders() {2  let order = 1;3  while (order <= 3) {4    yield "order " + order;5    order += 1;6  }7}8 9const orders = countOrders();10console.log(orders.next().value);11console.log(orders.next().value);

Line by line:

• Line 2 makes the local variable order and sets it to 1. This happens only once.
• Line 9 makes the generator object, orders.
• Line 10 calls next(). Line 4 hands back order 1 and pauses, and line 10 prints it.
• Line 11 calls next() again. The generator carries on right after the yield.
• Line 5 adds 1 to the same order variable. The loop goes round, line 4 hands back order 2, and line 11 prints it.

The generator never went back to line 1, so order was not set back to 1.

This is why rewritten code must save local variables. In the async example, item gets its value after the pause. The rewritten code stores enough to make the later branch act as if the function had never stopped.

The cost of older async output

Rewriting for older browsers solves one problem: old browsers can run the code. But it adds code. One short async function can turn into several pieces:

• a generator body, or a switch like the tea machine;
• a runner;
• promise callbacks and saved local variables;
• sometimes a shared helper library, called the Regenerator runtime. It goes into the bundle: the JavaScript file your site sends to the browser.

1async function saveOrder(order) {2  const receipt = await send(order);3  return receipt.id;4}5 6// Older targets can add a runner, a generator body,7// saved state, and sometimes a shared helper library.

Line by line:

• Line 1 starts a short async function.
• Line 2 pauses until send(order) is ready, and saves the result in receipt.
• Line 3 reads receipt after the pause. So older output must keep receipt safe across the pause.
• The comments on lines 6 and 7 name the extra pieces. Different tools write different code, so the sketch does not show exact output.

The table below lists four kinds of cost. Read each row as: what it affects, what can change, and what you can do. It gives no fixed numbers, because the real cost depends on your code and your browsers.

Each pause can add extra function calls and extra objects. Debugging gets harder, too: one line you wrote, like line 2, can turn into several places in the rewritten code. A source map is a file that links the rewritten code back to the lines you wrote. With it, developer tools can show your own code.

Choosing which browsers to build for

Do not rewrite async code out of habit. First, decide where your product must run:

• which browsers;
• which web views (a small browser built into an app);
• which runtimes (programs that run JavaScript outside a browser, such as Node.js).

This list is your target. All modern browsers run async and await as they are. So a modern target can keep the clear code you wrote.

Some projects must support older browsers. Then the extra helper code is a fair price, because it lets those users run the product. The important part is to choose the target on purpose. Then check the output and the bundle size yourself, instead of guessing.

• Set your browser targets before you compare bundle output.
• Look at the rewritten code when a stack trace (the list of function calls shown with an error) looks strange.
• Keep source maps for debugging, both while you build and, if your team allows it, on the live site.
• Read transpilers and polyfills for how to make the support decision.
• Use native async wherever all your users' browsers can run it.

This does not mean modern output is always right for every site. It means helper code should be there because real users need it. Its size and its debugging cost should be part of that choice.

Common misconceptions

• “A generator runs in parallel, at the same time as other code.” It runs only when someone calls next(), and it stops at each yield.
• “A state machine is fake async.” It is a real way to write a pause, and the later restart, in ordinary code.
• “Every transpiler outputs Regenerator code.” The output depends on the tool, its settings, and the target.
• “Older output always costs the same fixed amount.” The code and its speed vary, so measure on your own target.
• “Async functions lose their local variables while they wait.” The paused function keeps everything that later lines need.

The table below lists words that are easy to mix up. Read each row as: the word, what it means, and the wrong idea people often have about it.

Keep the picture simple. A transpiler can rewrite pauses into step numbers, saved values, and callbacks. The program still follows the promise and microtask rules from the last lesson. (A microtask is a small job that runs as soon as the current code finishes.) Rewritten code does not get a secret clock of its own.

Practice exercises

function* makeTea() {
  yield "boil water";
  yield "add tea";
}
const tea = makeTea();
console.log(tea.next().value);

const machine = makeTeaMachine();
console.log(machine.next().value);
console.log(machine.getState());

function run(genFn) {
  const iterator = genFn();
  function advance(value) {
    const step = iterator.next(value);
    return step.done ? Promise.resolve(step.value) : Promise.resolve(step.value).then(advance);
  }
  return advance();
}
function* work() {
  console.log("start");
  const item = yield Promise.resolve("tea");
  console.log("finish " + item);
}
run(work);

Check your understanding

Use the tea examples to keep three questions apart: what pauses, who starts it again, and what older output has to add. For code questions, go one pause at a time instead of guessing.

Key takeaways

• A generator pauses at each yield and carries on when someone calls next().
• A state machine can do the same job with a saved step number and a switch.
• Regenerator-style output turns generator pauses into step numbers and saved local variables.
• Async-to-generator uses a promise runner. The runner starts the generator again each time a promise is ready.
• Coroutines pause and carry on while keeping their local variables. Generators and async functions differ in who starts them again.
• Older async output can add bundle code, calls, objects, and debugging work. Choose a modern target when your users allow it.

Coming next: Writing engine-friendly code. You will learn simple code habits that help the engine run your code fast.