This site is mobile accessible. Press the "Tap Here" button to use a different font-size.

Smartphone icons created by Freepik - Flaticon

13.3 JS Promises

"I Promise a Result!"
"Producing code" is code that can take some time
"Consuming code" is code that must wait for the result
A Promise is a JavaScript object that links producing code and consuming code

JavaScript Promise Object

A JavaScript Promise object contains both the producing code and calls to the consuming code:

Promise Syntax

let myPromise = new Promise(function(myResolve, myReject) {
// "Producing Code" (May take some time)

  myResolve(); // when successful
  myReject();  // when error
});

// "Consuming Code" (Must wait for a fulfilled Promise)
myPromise.then(
  function(value) { /* code if successful */ },
  function(error) { /* code if some error */ }
);

When the executing code obtains the result, it should call one of the two callbacks:

Result	Call
Success	myResolve(result value)
Error	myReject(error object)

Promise Object Properties

A JavaScript Promise object can be:
- Pending
- Fulfilled
- Rejected
The Promise object supports two properties: state and result.
While a Promise object is "pending" (working), the result is undefined.
When a Promise object is "fulfilled", the result is a value.
When a Promise object is "rejected", the result is an error object.

myPromise.state	myPromise.result
"pending"	undefined
"fulfilled"	a result value
"rejected"	an error object

You cannot access the Promise properties state and result.
You must use a Promise method to handle promises.

Promise How To

Here is how to use a Promise:

myPromise.then(
  function(value) { /* code if successful */ },
  function(error) { /* code if some error */ }
);

Promise.then() takes two arguments, a callback for success and another for failure.
Both are optional, so you can add a callback for success or failure only.

Example 1: JS Promise Object - The then() Metod

function myDisplayer(some) {
  document.getElementById("demo").innerHTML = some;
}

let myPromise = new Promise(function(myResolve, myReject) {
  let x = 0;

// The producing code (this may take some time)

  if (x == 0) {
    myResolve("OK");
  } else {
    myReject("Error");
  }
});

myPromise.then(
  function(value) {myDisplayer(value);},
  function(error) {myDisplayer(error);}
);

JavaScript Promise Examples

To demonstrate the use of promises, we will use the callback examples from the previous chapter:

Waiting for a Timeout
Waiting for a File

Waiting for a Timeout

Example 2a: Timeout Using Callback

setTimeout(function() { myFunction("I love You !!!"); }, 3000);

function myFunction(value) {
  document.getElementById("demo").innerHTML = value;
}

Example 2b: Timeout Using Promise

let myPromise = new Promise(function(myResolve, myReject) {
  setTimeout(function() { myResolve("I love You !!"); }, 3000);
});

myPromise.then(function(value) {
  document.getElementById("demo").innerHTML = value;
});

Waiting for a file

Example 3a: JS Callbacks - Waiting for a file using Callback part 1

Example 3b: JS Callbacks - Waiting for a file using Callback part 2

function getFile(myCallback) {
  let req = new XMLHttpRequest();
  req.open('GET', "mycar.html");
  req.onload = function() {
    if (req.status == 200) {
      myCallback(req.responseText);
    } else {
      myCallback("Error: " + req.status);
    }
  }
  req.send();
}

getFile(myDisplayer);

Example 3c: JS Promise Object - Waiting for a file using Promise part 1

Example 3d: JS Promise Object - Waiting for a file using Promise part 2

let myPromise = new Promise(function(myResolve, myReject) {
  let req = new XMLHttpRequest();
  req.open('GET', "mycar.htm");
  req.onload = function() {
    if (req.status == 200) {
      myResolve(req.response);
    } else {
      myReject("File not Found");
    }
  };
  req.send();
});

myPromise.then(
  function(value) {myDisplayer(value);},
  function(error) {myDisplayer(error);}
);

Browser Support

ECMAScript 2015, also known as ES6, introduced the JavaScript Promise object.
The following table defines the first browser version with full support for Promise objects:


Chrome 33	Edge 12	Firefox 29	Safari 7.1	Opera 20
Feb, 2014	Jul, 2015	Apr, 2014	Sep, 2014	Mar, 2014

JavaScript Fundamentals course home
Module 13. JS Async

Navigate this module

Eventually the navigation links, above, will be replaced by these << (previous) and >> (next) buttons below.

JavaScript icons used in the buttons provided by ICONS8.COM. Smartphone icons created by Freepik - Flaticon

Example files created in this module:
JS Functions - Function Sequence part 1 JS Functions - Function Sequence part 2 JS Functions - Function Sequence part 3 JS Functions - Function Sequence part 4 JS Functions - Callback Functions JS Functions - setTimeout() with a Callback part 1 JS Functions - setTimeout() with a Callback part 2 JS Functions - setInterval() with a Callback JS Promise Object - The then() Method part 1 JS Promise Object - The then() Method part 2 JS Callbacks - Waiting for a file part 1 JS Callbacks - Waiting for a file part 2 JS Promise Object - Waiting for a file part 1 JS Promise Object - Waiting for a file part 2 JS async / await part 1 JS async / await part 2