Promise Object (JavaScript)

Provides a mechanism to schedule work to be done on a value that has not yet been computed. It is an abstraction for managing interactions with asynchronous APIs.

Syntax

var promise = new Promise(function(resolve, reject) { ... });  

Parameters

promise
Required. The variable name to which the promise is assigned.

resolve
Required. A function that runs to indicate that the promise has completed successfully.

reject
Optional. A function that runs to indicate that the promise has been rejected with an error.

Remarks

A Promise must either be completed with a value, or it must be rejected with a reason. The then method of the Promise object runs when the promise is completed or rejected, whichever occurs first. If the promise is completed successfully, the fulfillment handler function of the then method runs. If the promise is rejected, the error handler function of the then method (or the catch method) runs.

Example

The following example shows how to call a function (timeout) that returns a promise. The fulfillment handler of the then method runs after the 5000ms timeout period expires.

function timeout(duration) {  
    return new Promise(function(resolve, reject) {  
        setTimeout(resolve, duration);  
    });  
}  

// Note: This code uses arrow function syntax  
var m = timeout(5000).then(() => {  
    console.log("done!");  
})  

// Output (after 5 seconds):  
// done!  

Example

You can also chain calls to the then method as shown in the following code. Each completion handler must itself return a promise to support chaining. In this code, which calls the same timeout function, the first call to timeout returns after 1000 ms. The first completion handler calls timeout again, and this promise returns after 2000ms. Its completion handler then throws an error. The error handler calls Promise.all, which returns only when both calls to timeout are completed or rejected.

var p = timeout(1000).then(() => {  
    return timeout(2000);  
}).then(() => {  
    throw new Error("error");  
}).catch(err => {  
    return Promise.all([timeout(100), timeout(200)]);  
})  

Requirements

Supported in Microsoft Edge (Edge browser). Also supported in Store apps (Microsoft Edge on Windows 10). See Version Information.
Not supported in the following document modes: Quirks, Internet Explorer 6 standards, Internet Explorer 7 standards, Internet Explorer 8 standards, Internet Explorer 9 standards, Internet Explorer 10 standards, Internet Explorer 11 standards. Not supported in Windows 8.1.

Functions

The following table describes the functions of the Promise object.

Methods

The following table describes the methods of the Promise object.