The microtask queue

A small queue with a big effect

A callback is a function you hand over to be called later. A browser or Node does not run every waiting callback at once. First, the code that is running now finishes. Then the browser or Node picks what runs next.

In this lesson, the browser or Node is called the host: the program that runs your JavaScript. The host runs work in pieces:

• A task is one piece of work the host runs from start to end. The whole script is a task. So is one timer callback, or one click handler.
• A queue is a waiting line. The first one in is the first one out.
• Promise callbacks wait in a special line called the microtask queue.

1setTimeout(() => console.log("timer"), 0);2Promise.resolve().then(() => console.log("promise"));3console.log("script");

Line 1 asks the host to run a timer callback later. setTimeout(callback, 0) means "run this as a new task, as soon as you can". Line 2 makes a promise that is already done and gives it a then callback. Because the promise is ready, the callback goes into the microtask queue. Line 3 logs right away. The output is script, then promise, then timer.

The Microtasks lesson showed this order. This lesson looks closer. Where do promise jobs wait? And why does the host run all of them before a timer, a click, or any other task?

Promise jobs in the language rules

ECMAScript is the official rulebook for JavaScript. People also call it the specification, or the spec. The spec calls work that must happen later a job. When a promise is done and has a then callback, the spec makes a promise job to call it.

The spec says promise jobs wait and run later, in order. It does not describe browser tabs, Node, the screen, or timers. Those belong to the host.

1Promise.resolve("tea").then(() => console.log("job"));2console.log("task");3console.log("task still running");

Line 1 makes a promise job for the then callback. Line 2 logs while the current task is still running. Line 3 shows that the task keeps going. The output is task, task still running, then job.

This split is useful. The spec can promise that a then callback is never called in the middle of your current code. At the same time, browsers and Node are free to fit jobs into their own way of running tasks. How they store the queue inside is up to them.

So when you debug, think in two layers:

• The language says: a ready promise callback runs later.
• The host says when the current task ends and when a checkpoint starts.

1Promise.resolve("tea").then(() => console.log("job"));2console.log("task");3console.log("task still running");

Run the same three lines yourself. Line 1 adds the callback to a promise that is already done. Lines 2 and 3 are ordinary code in the current task. The output is again task, task still running, then job.

The word job is broad on purpose. It means a piece of later work in the language rules. It is not a queue you can see in the browser. If a browser changes how it draws the page, or Node changes how it reads files, the promise rule stays the same.

HostEnqueuePromiseJob: the hand-over

HostEnqueuePromiseJob is a step in the spec. "Enqueue" means "add to a queue". The promise rules use this step to hand a ready promise job to the host.

You can't call it from your code. It marks the place where the promise rules end and the browser's or Node's queue begins.

1const order = Promise.resolve("tea");2order.then(() => console.log("serve tea"));3console.log("take next order");

Line 1 makes a promise that is already done. Line 2 adds a callback. The promise rules then use HostEnqueuePromiseJob to hand a job for that callback to the host. Line 3 runs before that job. The output is take next order, then serve tea.

The name helps you avoid a common mistake. ECMAScript sets the promise rules. But no line of your code reaches inside Chrome or Node and pushes onto their queue. Your code asks for promise behavior. The host receives the job.

This is why the docs for different hosts can sound different, while the basic promise order stays the same. The shared rule is: promise callbacks run later. The tasks around them, and when the page is drawn, depend on the host.

1const hostMicrotasks = [];2 3function HostEnqueuePromiseJob(job) {4  hostMicrotasks.push(job);5}6 7HostEnqueuePromiseJob(() => console.log("serve tea"));8console.log("take next order");9hostMicrotasks.shift()();

Line 1 is a plain array. It stands in for the host's microtask queue. Lines 3 to 5 are a pretend version of the step: it takes a job and stores it. Line 7 hands over the tea job. Line 8 still prints first. Line 9 takes the stored job out and calls it. shift() removes the first item of an array and returns it.

This is not the browser's real code. It only shows the hand-over. The promise rules ask for a job to be queued. They don't say how the host stores the queue, or when it picks its next task.

Microtask checkpoints

A microtask checkpoint is the moment the host runs the microtask queue until it is empty. People call this draining the queue. A simple way to picture one turn of the host:

1. Run one task.
2. Wait until the JavaScript stack is empty. The stack is the list of functions running right now. Empty means no JavaScript is running.
3. Run every microtask, one by one, until none are left.
4. Only then, pick the next task.

Hosts have other checkpoints too, for example between two click listeners. You'll see that later in this section.

1queueMicrotask(() => {2  console.log("first");3  queueMicrotask(() => console.log("second"));4});5console.log("script");

Lines 1 to 4 queue a callback. That callback, on line 3, queues one more callback. Line 5 logs right away. At the checkpoint, the first callback runs and adds the second one to the queue. The checkpoint keeps going, so the second one runs too. The output is script, first, then second.

Browsers also run checkpoints around events, and before they draw the page. For example, when a user clicks, there can be a checkpoint between two click listeners. When the page gets drawn is a browser rule, not an extra promise rule.

1const log = [];2 3function firstListener() {4  log.push("first listener");5  queueMicrotask(() => log.push("microtask"));6}7 8function secondListener() {9  log.push("second listener");10}11 12firstListener();13queueMicrotask(secondListener);14queueMicrotask(() => console.log(log.join(", ")));

Lines 3 to 6 stand in for the first listener. It logs, then queues a small follow-up microtask. Lines 8 to 10 stand in for a second listener. Line 12 runs the first listener. Lines 13 and 14 queue the second listener and a final log, behind the follow-up. The printed list is first listener, microtask, second listener.

A real click has more steps than this. The point is smaller: don't assume every callback from one click runs as one unbroken block. The host may run a checkpoint between two listeners.

A small model of one checkpoint

The next code is a teaching model. It is not the browser's real code. It shows one rule clearly: runTask takes one task, then takes microtasks out one by one until none are left.

1const tasks = ["timer"];2const microtasks = ["promise"];3 4function runTask(label) {5  const output = [label];6  while (microtasks.length) output.push(microtasks.shift());7  return output;8}9 10console.log(runTask(tasks.shift()).join(", "));

Lines 1 and 2 make the two queues as arrays. Lines 4 to 8 define runTask, which runs one task. Line 6 is the drain: while the microtasks array still has items, it moves the first one into the output. Line 10 runs the timer task and prints timer, promise.

1const loop = makeLoop(["timer"], ["promise"]);Run2loop.queueMicrotask("follow-up");3const output = loop.runTask();4console.log(output.join(", "));

The step-through calls the lesson's real model. It queues a follow-up job, runs the timer task, and shows the result list. It replays the model code. It is not a debugger paused inside a browser.

The model leaves things out on purpose. It does not draw the page. It does not choose between many kinds of tasks. It only makes the drain rule easy to see and test.

Microtask starvation

Microtask starvation happens when each microtask adds another microtask, so the checkpoint never ends. The host can't get to the timer, or draw the page, until the microtasks stop. The waiting work "starves": it never gets a turn.

1let rounds = 0;2function addMicrotask() {3  console.log("microtask", rounds);4  rounds += 1;5  if (rounds < 5) queueMicrotask(addMicrotask);6}7setTimeout(() => console.log("timer"), 0);8queueMicrotask(addMicrotask);

Line 1 counts rounds. Lines 2 to 6 define addMicrotask. It logs one round, adds 1 to the count, and queues itself again while the count is below 5. Line 7 asks for a timer. Line 8 starts the first microtask. The output is microtask 0 to microtask 4, then timer.

The limit of 5 matters. A version without a limit would never stop. It would freeze the page, and you would have to close the tab.

Starvation is not a promise bug. It comes from how the work is scheduled. A long chain of promise callbacks or queued microtasks can do useful work, and still keep clicks, timers, and drawing from getting a turn.

Back to the checkout lines: the cashier can't go back to the main line while each person in the express lane calls one more friend into it. With the limit, the fifth person brings no one. The express lane empties, and the timer gets its turn.

1let rounds = 0;2 3function continueLater() {4  console.log("round", rounds);5  rounds += 1;6  if (rounds < 3) setTimeout(continueLater, 0);7}8 9continueLater();

Yielding means pausing your work so the host can run other things first. Line 1 starts a counter. Lines 3 to 7 define continueLater. Line 6 asks for a timer for the next round, instead of adding a microtask. Line 9 starts the first round. The output is round 0, round 1, then round 2. Between rounds, the host gets a fresh turn.

Try it: how fast the queue grows

Change one setting: how many new microtasks each microtask adds. The playground calls these its "children". The model stops at 12 microtasks, so the output stays short. Try 0, then 1, then 2, and watch where the timer appears.

const tasks = ["timer"];
const microtasks = ["promise"];

function runTask(label) {
  const output = [label];
  while (microtasks.length) output.push(microtasks.shift());
  return output;
}

console.log(runTask(tasks.shift()).join(", "));

With 0 children, the queue is empty after the first microtask. With 1 child, each microtask adds the next one, like a chain. With 2 children, the queue grows faster. In every run, the timer comes only after all the microtasks shown.

Reset goes back to 1 child and clears the old output. So every try starts from the same state.

queueMicrotask and promise jobs share one queue

queueMicrotask(callback) adds a callback straight to the microtask queue. Ready promise jobs wait in that same queue. The queue is FIFO: first in, first out. So callbacks run in the order they were added, whichever way they were added.

1queueMicrotask(() => console.log("microtask"));2Promise.resolve().then(() => console.log("promise job"));3queueMicrotask(() => console.log("last microtask"));4console.log("script");

Line 1 queues the first microtask. Line 2 queues a promise job behind it. Line 3 queues one more callback. Line 4 logs right away. The output is script, microtask, promise job, then last microtask.

1const loop = makeLoop(["click"], []);Run2loop.queueMicrotask("first");3loop.queueMicrotask("second");4const output = loop.runTask();5console.log(output.join(", "));

There is one real difference between the two. It shows when the callback throws an error:

• A throw inside a then callback makes the promise returned by then fail. A .catch later in the chain can handle it.
• A throw inside a queueMicrotask callback is reported as an uncaught error. There is no promise around it to catch it.

Use queueMicrotask when you mean "run this small callback right after the current code". Use promises when the work has a result or an error to pass along. With either one, you still have to handle errors.

1Promise.resolve()2  .then(() => {3    throw new Error("promise problem");4  })5  .catch((error) => console.log("caught", error.message));6 7queueMicrotask(() => console.log("microtask still runs"));

Lines 1 to 5 make a promise chain. The throw on line 3 makes the chain fail, so the .catch on line 5 logs caught promise problem. Line 7 queues a separate callback, which logs microtask still runs.

The output is microtask still runs first, then caught promise problem. The .catch callback is only queued after the throw on line 3 happens. By then, the callback from line 7 is already waiting in the queue.

If the callback on line 7 threw an error, nothing would catch it. There is no promise for it to fail.

So pick by what you need. Use a promise chain when the caller needs a result and a way to handle errors. Use queueMicrotask for a small callback right after the current code, and handle errors inside it.

Using the queue in an app

Microtasks are good for small tidy-up work right after the current code finishes. They are not for heavy work. For example, after a cart changes, you can queue one quick update of the total. But a big loop should pause, so the browser can respond to the user.

1function updateCart() {2  queueMicrotask(() => console.log("update total"));3}4updateCart();5console.log("click finished");

Lines 1 to 3 define updateCart. Line 2 queues the quick total update. Line 4 calls the function. Line 5 finishes the click handler first. The output is click finished, then update total.

If the queued work keeps adding more of itself, use a task instead, such as a timer. That lets the host draw the page, handle clicks, and run other waiting work.

Keep each microtask small and on purpose. Queue one update after a click, and let it finish. Don't let a microtask quietly turn into a loop that never ends. A checkout page should stay quick, even when the cart changes many times in a row.

Common misconceptions

• "A microtask is just a faster timer." It is not a timer at all. It runs at a checkpoint, before the next task.
• "A checkpoint runs one callback." It keeps running callbacks until the queue is empty.
• "The spec controls the browser's queue." The spec only hands promise jobs to the host, through HostEnqueuePromiseJob.
• "queueMicrotask turns errors into failed promises." There is no promise around its callback, so an error is reported as uncaught.
• "Starvation means a timer got lost." The timer is still waiting. It runs once the checkpoint ends.

Each row of this table is one word from the lesson: what it means, and what it is easy to mix it up with.

When an output surprises you, write it out in this order:

1. The normal logs from the current code.
2. The microtasks, in the order they were queued. Include new ones that a running microtask adds.
3. Only then, the next task, such as a timer.

This also stops vague answers like "the event loop did it". The event loop is the host's cycle: pick a task, run it, run a checkpoint, repeat. A useful answer names the task, the queued microtask, the checkpoint, and the task that had to wait.

Practice exercises

setTimeout(() => console.log("timer"), 0);
Promise.resolve().then(() => console.log("promise"));
console.log("script");

setTimeout(() => console.log("timer"), 0);
Promise.resolve().then(() => console.log("promise"));
console.log("script");

let rounds = 0;
function addMicrotask() {
  console.log("microtask", rounds);
  rounds += 1;
  if (rounds < 5) queueMicrotask(addMicrotask);
}
setTimeout(() => console.log("timer"), 0);
queueMicrotask(addMicrotask);

queueMicrotask(() => console.log("microtask"));
Promise.resolve().then(() => console.log("promise job"));
queueMicrotask(() => console.log("last microtask"));
console.log("script");

Check your understanding

Read each code question in the same order: the current code first, then the microtasks in the order they were queued, then any later task.

Key takeaways

• ECMAScript says promise jobs run later, in order. The host (a browser or Node) owns the real queues.
• HostEnqueuePromiseJob is the spec step that hands a ready promise job to the host.
• A checkpoint runs every waiting microtask after a task, before the next task.
• Microtasks that keep adding microtasks stop timers and page drawing from getting a turn, until the queue is empty.
• Promise jobs and queueMicrotask callbacks share one first-in, first-out queue, but handle errors differently.

Coming next: How async code is compiled down.