Async Promises

"I Promise a Result!"

A Promise represents the future result of an asynchronous operation.

It acts as a placeholder for a value that is not available yet.

When the operation finishes, the Promise is either fulfilled with a value or rejected with an error.

Why Promises?

Callbacks work well for simple asynchronous operations.

However, several dependent callbacks can become difficult to read.

Promises provide a cleaner and more readable way to organize asynchronous code.

Callback Example

step1(function(result1) {

  step2(result1, function(result2) {

    step3(result2, function(result3) {

      display(result3);

    });

  });

});

Note: This style is often called callback hell.

The Same Flow with Promises

step1()

  .then(step2)

  .then(step3)

  .then(display);

The code becomes flatter and easier to read.

Promise States

Every Promise is always in one of three states.

Pending
   │
   ├────────► Fulfilled
   │
   └────────► Rejected

Note: A Promise is settled when it is fulfilled or rejected.

Promises Returned by JavaScript APIs

Many JavaScript APIs return Promises.

The fetch() method is one example.

Example

fetch("fetch.txt")

.then(function(response) {

  return response.text();

})

.then(function(text) {

  myDisplayer(text);

})

.catch(function(error) {

  myDisplayer(error);

});

The fetch() method immediately returns a Promise.

The download continues in the background while JavaScript runs other code.

How then() Works

The then() method is called immediately.

It registers a function that JavaScript will call after the Promise is fulfilled.

The registered function runs later when the Promise has a result.

Each call to then() returns a new Promise.

Note: The then() method itself does not wait. It registers a callback and immediately returns a new Promise.

Promise Flow

fetch()
⮯
returns a Promise
⮯
then() registers a callback
⮯
JavaScript continues
⮯
Promise becomes fulfilled
⮯
callback runs

Example

let promise = fetch("fetch.txt");

promise.then(function(response) {

  return response.text();

});

myDisplayer("JavaScript continues...");

Note: The callback passed to then() receives the Promise's fulfillment value. For fetch(), that value is a Response object. In the next section you will learn how to create your own Promise.

Creating a Promise

Most of the time you will use Promises returned by JavaScript APIs such as fetch().

Sometimes you need to create your own Promise.

Create a Promise with the Promise() constructor.

Syntax

const promise = new Promise(function(resolve, reject) {

  // Asynchronous work

  if (success) {

    resolve(value);

  } else {

    reject(error);

  }

});

The constructor receives a function with two parameters.

Note: Call either resolve() or reject(). A Promise can settle only once.

Example

Create and Use a Promise

const promise = new Promise(function(resolve, reject) {

  const success = true;

 if (success) {

    resolve("Operation completed");

 } else {

    reject("Operation failed");

  }

});

promise.then(function(value) {

  myDisplayer(value);

})

.catch(function(error) {

  myDisplayer(error);

});

The then() Method

The then() method registers a function that handles a fulfilled Promise.

The registered function receives the fulfillment value.

Example

fetch("fetch.txt")

.then(function(response) {

  return response.text();

})

.then(function(text) {

  myDisplayer(text);

});

Note: Each call to then() returns a new Promise. This makes Promise chaining possible.

The catch() Method

The catch() method registers a function that handles a rejected Promise.

Example

fetch("missing.txt")

.then(function(response) {

  if (!response.ok) {

    throw new Error(response.statusText);

  }

  return response.text();

})

.then(function(text) {

  myDisplayer(text);

})

.catch(function(error) {

  myDisplayer(error.message);

});

Note: A single catch() can handle errors from any earlier step in the Promise chain.

The finally() Method

The finally() method registers a function that runs when a Promise settles.

It runs whether the Promise is fulfilled or rejected.

Example

fetch("fetch.txt")

.then(function(response) {

  return response.text();

})

.then(function(text) {

  myDisplayer(text);

})

.catch(function(error) {

  myDisplayer(error.message);

})

.finally(function() {

  myDisplayer("Finished");

});

Promise Chaining

Since then() returns a new Promise, several asynchronous operations can be chained together.

Example

function step1() {

  return Promise.resolve("A");

}

function step2(value) {

  return Promise.resolve(value + "B");

}

function step3(value) {

  return Promise.resolve(value + "C");

}

step1()

.then(function(value) {

  return step2(value);

})

.then(function(value) {

  return step3(value);

})

.then(function(value) {

  myDisplayer(value);

})

.catch(function(error) {

  myDisplayer(error);

});

Note: Each step waits for the Promise returned by the previous step.

Returning a Promise

If a then() callback starts another asynchronous operation, return its Promise.

Correct

step1()

.then(function(value) {

  return step2(value);

})

.then(function(value) {

  myDisplayer(value);

});

Warning: If you forget to return the Promise, the next step in the chain may run before the asynchronous operation has finished.

Common Promise Mistakes

Forgetting to Return a Promise

If a then() callback starts another asynchronous operation, return its Promise.

Incorrect

step1()

.then(function(value) {

  step2(value);

})

.then(function(value) {

  myDisplayer(value);

});

The second then() may run before step2() has finished.

Correct

step1()

.then(function(value) {

  return step2(value);

})

.then(function(value) {

  myDisplayer(value);

});

Note: Returning the Promise keeps the chain in the correct order.

Forgetting to Handle Errors

Unhandled Promise rejections make debugging difficult.

Use catch() to handle errors.

Example

fetch("missing.txt")

.then(function(response) {

  if (!response.ok) {

    throw new Error(response.statusText);

  }

  return response.text();

})

.catch(function(error) {

  myDisplayer(error.message);

});

Expecting Promises to Block JavaScript

Creating a Promise does not pause JavaScript.

JavaScript continues executing while the asynchronous operation is in progress.

Example

myDisplayer("Start");

fetch("fetch.txt")

.then(function() {

  myDisplayer("Finished");

});

myDisplayer("JavaScript continues");

The output is:

Start

JavaScript continues

Finished

Note: Promises represent asynchronous operations. They do not stop JavaScript from executing other code.

Promises and Asynchronous Programming

A Promise represents the result of an asynchronous operation.

The asynchronous work is usually performed by a browser API such as fetch() or setTimeout().

The Promise provides a clean way to receive the result when that operation finishes.

Note: A Promise does not make code asynchronous. It represents the result of an asynchronous operation.

Promises and the Event Loop

Promise callbacks do not run immediately.

They are scheduled to run after the current JavaScript task has completed.

The JavaScript Event Loop is responsible for running these callbacks.

Note: You will learn more about this in the JavaScript Event Loop chapter.

Promises vs Callbacks

Summary

• A Promise represents the future result of an asynchronous operation.
• A Promise is either pending, fulfilled, or rejected.
• then() registers fulfillment handlers.
• catch() registers rejection handlers.
• finally() registers a handler that runs when the Promise settles.
• Return Promises from then() to keep Promise chains in the correct order.
• Most JavaScript APIs, including fetch(), return Promises.

Note: Next Step Promises make asynchronous code easier to organize. JavaScript also provides the async and await keywords, which let you write Promise-based code in a style that looks like synchronous JavaScript. Continue with the next chapter to learn Async and Await. JavaScript Async/Await