Skip to Main Content
Perplexed Owl Random Ponderings

Benjamin ‘Benilda’ Key:

October 09, 2023

Why it took me forever to figure out JavaScript promises.

It took me forever to figure out how to use JavaScript promises despite reading the following articles multiple times.

All of these articles have the same critical flaw. They fail to adequately explain how to use promises for anything other than the most simple of single step tasks. They do not adequately explain how to use promises for multiple step tasks when every step can possibly fail.

I know what many of you are thinking right now. You are most likely thinking that I did not actually read the articles because they all answer that question.

I acknowledge that they all answer the question but the explanation is inadequate. I am well aware that the Using promises page contains the Chaining section and the Promise page contains the Chained Promises section. However, the information contained in those sections is incomplete and inadequate.

The Chained Promises section of the Promise page contains the following code sample.

const myPromise = new Promise((resolve, reject) => {
  setTimeout(() => {
    resolve("foo");
  }, 300);
});

myPromise
  .then(handleFulfilledA, handleRejectedA)
  .then(handleFulfilledB, handleRejectedB)
  .then(handleFulfilledC, handleRejectedC);

Unfortunately, the sample does not show the code of the following methods.

In addition, the Chained Promises section does not even mention those methods or tell the reader what the methods return. Note that the following does not count as a description of what these methods return.

The methods Promise.prototype.then(), Promise.prototype.catch(), and Promise.prototype.finally() are used to associate further action with a promise that becomes settled. As these methods return promises, they can be chained.

That paragraph explains what the Promise.prototype.then(), Promise.prototype.catch(), and Promise.prototype.finally() methods return. It does not explain what the handleFulfilled* and handleRejected* methods return.

A code sample is incomplete and inadequate unless it does one of the following.

It does not matter if the missing information can be found in another section of the article for one simple reason. If the reader gets to the end of the section containing the code sample without knowing how to implement every method in the code sample they may assume that the article does not provide this information and they may stop reading the article.

Despite reading the Chained Promises section of the Promise page multiple times I did not learn how to chain promises until recently because I reached the beginning of the Thenables section without knowing how to implement the handleFulfilled* and handleRejected* methods.

It does not matter that the Promise page provides this information in the Example with diverse situations section because I never read that section until very recently. When I got to the Thenables section without seeing the missing information I stopped reading!

If the Chained Promises section contained the following information I would have found the answer to my question much sooner.

The following methods should return a Promise.

For a complete example see Example with diverse situations.

Back to top