How promises work inside

A promise has waiting lists

A promise looks small in app code. You create one, attach then or catch, and wait. Inside the language model, that small object remembers its state, its result, and the reactions that are waiting for that result.

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

Line 1 creates an order that is already fulfilled with "burger". Line 2 adds a reaction that will log the food. Line 3 logs synchronously, so the real output is waiting and then burger.

The everyday lessons Promises, Promise chaining, Microtasks, and Build a promise teach how to use these APIs. This lesson keeps that order-token model and looks one layer lower.

States and reaction records

Pending means the order has not settled. Fulfilled means it has a value. Rejected means it has a reason. A promise begins pending, settles once, and never changes to a different state afterward.

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 creates the pending teaching-model order. Lines 3 and 4 add Asha and Noah to its reaction list. Line 6 fulfills the order, moving both saved reactions into jobs. Line 7 drains those jobs, so the visible order is Asha first and Noah second.

A reaction record is more than a function name in the real specification. It also connects to the promise created by that then call. The teaching model keeps only the part we need here: a handler, an order, and a jobs queue.

PromiseReactionJob

A PromiseReactionJob is the queued work that runs one ready reaction. When a pending promise settles, every waiting reaction becomes one of these jobs. When you call then on an already settled promise, its reaction can become a job straight away.

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

Line 1 creates a fulfilled order. Line 3 adds its reaction, which is queued instead of called inline. Line 4 therefore prints first. The real 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 replay instruments the small model from the source file. First it stores Asha, then Noah. Settlement changes the model state and fills its jobs queue. Draining that queue produces Asha before Noah, just as the order-token list promised.

This separation protects ordinary JavaScript reasoning. The code that calls fulfill can finish its own work before a reaction starts. A handler can add more promise work, return another promise, or throw; each outcome gets its own continuation rules instead of interrupting the statement that settled the first order.

Registration order matters only among reactions that are ready in the same queue. It is not a promise that every unrelated browser action waits behind them. The next lesson on the microtask queue will place these jobs beside rendering, timers, and host checkpoints.

PromiseResolveThenableJob

A thenable is an object or function with a callable then method. It is promise-like, but it is not necessarily a native promise. That matters because its then method is ordinary user-provided code.

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

Line 1 makes the outer pending order. Lines 3 through 5 make a plain object with then. Line 8 resolves the outer order with that object, so the model queues a PromiseResolveThenableJob. Line 9 drains it; only then does the outer order receive burger.

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

The separate job is useful because thenables can throw, resolve twice, or come from code you do not control. The resolution procedure has rules for those cases. Our model stays small, but it preserves the important boundary: adopting a thenable is extra queued work.

Native promises are designed to cooperate with this procedure too. That is why a library can return a promise-like object without every caller needing special syntax. The trade-off is that adopting another result is not the same small path as storing a plain string.

When you debug an ordering problem, do not start by blaming the thenable. First ask whether the value being resolved is plain, native-promise-shaped, or a custom object with then. That one question often explains why a familiar callback moved to a later turn.

Why promise resolution takes extra ticks

Resolving with a plain value and resolving with another promise look similar at a call site. They are not identical internally. The second case needs the outer promise to follow the inner promise, so jobs can be added before the outer reaction is ready.

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}

Line 1 makes the inner ready promise. Lines 2 and 3 call fresh promise resolvers, once with a value and once with that inner promise. Lines 5 and 6 schedule their output reactions. Lines 8 through 10 add tick markers. In the tested output, value arrives appears before tick 1, while promise arrives appears two ticks later.

Do not turn this into a stopwatch rule. The markers are promise jobs that make one ordering relationship easy to see. The lesson test proves this exact snippet's printed order, not a timing promise for every engine or application.

The important comparison is relative. Both results are asynchronous. The plain-value order can become fulfilled during its resolver call, so its reaction is ready immediately. The promise-value order must first follow later; that adoption creates more work before its reaction can be queued.

This is also why copying a short output sequence from a console can mislead. Add your own small marker jobs, like this lesson does, and compare the whole sequence. A marker is easier to reason about than milliseconds, which can vary with a busy device.

Unhandled rejection tracking

Unhandled rejection tracking is host behavior around a rejected promise that still has no rejection handler at the end of a job checkpoint. The language defines promise behavior; browsers and Node decide how to notify developers about a missing owner.

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

Lines 1 through 4 register a browser listener and prevent its default report. Line 6 creates a rejected order. Line 7 attaches a handler in a later microtask. This browser-runnable example demonstrates registration and a later handler without leaving a deliberately unhandled rejection 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 registers Node's unhandledRejection listener. Line 5 rejects with sold out. The lesson test runs this in a child process and proves stable output: unhandled sold out, then done. Attach handlers in real app code instead of depending on host reports.

A browser can dispatch rejectionhandled when a promise that was reported later gains a handler. That event is useful diagnostic evidence, not a pattern for delaying error handling. A request should normally have a clear failure path before users can interact with its result.

Node policies and browser console presentation can differ, which is why this lesson proves only the stable listener output from its own child process. The rule your application controls is simpler: return the promise to an owner or attach the handler yourself.

Compare resolution inputs

Use one input at a time. A plain value has no adoption work. A native promise and a thenable both ask the outer promise to follow another result. The playground runs real promises and prints marker jobs beside the final arrival.

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 restores the plain-value selection and clears the output. That makes each run independent, so you can compare the order without an earlier run leaving jobs or text behind.

What this changes in app code

Most application code should not recreate the promise resolution procedure. The useful habit is to know who owns each promise. A function can return a request promise to its caller, or it can attach a failure handler at the boundary that can show a message, retry, 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 names the boundary that chooses what successful food display means. Line 2 returns the chained promise, so a later failure can still be owned. Line 5 attaches that owner. Returning promises is often clearer than starting a chain and forgetting where failure should go.

Common misconceptions

• “Resolve runs handlers now.” It starts resolution; reactions run as later jobs.
• “A settled promise makes `then` synchronous.” Its new reaction still queues work.
• “Every thenable is a Promise.” A thenable only needs a callable then.
• “An unhandled report handles the error.” It only tells you that your code did not handle it in time.
• “Extra ticks mean a timer.” The lesson's extra turns are promise jobs, not timer tasks.

When an ordering surprise appears, write the synchronous statements first. Then list the promise jobs that were created. This simple trace is more useful than guessing that a browser, network request, or timer changed the order.

It also keeps the vocabulary honest. A reaction is saved information. A job is runnable work. A host report is outside the promise's success or failure value. Calling all three things “callbacks” hides the exact step that made an output move.

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 burger-order model, then verify each answer with state, reaction, job, and host-tracking vocabulary.

Key takeaways

• A pending promise stores reaction records from then and catch.
• Settlement turns ready reactions into PromiseReactionJobs, so handlers run after synchronous code.
• Thenable adoption uses PromiseResolveThenableJob, which can add observable microtask turns.
• Resolving with another promise can arrive later than resolving with a plain value.
• Browsers and Node track rejected promises that remain unhandled and report them through host events.
• Real code still needs a clear owner for every failure.

Coming next: await under the hood, where an async function pauses and resumes using this promise machinery.