new Promise() / then() / catch() / finally() Since: ES6（ECMAScript 2015）

An object that represents the result of an asynchronous operation. When the operation completes successfully, you receive the result with then(); if it fails, you handle the error with catch().

Syntax

// Create a Promise.
var promise = new Promise(function(resolve, reject) {
	// Call resolve() on success.
	// Call reject() on failure.
});

// Receive the result.
promise
	.then(function(result) { /* handler for success */ })
	.catch(function(error) { /* handler for failure */ })
	.finally(function() { /* runs regardless of success or failure */ });

Methods

Method	Description
promise.then(function)	Registers a function to run when the Promise succeeds. The value passed to `resolve()` is received as the argument.
promise.catch(function)	Registers a function to run when the Promise fails. The value passed to `reject()` is received as the argument.
promise.finally(function)	Registers a function that always runs at the end, regardless of success or failure. No argument is received.

Sample Code

// Basic Promise usage
var promise = new Promise(function(resolve, reject) {
	var success = true;
	if (success) {
		resolve("The operation succeeded!"); // Pass the success value.
	} else {
		reject("The operation failed..."); // Pass the failure value.
	}
});

promise
	.then(function(result) {
		console.log(result); // Outputs "The operation succeeded!".
	})
	.catch(function(error) {
		console.log(error); // Runs here if the operation fails.
	});

// Simulating a time-consuming operation
function wait(ms) {
	return new Promise(function(resolve) {
		setTimeout(function() {
			resolve("Waited " + ms + " ms");
		}, ms);
	});
}

wait(2000).then(function(message) {
	console.log(message); // Outputs "Waited 2000 ms" after 2 seconds.
});

// Practical example: fetching data from a server
fetch("https://api.example.com/data")
	.then(function(response) {
		return response.json(); // Parse as JSON. This also returns a Promise.
	})
	.then(function(data) {
		console.log(data); // Outputs the retrieved data.
	})
	.catch(function(error) {
		console.log("Request failed: " + error.message);
	})
	.finally(function() {
		console.log("Request finished."); // Runs regardless of success or failure.
	});

// Chaining then() calls
wait(1000)
	.then(function(msg) {
		console.log(msg); // Outputs "Waited 1000 ms".
		return wait(1000); // Return the next Promise.
	})
	.then(function(msg) {
		console.log(msg); // Outputs "Waited 1000 ms" again after another second.
	});

The Three States of a Promise

A Promise has three states, and once a state is settled it never changes.

State	Description
pending	The waiting state. The Promise has just been created and has neither succeeded nor failed yet.
fulfilled	The success state. `resolve()` has been called and the result can be received via `then()`.
rejected	The failure state. `reject()` was called or an error occurred; the error can be handled via `catch()`.

Overview

A Promise is an object that represents a value that is not yet available but will eventually resolve to either a success or a failure. It is used to handle operations that take time to complete, such as server communication, file loading, and timer-based processing.

Before Promises, you had to nest callback functions multiple levels deep to handle the results of asynchronous operations, which significantly reduced code readability — a problem known as "callback hell." By chaining the then() method, you can write asynchronous code in a linear, top-to-bottom style that is much easier to follow.

If you want to write asynchronous code even more concisely, the 'async / await' syntax lets you express the same logic in an intuitive, synchronous-looking style.