Promises

Consuming Promises

let res = fetch('https://www.example.com');
const isProm = res instanceof Promise; // returns true

Thenables

func() // Call the function that returns a promise
  .then((value) => { handle resolved; })
  .catch((err) => { handle rejected; })
  .finally(() => { optional final method; });

• The format starts with the call to a function that returns a promise. The initial return value is a Promise object with status pending. 
• When the function finishes its task it "settles". If the task is successful it is "fulfilled" and returns a value. If it is not successful it is "rejected" and returns a rejection reason.

• Chain the instance methods to the function call. The instance methods each take a handler function as the argument. Once the promise settles, the instance methods get invoked in order.
• The then method gets invoked if the promise is successfully fulfilled. It is skipped if the promise is rejected.
• The catch method gets invoked if the promise is rejected. It is skipped if the promise is successfully fulfilled.
• The optional finally method gets invoked if the promise is settled (whether fulfilled or rejected). 

let isLoading = true;
console.log(1, 'isLoading:', isLoading);

fetch('https://jsonplaceholder.typicode.com/users')
  .then((res) => { return res.json(); })
  .then((data) => { console.log(2, data); })
  .catch((err) => { console.error(2, err.toString()); })
  .finally(() => console.log(3, 'isLoading:', isLoading = false));

console.log(4, 'Last statement.');

1 'isLoading:' true
4 'Last statement.'
2 [{…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}]
3 'isLoading:' false

• The first statement above sets the isLoading variable to true, then logs it.
• Call the fetch function: fetch('url')
• Fetch takes a URL as the argument. The URL we are using is a real website for testing APIs.
• Fetch is an asynchronous Web API. It makes a GET request to the URL provided and waits for the response.
• JavaScript does not wait for the result before going to the next line. It skips over the chained thenables, goes to the last line and logs: 4 Last statement., then the script stops.

• When the HTTP response comes back with data from the server, the Fetch API resolves the promise and passes the response object to the then method.
• First then method: .then((res) => { return res.json(); })
• The first then method has a handler function as its argument to handle the response. It takes the HTTP response object as its argument.
• The HTTP response object contains several properties including the body property containing the requested data in JSON format. 
• The handler function calls the .json() method on the response object. 
• .json() is part of the Fetch API. 
• Like fetch(), it is asynchronous and returns a promise.
• It extracts the data property from the response object and converts it from JSON format to JavaScript. Then resolves the promise, passing the JavaScript data to the next then method.
• Second then method: .then((data) => { console.log(2, data); })
• The handler function in the second then method takes in the JavaScript data as its argument and logs it to the console.
• Catch method: .catch((err) => { console.error(2, err.toString()); })
• If there was a problem fetching the data then the promise is rejected and the catch method is called. In the callback we just log the error to the console.
• Finally method: .finally(() => console.log(3, 'isLoading:', isLoading = false));
• In the finally method we set isLoading to false and log it.

Async / await syntax

async function parentFunction() {
  try {
    const res = await asyncFunc();
  } catch (err) {
    // handle error;
  }
}

• Executing the above code will log:

Fetch with async await - Reject

• Then when you execute the code it will log:

• There are asynchronous Web APIs and npm packages that return callback functions instead of Promises. They work fine but if you want to pause your script until the result is returned you can add promises to them. 
• The format to create a new promise object is:

const prom = new Promise((resolve, reject) => {
  // Perform a task. Return a value if the task is successful or a reason if not.
  if (success) resolve(value);
  else reject(reason);
});

• Parameter - the Executor function: The parameter for the Promise constructor function is the executor function.
• The executor function includes the statements to perform some task. If it is successful it resolves to a value. If not it gives a reason.
• The executor function passes in two built-in functions as parameters: 
1. The resolve function. Call this function when the function task is successfully fulfilled, passing in the resulting value as the argument: resolve(value);
2. The optional reject function. Call this function if the task is unsuccessful, passing in a reject reason as the argument: reject(reason); 

• Let's demonstrate this with an actual asynchronous function, setTimeout. This is available both as a Web API and a Node.js module. It is as basic of an asynchronous function as there is. All it does is count down a timer then return a callback function to execute. You provide the callback function and the duration to count down in milliseconds.
• To make it slightly more tangible we will simulate querying a database. In web applications querying a database from the server is a common asynchronous task. The process is managed by npm packages such as Sequelize for relational databases and Mongoose for MongoDB. 
• Our setTimeout simulated database will return a set of usernames, as if it was pulled from a database, or an error message if there was a problem. 

const simulateDbQuery = () => {
  return new Promise((resolve, reject) => {
    setTimeout(function processQuery() {
      console.log('Processing the database query'); 
      const success = Math.round(Math.random()) === 1; // Randomly returns true or false
      if (success) {   
        const data = ['Joey', 'Sheena', 'Johnny', 'Judy'];
        resolve(data);
      } else {
        const reason = 'There was a problem';
        reject(reason);
      }
    }, 2000);
  });
};

• When the above simulateDbQuery function is called it takes no arguments and returns a new Promise object. 
• The Promise constructor function takes in the executor function as its argument.
• Our executor function contains the setTimeout Web API. 
• SetTimeout: The setTimeout takes two arguments:
1. The callback function which we named processQuery that executes after the timer delay expires.
2. The timer delay of 2000 milliseconds (i.e., 2 seconds).
• The ProcessQuery function: simulates our database query.
• The first line simulates a database query by logging: "Processing the database query"
• The second line randomly determines if the query was successful or not. The Math.round(Math.random()) === 1 formula randomly sets the success variable to either true or false. 
• The if statement checks if success is true. If so it calls the resolve function passing in an array of usernames: resolve(data). This gets returned as the fulfilled promise value.
• If success is false it calls the reject function passing in a reason as the argument: reject(reason)

• Now that we have a function that returns a promise, we can consume the promise the same way we did with the Fetch API, using either the thenables or async / await syntax. We'll start with thenables.

console.log(1, 'First statement');

simulateDbQuery()
  .then((data) => { console.log(2, data); })
  .catch((err) => { console.error(2, err); })
  .finally(() => { console.log(3, 'Promise has settled.'); });

console.log(4, 'Last statement'); 

• Executing the above code, if successful will log:

btn2.addEventListener('click', async function eventHandler() {
  console.log(1, 'First statement.');

  try {
    const data = await simulateDbQuery();
    console.log(2, data);
  } catch (err) {
    console.error(2, err);
  }

  console.log(3, 'Last statement.');
});

1 First statement
Processing the database query
2 ['Joey', 'Sheena', 'Johnny', 'Judy']
3 Last statement.

immediately Resolved Promises

• Static methods are methods that you call on the class instead of on an instance of the class. There are six Promise static methods (length, name, and prototype are properties).

Object.getOwnPropertyNames(Promise); // returns: length, name, prototype, all, allSettled, any, race, resolve, reject

• You may never have a need to use these methods but we will demonstrate simple examples of each anyway.

• There are also static Promise resolve and reject methods that return a new Promise object already fulfilled or rejected with the given value. 

• Immediately returns the resolved promise. You still need to use async / await or thenables.

btn2.addEventListener('click', async function eventHandler() {
  try {
    await Promise.reject(new Error('This promise was rejected.'));
  } catch (err) {
    console.error(2, err.toString()); // logs: 2 'Error: This promise was rejected.'
  }
});

• Immediately returns the rejected promise and throws an error. Use a try...catch statement to catch the error.

Static Methods - any, race, all, allSettled

• The any, race, all, and allSettled methods deal with running multiple promises concurrently. Each of these methods takes an array of promise objects as the argument.

• Below are three Promise constructors that settle after 1, 2, and 3 seconds respectively. The first is rejected and the other two are fulfilled.

// Prom 1 returns a rejected promise after 1 second
const prom1 = new Promise((resolve, reject) => {
  setTimeout(() => reject(new Error('1 Rejected after 1 sec')), 1000);
});

// Prom2 returns a resolved promise after 2 seconds 
const prom2 = new Promise((resolve, reject) => {
  setTimeout(() => resolve('2 Resolved after 2 secs'), 2000);
});

// Prom3 returns another resolved promise after 3 seconds
const prom3 = new Promise((resolve, reject) => {
  setTimeout(() => resolve('3 Resolved after 3 secs'), 3000);
});

const res = await Promise.any([prom1, prom2, prom3]); 
console.log(res); // logs '2 Resolved after 2 secs'

try {
  const res = await Promise.race([prom1, prom2, prom3]);
  console.log(res);
} catch (err) {
  console.error(err); // logs 'Error: 1 Rejected after 1 sec'
}

• Promise.all([prom1, prom2[,...]]) // Returns a promise that resolves when all promises resolve, returning an array of the resolved promise values. But if any promise rejects, then the whole thing rejects.

try {
  const res = await Promise.race([prom1, prom2, prom3]);
  console.log(res);
} catch (err) {
  console.error(err); // logs 'Error: 1 Rejected after 1 sec'
}

• Promise.allSettled([prom1, prom2[,...]]) // Returns a promise that resolves when all promises have settled. It returns an array of objects for all the promises, whether fulfilled or rejected. Each object has properties for status and value if it was fulfilled, or reason if it was rejected.

const res = await Promise.allSettled([prom1, prom2, prom3]);
console.log(res); // logs array promise objects

• The last topic we will cover is handling asynchronous functions using callbacks. This is how asynchronous functions were handled before Promises were introduced. Callbacks are still commonly used so it is useful to know how they work. They work perfectly fine, they are just messier to work with than Promises if there are multiple nested callbacks (i.e., callbacks within callbacks).

const asyncFunc = (callback) => {
  const result = /* do some task that returns a result */
  return callback(result);
};

const callback = (result) => /* do some operation on the result */;

asyncFunc(callback); //Call an asynchronous function passing in a callback.

// Asynchronous function
const simulateDbQuery = (dbCallback) => {
  setTimeout(function processQuery() {
    console.log('database processes the query and returns the data');
    const data = ['Joey', 'Sheena', 'Johnny', 'Judy'];
    return dbCallback(data);
  }, 2000);
};

// Callback function
const dbCallback = (data) => {
  console.log(data);
}

// Function call
simulateDbQuery(dbCallback);

console.log('Last statement.');

• And that concludes this tutorial on JavaScript Promises.