Mastering JavaScript Promise Polyfill: A Complete Guide with Examples

A Promise polyfill is a JavaScript code snippet designed to fill the gap left by browsers that lack native support for Promises. These polyfills replicate the Promise API, enabling developers to leverage Promises in environments where they are not natively available.

In the ever-evolving web ecosystem, ensuring cross-browser compatibility is paramount. By employing Promise polyfills, developers can write code using modern asynchronous patterns without worrying about compatibility issues in older browsers. This approach leads to cleaner, more maintainable codebases and enhances the user experience across diverse browsing environments.

The Promise API in JavaScript provides a set of methods and functionality for handling asynchronous operations. Here are the key functionalities supported by the Promise API:

1. Creating Promises object
2. Chaining Promises
3. Error handling (Reject function support)
4. On fulfill (Resolver function support)
5. Helper functions, eg. Promise.all, Promise.any, Promise.race ....

Traditional way of creating and using promise

const Executor = ((resolve, reject) => {
  //async task
  setTimeout(() => {
    resolve(2);
  },1000);
  //if something went wrong => call reject
})

const myPromise = new Promise(Executor);

myPromise.then(ans => {console.log(ans)}).catch(e =>handleError(e));

Promise states

1. Promise Fulfilled : meaning that the operation was completed successfully.
2. Promise Rejected : meaning that the operation failed.
3. Promise Pending : initial state, neither fulfilled nor rejected.
4. Promise Settled : Either fulfilled or rejected

Let's explore a simplified example of a Promise polyfill:

In this example, we create a basic implementation of a Promise polyfill that supports the then and catch methods.

1. Creating the Promise Constructor

The Promise constructor is the foundation of the polyfill. It accepts an executor function, which in turn receives resolve and reject functions as arguments. Inside this executor function, the asynchronous operation is performed, and based on its outcome, either resolve or reject is called.

if (!window.Promise) { //checks if Promise object is available or not in global object
  window.Promise = function (executor) {
    // Polyfill implementation
  };
}

2. Handling Promise State and Values

The polyfill needs to maintain the state of the Promise (pending, fulfilled, or rejected) and store the value or reason when the Promise settles.

window.Promise = function (executor) {
  var ref= this;
  ref.state = 'pending';
  ref.value = undefined;
  ref.callbacks = [];
  
  // executor function and state transitions
};

3. Implementing Resolve and Reject

Inside the executor function, resolve and reject are defined. These functions transition the Promise's state to either fulfilled or rejected and store the corresponding value or reason. Additionally, they execute any registered callback functions.

window.Promise = function (executor) {
  // Other code...

  /*
  Resolve function is called by executor when the asynchronous task is finished.
  like in the uses example : we are calling the resolve after waiting for 1000 ms.
  */

  function resolve(value) {
    //
    if (ref.state !== 'pending') return; 

    ref.state = 'fulfilled';
    ref.value = value;
    ref.callbacks.forEach(function (callback) {
      return callback.onFulfilled(value);
    });
  }

/*
  Resolve function is called by executor when the asynchronous task has thrown error.
  */

  function reject(reason) {
    if (ref.state !== 'pending') return;
    ref.state = 'rejected';
    ref.value = reason;
    ref.callbacks.forEach(function (callback) {
      return callback.onRejected(reason);
    });
  }

  //Whenever we define a Promise object the executor function is called immediately
  executor(resolve, reject);
};

4. Chaining Promises with then()

The then method is crucial for chaining Promises. It registers callback functions to be executed when the Promise is fulfilled or rejected. This involves handling different scenarios based on the Promise's state at the time thenis called.

window.Promise.prototype.then = function (onFulfilled, onRejected) {
  var ref= this;
  return new Promise(function (resolve, reject) {
    // Handling different states and executing callbacks
  });
};

5. Handling Errors with catch()

The catch method is used to handle errors that occur within the Promise chain. It acts as a shorthand for calling then(undefined, onRejected). This ensures consistent error handling throughout the Promise chain.

window.Promise.prototype.catch = function (onRejected) {
  return this.then(null, onRejected);
};

if (!window.Promise) {
  window.Promise = function (executor) {
    var ref= this;
    ref.state = 'pending';
    ref.value = undefined;
    ref.callbacks = [];

    function resolve(value) {
      if (ref.state !== 'pending') return;
      ref.state = 'fulfilled';
      ref.value = value;
      ref.callbacks.forEach(function (callback) {
        return callback.onFulfilled(value);
      });
    }

    function reject(reason) {
      if (ref.state !== 'pending') return;
      ref.state = 'rejected';
      ref.value = reason;
      ref.callbacks.forEach(function (callback) {
        return callback.onRejected(reason);
      });
    }

    executor(resolve, reject);
  };

  window.Promise.prototype.then = function (onFulfilled, onRejected) {
    var ref= this;
    return new Promise(function (resolve, reject) {
      function handle(callback) {
        try {
          var result = callback(ref.value);
          if (result instanceof Promise) {
            result.then(resolve, reject);
          } else {
            resolve(result);
          }
        } catch (error) {
          reject(error);
        }
      }

      if (ref.state === 'fulfilled') {
        handle(onFulfilled);
      } else if (ref.state === 'rejected') {
        handle(onRejected);
      } else {
        ref.callbacks.push({
          onFulfilled: function onFulfilled(value) {
            return handle(onFulfilled);
          },
          onRejected: function onRejected(reason) {
            return handle(onRejected);
          },
        });
      }
    });
  };

  window.Promise.prototype.catch = function (onRejected) {
    return this.then(null, onRejected);
  };
}```

Promise polyfills play a crucial role in ensuring the compatibility of modern JavaScript code across different browsers. By understanding how Promise polyfills work and implementing them effectively, developers can maintain consistency and reliability in their applications, regardless of the browser environment. With this knowledge, you can confidently leverage Promises in your projects, knowing that they will function reliably across all platforms.