Blog Single

JavaScript Promises

A promise is an object that may produce a single value some time in the future: either a resolved value, or a reason that it’s not resolved (e.g., a network error occurred). A promise may be in one of 3 possible states: fulfilled, rejected, or pending. Promise users can attach callbacks to handle the fulfilled value or the reason for rejection.

Promises are eager, meaning that a promise will start doing whatever task you give it as soon as the promise constructor is invoked. If you need lazy, check out observables or tasks.

Promises are used to handle asynchronous operations in JavaScript. They are easy to manage when dealing with multiple asynchronous operations where callbacks can create callback hell leading to unmanageable code. Prior to promises events and callback functions were used but they had limited functionalities and created unmanageable code. Multiple callback functions would create callback hell that leads to unmanageable code. Events were not good at handling asynchronous operations.

Promises basics Promises and cs Promises are the ideal choice for handling asynchronous operations in the simplest manner. They can handle multiple asynchronous operations easily and provide better error handling than callbacks and events.

A Promise is an object representing the eventual completion or failure of an asynchronous operation. Essentially, a promise is a returned object to which you attach callbacks, instead of passing callbacks into a function.

Promises give us a way to handle asynchronous processing in a more synchronous fashion. They represent a value that we can handle at some point in the future. And, better than callbacks here, Promises give us guarantees about that future value, specifically: No other registered handlers of that value can change it (the Promise is immutable) We are guaranteed to receive the value, regardless of when we register a handler for it, even if it’s already resolved (in contrast to events, which can incur race conditions)

I

#2. How Promises Work

A promise is an object which can be returned synchronously from an asynchronous function. It will be in one of 3 possible states:

Fulfilled: onFulfilled() will be called (e.g., resolve() was called)

Rejected: onRejected() will be called (e.g., reject() was called)

Pending: not yet fulfilled or rejected

A promise is settled if it’s not pending (it has been resolved or rejected). Sometimes people use resolved and settled to mean the same thing: not pending. Once settled, a promise can not be resettled. Calling resolve() or reject() again will have no effect. The immutability of a settled promise is an important feature.

Native JavaScript promises don’t expose promise states. Instead, you’re expected to treat the promise as a black box. Only the function responsible for creating the promise will have knowledge of the promise status, or access to resolve or reject.

Here is a function that returns a promise which will resolve after a specified time delay:

                           
 const wait = time => new Promise((resolve) => setTimeout(resolve, time));

  wait(3000).then(() => console.log('Hello!')); // 'Hello!'
                            
 

Our wait(3000) call will wait 3000ms (3 seconds), and then log 'Hello!'. All spec-compatible promises define a .then() method which you use to pass handlers which can take the resolved or rejected value.

The ES6 promise constructor takes a function. That function takes two parameters, resolve(), and reject(). In the example above, we’re only using resolve(), so I left reject() off the parameter list. Then we call setTimeout() to create the delay, and call resolve() when it’s finished.

You can optionally resolve() or reject() with values, which will be passed to the callback functions attached with .then().

When I reject() with a value, I always pass an Error object. Generally I want two possible resolution states: the normal happy path, or an exception — anything that stops the normal happy path from happening. Passing an Error object makes that explicit.

#2. Creating Promises

The standard way to create a Promise is by using the new Promise constructor which accepts a handler that is given two functions as parameters.

The first handler (typically named resolve) is a function to call with the future value when it’s ready; and the second handler (typically named reject) is a function to call to reject the Promise if it can’t resolve the future value.

T

     const me = new Promise(function(resolve, reject) {  
        if (/* condition */) {
         resolve(/* value */);  // fulfilled successfully
       }
      else {
      reject(/* reason */);  // error, rejected
         }
      });

In this way, a Promise itself has one of the following three states: Pending. Until a Promise is fulfilled it is in pending state Fulfilled. When the first handler (typically resolve) is called the Promise is considered fulfilled with the value passed to that handler. Rejected. If the second handler (typically reject) is called, the Promise is considered rejected with the value passed to that handler. A Promise can only be “settled” (meaning it has been fulfilled or rejected) once. You can also create an immediately resolved Promise by using the Promise.resolve() method.

            const me = Promise.resolve(42); 

      

As you can see, .

#3. Consuming Promises

Once we have a Promise, it can be passed around as a value. The Promise is a stand-in for a future value, and so it can be returned from a function, passed as a parameter and used in any other way a standard value would be used.

      const p = new Promise((resolve, reject) => resolve("me"));  
        p.then((val) => console.log(val)); //  me
            
                  

A Promise’s .then() method actually takes two possible parameters.

The first is the function to be called when the Promise is fulfilled.

The second is a function to be called if the Promise is rejected.

         p.then((val) => console.log("fulfilled:", val),  
       (err) => console.log("rejected: ", err));
            
                  

v

To consume the Promise - meaning we want to process the Promises value once fulfilled - we attach a handler to the Promise using it’s .then() method. This method takes a function that will be passed the resolved value of the Promise once it is fulfilled.

You can omit either handler in a .then(), so sending a null as the first handler and providing the second is the same as the standard Promise.catch(), which takes a single handler to be called when a promise is rejected.

The following are equivalent:

              p.then((val) => console.log("fulfilled:", val))  
               .catch((err) => console.log("rejected:", err));
                       
              p.then((val) => console.log("fulfilled:", val))  
               .then(null, (err) => console.log("rejected:", err));
            
                  

And, as shown above .then() calls can be chained. If a handler returns a value in the a .then() call it is automatically wrapped in a Promise when returned and then properly unwrapped to pass the value to further chained .then() calls.

#4. Dealing with errors

You should use .catch() for handling errors, rather than .then(null, function). Using .catch() is more explicit and idiomatic, and when chaining you can have a single .catch() at the end of the chain to handle any rejection or thrown exceptions from either the original promise or any of it’s handlers.

Throwing an exception in a Promise will automatically reject that Promise as well. This is the same for .then() handlers and their results and return values as well. A thrown error is wrapped in a Promise and treated as a rejection.

      const p1 = new Promise((resolve, reject) => {  
       if (true)  
          throw new Error("rejected!"); 
                    else
                   resolve(4);
                     });
                      
      p1.then((val) => val + 2)  
         .then((val) => console.log("got", val))
          .catch((err) => console.log("error: ", err.message));
             // => error: rejected!
                  
                        

Error Handling

Believe it or not,

#3. Promises All

There will be sometime we will need to wait more than one Promise to complete to continue our program, no worries, you can use Promise.all()

The Promise.all() method returns a single Promise that resolves when all of the promises in the iterable argument have resolved or when the iterable argument contains no promises. It rejects with the reason of the first promise that rejects. This method can be useful for aggregating the results of multiple promises.

Fulfillment

• If an empty iterable is passed, then this method returns (synchronously) an already resolved promise.
• If all of the passed-in promises fulfill, or are not promises, the promise returned by Promise.all is fulfilled asynchronously.
• In all cases, the returned promise is fulfilled with an array containing all the values of the iterable passed as argument (also non-promise values).

Rejection
If any of the passed-in promises reject, Promise.all asynchronously rejects with the value of the promise that rejected, whether or not the other promises have resolved.

                                const p1 = Promise.resolve(3);
     const p2 = 1337;
     const p3 = new Promise((resolve, reject) => {
       setTimeout(resolve, 100, 'foo');
     }); 

   Promise.all([p1, p2, p3]).then(values => { 
    console.log(values); // [3, 1337, "foo"] 
  });
                            
                                            
                            

Promises Visualization

                    Promise.all([
                    new Promise(resolve => setTimeout(resolve, 1500)),
                    new Promise(resolve => setTimeout(resolve, 900)),
                    new Promise(resolve => setTimeout(resolve, 2200))
                  ])
                  .then(results => results.length.b.c)
                  .then(c => console.info(c))
                  .catch(err => console.error(err))
                            
                                            
                

Let’s see in a more graphically way how the promises work, check out this Promises Visualization web, where we can see how each of the promises are been resolved after each of the setTimeout.

#7. Important Promise Rules

A standard for promises was defined by the Promises/A+ specification community. There are many implementations which conform to the standard, including the JavaScript standard ECMAScript promises. Promises following the spec must follow a specific set of rules:

A promise or “thenable” is an object that supplies a standard-compliant .then() method.

A pending promise may transition into a fulfilled or rejected state.

A fulfilled or rejected promise is settled, and must not transition into any other state.

Once a promise is settled, it must have a value (which may be undefined). That value must not change.

Change in this context refers to identity (===) comparison. An object may be used as the fulfilled value, and object properties may mutate.

Every promise must supply a .then() method with the following signature:

       promise.then(
        onFulfilled?: Function,
        onRejected?: Function
        ) => Promise
                                    
                                          

The .then() method must comply with these rules:

Both onFulfilled() and onRejected() are optional.

If the arguments supplied are not functions, they must be ignored.

onFulfilled() will be called after the promise is fulfilled, with the promise’s value as the first argument.

onRejected() will be called after the promise is rejected, with the reason for rejection as the first argument. The reason may be any valid JavaScript value, but because rejections are essentially synonymous with exceptions, I recommend using Error objects.

Neither onFulfilled() nor onRejected() may be called more than once.

.then() may be called many times on the same promise. In other words, a promise can be used to aggregate callbacks.

.then() must return a new promise, promise2.

If onFulfilled() or onRejected() return a value x, and x is a promise, promise2 will lock in with (assume the same state and value as) x. Otherwise, promise2 will be fulfilled with the value of x.

If either onFulfilled or onRejected throws an exception e, promise2 must be rejected with e as the reason.

If onFulfilled is not a function and promise1 is fulfilled, promise2 must be fulfilled with the same value as promise1.

If onRejected is not a function and promise1 is rejected, promise2 must be rejected with the same reason as promise1.

#8. Promise Chaining

Because .then() always returns a new promise, it’s possible to chain promises with precise control over how and where errors are handled. Promises allow you to mimic normal synchronous code’s try/catch behavior.

Like synchronous code, chaining will result in a sequence that runs in serial. In other words, you can do:

        fetch(url)
  .then(process)
  .then(save)
  .catch(handleErrors)
;
                                     
                                           

Assuming each of the functions, fetch(), process(), and save() return promises, process() will wait for fetch() to complete before starting, and save() will wait for process() to complete before starting. handleErrors() will only run if any of the previous promises reject.

Here’s an example of a complex promise chain with multiple rejections:

        
        const wait = time => new Promise(
            res => setTimeout(() => res(), time)
          );
          
          wait(200)
            // onFulfilled() can return a new promise, `x`
            .then(() => new Promise(res => res('foo')))
            // the next promise will assume the state of `x`
            .then(a => a)
            // Above we returned the unwrapped value of `x`
            // so `.then()` above returns a fulfilled promise
            // with that value:
            .then(b => console.log(b)) // 'foo'
            // Note that `null` is a valid promise value:
            .then(() => null)
            .then(c => console.log(c)) // null
            // The following error is not reported yet:
            .then(() => {throw new Error('foo');})
            // Instead, the returned promise is rejected
            // with the error as the reason:
            .then(
              // Nothing is logged here due to the error above:
              d => console.log(`d: ${ d }`),
              // Now we handle the error (rejection reason)
              e => console.log(e)) // [Error: foo]
            // With the previous exception handled, we can continue:
            .then(f => console.log(`f: ${ f }`)) // f: undefined
            // The following doesn't log. e was already handled,
            // so this handler doesn't get called:
            .catch(e => console.log(e))
            .then(() => { throw new Error('bar'); })
            // When a promise is rejected, success handlers get skipped.
            // Nothing logs here because of the 'bar' exception:
            .then(g => console.log(`g: ${ g }`))
            .catch(h => console.log(h)) // [Error: bar]
          ;
                                     
                                           

Summary

We just learn a super powerfull tool for dealing with asynchrnous code. Promises give us the ability to write asynchronous code in a synchronous fashion, with flat indentation and a single exception channel.