Questions And Answers

More Tutorials

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:

  • pending — The underlying operation has not yet completed, and the promise is pending fulfillment.
  • fulfilled — The operation has finished, and the promise is fulfilled with a value. This is analogous to returning a value from a synchronous function.
  • rejected — An error has occurred during the operation, and the promise is rejected with a reason. This is analogous to throwing an error in a synchronous function.

  • 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

    Javascript Promises
    const promise = new Promise((resolve, reject) => {
     // Perform some work (possibly asynchronous)
     // ...
     if (/* Work has successfully finished and produced "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);
     // 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));
     // 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));


    "oh yes"

    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'))


    "oh yes"

    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.

     .then(result => {
     if (result.condition) {
     return handlerFn1()
     } else if (result.condition2) {
     return handlerFn3()
     } else {
     throw new Error("Invalid result");
     .catch(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.


    In this page (written and validated by ) you learned about Javascript Promises . What's Next? If you are interested in completing Javascript tutorial, your next topic will be learning about: Javascript Modals - Prompts.

    Incorrect info or code snippet? We take very seriously the accuracy of the information provided on our website. We also make sure to test all snippets and examples provided for each section. If you find any incorrect information, please send us an email about the issue:

    Share On:

    Mockstacks was launched to help beginners learn programming languages; the site is optimized with no Ads as, Ads might slow down the performance. We also don't track any personal information; we also don't collect any kind of data unless the user provided us a corrected information. Almost all examples have been tested. Tutorials, references, and examples are constantly reviewed to avoid errors, but we cannot warrant full correctness of all content. By using, you agree to have read and accepted our terms of use, cookies and privacy policy.