No history yet

Internal Promise Mechanics

Promise States and Fates

Every Promise is a state machine. It exists in one of three mutually exclusive states: pending, fulfilled, or rejected. A Promise starts in the pending state. This means the asynchronous operation it represents hasn't completed yet. It's waiting.

From pending, it can transition to one of two final states. If the operation succeeds, the Promise becomes fulfilled, holding a resulting value. If the operation fails, it becomes rejected, holding a reason for the failure, typically an error object. Once a Promise is fulfilled or rejected, it is considered settled. This transition is a one-way street; a settled Promise can never change its state again. This immutability is crucial for creating predictable asynchronous code.

A Promise is in one of these states:

  • pending: initial state, neither fulfilled nor rejected.
  • fulfilled: meaning that the operation completed successfully.
  • rejected: meaning that the operation failed.

The Executor Function

The life of a Promise begins with its constructor, which takes a single argument: an executor function. This function is not saved for later; it is executed immediately and synchronously when the Promise is created.

The JavaScript engine passes two functions as arguments to your executor: resolve and reject. Your executor's job is to start an asynchronous operation and then, upon its completion, call either resolve with the result or reject with an error. It's the bridge between your asynchronous work and the Promise's state.

const myPromise = new Promise((resolve, reject) => {
  // This code runs immediately!
  console.log('Executor function has started.');

  // Kick off an async operation, e.g., a network request
  const operationSucceeded = true; // Simulate the outcome

  if (operationSucceeded) {
    resolve('Operation was successful!'); // Fulfills the promise
  } else {
    reject(new Error('Operation failed.')); // Rejects the promise
  }
});

Even though the work inside might be asynchronous, the executor itself starts synchronously. The resolve and reject functions, when called, are what queue up the reactions to the Promise's settlement.

The Microtask Queue

To understand why Promises behave the way they do, we need to look at how JavaScript's handles tasks. It's not just one single queue. There are two primary queues: the Macrotask Queue (often just called the Task Queue) and the high-priority Microtask Queue.

The Macrotask Queue handles tasks like setTimeout, setInterval, user interactions (like clicks), and I/O operations. The Microtask Queue is for smaller, urgent tasks that need to run immediately after the current script finishes. This is where Promise callbacks (.then(), .catch(), .finally()) live. The specification calls these s.

The rule is simple but critical: after the currently executing script finishes and the call stack is empty, the Event Loop will run all tasks in the Microtask Queue until it's empty. Only after the Microtask Queue has been completely drained will it process the next single task from the Macrotask Queue.

This prioritisation explains a classic JavaScript puzzle: why a Promise.then() callback always runs before a setTimeout with a delay of 0 milliseconds.

console.log('Start');

setTimeout(() => {
  console.log('setTimeout callback (Macrotask)');
}, 0);

Promise.resolve().then(() => {
  console.log('Promise.then callback (Microtask)');
});

console.log('End');

// Output:
// Start
// End
// Promise.then callback (Microtask)
// setTimeout callback (Macrotask)

Here’s the execution order:

  1. 'Start' is logged.
  2. setTimeout is called. Its callback is placed in the Macrotask Queue.
  3. Promise.resolve().then() is called. Its callback is placed in the Microtask Queue.
  4. 'End' is logged. The main script is now finished.
  5. The Event Loop checks the Microtask Queue. It's not empty, so it runs the promise callback, logging 'Promise.then callback (Microtask)'.
  6. The Microtask Queue is now empty. The Event Loop checks the Macrotask Queue, finds the timeout callback, and runs it, logging 'setTimeout callback (Macrotask)'.

Understanding this internal queuing mechanism is key to mastering asynchronous JavaScript. It explains why your promise-based logic executes in a specific, predictable order, separate from other asynchronous events.

Quiz Questions 1/5

What are the three mutually exclusive states of a JavaScript Promise?

Quiz Questions 2/5

True or False: Once a Promise is settled (either fulfilled or rejected), its state can change again.