Javascript Promises

A Promise object represents an operation which has produced or will eventually produce a value. Promises provide a robust way to wrap the (possibly pending) result of asynchronous work, mitigating the problem of deeply nested callbacks (known as "callback hell").

States and control flow

A promise can be in one of three states:

A promise is said to be settled (or resolved) when it is either fulfilled or rejected. Once a promise is settled, it becomes immutable, and its state cannot change. The then and catch methods of a promise can be used to attach callbacks that execute when it is settled. These callbacks are invoked with the fulfillment value and rejection reason, respectively

const promise = new Promise((resolve, reject) => {
 // Perform some work (possibly asynchronous)
 // ...
 if (/* Work has successfully finished and produced "value" */) {
 resolve(value);
 } else {
 // Something went wrong because of "reason"
 // The reason is traditionally an Error object, although
 // this is not required or enforced.
 let reason = new Error(message);
 reject(reason);
 // Throwing an error also rejects the promise.
 throw reason;
 }
});

The then and catch methods can be used to attach fulfillment and rejection callbacks:

promise.then(value => {
 // Work has completed successfully,
 // promise has been fulfilled with "value"
}).catch(reason => {
 // Something went wrong,
 // promise has been rejected with "reason"
});

Calling promise.then(...) and promise.catch(...) on the same promise might result in an Uncaught exception in Promise if an error occurs, either while executing the promise or inside one of the callbacks, so the preferred way would be to attach the next listener on the promise returned by the previous then / catch.
Alternatively, both callbacks can be attached in a single call to then:
promise.then(onFulfilled, onRejected);
Attaching callbacks to a promise that has already been settled will immediately place them in the microtask queue, and they will be invoked "as soon as possible" (i.e. immediately after the currently executing script). It is not necessary to check the state of the promise before attaching callbacks, unlike with many other event-emitting implementations

Promise chaining

The then method of a promise returns a new promise.

const promise = new Promise(resolve => setTimeout(resolve, 5000));
promise
 // 5 seconds later
 .then(() => 2)
 // returning a value from a then callback will cause
 // the new promise to resolve with this value
 .then(value => { /* value === 2 */ });

Returning a Promise from a then callback will append it to the promise chain.

function wait(millis) {
 return new Promise(resolve => setTimeout(resolve, millis));
}
const p = wait(5000).then(() => wait(4000)).then(() => wait(1000));
p.then(() => { /* 10 seconds have passed */ });

A catch allows a rejected promise to recover, similar to how catch in a try/catch statement works. Any chained then after a catch will execute its resolve handler using the value resolved from the catch.

const p = new Promise(resolve => {throw 'oh no'});
p.catch(() => 'oh yes').then(console.log.bind(console));

Output

If there are no catch or reject handlers in the middle of the chain, a catch at the end will capture any rejection in
the chain:

p.catch(() => Promise.reject('oh yes'))
.then(console.log.bind(console)) 
.catch(console.error.bind(console)); 

Output

On certain occasions, you may want to "branch" the execution of the functions. You can do it by returning different promises from a function depending on the condition. Later in the code, you can merge all of these branches into one to call other functions on them and/or to handle all errors in one place.

promise
 .then(result => {
 if (result.condition) {
 return handlerFn1()
 .then(handlerFn2);
 } else if (result.condition2) {
 return handlerFn3()
 .then(handlerFn4);
 } else {
 throw new Error("Invalid result");
 }
 })
 .then(handlerFn5)
 .catch(err => {
 console.error(err);
 });

Thus, the execution order of the functions looks like:

promise --> handlerFn1 -> handlerFn2 --> handlerFn5 ~~> .catch()
        |                             ^
        V                             |
        -> handlerFn3 -> handlerFn4 -^

The single catch will get the error on whichever branch it may occur.