How promises work inside

A promise keeps a waiting list

A promise is an object that stands for a result that may not be ready yet. In your code, you make one, call then or catch on it, and wait. Inside, the promise keeps track of three things:

• its state: still waiting, done, or failed;
• its result: the value, or the reason it failed;
• a waiting list of functions that want the result.

1const order = Promise.resolve("burger");2order.then((food) => console.log(food));3console.log("waiting");

Line 1 makes a promise called order that already holds "burger". Line 2 adds a handler: a function that runs once the promise has its result. This one prints the food. Line 3 prints waiting.

The output is waiting, then burger. The handler on line 2 waited, even though the burger was already there.

You learned how to use promises in Promises, Promise chaining, Microtasks, and Build a promise. This lesson uses the same food-order examples and shows what happens inside the promise.

States and saved handlers

A promise is always in one of three states:

• Pending: there is no result yet.
• Fulfilled: it has a value, like "burger".
• Rejected: it failed, and it has a reason, like "sold out".

Every promise starts pending. It settles only once: it becomes fulfilled or rejected. After that, its state never changes again.

The next code is not the real Promise. It is a small model made for this lesson, so you can see the waiting list. It has three helpers:

• makeOrder() makes a pending order. Its then adds a handler to the waiting list.
• order.fulfill(value) gives the order its value.
• runJobs() runs every job in the line, first to last.

1const order = makeOrder();2 3order.then((food) => console.log("Asha gets", food));4order.then((food) => console.log("Noah gets", food));5 6order.fulfill("burger");7runJobs();

Line 1 makes a pending order. Lines 3 and 4 add two handlers, one for Asha and one for Noah. The order has no food yet, so it saves both on its waiting list.

Line 6 fulfills the order with "burger". This does not run the handlers. It moves them into the line of jobs, Asha first. Line 7 runs the jobs. The output is Asha gets burger, then Noah gets burger.

In the real specification, a saved handler is called a reaction record. It holds two things:

• the function you passed to then;
• the new promise that then gave back. That promise gets the function's result.

The model keeps only the function, because that is all this lesson needs.

Reaction jobs run the handlers later

When a saved handler is ready to run, JavaScript makes a PromiseReactionJob. That is the specification's name for "the job that runs one saved handler". It happens in two cases:

• A pending promise settles. Each handler on its waiting list becomes one job.
• You call then on a promise that has already settled. The new handler becomes a job straight away.

Either way, the job waits in line. Promise jobs wait in a line called the microtask queue. That line starts as soon as the code running now has finished.

1const order = Promise.resolve("burger");2 3order.then((food) => console.log("first", food));4console.log("after then");

Line 1 makes an order that already holds "burger". Line 3 adds a handler. The order is ready, but the handler is not called here. It goes into the job line. Line 4 prints straight away. The output is after then, then first burger.

1const order = makeOrder();Run2 3order.then((food) => console.log("Asha gets", food));4order.then((food) => console.log("Noah gets", food));5 6order.fulfill("burger");7runJobs();

The step-through above replays the small model from the last section, one step at a time. It is a replay of the lesson's model, not a look inside a real JavaScript engine:

1. Lines 3 and 4 save Asha, then Noah.
2. Line 6 settles the order and fills the job line.
3. Line 7 runs the line, so Asha comes before Noah.

Why wait at all? The code that settles a promise can finish its own work first. A handler can do many things: start more promise work, return another promise, or throw an error. None of that can break into the middle of the line that settled the promise.

Handlers run in the order they were added. That order only counts among jobs in the same line. It does not mean every browser event waits behind them. A later lesson on the microtask queue shows where these jobs sit next to timers and screen updates.

Thenables get one extra job

A thenable is any object (or function) that has a then method you can call. From the outside it looks like a promise, but it may not be a real one. Its then method is ordinary code that someone wrote. It might throw an error, or call back twice.

When you resolve a promise with a thenable, the promise does not keep the thenable as its value. It adopts it: it calls the thenable's then and takes the result that comes back. To do that safely, JavaScript queues a separate job called PromiseResolveThenableJob.

1const order = makeOrder();2const kitchenToken = {3  then(resolve) {4    resolve("burger");5  },6};7 8resolveOrder(order, kitchenToken);9runJobs();

Line 1 makes a pending order. Lines 2 to 6 make a plain object, kitchenToken, with a then method. That makes it a thenable. Its then calls resolve("burger") on line 4.

Line 8 resolves the order with kitchenToken. The model does not call then right here. It queues a PromiseResolveThenableJob. Line 9 runs the jobs. Only then does the order get "burger".

1const order = makeOrder();Run2const kitchenToken = {3  then(resolve) {4    resolve("burger");5  },6};7 8resolveOrder(order, kitchenToken);9runJobs();

Why a separate job? A thenable can throw an error, call resolve twice, or come from code you don't control. The rules for adopting a thenable deal with each of those cases. The model leaves those rules out. It keeps the main point: taking a thenable's result costs one extra job.

Real promises have a then method too, so they follow the same rules. That is why a library can hand you a promise-like object, and you can still call then on it. The cost is a few more jobs than for a plain string.

When your output comes in a surprising order, first ask: what did I resolve with?

• A plain value, like a string.
• A real promise.
• Some other object with a then method.

The answer often explains why a handler ran a little later.

Why a promise inside a promise arrives later

Resolving with a plain value and resolving with another promise look alike when you write them. Inside, they are different. With another promise, the outer promise must first follow the inner one. That takes extra jobs before the outer handler can run.

A tick here means one turn of the job line: one waiting job runs. To make the ticks visible, the next code adds two marker jobs. They are tiny promise jobs that only print tick 1 and tick 2.

1const later = Promise.resolve("tea");2const valueOrder = new Promise((resolve) => resolve("value"));3const promiseOrder = new Promise((resolve) => resolve(later));4 5valueOrder.then(() => console.log("value arrives"));6promiseOrder.then(() => console.log("promise arrives"));7 8for (let tick = 1; tick <= 2; tick += 1) {9  Promise.resolve().then(() => console.log("tick", tick));10}

1. Line 1 makes a promise called later that already holds "tea".
2. Line 2 makes valueOrder and resolves it with the plain string "value".
3. Line 3 makes promiseOrder and resolves it with the promise later.
4. Lines 5 and 6 add a handler to each order.
5. Lines 8 to 10 add the two marker jobs.

The output is value arrives, tick 1, tick 2, promise arrives. valueOrder was fulfilled during line 2, so its handler was ready first. promiseOrder had to follow later first. That took two extra jobs, so both markers ran before it.

Read this as an order, not a time. The markers make one fact easy to see in this exact code. The lesson test checks this printed order. It does not promise the same number of ticks in every engine or every app.

Both results still come later than the code running now. The only difference is how many jobs run first.

To check your own code, add marker jobs like these and compare the whole output. Markers are easier to reason about than milliseconds, which change when the computer is busy.

The table below lists the four kinds of promise work in this lesson. Read each row as: what it is, when it shows up, and what it does.

Reports for rejections nobody handles

A rejected promise needs a handler, such as catch, that decides what the failure means. Sometimes a promise is rejected, and it still has no handler after the waiting jobs have run. Then the host notices. The host is the program that runs your JavaScript: a browser or Node. This is called unhandled rejection tracking.

The JavaScript language says how promises behave. The host decides how to tell you about a rejection that nobody handled:

• A browser fires an unhandledrejection event on window.
• Node fires an unhandledRejection event on process.

1window.addEventListener("unhandledrejection", (event) => {2  console.log("unhandled", event.reason);3  event.preventDefault();4});5 6const order = Promise.reject("sold out");7queueMicrotask(() => order.catch(() => console.log("handled later")));

1. Lines 1 to 4 add a listener for the browser's unhandledrejection event. On line 3, event.preventDefault() stops the browser from printing its own error.
2. Line 6 makes an order that is already rejected with "sold out".
3. Line 7 adds a catch handler a moment later. queueMicrotask(fn) puts fn in the job line, so the handler is added by a job.

The handler arrives before the browser checks for unhandled rejections. So the code shows the listener and a late handler, without leaving a real unhandled error in the editor.

1process.on("unhandledRejection", (reason) => {2  console.log("unhandled", reason);3});4 5Promise.reject("sold out");6setTimeout(() => console.log("done"), 0);

Line 1 adds a listener for Node's unhandledRejection event. Line 5 makes a promise rejected with "sold out" and never handles it. Line 6 sets a timer that prints done.

The lesson test runs this code in a separate Node program. It prints unhandled sold out, then done. In real code, add the handler yourself. Don't count on the host's report.

A browser can also fire rejectionhandled. That happens when a promise was already reported, and a handler is added later. The event helps you find bugs. It is not a reason to add handlers late. A request should have a clear plan for failure before the user sees its result.

Node and browsers show these reports in different ways, and Node has settings that change them. So the lesson only checks the listener's output. The rule you control is simpler: return the promise to code that handles it, or add the handler yourself.

Try three kinds of input

The playground resolves a new promise with the input you pick. Pick one at a time and run it:

• Plain value: the string "burger". No extra jobs are needed.
• Real promise: a promise made by Promise.resolve that holds the burger. The outer promise must follow it.
• Thenable object: an object with a then method. The outer promise must follow it too.

The playground runs real promises. It prints the two marker jobs and the moment the food arrives, in the order they happen.

1const received = selected === "value"2  ? "burger"3  : selected === "promise"4    ? Promise.resolve("burger")5    : { then(resolve) { resolve("burger"); } };6 7new Promise((resolve) => resolve(received))8  .then((food) => console.log("food", food));9Promise.resolve().then(() => console.log("tick 1"));10Promise.resolve().then(() => console.log("tick 2"));

Reset picks Plain value again and clears the output. So every run starts fresh, and an earlier run can't leave jobs or text behind.

What this changes in your code

Most app code never rebuilds these rules. The useful habit is to know who owns each promise. The owner is the code that decides what happens when the promise fails. A function can do one of two things:

• return the promise, so the code that called it can handle the failure;
• add a catch handler itself, at a place that can show a message, try again, or recover.

1function showOrder(order) {2  return order.then((food) => console.log("show", food));3}4 5showOrder(Promise.resolve("burger")).catch((reason) => console.log("problem", reason));

Line 1 starts showOrder, which decides how to show the food. Line 2 returns the promise chain, so whoever called showOrder can still handle a failure. Line 5 calls showOrder and adds catch. That catch is the owner of any failure. Here nothing fails, so the code prints show burger.

Returning promises is usually clearer than starting a chain and forgetting where failures should go.

Common misconceptions

• "resolve runs the handlers right away." It only starts the process. The handlers run later, as jobs.
• "then on a settled promise runs at once." The new handler still waits in the job line.
• "Every thenable is a real promise." A thenable only needs a then method you can call.
• "The unhandled report handles the error." It only tells you that your code did not handle it in time.
• "Extra ticks mean a timer." The extra turns in this lesson are promise jobs, not timers.

Each row of the table takes one word from this lesson. Read it as: what the word really means, and what it does not mean.

When the output order surprises you, first write down the lines that run straight away. Then list the promise jobs, in the order they were made. This short list usually explains the order. Don't guess that the browser, the network, or a timer changed it.

It also keeps the words clear:

• A reaction is a saved handler.
• A job is work waiting in line to run.
• A host report is a message from the browser or Node. It is not the promise's value or reason.

If you call all three "callbacks", you can't tell which step moved your output.

Practice exercises

const order = Promise.resolve("burger");
order.then((food) => console.log(food));
console.log("waiting");

const order = Promise.resolve("tea");
order.then((food) => console.log("Asha", food));
order.then((food) => console.log("Noah", food));
console.log("waiting");

const order = Promise.reject("sold out");
order.catch((reason) => console.log("handled", reason));

order.catch((reason) => console.log("handled", reason));

function showOrder(order) {
  order.then((food) => console.log("show", food));
}
showOrder(Promise.resolve("burger"));

Check your understanding

Use the food-order examples. For each answer, ask: is this a saved handler, a job waiting in line, an extra job for a thenable, or a report from the host?

Key takeaways

• A pending promise saves the handlers from then and catch on a waiting list.
• When it settles, each saved handler becomes a job, called a PromiseReactionJob. So handlers run after the code running now.
• Taking a thenable's result needs one more job, called a PromiseResolveThenableJob. That can add extra ticks.
• Resolving with another promise can arrive later than resolving with a plain value.
• Browsers and Node report rejected promises that nobody handled, through events.
• Your code still needs a clear owner for every failure.

Coming next: await under the hood. You will see how an async function pauses and starts again, using these same promise jobs.