How to implement your own Promise. Implement promise-related methods(race, any, all, allSettled, then, finally, catch, resolve & reject, promisify)

In this article, I’d like to walk you through a simplified implementation of ES6 Promise and its related methods.

Let’s look at an example of promise. In the following example, A promise is created and will resolve in1 second. A couple of methods are chained to transform the resolved result.

Could you try answer these questions:

• What is a promise?
• Where is resolve, reject coming from?
• When calling resolve with ‘some string result’, what happens under the hood?
• What is Promise chaining and why the syntax?
• Sometimes I see Promise.resolve & Promise.reject, what do these methods do?
• What are some best practices when writing promise or async /await?
• etc…

Below is an example from AWS SDK. If you have used AWS JavaScript SDK before, you probably have seen something similar:

• What in the world does promise() method do under the hood? How to reason about this code?

These questions all became clear to me after implementing my own simplified version of promise and promise-related methods from scratch. If you are having the similar questions with promise or async/await syntax like I did, I hope you will find this article helpful. If you have any suggestions or comments to this article, feel free to drop a message. All the references are attached in the end.

Before getting started, here are some pre-requisites that would help you understand why we want to use promise and how is asynchronous code executed in browser, these are the foundations to the final implementation, so don’t skip it.

• https://javascript.info/callbacks
• https://www.youtube.com/watch?v=8aGhZQkoFbQ

After brushing up on the basics, let’s get started with implementing our own promise and promise-related methods.

Implement your own Promise & “then” method

The first place to check out what is a promise is probably the MDN description. (Don’t worry if it doesn’t make sense to you)

A Promise is a proxy for a value not necessarily known when the promise is created. It allows you to associate handlers with an asynchronous action's eventual success value or failure reason. This lets asynchronous methods return values like synchronous methods: instead of immediately returning the final value, the asynchronous method returns a promise to supply the value at some point in the future.

A Promise is in one of these states: * pending: initial state, neither fulfilled nor rejected. * fulfilled: meaning that the operation was completed successfully. * rejected: meaning that the operation failed.

In the Promises/A+ spec, it is translated to something more reflective of the technical implementation:

A promise represents the eventual result of an asynchronous operation. The primary way of interacting with a promise is through its then method, which registers callbacks to receive either a promise’s eventual value or the reason why the promise cannot be fulfilled.

Below is how I picture a promise:

The promise is associated with the eventual result of an asynchronous operation.

At any time, the Promise is in one of the following state: pending, fulfilled or rejected. And once it is fulfilled or rejected, it will stay that way.

The then() method returns a Promise. It takes up to two arguments: callback functions for the success and failure cases of the Promise. The interface of a then() method looks like this:

Below is an example to walk you through what happens when you create a promise and do promise chaining.

Promise 1 is created when executing line 1 — line 5. Promise 1 is set at pending state when created. The asynchronous operation hasn’t finished yet and will be finished in 1 second to resolve promise 1.

line 8–10 is then executed, the first callback function is added to the handlers variable of promise 1, and a new promise — Promise 2 is returned at line 10.

The then method at line 10 adds a callback to Promise 2’s handlers variable, and returns a new promise — Promise 3

The catch method at line 13 adds a handler to the promise 3 and returns a new promise — promise 4

After 1 second, line 3 is executed, promise 1 is resolved. When resolving promise 1, its state is updated to ‘fulfilled’ with value: ‘some string result’.

All promise 1’s callback methods(inside handlers variable) are then executed, after all the callback methods are executed, promise 2 is fulfilled.

All promise 2’s callback methods(inside handlers variable) are then executed, after all the callback methods are executed, promise 3 is fulfilled.

All promise 3’s callback methods(inside handlers variable) are then executed, after that, promise 4 is fulfilled.

Now let’s look at the implementation.

Now you can see how resolve & reject method work. When promise is initiated, it accepts a callback function as a parameter. The callback function accepts 2 parameters: resolve method & reject method. The callback function is executed immediately when the promise is initiated(inside constructor method), and promise’s internal _resolve & _reject method is passed into the callback function. When the asynchronous operation is completed, _resolve & _reject is triggered to update the promise’s state and value.

You might be confused with line 37–39

They exist because resolve method could accept not only a string result, but also a promise. Take a look at below example:

When this code is executed, the following four promises are still created. Browser still registers the callback method of setTimeout (line 2 — line 8).

However, after 1 second, the callback method of setTimeout is executed, which creates a new promise — Promise 5. And a callback method to resolve promise 1 is added to promise 5’s handlers variable. Browser then registers the callback method of setTimeout(line 4– line 6)

In one second, promise 5 is resolved with value ‘some string’:

Promise 5’s callback methods(inside handlers variable) are then executed, which resolves promise 1,

Promise 1’s callback methods(inside handlers variable) are then executed, resolving promise 2, etc…

Implement your own Promise.catch, finally method

As the MDN description pointed out, Promise.catch behaves the same as calling Promise.prototype.then(undefined, onRejected)

The catch() method returns a Promise and deals with rejected cases only. It behaves the same as calling Promise.prototype.then(undefined, onRejected) (in fact, calling obj.catch(onRejected) internally calls obj.then(undefined, onRejected)). This means that you have to provide an onRejected function even if you want to fall back to an undefined result value - for example obj.catch(() => {}).

Here is an implementation:

MDN description for Promise.prototype.finally method

The finally() method returns a de>Promise. When the promise is finally either fulfilled or rejected, the specified callback function is executed. This provides a way for code to be run whether the promise was fulfilled successfully, or instead rejected.

One important callout is:

A finally callback will not receive any argument, since there's no reliable means of determining if the promise was fulfilled or rejected. This use case is for precisely when you do not care about the rejection reason, or the fulfillment value, and so there's no need to provide it. So for example:

Unlike Promise.resolve(2).then(() => {}, () => {}) (which will be resolved with undefined), Promise.resolve(2).finally(() => {}) will be resolved with 2.

Similarly, unlike Promise.reject(3).then(() => {}, () => {}) (which will be fulfilled with undefined), Promise.reject(3).finally(() => {}) will be rejected with 3.

This makes our implementation a little different from just calling this.then(onFinally, onFinally).

Here is an implementation

You can see the difference is that after executing onFinally method, we return a new Promise depends on the state and value of the promise before onFinally is executed.

Implement your own Promise.resolve & Promise.reject

You might be confused with the Promise.resolve method and Promise.reject method in the above example.

When calling Promise.resolve(value), If the value is a promise, that promise is returned; if the value is a thenable (i.e. has a "then" method), the returned promise will "follow" that thenable, adopting its eventual state; otherwise the returned promise will be fulfilled with the value. MDN

The Promise.reject() method returns a Promise object that is rejected with a given reason. MDN

Implement your own Promise.all & Promise.allSettled

MDN for Promise.all method

The Promise.all() method takes an iterable of promises as an input, and returns a single Promise that resolves to an array of the results of the input promises.

This returned promise will resolve when all of the input's promises have resolved, or if the input iterable contains no promises.

It rejects immediately upon any of the input promises rejecting or non-promises throwing an error, and will reject with this first rejection message / error.

Here is an implementation of the Promise.all method

The difference from Promise.all() and Promise.allSettled() is that Promise.all method returns a promise that rejects “eagerly”. However, Promise.allSettled() returns a promise that resolves/rejects when all promises are settled(fulfilled/rejected)

MDN for Promise.allSettled()

The Promise.allSettled() method returns a promise that resolves after all of the given promises have either fulfilled or rejected, with an array of objects that each describes the outcome of each promise.

Below is an implementation:

Implement your own Promise.race & Promise.any

MDN for Promise.race()

The Promise.race() method returns a promise that fulfills or rejects as soon as one of the promises in an iterable fulfills or rejects, with the value or reason from that promise.

MDN for Promise.any()

Promise.any() takes an iterable of Promise objects. It returns a single promise that resolves as soon as any of the promises in the iterable fulfills, with the value of the fulfilled promise. If no promises in the iterable fulfill (if all of the given promises are rejected), then the returned promise is rejected with an AggregateError, a new subclass of Error that groups together individual errors.

Promise.all return a new promise that will resolve with the aggregated results from all promises or reject with the error from the first rejected promise.

Promise.any instead returns a promise that resolves with the value from first resolved promise, or rejects with the aggregated errors from all the rejected promises.

Convert any callback to promise using Promisify helper method

Sometimes, you may prefer promise syntax and want to convert your callback to a promise. Here is a helper method that achieves the functionality:

That’s it for the implementation of Promise and related methods. Feel free to leave any comments or suggestions or give it a like if you enjoyed the article.

Reference