JavaScript Promise : Object

constructor

A Promise is an object that represents an asynchronous operation that will eventually produce a value. Use the then() method to hook up a callback that will be called when the result of the asynchronous operation is ready. ECMAScript 2017 introduced async function()s which return Promises and the await keyword which can simplify Promise based code.

ECMAScript 2015 Spec

Constructors

new Promise(executor : Function) : Promise

executor(resolve : Function, reject : Function) : undefined

resolve(value : Object) : undefined

reject(error : Error) : undefined

Creates a new Promise. The Promise constructor calls executer immediately with the two functions resolve and reject. executor should begin the asynchronous operation. When the operation is complete, call the resolve function with the result. If there is an error during the operation, call reject with the error information.

Example:

var promise = new Promise(function(resolve, reject) {
  console.log('in Promise constructor function');
  setTimeout(function() {
    console.log('in setTimeout callback');
    resolve('foo');
  }, 100);
});
console.log('created promise');

promise.then(function(result) {
  console.log('promise returned: ' + result);
});
console.log('hooked promise.then()');

Run

Results:

Spec

Instance Methods

catch(onReject : Function) : Promise

onReject(error : Error) : undefined

Schedules onReject to be called if the promise had an error (ie, the executer function called reject() or a method in the promise chain threw an error). error is the value passed to reject. This is a shorthand for calling then(undefined, onReject). See also the window unhandledrejecton event.

Example:

var throwPromise = new Promise(function(resolve, reject) {
  throw 'value thrown';
});

throwPromise.catch(function(result) {
  console.log('caught: ' + result);
});

var rejectPromise = new Promise(function(resolve, reject) {
  setTimeout(function() {
    reject('value passed to reject()');
  }, 100);
});

rejectPromise.catch(function(result) {
  console.log('caught: ' + result);
});

Run

Results:

Spec

finally(onFinally : Function) : Promise

onFinally() : undefined

Also schedules onFinally to be called when the promise has been either resolved or rejected.

Example:

var promise = new Promise((reject, resolve) => {
  let x = Math.random();
  if (x < 0.5) {
    resolve(x);
  }
  else {
    reject(x);
  }
}).then(x => {
  console.log('resolved:', x);
}).catch(e => {
  console.log('rejected:', e);
}).finally(() => {
  console.log('in finally');
});

Run

Results:

ECMAScript 2018 Spec

then(onResolve : Function, [onReject : Function]) : Promise

onResolve(value : Object) : Object

onReject(error : Error) : Object

Schedules onResolve (if provided) to be called when the promise has been resolved. value is the object passed to the resolve() function.

Also schedules onReject (if provided) to be called when the promise has been rejected or an exception was thrown in the executor method. error is the object passed to the reject() function.

The return value from onResolve (or onReject) can either be a normal Object or a Promise. If the return value from onResolve is a normal Object, the Promise returned by then() will be resolved with that Object. If the return value from onResolve is a Promise, then() will wait for that Promise to be resolved. then() will resolve the Promise it returned with the same value.

Example:

// This promise randomly passes or fails.
var promise = new Promise(function(resolve, reject) {
  var random = Math.random();
  if (random < 0.5) {
    resolve('resolving with ' + random);
  }
  else {
    reject('rejecting with ' + random);
  }
});

promise.then(function(result) {
  console.log('onResolve: ' + result);
},
function(error) {
  console.log('onReject: ' + error);
});


// The following shows a simple 'Promise-ified' version of XMLHttpRequest
var loadUrl = function(url) {
  return new Promise(function(resolve, reject) {
    var request = new XMLHttpRequest();
    request.open('GET', url);
    request.onload = function() {
      resolve(request.response);
    };
    request.send(); 
  });
};

// The following demonstrates chaining Promises and how you can return
// either a Promise or a normal object to the next part of the chain 
loadUrl('/JSON').then(
  function(promiseText) {
    // Find the first link in the page and return a Promise that will load
    // that page.  The next block will run when this Promise completes.
    var firstLink = promiseText.match(/href="(\/.*?)"/)[1];
    return loadUrl(firstLink);
  }
).then(
  function(firstLinkText) {
    // Return the beginning of the first page's text. Since this is 
    // not returning a Promise.  The next block will run immediately.
    return firstLinkText.substring(0, 50);
  }
).then(
  function(firstLinkBeginning) {
    console.log('firstLinkBeginning: ' + firstLinkBeginning);
});

Run

Results:

Spec

Promise Methods

all(promises : Iterable<Promise>) : Promise<Array>

Creates a new Promise that will be resolved when all of promises are resolved. If any of the promises are rejected, the returned Promise will be rejected immediately and will provide the value of the Promise that was rejected. See also allSettled().

Example:

var promises = [];

for (var i = 0; i < 10; i++) {
  promises.push(new Promise(function(resolve, reject) {
    var timeout = i * 10;
    setTimeout(function() {
      resolve('resolving after ' + timeout + ' milliseconds');
    }, timeout);
  }));
}

Promise.all(promises).then(function(results) {
  console.log('all results:');
  for (var result of results) {
    console.log('  ' + result);
  }
});

Run

Results:

Spec

allSettled(promises : Iterable<Promise>) : Promise<Array>

Creates a new Promise that will be resolved when all of promises are resolved or rejected. The result of the promise is an Array containing objects with a status property (containing either 'fulfilled' or 'rejected') and either a value property (for fulfilled promises) or reason property (for rejected promises). See also all().

Example:

var promises = [];

for (let i = 0; i < 10; i++) {
  promises.push(new Promise(function(resolve, reject) {
    var timeout = i * 10;
    setTimeout(function() {
      if (i % 3 === 0) {
        reject('rejecting after ' + timeout + ' milliseconds');
      }
      else {
        resolve('resolving after ' + timeout + ' milliseconds');
      }
    }, timeout);
  }));
}

Promise.allSettled(promises).then(function(results) {
  console.log('all results:');
  for (var result of results) {
    console.dir(result);
  }
});

Run

Results:

ECMAScript 2020 Spec

race(promises : Iterable<Promise>) : Promise

Creates a new Promise that will be resolved when the first of promises is resolved. If a promise is rejected before any resolve, the returned Promise will be rejected immediately and will provide the value of the Promise that was rejected.

Example:

var promises = [];

for (var i = 0; i < 10; i++) {
  promises.push(new Promise(function(resolve, reject) {
    var random = Math.random() * 1000;
    setTimeout(function() {
      resolve('resolving after ' + random + ' milliseconds');
    }, random);
  }));
}

Promise.race(promises).then(function(result) {
  console.log('first result: ' + result);
});

Run

Results:

Spec

reject(error : Error) : Promise

Returns a new Promise that is in the rejected state with error as the rejected error. Useful for passing values to APIs that expect promises.

Example:

// The following are equivalent
var w = Promise.reject('foo');
var x = new Promise(function(resolve, reject) {
                      reject('foo');
                    });
var y = (async function() { throw 'foo' })();
var z = (async () => { throw 'foo' })();

Run

Results:

Spec

resolve(value : Object) : Promise

Returns a new Promise that is in the resolved state with value as the resolved value. Useful for passing values to APIs that expect promises.

Example:

// The following are equivalent
var w = Promise.resolve('foo');
var x = new Promise(function(resolve) {
                      resolve('foo');
                    });
var y = (async function() { return 'foo' })();
var z = (async () => 'foo')();

Run

Results:

Spec

home license contribute feedback