Understanding and implementing basic Promises

Before you start using promises, you should first understand the problem they are trying to solve. Without worrying too much about the internals, you can classify the concept of a Promise into three distinct stages:

There is more nuance to how promises work, but for now, this is sufficient to get into some of the code.

A promise implementation in one of its simplest forms is as follows:

// promises are instantiated with the 'new' keyword   var promise = new Promise(() => {});   

The function passed to the Promise constructor is the piece of work that is expected to execute asynchronously. The formal term for this function is executor.

When this function is executed, internally it understands when it is completed; however, on the outside, there is no construct that represents the concept of "run this when the executor function is completed". Therefore, its first two parameters are the resolve and reject functions. The promise wrapping the executor function is in the pending state until one of these is invoked. Once invoked, the promise irreversibly assumes the respective state.

The following code demonstrates five different examples of ways that a promise can be instantiated, resolved, or rejected:

// This executor is passed resolve and reject, but is    // effectively a no-op, so the promise p2 will forever    // remain in the 'pending' state.   const p1 = new Promise((resolve, reject) => {});      // This executor invokes 'resolve' immediately, so   // p2 will transition directly to the 'fulfilled' state.   const p2 = new Promise((resolve, reject) => resolve());      // This executor invokes 'reject' immediately, so   // p3 will transition directly to the 'rejected' state.   // A transition to the 'rejected' state will also throw   // an exception. This exception is thrown after the    // executor completes, so any logic following the    // invocation of reject will still be executed.   const p3 = new Promise((resolve, reject) => {     reject();     // This log() prints before the exception is thrown     console.log('I got rejected!');    });      // This executor invokes 'resolve' immediately, so   // p4 will transition directly to the 'fulfilled' state.   // Once a promise exits the 'pending' state, it cannot change   // again, so even though reject is invoked afterwards, the   // final state of p4 is still 'fulfilled'.   const p4 = new Promise((resolve, reject) => {     resolve();     reject();   });      // This executor assigns its resolve function to a variable   // in the encompassing lexical scope so it can be called   // outside the promise definition.   var outerResolve;   const p5 = new Promise((resolve, reject) => {     outerResolve = resolve();   });   // State of p5 is 'pending'      outerResolve();   // State of p5 is 'fulfilled'   

With what you've done so far, you will not find the promise construct to be of much use; this is because all that the preceding code accomplishes is the setting up of the state of a single promise. The real value emerges when you set the subsequent state handlers. A Promise object's API exposes a then() method, which allows you to set handlers to be executed when the Promise reaches its final state:

// p1 is a simple promise to which you can attach handlers   const p1 = new Promise((resolve, reject) => {});      // p1 exposes a then() method which accepts a    // resolve handler (onFulfilled), and a    // reject handler (onRejected)   p1.then(     // onFulfilled is invoked when resolve() is invoked     () => {},     // onRejected is invoke when reject() is invoked     () => {});   // If left here, p1 will forever remain "pending"         // Using the 'new' keyword still allows you to call a   // method on the returned instance, so defining the   // then() handlers immediately is allowed.   //   // Instantly resolves p2   const p2 = new Promise((resolve, reject) => resolve())     .then(       // This method will immediately be invoked following       // the p2 executor invoking resolve()       () => console.log('resolved!'));   // "resolved!"         // Instantly rejects p3   const p3 = new Promise((resolve, reject) => reject())     .then(       () => console.log('resolved!'),       // This second method will immediately be invoked following       // the p3 executor invoking reject()       () => console.log('rejected!'));   // "rejected!"         const p4 = new Promise((resolve, reject) => reject())     // If you don't require use of the resolve handler,     // catch() allows you to define just the error handling     .catch(() => console.log('rejected!'));         // executor parameters can be captured outside its lexical   // scope for later invocation   var outerResolve;   const p5 = new Promise((resolve, reject) => {     outerResolve = resolve;   }).then(() => console.log('resolved!'));      outerResolve();   // "resolved!"   

Promises in JavaScript confer to the developer the ability to write asynchronous code in parallel with synchronous code more easily. In JavaScript, this was formerly solved with nested callbacks, colloquially referred to as "callback hell." A single callback-oriented function might be written as follows:

// a generic asynchronous callback function   function asyncFunction(data, successCallback, errorCallback) {     // asyncFunction will perform some operation that may succeed,     // may fail, or may not return at all, any of which     // occurs in an unknown amount of time        // this pseudo-response contains a success boolean,     // and the returned data if successful     asyncOperation(data, function(response) {       if (response.success === true) {         successCallback(response.data);       } else {         errorCallback();       }     });   };   

If your application does not demand any semblance of in-order or collective completion, then the following will suffice:

function successCallback(data) {     // asyncFunction succeeded, handle data appropriately   };   function errorCallback() {     // asyncFunction failed, handle appropriately   };      asyncFunction(data1, successCallback, errorCallback);   asyncFunction(data2, successCallback, errorCallback);   asyncFunction(data3, successCallback, errorCallback);   

This is almost never the case though. Often, your application will either demand that this data is acquired in a sequence, or that an operation that requires multiple asynchronously acquired pieces of data executes once all of the data has been successfully acquired. In this case, without access to promises, the callback hell emerges:

asyncFunction(data1, (foo) => {     asyncFunction(data2, (bar) => {       asyncFunction(data3, (baz) => {         // foo, bar, baz can now all be used together         combinatoricFunction(foo, bar, baz);       }, errorCallback);     }, errorCallback);   }, errorCallback);   

This so-called callback hell here is really just an attempt to serialize three asynchronous calls, but the parametric topology of these asynchronous functions forces the developer to subject their application to this ugliness.

An important point to remember about promises is that they allow you to break apart a calculation into two parts: the part that understands when the promise's "execution" has been completed and the part that signals to the rest of the program that the execution has been completed.

const p = new Promise((resolve, reject) => {     // the following are pseudo-methods, each of which can be called      // independently and asynchronously, or not at all     function canHappenFirst() { resolve(); };     function mayHappenFirst() { resolve(); }     function mightHappenFirst() { reject(); };   });    

var outerResolve;   const p = new Promise((resolve, reject) => {     outerResolve = resolve;   });       // the following are pseudo-methods, each of which can be called    // independently and asynchronously, or not at all   function canHappenFirst() { outerResolve (); };   function mayHappenFirst() { outerResolve (); }   function mightHappenFirst() { outerResolve (); };   

var resolveHandler = () => {},        rejectHandler = () => {};   const p0 = new Promise((resolve, reject) => {     // state can be defined with any of the following:     // resolve();     // reject();     // resolve(myData);     // reject(myData);   }).then(resolveHandler, rejectHandler);   

const p1 = new Promise((resolve, reject) => {     // console.info is the resolve handler,     // console.error is the reject handler          resolve(123);   }).then(console.info, console.error);       // (info) 123      // reset to demonstrate reject()   const p2 = new Promise((resolve, reject) => {     // console.info is the resolve handler,     // console.error is the reject handler          reject(456);   }).then(console.info, console.error);       // (error) 456   

const p3 = new Promise((resolve, reject) => {     // immediately resolve the promise     resolve(123);   });      // subsequently define a handler, will be immediately   // invoked since promise is already resolved    p3.then(console.info);      // (info) 123   

const p4 = new Promise((resolve, reject) => {     // Invoke resolve() after 1 second     setTimeout(() => resolve(), 1000);   });      const cb = () => console.log('called');      p4.then(cb);   p4.then(cb);      // After 1 second:   // "called"   // "called"   

Promise {     [[PromiseStatus]]: "fulfilled",      [[PromiseValue]]: 123   }