Inside a Promise

A Promise is three fields and a list

Strip away the API and a Promise object in V8 is small. Its essential internal slots are:

• [[PromiseState]] — one of pending, fulfilled, rejected. It starts pending and transitions exactly once. This settle-once invariant is the heart of the machine: after it leaves pending, no later resolve/reject can change it.
• [[PromiseResult]] — the value it fulfilled with or the reason it rejected with. Meaningless while pending.
• [[PromiseFulfillReactions]] / [[PromiseRejectReactions]] — two lists of PromiseReaction records, the handlers registered by .then/.catch while the promise was still pending. Once settled, these lists are cleared and replaced by the result.

A PromiseReaction record bundles three things: the type (fulfill or reject), the handler (your onFulfilled / onRejected callback, or undefined), and the capability of the new promise that .then returned (the resolve/reject functions that will settle that downstream promise). That last part is why chaining works at all.

What .then actually does

promise.then(onF, onR) does three concrete things, in order:

1. Creates a new promise (the “result capability”) and remembers its resolve/reject functions.
2. Builds two PromiseReaction records — one fulfill, one reject — each wrapping the matching handler and that new capability.
3. Either registers or schedules them. If the original promise is still pending, the reactions are appended to its reaction lists and nothing runs yet. If the promise is already settled, .then does not run the handler synchronously — it immediately enqueues a PromiseReactionJob as a microtask for the matching reaction.

const p = Promise.resolve(42);   // already fulfilled with 42
const q = p.then(v => v + 1);     // q is a NEW promise; one PromiseReactionJob queued now
// q settles with 43 after that job runs (one microtask later)

So .then never runs your handler “right now,” even on an already-settled promise. It always defers to a microtask. That single guarantee is what makes Promise ordering predictable: a .then callback is always one microtask removed from the settling, never synchronous.

Settling enqueues one job per reaction

When the producer calls the resolve function (settling the promise to fulfilled), the engine runs FulfillPromise: it sets [[PromiseState]] to fulfilled, stores the value, and then walks [[PromiseFulfillReactions]], enqueuing a PromiseReactionJob microtask for each registered reaction. Each job, when the microtask checkpoint runs it, calls the reaction’s handler with the result, and uses the return value to settle that reaction’s downstream promise (which may itself have reactions, cascading more jobs). Rejection is symmetric via RejectPromise and [[PromiseRejectReactions]].

This is why fan-out costs N microtasks: p.then(a); p.then(b); p.then(c) on a settled p registers three reactions and enqueues three PromiseReactionJobs — a, b, c run as three separate microtasks in registration order.

The extra tick: resolving with a thenable

Here is the subtlety that trips up tick-counting. If you resolve a promise with another promise (or any thenable), the engine cannot adopt its value synchronously — a thenable might settle later. So ResolvePromise schedules a PromiseResolveThenableJob: a microtask whose only purpose is to call the inner thenable’s .then to subscribe to it. That subscription is itself another deferral. The consequence: resolving promise A with promise B adds an extra microtask tick compared to resolving A with a plain value, because the engine must bounce through PromiseResolveThenableJob before A can even start adopting B’s eventual state.

// Plain value: q settles one tick after p's reaction runs.
Promise.resolve(1).then(v => v);

// Thenable: returning a promise from a handler costs an extra tick,
// because the outer promise must adopt the inner one via a resolve job.
Promise.resolve(1).then(v => Promise.resolve(v));   // extra PromiseResolveThenableJob

This is the mechanical reason the original await cost three ticks (covered next lesson): the spec wrapped the awaited value in a throwaway promise and adopted it through a thenable job. V8 7.2 (2018) special-cased native promises to skip those extra jobs.

Unhandled-rejection tracking

The engine also watches for rejections with no reject handler. When RejectPromise runs and the reject reaction list is empty (no .catch/.then(_, onR) attached), the promise is flagged as having a potentially unhandled rejection. The host is notified via HostPromiseRejectionTracker, which is what fires the browser’s unhandledrejection event and Node’s process.on('unhandledRejection'). Crucially this is deferred: a handler attached later in the same turn clears the flag (fires rejectionhandled), because attaching .catch registers a reject reaction that consumes the stored rejection. This deferral is why “add a .catch on the next line” still suppresses the warning — but a .catch attached a macrotask later does not.