W3Schools.com (original) (raw)

JavaScript Promises

"I Promise a Result!"

JavaScript Promises were created to make asynchronous JavaScript easier to use.

A Promise object represents the completion or failure of an asynchronous operation.

A Promise can be in one of three exclusive states:

Why Promises?

Many callbacks become hard to read and hard to maintain.

Example

step1(function(r1) {
step2(r1, function(r2) {
step3(r2, function(r3) {
console.log(r3);
});
});
});

The style above is often called callback hell.

Promises let you write the same logic in a cleaner way.

A Promise acts as a placeholder for a value that will be available at some point in the future, allowing you to handle asynchronous code in a cleaner way than traditional callbacks.

Promise States

A promise can be in one of three exclusive states:

• Pending:
  The initial state; the operation has started but is neither fulfilled nor rejected.
• Fulfilled:
  The operation completed successfully, and a value is available.
• Rejected:
  The operation failed, and a reason (error) is available.

A promise is considered settled if it is fulfilled or rejected (not pending).

Creating a Promise

Syntax

let myPromise = new Promise(function(resolve, reject) {

// Code that may take some time

resolve(value); // when successful
reject(value); // when error
});

The promise constructor takes a function with two parameters.

Promises How To

Here is how to use a Promise:

Example

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

then() takes two arguments, one callback function for success and another for failure.

Both are optional, so you can add a callback function for success or failure only.

Examples

// Create a Promise Object
let myPromise = new Promise(function(resolve, reject) {
ok = true;

// Code that may take some time

if (ok) {
resolve("OK");
} else {
reject("Error");
}
});

// Using then() to display the result
myPromise.then(
function(value) {myDisplayer(value);},
function(value) {myDisplayer(value);}
);

Try it Yourself »

// Create a Promise Object
let myPromise = new Promise(function(resolve, reject) {
ok = false;

// Code that may take some time

if (ok) {
resolve("OK");
} else {
reject("Error");
}
});

// Using then() to display the result
myPromise.then(
function(value) {myDisplayer(value);},
function(value) {myDisplayer(value);}
);

Try it Yourself »

A promise represents a value that will be available later.

A promise is a container for a future result.

The result can be a value or an error.

The JavaScript Promise Object

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

Promise Syntax

let myPromise = new Promise(function(resolve, reject) {

// "Producing Code" (May take some time)

resolve(value); // when successful
reject(value); // when error
});

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

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

A promise can resolve or reject only once.

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.

You cannot access the Promise properties state and result.

You must use a Promise method to handle promises.

Core Methods and Usage

Promises are consumed using methods attached to the promise object:

• .then(onFulfilled, onRejected):
  This method attaches handlers for both the fulfillment and rejection cases. It returns a new promise, which enables method chaining.
• .catch(onRejected):
  This is a shorthand for .then(null, onRejected) and is typically used to handle errors at the end of a promise chain.
• .finally(onFinally):
  This handler is called when the promise is settled (either fulfilled or rejected), regardless of the outcome. It's useful for cleanup operations.

Using then and catch

You do not read a promise result immediately.

You attach code that runs when the promise finishes.

then() runs when a promise is fulfilled.

catch() runs when a promise is rejected.

Examples

let promise = Promise.resolve("OK");

promise
.then(function(value) {
console.log(value);
})
.catch(function(value) {
myDisplayer(value);
});

Try it Yourself »

let promise = Promise.reject("Error");

promise
.then(function(value) {
console.log(value);
})
.catch(function(value) {
myDisplayer(value);
});

Try it Yourself »

When a promise is fulfilled, the then() function runs.

Returning a Promise

Promises become powerful when you return a promise from then().

This creates a clean chain.

Example

// Three functions to run in steps
function step1() {
return Promise.resolve("A");
}
function step2(value) {
return Promise.resolve(value + "B");
}
function step3(value) {
return Promise.resolve(value + "C");
}

// Run the three functions in steps
step1()
.then(function(value) {
return step2(value);
})
.then(function(value) {
return step3(value);
})
.then(function(value) {
myDisplayer(value);
});

Try it Yourself »

The chain runs step by step as each promise finishes.

Where to Put catch

You can handle errors at the end of the chain.

A single catch() can catch errors from any step above.

Example

step1()
.then(function(value) {
return step2(value);
})
.then(function(value) {
return step3(value);
})
.catch(function(error) {
console.log(error);
});

This is one reason promises are easier than many nested callbacks.

Common Beginner Mistakes

Forgetting to return a promise breaks the chain.

Example

step1()
.then(function(value) {
step2(value);
})
.then(function(value) {
console.log(value);
});

The second then() runs too early.

It runs because nothing was returned from the first then().

If you start an async step in then(), return it.

Promises and Real JavaScript

Many web APIs return promises.

fetch() is a common example.

Example

fetch("data.json")
.then(function(response) {
return response.json();
})
.then(function(data) {
console.log(data);
})
.catch(function(error) {
console.log(error);
});

This is promise-based async programming.

Promise API Static Methods

JavaScript also provides static methods on the Promise object for handling multiple promises at once:

• Promise.all(iterable):
  Fulfills when all promises in the iterable are fulfilled; rejects immediately if any promise rejects.
• Promise.allSettled(iterable):
  Waits for all promises to settle (either fulfill or reject) and returns an array of their results.
• Promise.race(iterable):
  Settles (fulfills or rejects) as soon as any of the promises in the iterable settles.
• Promise.any(iterable):
  Fulfills as soon as any promise in the iterable fulfills; rejects if all promises reject.

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 Using Callback

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

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

Try it Yourself »

Example 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;
});

Try it Yourself »

Waiting for a file

Example using Callback

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

Try it Yourself »

Example using Promise

let myPromise = new Promise(function(myResolve, myReject) {
let req = new XMLHttpRequest();
req.open('GET', "mycar.html");
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);}
);

Try it Yourself »

Next Chapter

Promises work well, but chains can still become long.

async and await let you write promise code like normal code.

JS Async & Await