Building XPromise: A Deep Dive into Custom JavaScript Promises

JavaScript is known for its asynchronous nature, enabling operations like data fetching, animations, and file handling without blocking other processes. Promises are at the heart of handling asynchronous operations gracefully, making our code cleaner and more manageable. This project, XPromise, is a custom implementation of JavaScript Promises, helping us explore how the Promise mechanism works internally.

You can check out the full implementation on GitHub.

What is a Promise?

A Promise in JavaScript is a special object representing the eventual completion or failure of an asynchronous operation. With Promises, we can queue up operations to run after the completion of a task, even if we don’t know when it will be done. Here’s what makes a Promise unique:

1. Three States: A Promise can be Pending, Fulfilled, or Rejected.
2. Immutable State Change: Once a Promise is resolved (fulfilled or rejected), it cannot change states.
3. Chaining with .then and .catch: Promises provide .then() for handling fulfilled values and .catch() for errors, making them composable.

Why Build a Custom Promise?

Creating a custom Promise, like XPromise, provides a deeper understanding of its inner workings:

• State Management: We handle states in a way that ensures only one final state.
• Callback Queuing: The Promise must queue up callbacks to be executed once it’s resolved.
• Error Handling: It includes a way to handle asynchronous errors gracefully, emulating native Promise behavior.

Project Walkthrough

Let’s go through the code for XPromise, exploring each component that makes it work just like JavaScript’s native Promises.

Setting Up States and Basic Structure

XPromise starts by defining three states: PENDING, FULFILLED, and REJECTED.

const PENDING = "PENDING";
const FULFILLED = "FULFILLED";
const REJECTED = "REJECTED";

class XPromise {
  constructor(executor) {
    this.state = PENDING;
    this.queue = [];
    doResolve(this, executor);
  }
  // ...
}

1. Constructor and Initial Setup:
   • XPromise accepts an executor function, which runs immediately.
   • this.state keeps track of the current state, while this.queue holds all functions queued up by .then() calls.

Adding the then, catch, and finally Methods

With then, catch, and finally, we handle fulfilled, rejected, and cleanup scenarios. Here’s how XPromise achieves chaining:

then(onFulfilled, onRejected) {
  const promise = new XPromise(() => {});
  handle(this, { promise, onFulfilled, onRejected });
  return promise;
}

catch(onRejected) {
  return this.then(null, onRejected);
}

finally(onFinally) {
  return this.then(onFinally, onFinally);
}

1. then: The then method creates a new XPromise instance and stores it along with onFulfilled and onRejected callbacks. This ensures that the next Promise in the chain receives the output of the previous one.
2. catch: A shorthand for handling errors, equivalent to calling then(null, onRejected).
3. finally: Handles cleanup actions that execute regardless of the Promise’s outcome.

Managing Resolved States with handle

The handle function decides if the Promise is still pending or resolved. If it’s pending, the handler is added to the queue to be executed later. If the Promise is resolved, it immediately processes the handler.

function handle(promise, handler) {
  while (promise.state !== REJECTED && promise.value instanceof XPromise) {
    promise = promise.value;
  }

  if (promise.state === PENDING) {
    promise.queue.push(handler);
  } else {
    handleResolved(promise, handler);
  }
}

Resolving and Rejecting Promises

Fulfilled and rejected Promises need special functions to handle their results. Here’s how XPromise achieves it:

function fulfill(promise, value) {
  if (value === promise) {
    return reject(promise, new TypeError());
  }

  if (value && (typeof value === "object" || typeof value === "function")) {
    let then;
    try {
      then = value.then;
    } catch (e) {
      return reject(promise, e);
    }

    if (typeof then === "function") {
      return doResolve(promise, then.bind(value));
    }
  }

  promise.state = FULFILLED;
  promise.value = value;
  finale(promise);
}

function reject(promise, reason) {
  promise.state = REJECTED;
  promise.value = reason;
  finale(promise);
}

1. Fulfill and Reject:

   • fulfill and reject finalize the Promise, updating its state and value.
   • If value is a Promise or thenable, we defer to doResolve to ensure it’s handled correctly.

2. Finalizing Queued Handlers:

   • Once the Promise is resolved, finale iterates through the queue to execute all handlers in order.

The Executor Function doResolve

The doResolve function runs the executor safely by wrapping resolve and reject calls, preventing any further state changes if they are called multiple times.

function doResolve(promise, executor) {
  let called = false;
  function wrapFulfill(value) {
    if (called) return;
    called = true;
    fulfill(promise, value);
  }

  function wrapReject(reason) {
    if (called) return;
    called = true;
    reject(promise, reason);
  }
  try {
    executor(wrapFulfill, wrapReject);
  } catch (e) {
    wrapReject(e);
  }
}

Example Usage of XPromise

Now that we have a working XPromise, let’s try it out with a simple example:

const myPromise = new XPromise((resolve, reject) => {
  setTimeout(() => resolve("Operation Successful!"), 1000);
});

myPromise
  .then((value) => {
    console.log(value);  // "Operation Successful!"
    return "Next Step";
  })
  .then((nextValue) => console.log(nextValue))
  .catch((error) => console.error(error));

Key Takeaways

Reimplementing Promises from scratch provides hands-on insight into how asynchronous programming is managed in JavaScript:

• State Management ensures that the Promise resolves only once, staying either fulfilled or rejected.
• Callback Queueing allows for handling multiple chained .then() calls effectively.
• Error Handling with catch and finally helps in handling asynchronous errors gracefully.

To dive deeper into the code, check out the XPromise project on GitHub. Experiment with the code and feel free to customize it to explore more advanced features, such as Promise race conditions, chaining, and nesting!