The Promise
object is used for asynchronous computations. A Promise
represents a value which may be available now, or in the future, or never.
Syntax
new Promise( /* executor */ function(resolve, reject) { ... } );
Parameters
- executor
- A function that is passed with the arguments
resolve
andreject
. Theexecutor
function is executed immediately by the Promise implementation, passingresolve
andreject
functions (the executor is called before thePromise
constructor even returns the created object). Theresolve
andreject
functions, when called, resolve or reject the promise respectively. The executor normally initiates some asynchronous work and then, once that completes, calls either theresolve
orreject
function to resolve the promise or else reject it if an error occurred.
Description
A Promise
is a proxy for a value not necessarily known when the promise is created. It allows you to associate handlers to an asynchronous action's eventual success value or failure reason. This lets asynchronous methods return values like synchronous methods: instead of the final value, the asynchronous method returns a promise for the value at some point in the future.
A Promise
is in one of these states:
- pending: initial state, not fulfilled or rejected.
- fulfilled: meaning that the operation completed successfully.
- rejected: meaning that the operation failed.
A pending promise can either be fulfilled with a value, or rejected with a reason (error). When either of these happens, the associated handlers queued up by a promise's then
method are called. (If the promise has already been fulfilled or rejected when a corresponding handler is attached, the handler will be called, so there is no race condition between an asynchronous operation completing and its handlers being attached.)
As the
and Promise.prototype.then()
methods return promises, they can be chained.Promise.prototype.catch()
Not to be confused with: Several other languages have mechanisms for lazy evaluation and deferring a computation, which they also call “promises” — e.g. Scheme. Promises in JavaScript represent processes which are already happening, which can be chained with callback functions. If you are looking to lazily evaluate an expression, consider the arrow function with no arguments: f = () => expression
to create the lazily-evaluated expression, and f()
to evaluate.
Note: A promise is said to be settled if it is either fulfilled or rejected, but not pending. You will also hear the term resolved used with promises — this means that the promise is settled, or it is locked into a promise chain. Domenic Denicola's States and fates contains more details about promise terminology.
Properties
Promise.length
- Length property whose value is always 1 (number of constructor arguments).
Promise.prototype
- Represents the prototype for the
Promise
constructor.
Methods
Promise.all(iterable)
- Returns a promise that either fulfills when all of the promises in the iterable argument have fulfilled or rejects as soon as one of the promises in the iterable argument rejects. If the returned promise fulfills, it is fulfilled with an array of the values from the fulfilled promises in same order as defined in the iterable. If the returned promise rejects, it is rejected with the reason from the first promise in the iterable that rejected. This method can be useful for aggregating results of multiple promises.
Promise.race(iterable)
- Returns a promise that fulfills or rejects as soon as one of the promises in the iterable fulfills or rejects, with the value or reason from that promise.
Promise.reject(reason)
- Returns a
Promise
object that is rejected with the given reason.
Promise.resolve(value)
- Returns a
Promise
object that is resolved with the given value. If the value is a thenable (i.e. has athen
method), the returned promise will "follow" that thenable, adopting its eventual state; otherwise the returned promise will be fulfilled with the value. Generally, if you don't know if a value is a promise or not,Promise.resolve(value)
it instead and work with the return value as a promise.
Promise
prototype
Properties
Promise.prototype.constructor
- Returns the function that created an instance's prototype. This is the
Promise
function by default.
Methods
Promise.prototype.catch(onRejected)
- Appends a rejection handler callback to the promise, and returns a new promise resolving to the return value of the callback if it is called, or to its original fulfillment value if the promise is instead fulfilled.
Promise.prototype.then(onFulfilled, onRejected)
- Appends fulfillment and rejection handlers to the promise, and returns a new promise resolving to the return value of the called handler, or to its original settled value if the promise was not handled (i.e. if the relevant handler
onFulfilled
oronRejected
is not a function).
Examples
Creating a Promise
This small example shows the mechanism of a Promise
. The testPromise()
method is called each time the <button>
is clicked. It creates a promise that will fulfill, using window.setTimeout()
, to the promise count (number starting from 1) every 1-3 seconds, at random. The Promise()
constructor is used to create the promise.
The fulfillment of the promise is simply logged, via a fulfill callback set using p1.then()
. A few logs shows how the synchronous part of the method is decoupled of the asynchronous completion of the promise.
'use strict'; var promiseCount = 0; function testPromise() { var thisPromiseCount = ++promiseCount; var log = document.getElementById('log'); log.insertAdjacentHTML('beforeend', thisPromiseCount + ') Started (<small>Sync code started</small>)<br/>'); // We make a new promise: we promise a numeric count of this promise, starting from 1 (after waiting 3s) var p1 = new Promise( // The resolver function is called with the ability to resolve or // reject the promise function(resolve, reject) { log.insertAdjacentHTML('beforeend', thisPromiseCount + ') Promise started (<small>Async code started</small>)<br/>'); // This is only an example to create asynchronism window.setTimeout( function() { // We fulfill the promise ! resolve(thisPromiseCount); }, Math.random() * 2000 + 1000); } ); // We define what to do when the promise is resolved/fulfilled with the then() call, // and the catch() method defines what to do if the promise is rejected. p1.then( // Log the fulfillment value function(val) { log.insertAdjacentHTML('beforeend', val + ') Promise fulfilled (<small>Async code terminated</small>)<br/>'); }) .catch( // Log the rejection reason function(reason) { console.log('Handle rejected promise ('+reason+') here.'); }); log.insertAdjacentHTML('beforeend', thisPromiseCount + ') Promise made (<small>Sync code terminated</small>)<br/>'); }
This example is executed when clicking the button. You need a browser supporting Promise
. By clicking several times the button in a short amount of time, you'll even see the different promises being fulfilled one after the other.
Example using XMLHttpRequest
Creating a Promise
This example shows the implementation of a method which uses a Promise
to report the result of (or failure of) an XMLHttpRequest
.
'use strict'; // A-> $http function is implemented in order to follow the standard Adapter pattern function $http(url){ // A small example of object var core = { // Method that performs the ajax request ajax: function (method, url, args) { // Creating a promise var promise = new Promise( function (resolve, reject) { // Instantiates the XMLHttpRequest var client = new XMLHttpRequest(); var uri = url; if (args && (method === 'POST' || method === 'PUT')) { uri += '?'; var argcount = 0; for (var key in args) { if (args.hasOwnProperty(key)) { if (argcount++) { uri += '&'; } uri += encodeURIComponent(key) + '=' + encodeURIComponent(args[key]); } } } client.open(method, uri); client.send(); client.onload = function () { if (this.status >= 200 && this.status < 300) { // Performs the function "resolve" when this.status is equal to 2xx resolve(this.response); } else { // Performs the function "reject" when this.status is different than 2xx reject(this.statusText); } }; client.onerror = function () { reject(this.statusText); }; }); // Return the promise return promise; } }; // Adapter pattern return { 'get': function(args) { return core.ajax('GET', url, args); }, 'post': function(args) { return core.ajax('POST', url, args); }, 'put': function(args) { return core.ajax('PUT', url, args); }, 'delete': function(args) { return core.ajax('DELETE', url, args); } }; }; // End A // B-> Here you define its functions and its payload var mdnAPI = 'https://developer.mozilla.org/en-US/search.json'; var payload = { 'topic' : 'js', 'q' : 'Promise' }; var callback = { success: function(data) { console.log(1, 'success', JSON.parse(data)); }, error: function(data) { console.log(2, 'error', JSON.parse(data)); } }; // End B // Executes the method call $http(mdnAPI) .get(payload) .then(callback.success) .catch(callback.error); // Executes the method call but an alternative way (1) to handle Promise Reject case $http(mdnAPI) .get(payload) .then(callback.success, callback.error); // Executes the method call but an alternative way (2) to handle Promise Reject case $http(mdnAPI) .get(payload) .then(callback.success) .then(undefined, callback.error);
Loading an image with XHR
Another simple example using Promise
and XMLHttpRequest
to load an image is available at the MDN GitHub promise-test repository. You can also see it in action. Each step is commented and allows you to follow the Promise and XHR architecture closely.
Specifications
Specification | Status | Comment |
---|---|---|
ECMAScript 2015 (6th Edition, ECMA-262) The definition of 'Promise' in that specification. |
Standard | Initial definition in an ECMA standard. |
ECMAScript 2017 Draft (ECMA-262) The definition of 'Promise' in that specification. |
Draft |
Browser compatibility
To contribute to this compatibility data, please write a pull request against this file: https://github.com/mdn/browser-compat-data/blob/master/javascript/promise.json.
Feature | Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | Servo |
---|---|---|---|---|---|---|---|
Promise | 32.0 | (Yes) | 29.01 | No support | 19 | 7.12 | No support |
Promise.all | 32.0 | (Yes) | 29.0 | No support | 19 | 7.1 | No support |
Promise.prototype | 32.0 | (Yes) | 29.0 | No support | 19 | 7.1 | No support |
Promise.prototype.catch | 32.0 | (Yes) | 29.0 | No support | 19 | 7.1 | No support |
Promise.prototype.then | 32.0 | (Yes) | 29.0 | No support | 19 | 7.1 | No support |
Promise.race | 32.0 | (Yes) | 29.0 | No support | 19 | 7.1 | No support |
Promise.reject | 32.0 | (Yes) | 29.0 | No support | 19 | 7.1 | No support |
Promise.resolve | 32.0 | (Yes) | 29.0 | No support | 19 | 7.1 | No support |
Feature | Android | Chrome for Android | Edge Mobile | Firefox for Android | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|---|
Promise | 4.4.4 | 32.0 | (Yes) | 291 | No support | (Yes) | 8.02 |
Promise.all | 4.4.4 | 32.0 | (Yes) | 29 | No support | (Yes) | 8.0 |
Promise.prototype | 4.4.4 | 32.0 | (Yes) | 29 | No support | (Yes) | 8.0 |
Promise.prototype.catch | 4.4.4 | 32.0 | (Yes) | 29 | No support | (Yes) | 8.0 |
Promise.prototype.then | 4.4.4 | 32.0 | (Yes) | 29 | No support | (Yes) | 8.0 |
Promise.race | 4.4.4 | 32.0 | (Yes) | 29 | No support | (Yes) | 8.0 |
Promise.reject | 4.4.4 | 32.0 | (Yes) | 29 | No support | (Yes) | 8.0 |
Promise.resolve | 4.4.4 | 32.0 | (Yes) | 29 | No support | (Yes) | 8.0 |
1. Constructor requires a new operator since version 37.
2. Constructor requires a new operator since version 10.
See also
- Promises/A+ specification
- Venkatraman.R - JS Promise (Part 1, Basics)
- Jake Archibald: JavaScript Promises: There and Back Again
- Domenic Denicola: Callbacks, Promises, and Coroutines – Asynchronous Programming Patterns in JavaScript
- Matt Greer: JavaScript Promises ... In Wicked Detail
- Forbes Lindesay: promisejs.org
- Nolan Lawson: We have a problem with promises — Common mistakes with promises
- Promise polyfill
- Udacity: JavaScript Promises