DEV Community: Saurabh Misra

Using CommonJS Modules in NodeJS with module.exports and require() | Cheatsheet

Saurabh Misra — Fri, 08 Sep 2023 12:58:07 +0000

This blog post serves as a quick reference aka cheatsheet( primarily intended for my future self ), to understand the syntactic peculiarities of the CommonJS style of module exports in NodeJS with a quick glance.

While NodeJS now supports ES6 modules, there are still a lot of projects out there that use CommonJS modules which is why NodeJS hasn't dropped support for them and doesn't seem like it will, in the near future.

Default Export

You can directly assign a value to module.exports.

const display = () => console.log( "Hello World" );

module.exports = display;

And then while using require(), you can either use the same name or a different one.

const display = require( "./my-module" );
display();

// or

const show = require( "./my-module" );
show();

Named Exports

Named Exports can be done in one of the following ways:

const display = () => console.log( "Hello World" );

exports.display = display;

// or

module.exports.display = display;

// or

module.exports = {
  display
};

While requiring or importing these named exports, we can choose one of the following options.

// import everything into one object
const myModule = require( "./my-module" );
myModule.display();

// or

// import only selected properties from module.exports
const { display } = require( "./my-module" );
display();

// or

// another way to reference only a single property while require()-ing  
const display = require( "./my-module" ).display;
display();

Hope this helps!🙏

ES6 Modules Cheatsheet | Quick Reference Guide

Saurabh Misra — Fri, 08 Sep 2023 12:57:07 +0000

This blog post serves as a quick reference aka cheatsheet( primarily intended for my future self ), to understand the syntactic peculiarities of the ES6 style of module exports with a quick glance.

DEFAULT EXPORT & IMPORT

Export an anonymous function as default and then import it with a name.

export default function(){ ... };

import anyName from '...';

Export an anonymous arrow function as default and then import it with a name.

export default () => { ... };

import anyName from '...';

Export a function as default after it has been declared and then import it with a name.

function foo(){ 
  ... 
}
export default foo;

import anyName from '...';

Export a variable as default after it has been declared and then import it with a name.

const foo = () => { ... };
export default foo;

import anyName from '...';

Another way to export a variable as default and then import it with a name.

export { foo as default };

import anyName from '...';

Default + Named export followed by a Default + Named import.

export { foo as default, bar };

import { default as anyName, bar } from '...';

NAMED EXPORT & IMPORT

Export inline with each declaration.

export const foo = () => { ... };

export function bar(){ ... };

Export at the end after all declarations

const foo = () => { ... };
function bar(){ ... };

export { foo, bar };

Import a single export.

import { foo } from '...';

Import multiple exports.

import { foo, bar } from '...';

IMPORT ALL

Import everything into an object. All exports will be referenced as the object properties including the default export.

import * as obj from '...';

obj.default();
obj.bar();

You can also name the default during import and also import all named exports into an object.

import foo, * as obj from '...';

foo();
obj.default();
obj.bar();

RENAMING EXPORTS & IMPORTS

Rename during export and then import as is.

export { foo, bar as baz };

import { foo, baz } from '...';

Export as is and then rename during import.

export { foo, bar };

import { foo, bar as baz } from '...';

MIXED EXPORT & IMPORT

Export some functions inline and others post declaration in the same module.

// export inline
export default () => { ... };
export const bar = () => { ... };

// export after declaration
function baz(){ ... }
export { baz };

Then during import, name the default, do a named as well as a renamed export.

import { default as foo, bar, baz as pie } from '...';
foo(); bar(); pie();

RE-EXPORT USING `export from ...`

We'll be using two modules: first.js and second.js. The latter will re-export or forward the exports from the former.

export { foo as default, bar, baz };

In second.js, we'll do a simple re-export of only the default.

export { default } from 'first.js';

And then import the default from second.js like we have seen before.

import foo from 'second.js';

Next, we'll re-export the default along with another named export.

export { default, bar } from 'first.js';

And then we'll do a named import of both.

import { default as foo, bar } from 'second.js';

Next, in second.js, we'll add a renamed export to the mix.

export { default, bar, baz as pie } from 'first.js';

And then we'll do a named import of all the three forwarded exports.

import foo, { bar, pie } from 'second.js';

Serve a static HTML page using NodeJS and ExpressJS

Saurabh Misra — Fri, 14 Jul 2023 13:40:58 +0000

Introduction

I recently came across a situation where I had to serve a static HTML page from an API powered by ExpressJS on a NodeJS server.

This was a simple but interesting problem and I thought about documenting this in one place for my future self or for anybody else in the same situation as me looking for a solution and a straight-forward explanation.

Tutorial Project Setup

Download or clone the tutorial files from this github repo.

The project comprises of a basic NodeJS and ExpressJS setup. There is a server.js file which has the code to initialize the server. There is a /public folder which contains our static HTML, CSS, JS and media files.

Run npm i to install dependencies and then npm start to start the server.

The project will also install nodemon which will automatically restart the server for you whenever you make any changes to the files in the project.

Serve the HTML page

If you visit http://localhost:3000/ right now in the browser, you won't see anything because the API root endpoint is not returning any response.

What we want is that this URL should serve our static html: /public/index.html.

Open server.js in your editor and replace the definition of the root API service handler with this.

app.get( "/", ( req, res ) => {
  // send the HTML file in the API response
  res.sendFile( path.join( __dirname + "/public/index.html" ));
});

The sendFile() method, as the name suggests will send the HTML file as the response. The Content-Type will automatically be set to text/html.

If you visit http://localhost:3000/, you should be able to see the HTML page.

But our CSS, JS and media files are not served properly. If you look at the Console in Dev Tools, you'll see errors like this:

The cause of these issues is that ExpressJS is unaware of the existence of these static assets in the /public directory. To make it aware, we need to use the middleware returned by express.static().

Copy paste this entire code into your server.js file.

const express = require( "express" ),
  app = express(),
  path = require( "path" ),
  PORT = 3000;

// register the location of the static assets
app.use( express.static( 'public' ));

app.get( "/", ( req, res ) => {
  // send the HTML file in the API response
  res.sendFile( path.join( __dirname + "/public/index.html" ));
});

// Start the API server!
app.listen( PORT, () => console.log( `👂 API server listening on port ${ PORT }` ) );

express.static() takes in the location of the folder that contains the static files as an input argument.

If you reload the page, you should now be able to see the properly served page with all static assets in place🎉.

3 ways to upload files using NodeJS and Axios

Saurabh Misra — Wed, 21 Jun 2023 14:03:35 +0000

Introduction

Usually when we think about file uploads, the first thought that often comes to mind is to have a <form/> tag with the enctype="multipart/form-data" attribute set on it on the client-side with a file input to upload files.

But what if there were no forms or file inputs involved?

What if I want to upload files from the server-side to some other third-party server. For example, uploading files from your server to Amazon S3. Or maybe you are building an app or an API that is supposed to receive files. In such cases, how would we configure the API request to carry file data in the request payload?

Also, are there any other ways we can send file data in an HTTP request apart from multipart/form-data?

Yes there are and that is exactly what we're going to touch upon in this article.

We're going to learn how to send files in an HTTP request in binary format, as multipart form-data and as a base64-encoded string from the server-side and also learn how to receive and save these files in the filesystem.

For our tutorial, we're going to use NodeJS, ExpressJS and Axios.

The main aim of this tutorial is to make you aware of the various approaches for uploading files that you have at your disposal. Then you can go ahead and implement the one that suits your requirements the best using a language, library or framework of your choice.

Tutorial Project Setup

The starter files for this tutorial are in this github repo.

Once you clone or download the files, cd into the folder and run npm install followed by npm start. You should have a local server running at http://localhost:3000.

There are only two script files in the project folder: app.js and utils.js.

app.js at this point only contains imports, variable declarations, and server initialization logic. We'll go over and use these imported packages and variables as we move forward.

// imports
const express = require( 'express' ),
  axios = require( 'axios' ).default,
  multer = require( "multer" ),
  fsProm = require( "fs/promises" ),
  fs = require( "fs" ),
  FormData = require( "form-data" ),
  { getFilename } = require( "./utils" );

// global variables, constants and defaults
const PORT = 3000,
  FILE_SOURCE_DIR = "./images",
  FILE_UPLOADS_DIR = "./uploads",
  MAX_UPLOAD_SIZE = 2 * 1024 * 1024; // 2MB in bytes
  MAX_UPLOAD_SIZE_IN_MB = `${ MAX_UPLOAD_SIZE / 1024 / 1024 }MB`;
axios.defaults.baseURL = `http://localhost:${ PORT }`;
const app = express();

// YOUR CODE GOES HERE

app.listen( PORT, () => console.log( `👂API Server listening on port ${PORT}` ));

utils.js houses some basic helper functions. The getFileExtFromMimeType() function performs some simple mapping between MIME types and file extensions. The other function getFilename() accepts a MIME type as an input and creates a unique file name for saving our uploads.

You'll also notice two folders named images and uploads. The images folder contains some sample images we can use for testing and the uploads folder will serve as the destination for the uploaded files.

Approach 1: Binary Upload

This is possibly the simplest approach for uploading files.

All we do here is populate the request payload with the file data in binary format and set the Content-Type HTTP header as the MIME type of the file. That's it!

Let's see this in action.

We'll create two API routes in the project, one for sending the file in binary format and the other for receiving this binary payload and saving it as a file in the filesystem.

GET /send-binary
POST /receive-binary

In real-world scenarios, these two API services will mostly reside on different servers but for convenience in our tutorial project, we are going to implement them on the same server.

Also, since our focus in this tutorial is not on API design, I have designed /send-binary as a GET request instead of a POST request for convenience so that I can send the request directly from the browser.

Copy-paste this function definition for the /send-binary route into app.js.

app.get( "/send-binary", async ( req, res ) => {

  // Specify which image to read from the file system 
  // and the value for the Content-Type header for the upload.
  const filepath = `${ FILE_SOURCE_DIR }/valid.jpg`,
  headers = { "Content-Type": "image/jpeg" };

  let file = null;
  try {

    // Read the binary file data into a "Buffer" object.
    file = await fsProm.readFile( filepath );    

  } catch ( error ) {

    // respond with a 500 Internal Server Error if something goes wrong
    return res.status( 500 ).json({ 
      status: "error", 
      message: "Error while reading file", 
      error 
    });

  }

  try {

    // upload the binary data in the request payload
    await axios.post( "/receive-binary", file, { headers });    

  } catch (err) {

    // handle file size and file type validation error response
    if( err.response && ( err.response.status == 413 || err.response.status == 400 )) {
      return res.status( 400 ).json({ 
        status: "error", 
        message: "Invalid file. Please upload a JPEG or PNG file less than " + MAX_UPLOAD_SIZE_IN_MB + " in size."
      });
    } 

    // handle any generic error
    else {
      return res.status( 500 ).json({ 
        status: "error", 
        message: "Error while uploading file", 
        error: err 
      });
    }

  }

  return res.json({ status: "success", message: "File sent successfully." });

});

The only main steps here are reading the file from the filesystem in a Buffer instance and then sending it in the request payload using axios. Everything else like the try-catch is just best practice.

Buffer is basically NodeJS's way of referencing binary data which is currently stored in memory or RAM.

Now let's define the route handling logic for the /receive-binary route as well. Paste the below code into app.js.

// Configure middleware to parse raw request payloads.
const parseRawReqBody = express.raw({ 
  limit: MAX_UPLOAD_SIZE, 
  type: [ "image/jpeg", "image/png" ] 
});

app.post( "/receive-binary", parseRawReqBody, async ( req, res ) => {

  // validate if file type is valid. If not, return 400 Bad Request.
  if( req.headers[ "content-type" ] !== "image/jpeg" 
    && req.headers[ "content-type" ] !== "image/png" 
    ) {
    return res.status( 400 ).json({ 
      status: "error", 
      message: "Invalid file. Please upload a JPEG or PNG file only."
    });
  }

  // Set the path where the file should be saved.
  const filename = getFilename( req.header( "Content-Type" ) ),
    filepath = FILE_UPLOADS_DIR + '/' + filename;

  try {

    // write the binary data from the request body into a file.
    await fsProm.writeFile( filepath, req.body );

  } catch (error) {

    // respond with a 500 Internal Server Error if something goes wrong
    return res.status( 500 ).json({ 
      status: "error", 
      message: "Error while writing the binary file to disk.", 
      error 
    });

  }

  return res.json({ status: "success", message: "File received and saved successfully." });

});

Again the only main steps here are writing the binary data into a file using the writeFile() function from the fs/promises module.

Let's test this out. If you haven't already, spin up the server using npm start and visit http://localhost:3000/send-binary in the browser. You should see a successful API response. Check your uploads directory where the file should have been saved.

Let's change the name of the file in /send-binary to "too_large.jpg". Again hit the same URL as before. This time you'll see an error response which means that our file size validation does work.

Let's quickly make sure that our file format validation works as well or not. Change the name of the file to "invalid.pdf" and the Content-Type to "application/pdf". Hit the same URL. You'll again see the same error response.

You can also test uploading a PNG image by changing the file name in /send-binary to "heart.png" and changing the Content-Type to "image/png".

And there you have it! A simple way to send and save files across HTTP in binary format.

The downside of this approach is that the request body will only contain file data and nothing else. So sending any metadata in the request body is not possible. But in case you do need to send a few simple values as metadata, then that can be achieved using either query-string parameters or custom HTTP headers.

Approach #2: Multipart Uploads

So you might already be familiar with the mulipart/form-data value of the enctype attribute that is specified on a <form> tag. Multipart means that the request contains various parts separated by a pre-defined boundary. These parts can be of different types such as simple key-value pairs, plain text, file data, etc. Here is a great example of how a multipart HTTP request is formatted.

Let's implement this approach now. Just like the binary approach, we'll implement two routes here as well:

GET /send-multipart
POST /receive-multipart

Let's define the route handler for /send-multipart first. /send-multipart will use a FormData instance to construct a multipart request payload. We'll read the file data and append it to the FormData instance along with any other required metadata. We'll then use axios to send this info in a POST request to /receive-multipart. Paste the below code into app.js.

app.get( "/send-multipart", async ( req, res ) => {

  const form = new FormData();

  // read the file and append into the FormData instance.
  const filepath = `${ FILE_SOURCE_DIR }/valid.jpg`; 
  form.append( "file", fs.createReadStream( filepath ) );

  // append any other metadata
  form.append( "firstname", "Saurabh" );

  try {

    // Send the file using axios.
    // Since we're using the FormData instance, axios will automatically set 
    // the Content-Type header as 'mulitpart/form-data'.
    await axios.post( "/receive-multipart", form );

  } catch ( error ) {

    // handle file size and file type validation error response
    if( error.response && error.response.data ) {
      return res.status( error.response.status ).json( error.response.data );
    }

    // handle any generic error
    else {
      return res.status( 500 ).json({ 
        status: "error", 
        message: "Something went wrong while uploading the image.", 
        detail: error 
      });
    }

  }

  res.json({ status: "success", message: "File sent successfully." }); 
});

To receive and parse multipart requests, we'll use an NPM package called multer which exposes a middleware that parses multipart/form-data requests. multer is already installed in our tutorial project and also imported in our app.js file so let's go ahead and configure it. Paste the below code into app.js.

// configure multer to save images to disk.
const fileStorageEngine = multer.diskStorage({

  // configure the destination directory 
  destination: ( req, file, callback ) => {
    callback( null, FILE_UPLOADS_DIR );
  },

  // configure the destination filename
  filename: ( req, file, callback ) => {
    callback( null, getFilename( file.mimetype ) );
  }

});

// configure multer to handle single file uploads
const uploadSingleFile = multer({

  // use the configured file storage option
  storage: fileStorageEngine,

  // skip any files that do not meet the validation criteria
  fileFilter: ( req, file, callback ) => {

    if ( file.mimetype !== "image/png" && file.mimetype !== "image/jpeg" ) {

      // Store a flag to denote that this file is invalid.
      // Unlike `res.locals`, `req.locals` is not really 
      // a standard express object but we use it here
      // for convenience to pass data to the route handler.
      req.locals = { invalidFileFormat: true };

      // reject this file
      callback( null, false );
    }

    // accept this file
    callback( null, true );

  },

  // configure a max limit on the uploaded file size
  limits: { fileSize: MAX_UPLOAD_SIZE }

}).single( "file" );

Let's go ahead and implement the route handling functionality for /receive-multipart. /receive-multipart will forward the request to multer by calling uploadSingleFile() which will parse and upload the file. The route handler will then only validate whether everything went smoothly or not and respond accordingly. Paste the below code into app.js.

app.post( "/receive-multipart", ( req, res ) => {

  // `uploadSingleFile` is a middleware but we use it here 
  // inside the route handler because we want to handle errors.
  uploadSingleFile( req, res, err => {

    // if uploaded file size is too large or if its format is invalid
    // then respond with a 400 Bad Request HTTP status code.
    if( err instanceof multer.MulterError 
      || ( req.locals && req.locals.invalidFileFormat )
      ) {
        return res.status( 400 ).json({ 
          status: "error", 
          message: `Invalid file format. Please upload a JPEG or PNG image not greater than ${MAX_UPLOAD_SIZE_IN_MB} in size.` 
      });
    }

    // handle any other generic error
    else if ( err ) {
      return res.status( 500 ).json({ 
        status: "error", 
        message: "Something went wrong while uploading the image.", 
        detail: err 
      });
    }

    res.json({ status: "success" });

  });
});

Let's run this now and visit the URL http://localhost:3000/send-multipart. You should see a successful response and the file should have been uploaded to the uploads directory.

Now let's test our validations. Change the filepath variable to use the "too_large.jpg" file and visit the same URL again. You should see an error response.

I'll leave it up to you to test this using the PDF and PNG file.

This approach proves quite useful when you need to send metadata along with file data or multiple files in a single HTTP request.

Approach #3: Base64 uploads

Base-64 encoding is used to convert binary data into an ASCII string representation. A base64-encoded string can be easily transferred in an HTTP request as it is or as a part of a JSON.

Let's implement this approach now. Just like the binary approach, we'll implement two routes here as well.

GET /send-base64
POST /receive-base64

Let's implement the /send-base64 route first. /send-base64 will read the file from the filesystem, convert the entire file data into a base64-encoded string, include this string in a JSON and send this JSON in a POST request using axios to /receive-base64. Paste the below code into app.js.

app.get( "/send-base64", async ( req, res ) => {

  // Specify which image to read from the file system 
  // and the value for the Content-Type header for the upload.
  const filepath = `${ FILE_SOURCE_DIR }/valid.jpg`,
    mimetype = "image/jpeg";

  let file = null;
  try {

    // read the file as a base64-encoded string
    file = await fsProm.readFile( filepath, "base64" );    

  } catch ( err ) {

    // respond with a 500 Internal Server Error if something goes wrong
    return res.status( 500 ).json({ 
      status: "error", 
      message: "Error while reading file", 
      error: err 
    });

  }

  try {

    // Upload the base64 string as JSON with other metadata.
    // `Content-Type` will automatically be set to "application/json".
    const data = { mimetype, file };
    await axios.post( "/receive-base64", data );

  } catch ( err ) {

    // handle file size
    if( err.response && ( err.response.status == 413 || err.response.status == 400 )) {
      return res.status( 400 ).json({ 
        status: "error", 
        message: "Invalid file. Please upload a JPEG or PNG file less than " + MAX_UPLOAD_SIZE_IN_MB + " in size."
      });
    }

    // handle any other generic error
    else {
      return res.status( 500 ).json({ 
        status: "error", 
        message: "Error while uploading file", 
        error: err 
      });
    }

  }

  return res.json({ status: "success", message: "File uploaded and saved successfully." });
});

If you notice, we're using the same readFile() function from the fs/promises module that we used in the binary approach but this time we specify "base64" as the second argument as the encoding type.

Now let's implement the /receive-base64 route. /receive-base64 will receive the JSON payload, validate it, read the base64-encoded string, convert it into binary and will save the file in the filesystem. Paste the below code into app.js.

// configure middleware to parse JSON payloads in the request body.
const parseJSONReqBody = express.json({ limit: MAX_UPLOAD_SIZE });

app.post( "/receive-base64", parseJSONReqBody, async ( req, res ) => {

  // validate if file type is valid. If not, return 400 Bad Request.
  if( req.body.mimetype !== "image/jpeg" && req.body.mimetype !== "image/png" ) {
    return res.status( 400 ).json({ 
      status: "error", 
      message: "Invalid file. Please upload a JPEG or PNG file only."
    });
  }

  // convert the base64-encoded string into binary
  const binaryData = Buffer.from( req.body.file, 'base64' );

  // Set the path where the file should be saved.
  const filename = getFilename( req.body.mimetype ),
    filepath = FILE_UPLOADS_DIR + '/' + filename;

  try {

    // write the binary data into a file.
    await fsProm.writeFile( filepath, binaryData );

  } catch ( err ) {

    // respond with a 500 Internal Server Error if something goes wrong
    return res.status( 500 ).json({ 
      status: "error", 
      message: "Error while writing the file to disk.", 
      error: err 
    });

  }

  return res.json({ status: "success", message: "File saved successfully." });

});

The only main steps here are using Buffer.from() to convert the base64-encoded string into binary data and then using writeFile() to write the binary data into a file the same way we did with binary uploads.

Let's run this now and visit the URL http://localhost:3000/send-base64. You should see a successful response and the file should have been uploaded to the uploads directory.

Now let's test our validations. Change the filepath variable to use the "too_large.jpg" file and also change the mimetype variable accordingly and visit the same URL again. You should see an error response.

I'll leave it up to you to test this using the PDF and PNG file.

The pros of this approach is that you can design a file upload API service to accept JSON payloads and share a consistent and uniform interface with the rest of the API services. But keep in mind that this is not a hard-and-fast rule and it is perfectly fine for API services to accept file upload inputs as either multipart/form-data or binary.

The disadvantage of this approach is that base64-encoding increases the payload size by ~33%. For large files, the payload can end up weighing a lot.

Summary

You don't have to rely solely on multipart/form-data payloads to upload files.

We just learnt three ways to send and receive files using NodeJS, ExpressJS and Axios.

Direct Binary Uploads
Multipart Form-Data Uploads
Base64-encoded Uploads

It is helpful to keep these approaches in your arsenal and choose the one that best meets your needs when you need to design one for your projects.

Common Table Expressions(CTE) in SQL Server

Saurabh Misra — Tue, 13 Jul 2021 12:51:32 +0000

What is a Common Table Expression?

A Common Table Expression or CTE is a temporary result set that has a name and we can reference this result set using that name within SELECT, INSERT, UPDATE and DELETE statements.

Wait...aren't views supposed to be result sets with names that we can reference within SELECT, INSERT, UPDATE and DELETE statements?

Yes and CTEs are similar to views in that sense BUT there are some major differences:

CTEs are temporary meaning they are not stored as a DB object like views. They are only available within the scope of the current query.
CTEs can reference themselves and thus enable recursion.

We'll check out these differences in more detail later but for now lets first look at how to create and use CTEs.

Creating and Using a CTE

We're going to stick to tradition and use the most cliched example in the history of all programming related tutorials, the "Hello World!" example🤷‍♂️.

-- create a CTE
WITH cte_greeting
AS (
    SELECT 'Hello World!' as 'greeting'
)

-- use the CTE
SELECT * FROM cte_greeting;

/*

greeting
------------
Hello World!

*/

The structure of a basic CTE is pretty simple.

WITH <cte_name> (<optional_list_of_column_names>)
AS (
  <query_definition>
)

And using the CTE is pretty straight forward as well. You simply reference it like a table or view in a SELECT statement.

SELECT <list of columns> FROM <cte_name>;

In our "Hello World!" example, you'll notice we have skipped the optional column list. We can only do this if the query definition inside the CTE has defined names for all its columns otherwise we need to provide names for those columns in the column list.

So if we don't provide a column name in the column list and also omit the column name in the query definition, it'll throw an error.

WITH cte_greeting
AS (
    SELECT 'Hello World!'
)
SELECT * FROM cte_greeting;

/*

No column name was specified for column 1 of 'cte_greeting'.

*/

To resolve this we can re-instate the column name in the query definition like before or instead, provide a column name in the column list like this:

WITH cte_greeting( my_greeting )
AS (
    SELECT 'Hello World!'
)
SELECT * FROM cte_greeting;

/*

my_greeting
------------
Hello World!

*/

If we specify a column name in the column list as well as in the query definition then the name in the column list will take precedence and will override the column name in the query definition when we run the CTE in the SELECT clause.

WITH cte_greeting( my_greeting )
AS (
    SELECT 'Hello World!' as 'greeting'
)
SELECT * FROM cte_greeting;

/*

my_greeting
------------
Hello World!

*/

Also make sure the column names in the column list are the same number(and sequence) as in the query definition otherwise it'll throw an error.

WITH cte_greeting( my_greeting )
AS (
    SELECT 'Hello World!' as 'greeting1', 'Good Morning!' as 'greeting2'
)
SELECT * FROM cte_greeting;

/*

'cte_greeting' has more columns than were specified in the column list.

*/

A CTE should be used immediately

Remember that CTEs are a temporary result set so you must use a CTE immediately in a SQL statement after defining it otherwise you'll get an error.

WITH cte_greeting( my_greeting )
AS (
    SELECT 'Hello World!'
)
SELECT 'some other sql statement'
SELECT * FROM cte_greeting

/*

Common table expression defined but not used.

*/

Multiple CTEs

You can define multiple CTEs and then use them in the same SELECT statement. All you have to do is use a comma to separate your CTE definitions.

WITH cte_greeting1( greeting1 )
AS (
    SELECT 'Hello World!'
),
cte_greeting2( greeting2 )
AS (
    SELECT 'Good Morning!'
)
SELECT greeting1 as 'greetings' FROM cte_greeting1
UNION
SELECT greeting2 as 'greetings' FROM cte_greeting2

/*

greetings
-------------
Hello World!
Good Morning!

*/

Lets look at a slightly more complicated example. Please go ahead and create the sample table below and fill it up with some random statistical data.

CREATE TABLE tblMarvelMovies (
    id INT IDENTITY(1,1) PRIMARY KEY,
    name varchar(50),
    rating DECIMAL(2,1),
    gross_revenue_millions DECIMAL(5,2)
);
INSERT tblMarvelMovies (name, rating, gross_revenue_millions) 
VALUES ('Avengers: Endgame', 7.1, 777.27)
INSERT tblMarvelMovies (name, rating, gross_revenue_millions) 
VALUES ('Avengers: Infinity War', 8.9, 560.13)
INSERT tblMarvelMovies (name, rating, gross_revenue_millions) 
VALUES ('Avengers: Age of Ultron', 6.0, 874.85)
INSERT tblMarvelMovies (name, rating, gross_revenue_millions) 
VALUES ('The Avengers', 6.1, 918.44)
INSERT tblMarvelMovies (name, rating, gross_revenue_millions) 
VALUES ('Iron Man', 8.5, 918.75)
INSERT tblMarvelMovies (name, rating, gross_revenue_millions) 
VALUES ('Iron Man 2', 7.1, 798.97)
INSERT tblMarvelMovies (name, rating, gross_revenue_millions) 
VALUES ('Iron Man 3', 6.4, 524.08)
INSERT tblMarvelMovies (name, rating, gross_revenue_millions) 
VALUES ('Guardians of the Galaxy', 8.7, 711.11)
INSERT tblMarvelMovies (name, rating, gross_revenue_millions) 
VALUES ('Guardians of the Galaxy Vol. 2', 8.2, 963.13)
INSERT tblMarvelMovies (name, rating, gross_revenue_millions) 
VALUES ('Thor', 6.1, 871.70)
INSERT tblMarvelMovies (name, rating, gross_revenue_millions) 
VALUES ('Thor: The Dark World', 6.1, 898.57)
INSERT tblMarvelMovies (name, rating, gross_revenue_millions) 
VALUES ('Thor: Ragnarok', 6.4, 841.32)
INSERT tblMarvelMovies (name, rating, gross_revenue_millions) 
VALUES ('Captain America: The First Avenger', 9.5, 938.28)
INSERT tblMarvelMovies (name, rating, gross_revenue_millions) 
VALUES ('Captain America: The Winter Soldier', 8.7, 868.83)
INSERT tblMarvelMovies (name, rating, gross_revenue_millions) 
VALUES ('Captain America: Civil War', 8.3, 855.60)

Yes, I'm a fan of the Marvel movies! 🤷‍♂️

Now, lets construct a query to find the total gross revenue earned and the average rating grouped by the movie series. So basically total revenue and average rating for the Avengers movie series, the Iron Man movie series, the Captain America movie series, etc.

SELECT 
    series_category, 
    SUM(gross_revenue_millions) as 'total_gross_revenue', 
    CAST(AVG(rating) as DECIMAL(2,1)) as 'avg_rating'
FROM (
    SELECT 
        CASE 
            WHEN name like '%Avengers%' THEN 'The Avengers'
            WHEN name like '%Iron Man%' THEN 'Iron Man'
            WHEN name like '%Guardians%' THEN 'Guardians of the Galaxy'
            WHEN name like '%Thor%' THEN 'Thor'
            WHEN name like '%Captain%' THEN 'Captain America'
        END as 'series_category',
        gross_revenue_millions,
        rating
    FROM tblMarvelMovies 
) temp
GROUP BY series_category
ORDER BY avg_rating desc;

/*

series_category         total_gross_revenue    avg_rating
----------------------- ---------------------- -----------
Captain America         2662.71                8.8
Guardians of the Galaxy 1674.24                8.5
Iron Man                2241.80                7.3
The Avengers            3130.69                7.0
Thor                    2611.59                6.2

*/

Lets look at how we can make the main query a bit simpler and easier to read using a CTE.

-- complex logic encapsulated within CTE
WITH cte_series
AS (
    SELECT 
        CASE 
            WHEN name like '%Avengers%' THEN 'The Avengers'
            WHEN name like '%Iron Man%' THEN 'Iron Man'
            WHEN name like '%Guardians%' THEN 'Guardians of the Galaxy'
            WHEN name like '%Thor%' THEN 'Thor'
            WHEN name like '%Captain%' THEN 'Captain America'
        END as 'series_category',
        gross_revenue_millions,
        rating
    FROM tblMarvelMovies 
)
-- simpler and more readable main query
SELECT 
    series_category, 
    SUM(gross_revenue_millions) as 'total_gross_revenue', 
    CAST(AVG(rating) as DECIMAL(2,1)) as 'avg_rating'
FROM cte_series
GROUP BY series_category
ORDER BY avg_rating desc;

/*

series_category         total_gross_revenue    avg_rating
----------------------- ---------------------- -----------
Captain America         2662.71                8.8
Guardians of the Galaxy 1674.24                8.5
Iron Man                2241.80                7.3
The Avengers            3130.69                7.0
Thor                    2611.59                6.2

*/

Woo hoo! The main query no longer has to deal with a sub-query. All the CASE WHEN THEN statements are encapsulated in to the CTE. The result is a simpler looking, more maintainable and readable main query.

The benefit of making the main query simpler might not be very apparent in the example we have used above but in real life, more often than not, we encounter queries that look like a giant heap of complicated logic or inline sub-queries used in JOINs, WHERE and SELECT clauses. In such situations, we can clean the main query up into one or multiple CTEs.

It's kind of like how we separate concerns by encapsulating logic into functions in other application programming languages so that the main function that performs a lot of different tasks becomes more readable and maintainable.

So if you have a complex query that you want to clean up, ask yourself whether it would make more sense to encapsulate this complexity in a view or a CTE. If you think the complex query parts are not going to be used elsewhere like in other database objects or stored procedures or functions, then a view might be overkill but this is exactly where CTEs will come in handy.

Recursive CTEs

One of the most unique and useful features of a CTE is that you can reference a CTE by its name inside itself and create a recursive CTE similar to how we create recursive functions in application programming languages.

Lets code a simple recursive CTE that produces a result of rows from 1 to 10.

WITH cte_recursive( sequence )
AS (
    -- anchor member
    SELECT 1 as 'sequence'

    UNION ALL

    -- recursive member
    SELECT (sequence+1) as 'sequence'
    FROM cte_recursive
    WHERE sequence < 10 -- termination condition 
)
SELECT * FROM cte_recursive;

/*

sequence
-----------
1
2
3
4
5
6
7
8
9
10

*/

Lets understand how this works starting with how a recursive CTE is constructed. There are 3 building blocks of a recursive CTE:

1. Anchor member ⚓

The SELECT statement on line 4 provides the initial result set and is known as the anchor member.

2. Recursive Member 🔃

The SELECT statement on line 9 references the same CTE inside which it is being defined which enables recursion which is why it is known as the recursive member. This member is connected with the anchor member using a UNION ALL.

3. Termination condition 🛑

If you have worked with recursive functions before then you know you need a way to stop the recursion otherwise you'll run into stack overflow issues. In this example, we stop the recursion using a simple WHERE clause condition but there are other ways to stop the recursion also as you'll see in examples that follow.

How it all works?

The anchor member provides the initial result set and there after each iteration of the CTE operates on the result set produced by the previous iteration and produces a new result set for the next iteration until the termination condition stops the recursion. In the end, all these result sets are combined to produce the final result set.

Here is a walkthrough of the results sets produced by each iteration of the recursive CTE in the previous example.

Result set T0 ( returned by anchor member )

sequence
---------
1


Iteration 1 - Result set T1

sequence
---------
2


Iteration 2 - Result set T2

sequence
---------
3

...
...
...


Iteration 9 - Result set T9

sequence
---------
10

Iteration 10 ( termination condition ends recursion )

After the recursion ends, all the result sets from each iteration are joined together into the final result set.

sequence
-----------
1
2
3
4
5
6
7
8
9
10

`MAXRECURSION` query hint

In our previous recursive CTE example, lets remove the termination condition and see what happens.

WITH cte_recursive( sequence )
AS (
    -- anchor member
    SELECT 1 as 'sequence'

    UNION ALL

    -- recursive member
    SELECT (sequence+1) as 'sequence'
    FROM cte_recursive
)
SELECT * FROM cte_recursive;

By default, SQL Server limits the maximum number of iterations in a recursive CTE to 100. This is like a fallback to make sure that the CTE doesn't run infinitely because of an incorrectly scripted termination condition. So since we haven't specified a termination condition, our CTE kept on going till 100 iterations. It printed 101 and then reached the maximum recursion limit and terminated with the error in the screenshot.

We can control this recursion limit using the MAXRECURSION query hint which we can specify using the OPTION clause. Lets set the max recursion limit to a lower value like 10 and see what happens.

WITH cte_recursive( sequence )
AS (
    -- anchor member
    SELECT 1 as 'sequence'

    UNION ALL

    -- recursive member
    SELECT (sequence+1) as 'sequence'
    FROM cte_recursive
)
SELECT * FROM cte_recursive
OPTION ( MAXRECURSION 10 );

This time, instead of printing numbers from 1 to 101, the CTE prints numbers from 1 to 11 and then terminates because we have explicitly set the max recursion limit to 10. We can set this to a number higher than 100 as well.

Multiple anchor and recursive members

Since there is a clear distinction between the anchor and the recursive member in the fact that the recursive member references its own CTE, it is possible to have multiple anchor and/or recursive members.

Lets see how a CTE works with multiple anchor members.

WITH cte_recursive( sequence, anchor_member )
AS (
    -- anchor member 1
    SELECT 5 as 'sequence', 'first' as 'anchor_member'

    UNION

    -- anchor member 2
    SELECT 8 as 'sequence', 'second' as 'anchor_member'

    UNION ALL

    -- recursive member
    SELECT (sequence+1) as 'sequence', anchor_member
    FROM cte_recursive
    WHERE sequence < 10 -- termination condition 
)
SELECT * FROM cte_recursive;

/*

sequence    anchor_member
----------- -------------
5           first
8           second
9           second
10          second
6           first
7           first
8           first
9           first
10          first

*/

In the above example, we have two anchor members joined by a UNION and then we have the recursive member. The first 2 rows are provided by the anchor members. The anchor_member column helps identify which anchor member's result set is being recursed over. The recursive member first operates on the result set of the second anchor member. After completely recursing over the second anchor member, it moves on to the first one.

Lets now take an example with multiple recursive members. Please note that I have changed the termination condition so that we don't end up with a giant result set.

WITH cte_recursive( sequence, recursive_member, iteration )
AS (
    -- anchor member
    SELECT 
        1 as 'sequence', 
        cast('' as varchar(10)) as 'recursive_member', 
        0 as iteration

    UNION ALL

    -- recursive member 1
    SELECT 
        (sequence+1) as 'sequence', 
        cast('first' as varchar(10)) as 'recursive_member', 
        (iteration+1) as iteration
    FROM cte_recursive
    WHERE sequence < 4 -- termination condition 

    UNION ALL

    -- recursive member 2
    SELECT 
        (sequence+1) as 'sequence', 
        cast('second' as varchar(10)) as 'recursive_member', 
        (iteration+1) as iteration
    FROM cte_recursive
    WHERE sequence < 4 -- termination condition 
)
SELECT * FROM cte_recursive;

/*

sequence    recursive_member iteration
----------- ---------------- -----------
1                            0
2           first            1
2           second           1
3           first            2
3           second           2
4           first            3
4           second           3
4           first            3
4           second           3
3           first            2
3           second           2
4           first            3
4           second           3
4           first            3
4           second           3

*/

Ok so we have two recursive members now. Why are we using CAST() for the recursive_member columns? That is because the CTE is not aware of the datatype and length of the literal values we have used as column values so we must specify that else it'll throw an error. Go ahead and remove those CAST() calls and see what the error is all about.

If you need help understanding how the above result set is generated, follow the flow of control represented by numbers on the arrows in the image below.

Also here is the division in the result sets generated by each iteration of the CTEs.

T0

sequence    recursive_member iteration
----------- ---------------- -----------
1                            0


T1

sequence    recursive_member iteration
----------- ---------------- -----------
2           first            1
2           second           1


T2

sequence    recursive_member iteration
----------- ---------------- -----------
3           first            2
3           second           2


T3

sequence    recursive_member iteration
----------- ---------------- -----------
4           first            3
4           second           3


T4

sequence    recursive_member iteration
----------- ---------------- -----------
4           first            3
4           second           3


T5

sequence    recursive_member iteration
----------- ---------------- -----------
3           first            2
3           second           2


T6

sequence    recursive_member iteration
----------- ---------------- -----------
4           first            3
4           second           3


T7

sequence    recursive_member iteration
----------- ---------------- -----------
4           first            3
4           second           3

A realistic example

We have been working with generating result sets of numbers because I wanted to give you an idea of how CTEs operate on data with every iteration but now that we have understood all that, lets look at an example with the kind of data that we usually deal with when working with databases.

Recursive queries are commonly used to operate on hierarchical data. So for our example, we are again going to use the much cliched, self-referencing employee-manager data table.

CREATE TABLE tblEmployees (
    emp_id INT IDENTITY(1,1) PRIMARY KEY,
    name varchar(50) NOT NULL,
    designation varchar(50) NOT NULL,
    manager_id INT NULL
);

SET IDENTITY_INSERT tblEmployees ON;
INSERT INTO tblEmployees(emp_id, name, designation, manager_id) 
VALUES( 1, 'Michael Scott', 'Regional Manager', 9 );
INSERT INTO tblEmployees(emp_id, name, designation, manager_id) 
VALUES( 2, 'Dwight Schrute', 'Assistant to the Regional Manager', 1 );
INSERT INTO tblEmployees(emp_id, name, designation, manager_id) 
VALUES( 3, 'Jim Halpert', 'Salesman', 1 );
INSERT INTO tblEmployees(emp_id, name, designation, manager_id) 
VALUES( 4, 'Pam Beasley', 'Receptionist', 1 );
INSERT INTO tblEmployees(emp_id, name, designation, manager_id) 
VALUES( 5, 'Kevin Malone', 'Accountant', 6 );
INSERT INTO tblEmployees(emp_id, name, designation, manager_id) 
VALUES( 6, 'Angela Martin', 'Head Accountant', 1 );
INSERT INTO tblEmployees(emp_id, name, designation, manager_id) 
VALUES( 7, 'Oscar Gutierrez', 'Accountant', 6 );
INSERT INTO tblEmployees(emp_id, name, designation, manager_id) 
VALUES( 8, 'David Wallace', 'CEO', NULL );
INSERT INTO tblEmployees(emp_id, name, designation, manager_id) 
VALUES( 9, 'Jan', 'Vice-President', 8 );
SET IDENTITY_INSERT tblEmployees OFF;

Yes, I am a fan of "The Office" TV series! 🤷‍♂️

So our job is pretty simple, to arrange this data hierarchically starting from the top-level executive to the bottom-level employees using a CTE.

WITH cte_emp_levels( emp_id, name, designation, manager_id, level )
AS (
    -- anchor member
    SELECT emp_id, name, designation, manager_id, 0 as 'level'
    FROM tblEmployees
    WHERE manager_id IS NULL

    UNION ALL

    -- recursive member
    SELECT e.emp_id, e.name, e.designation, e.manager_id, ( level + 1 ) as 'level'
    FROM tblEmployees e
    INNER JOIN cte_emp_levels c ON e.manager_id = c.emp_id
)
SELECT * FROM cte_emp_levels;

and here is the output:

Mission Accomplished!!😎

Do you see something missing though? Where the heck is the termination condition!!?🤔

It's implicit. See the INNER JOIN in the recursive member. Well when it reaches the bottom-level employees, it does not find anyone else who is managed by them. When no records are returned, the recursion is terminated.

Here is a walkthrough of the result sets generated by each iteration of the CTE.

The CEO is not managed by anyone so the anchor member returns his record first.

T0 - result set returned by anchor member

emp_id      name            designation  manager_id  level
----------- --------------- ------------ ----------- -----------
8           David Wallace   CEO          NULL        0

In our data, the only person managed by the CEO is Vice-President Jan.

T1

emp_id      name   designation      manager_id  level
----------- ------ ---------------- ----------- -----------
9           Jan    Vice-President   8           1

In our data, the only person managed by the Vice-President is Michael, the Regional Manager.

T2

emp_id      name            designation         manager_id  level
----------- --------------- ------------------- ----------- -----------
1           Michael Scott   Regional Manager    9           2

Salesmen, receptionists and the head of accounting all report to Michael.

T3

emp_id      name            designation                         manager_id  level
----------- --------------- ----------------------------------- ----------- -----------
2           Dwight Schrute  Assistant to the Regional Manager   1           3
3           Jim Halpert     Salesman                            1           3
4           Pam Beasley     Receptionist                        1           3
6           Angela Martin   Head Accountant                     1           3

And finally, we have accountants who report to the head of accounting, Angela.

T4

emp_id      name                designation     manager_id  level
----------- ------------------- --------------- ----------- -----------
5           Kevin Malone        Accountant      6           4
7           Oscar Gutierrez     Accountant      6           4

I hope this article helps and encourages you to use CTEs in your queries. There are a variety of use cases where CTEs, particularly recursive CTEs can come very handy. One such scenario that I personally have come across a lot is splitting comma separated strings. If this interests you as well, check out this article to find out how we can use CTEs to accomplish this.

Keep on rocking! 🤘

References and Further Reading

https://docs.microsoft.com/en-us/previous-versions/sql/sql-server-2008-r2/ms186243(v=sql.105)?redirectedfrom=MSDN

https://stackoverflow.com/questions/30918633/sql-cte-vs-view

https://stackoverflow.com/questions/4740748/when-to-use-common-table-expression-cte

https://www.sqlshack.com/sql-server-common-table-expressions-cte/

Async-Await

Saurabh Misra — Mon, 12 Jul 2021 13:39:24 +0000

Just when you thought Promises couldn't get any better, they just did!😎

Presenting...

(drumroll)🥁🥁🥁

async/await 🎉

async/await are keywords and basically syntactic sugar on top of the Promises API that make promises even more awesome. If promises made async code feel synchronous, async/await make async code look synchronous. Let's dive straight in!

`async`

async is a keyword that you put in front of a function to make it an async function. So all of these are examples of async function declaration.

async function doSomething(){ ... }

var doSomethingElse = async function(){ ... }

var doSomethingMore = async () => { ... }

An async function is guaranteed to always return a promise. Even if we return a non-promise value from inside it, it will return a fulfilled promise, fulfilled with that value. If an error occurs inside the async function, then the returned promise will be rejected with the error reason.

async function returnValue() {
    return 1;
}
returnValue()
  .then( console.log ); 
// 1

async function throwError() {
    throw "oh no!";
}
throwError()
  .catch( console.log ); 
// "oh no!"

async function returnPromise() {
    return Promise.resolve(2);
}
returnPromise()
  .then( console.log ); 
// 2

`await`

The await keyword is placed in front of a promise object and signals JS to suspend execution of any consecutive statement until the promise is settled. It can only be used inside an async function.

async function doSomething() {

    var promise =  new Promise( resolve => {
        setTimeout( () => resolve( 1 ), 1000 );
    });

    var fulfilledValue = await promise;

    console.log( fulfilledValue );

};
doSomething();

// 1

In the above example, when doSomething() is invoked, JS starts executing the statements inside it synchronously. The first statement executes synchronously meaning a new Promise is created and assigned to the variable promise. The next statement has an await keyword and when JS encouters this keyword, it pauses the execution of doSomething(). While the execution of doSomething() is paused, JS works on executing other stuff like updating the DOM or responding to user interactions. After 1 second, when promise is fulfilled with the value 1, JS again resumes execution of the doSomething() and assigns the fulfilled value 1 to fulfilledValue. It then executes the console.log() and logs this fulfilled value onto the console.

You cannot use the await keyword in top-level code or inside a function which is not async. It will lead to an error. It only works inside an async function. For example, if we remove the async keyword from the above function, it will lead to an error.

function doSomething() {

    var promise =  new Promise( resolve => {
        setTimeout( () => resolve( 1 ), 1000 );
    });

    var fulfilledValue = await promise;

    console.log( fulfilledValue );

};
doSomething();

// Uncaught SyntaxError: await is only valid in async functions and async generators

Error handling

What happens if the promise that is awaited rejects with an error? Well in that case the await keyword will forward the error.

async function doSomething() {

  var promise = new Promise((resolve, reject) => {
    setTimeout(() => reject("oh no!"), 1000);
  });

  await promise;

};
doSomething();

// Uncaught (in promise) oh no!

In order to handle such errors we can wrap our code inside the async function with a try-catch block.

async function doSomething() {

  try {

    var promise = new Promise( (resolve, reject) => {
      setTimeout(() => reject("oh no!"), 1000);
    });

    await promise;

  } catch (err) {

    console.log(err);

  }

};
doSomething();

// "oh no!"

Since the async function returns a promise, we can also attach a catch() on the returned promise.

async function doSomething() {

  var promise = new Promise((resolve, reject) => {
    setTimeout(() => reject("oh no!"), 1000);
  });

  await promise;

};
doSomething().catch(console.log);

// "oh no!"

Replace promises with async/await(Example #1)

Remember the below example from one of the previous articles in this series where we fetched information about a github repo using promises.

// fetch all repos
fetch("https://api.github.com/users/saurabh-misra/repos")
    .then( response => response.json() )
    // return the github URL of the 3rd repo in the list
    .then( repos => repos[2].url )
    // fetch details for this repo
    .then( repoUrl => fetch(repoUrl) )
    .then( response => response.json() )
    .then( repoInfo => {
        console.log("Name: ", repoInfo.name);
        console.log("Description: ", repoInfo.description);
    })
    .catch( error => console.log("Error: ", error) );

/*
Name:  pomodoro-timer
Description: A simple pomodoro timer web app 
that helps you focus on your work.
*/

Let's re-write this example using async-await.

async function getRepoInfo() {

  // fetch repos and parse JSON
  var repoUrl = "https://api.github.com/users/saurabh-misra/repos";
  var reposResponse = await fetch(repoUrl);
  var repos = await reposResponse.json();

  // fetch info on one of the repos
  var repoInfoResponse = await fetch(repos[2].url)
  var repoInfo = await repoInfoResponse.json();

  return repoInfo;

}

getRepoInfo()
  .then(repoInfo => {
    console.log("Name: ", repoInfo.name);
    console.log("Description: ", repoInfo.description);
  })
  .catch(console.log);


/*
Name:  pomodoro-timer
Description: A simple pomodoro timer web app 
that helps you focus on your work.
*/

You can see the code is even more readable now. But more than being readable, it's intuitive! It's natural because this is the way we are used to writing and reading code, right?

This is because our brains find it easier to read/write synchronous code because the code executes in the same sequence that we read/write it. With asynchronous code, this is a bit of a challenge because some code executes now whereas some other code executes later.

As I mentioned before, Promises make asynchronous code feel synchronous since we can interact with the promise object while the asynchronous operation is in progress. And async/await make the code look synchronous so that it's easier for our brains to read and understand.

The more we can understand and reason about the code, the lesser the probability of introducing bugs.

Replace promises with async-await(Example #2)

Let's consider the case study example involving payment transactions from the previous section.

// pseudo code

fetch( /*store cc details*/ )
  .then( () => fetch( /*verify response*/ ))
  .then( () => fetch( /*make first payment*/ ))
  .then( () => fetch( /*verify response*/ ))
  .then( () => fetch( /*make second payment*/ ))
  .then( () => fetch( /*verify response*/ ))
  .then( () => fetch( /*mark order as complete*/ ))
  .catch( () => {
    // handle errors
  })
  .finally( () => {
    // perform clean up
  });

Let's re-write this example using async-await.

// pseudo code

async function doPayment() {

  var storeCCDetailsresponse = await fetch("store cc details");
  await fetch("verify response");

  var firstPaymentResponse = await fetch("make first payment");
  await fetch("verify response");

  var secondPaymentResponse = await fetch("make second payment");
  await fetch("verify response");

  await fetch("mark order as complete");

};

doPayment()
  .catch(console.log);
.finally(() => {
  // perform clean-up code.
});

Again...much better, right!

async/await and Paralell Async Operations

An interesting scenario is when we want to execute two different async operations in parallel using async/await. Let's see how we can achieve this. I'm going to use a small helper like function called promisifyTimeout() to basically make setTimeout() return a promise and fulfill it when the timeout occurs.

function promisifyTimeout(interval) {
  return new Promise(resolve => {
    setTimeout(resolve, interval);
  });
}

async function startParallelTimers() {
  await promisifyTimeout(1000);
  console.log("1st timer done."); // executes after 1 second

  await promisifyTimeout(1000);
  console.log("2nd timer done."); // executes after 2 seconds

  await promisifyTimeout(1000);
  console.log("3rd timer done."); // executes after 3 seconds
}

startParallelTimers();

/*
1st timer done.
2nd timer done. 
3rd timer done.
*/

If you run the above example, you'll notice that the logs are printed to the console one after the other each a second apart. The timers represent async operations that are not dependent on each other so they can run paralelly but the way we have placed our await keywords makes them run sequentially instead i.e the second timer cannot start until the first is done.

Let's refactor our code and re-arrange our await keywords.

function promisifyTimeout( interval ) {
  return new Promise( resolve => {
    setTimeout(resolve, interval);
  });
}

async function startParallelTimers() {
  var firstTimeoutPromise = promisifyTimeout(1000);
  var secondTimeoutPromise = promisifyTimeout(1000);
  var thirdTimeoutPromise = promisifyTimeout(1000);

  await firstTimeoutPromise;
  console.log("1st timer done.");
  await secondTimeoutPromise;
  console.log("2nd timer done.");
  await thirdTimeoutPromise;
  console.log("3rd timer done.");
}

startParallelTimers();

/*
1st timer done.
2nd timer done. 
3rd timer done.
*/

In this example, the entire output appears together after 1 second. This is because we started the timers together but awaited them later. There was no need to wait for the previous timer to complete before starting the next timer. This is a good pattern we can use to run parallel async operations using await which is to initiate them without using await and get the promise objects for each of them and then await the promise objects later.

async/await and the Promise API

Since await works with any function that returns a promise, it plays well with any of the Promise API methods. Here is an example of how it can work with Promise.all()

function promisifyTimeout( fulfilledValue, interval ) {
  return new Promise( resolve => {
    setTimeout(() => resolve(fulfilledValue), interval);
  });
}

async function startParallelTimers() {
  var firstTimeoutPromise = promisifyTimeout(1, 1000);
  var secondTimeoutPromise = promisifyTimeout(2, 1000);
  var thirdTimeoutPromise = promisifyTimeout(3, 1000);

  var values = await Promise.all([ 
    firstTimeoutPromise, 
    secondTimeoutPromise, 
    thirdTimeoutPromise 
  ]);

  return values;
}

startParallelTimers().then(console.log);

/*
Array(3) [ 1, 2, 3 ]
*/

async/await and Thenables

Remember our discussion about thenables from our previous sections. await plays well with thenables also.

var thenable = {
  then: function(onFulfilled, onRejected) {
    setTimeout(() => onFulfilled(1), 1000);
  }
};

async function testAwaitWithThenable() {
  return await thenable;
}

testAwaitWithThenable().then(console.log);

// 1

async/await with class methods

We can also declare class methods as async and use await inside them.

function promisifyTimeout(fulfilledValue, interval) {
  return new Promise(resolve => {
    setTimeout(() => resolve(fulfilledValue), interval);
  });
}

class Person {
  async displayGreetingAfterTimeout() {
    return await promisifyTimeout("Hello👋", 1000);
  }
}

new Person()
  .displayGreetingAfterTimeout()
  .then(console.log);

// Hello👋

To Summarize...

async/await keywords are syntactic sugar over promises.
Functions defined with the async keyword always return a Promise.
await keyword is placed in front of a promise object and can be used to pause the execution of an async function until the promise settles.
Promises make async code feel synchronous, async/await make async code look synchronous.

Honestly, I always found it difficult to wrap my head around Promises and their usage which is why I decided to study them in detail. This series of articles is a written expression of how I pieced together what I learnt. I hope these articles helped you understand Promises as well and made you feel more comfortable and confident in using them in your projects. Keep on Rocking!🤘

Promises vs Callbacks

Saurabh Misra — Mon, 12 Jul 2021 13:30:22 +0000

In this section, we are going to look at the differences between async callbacks and promises. I am going to assume that by now you must have already used async callbacks or at least know how to use them. Now that we also know how to work with and use Promises, I think now is a great time to discuss why we need to use promises if we already had a way to handle asynchronous operations by using async callbacks.

For simpler, smaller apps where there are not many async operations involved, async callbacks might be a simpler alternative to promises. But for larger, more complex apps where you as a developer, need to manage multiple consecutive or parallel asynchronous operations, managing all of them using callbacks can get ugly in a lot of ways.

Nowadays a lot of the apps are fat-client apps meaning a lot of the business logic is handled on the client-side using JS so the probability that you'll have to deal with multiple async operations at some point in your app development is quite high.

Also, promises are a dedicated way to manage async operations. They are especially built for that purpose. That is not the case with callbacks because they are used generically in other non-async contexts also. What this means is that using a specific tool for the job at hand can prove to be more efficient than a generic tool.

Let's take a look at some of the shortcomings of async callbacks.

Callback problem #1: Callback hell

A single callback based AJAX call might look something like this.

// jQuery based pseudo-code
$.ajax({
    ...
    success: function(){
        // handle success    
    },
    error: function(){
        // handle error
    }
});

What happens if we need to make 2 AJAX calls one after the other. Consider the same example from the previous sections where we fetch some basic github repo information.

// jQuery AJAX call
$.ajax({
  url: "https://api.github.com/users/saurabh-misra/repos",
  success: function(repos) {
    // jQuery AJAX call
    $.ajax({
      url: repos[2].url,
      success: function(repoInfo) {
        console.log("Name: ", repoInfo.name);
        console.log("Description: ", repoInfo.description);
      },
      error: function(error) {
        console.error(error);
      }
    });

  },
  error: function() {
    console.error(error);
  }
});

/*
Name: pomodoro-timer
Description: A simple pomodoro timer web app 
that helps you focus on your work.
*/

Run in JSBin

Notice how the code gets indented towards the right because of the nested AJAX call. Imagine what this code would look like if several such consecutive AJAX calls were involved.

// jQuery based pseudo code
$.ajax({
    success: function(response){
        $.ajax({
            success: function(){
                $.ajax({
                    success: function(){                  
                        $.ajax({
                            success: function(){     
                                $.ajax({
                                    success: function(){
                                        // handle success    
                                    }
                                });    
                            }
                        });
                    }
                });
            }
        });
    }
});

This kind of indented code is called as callback hell or the pyramid of doom. It's not difficult to understand why these names are given to this kind of code structure. But the callback hell problem is not limited to indentation alone. This code is indeed hard to read but the problem with this kind of code is more subtle. Let's try to make this more readable by encapsulating each AJAX call in a function

// jQuery pseudo code

function doAJAXCallOne(){
    $.ajax({
        success: function(){
            // handle success    
        }
    });
}

function doAJAXCallTwo(){
    $.ajax({
        success: function(){
            doAJAXCallOne();       
        }
    });
}

function doAJAXCallThree(){
    $.ajax({
        success: function(){
            doAJAXCallTwo();       
        }
    });
}

function doAJAXCallFour(){
    $.ajax({
        success: function(){
            doAJAXCallThree();       
        }
    });
}

function doAJAXCallFive(){
    $.ajax({
        success: function(){
            doAJAXCallFour();       
        }
    });
}

There you have it! We have taken care of the indentation problem. This code uses the same callback mechanism but is much more readable.

So is the problem solved?

Far from it. The more subtle problem with this kind of code is not the indentation but the mental strain your brain needs to go through while navigating through this code for understanding how it works or debugging. It may not seem like much in the above example because it's pseudo-code without actual success/error handling code but an actual script with these many ajax calls and handlers will prove my point.

You might be thinking that such kinds of situations are rare but that is not the case, at least not nowadays. I have had the displeasure of trying to find my way through such heavily nested callback-based code to make some changes to it and it was not fun. After the second or the third level of nesting, I had to literally go back to remember where I was before I tried to proceed.

Imagine bouncing around from one callback to another with all that code while keeping in mind what part of the code will execute immediately whereas what will execute later i.e. the code inside the callbacks.

So the code is still hard to read and navigate through. The problem with hard to read code is that when we don't fully understand what it's doing and make changes to it, we open our doors to bugs.

A Case Study

As I mentioned I faced this problem of callback hell first-hand which is why I'm going to discuss it to make it clearer why callbacks could be a bad idea for multiple async operations and how promises can save the day. The project that I work on required integration with a payment gateway. This payment solutions provider exposed a set of APIs that developers could call to make a purchase.

I can't use the actual code here of course so here is a rough pseudo-code representation of what was actually happening.

// pseudo code

// Make ajax request to store CC info in client's payment gateway account
ajax({
  success: function() {
    // Make an ajax call to verify this response
    ajax({
      success: function() {
        // Make ajax request to process one part of the payment
        ajax({
          success: function() {
            // Make an ajax call to verify this response
            ajax({
              success: function() {
                // Make ajax request to process second part of the payment
                ajax({
                  success: function() {
                    // Make an ajax call to verify this response
                    ajax({
                      success: function() {
                        // Make ajax call to mark order as complete in our own API
                        ajax({
                          success: function() {
                            // handle final success
                          },
                          error: function() {
                            // handle errors
                          }
                        });
                      },
                      error: function() {
                        // handle errors
                      }
                    });
                  },
                  error: function() {
                    // handle errors
                  }
                });
              },
              error: function() {
                // handle errors
              }
            });
          },
          error: function() {
            // handle errors
          }
        });
      },
      error: function() {
        // handle errors
      }
    });
  },
  error: function() {
    // handle errors
  }
});

Lo and behold, callback hell in all its glory!

This is a highly simplified version of the code of course. My teammate however did a splendid job of making this more readable by encapsulating it into various functions.

// pseudo code

function handleErrors(){ ... };

function verifyResponse( fnMakeNextAJAXCall ){ 
    ajax({
        success: function(){
            fnMakeNextAJAXCall();
        },
        error: handleErrors
    });
}

function storeCCDetails(){
    ajax({
        success: function(){
            verifyResponse( processFirstPayment );
        },
        error: handleErrors
    });
}

function processFirstPayment(){
    ajax({
        success: function(){
            verifyResponse( processSecondPayment );
        },
        error: handleErrors
    });
}

function processSecondPayment(){
    ajax({
        success: function(){
            verifyResponse( markOrderAsComplete );
        },
        error: handleErrors
    });
}

function markOrderAsComplete(){
    ajax({
        success: function(){
            // handle success
        },
        error: handleErrors
    });
}

storeCCDetails();

Again, the indentation problem is definitely resolved and this is much more readable. But try navigating through the code. Start with the call to storeCCDetails() at the bottom. Do you find yourself bouncing around from one function to the other? Now imagine doing that when these functions have several hundreds of lines of code inside them.

There is not really anything more than this that one can do to make callback based code more manageable.

But let's see how promises can take this to the next level.

// pseudo code

fetch( /*store cc details*/ )
  .then( () => fetch( /*verify response*/ ))
  .then( () => fetch( /*make first payment*/ ))
  .then( () => fetch( /*verify response*/ ))
  .then( () => fetch( /*make second payment*/ ))
  .then( () => fetch( /*verify response*/ ))
  .then( () => fetch( /*mark order as complete*/ ))
  .catch( () => {
    // handle errors
  })
  .finally( () => {
    // perform clean up
  });

Whoa!!😱 I don't know about you but to me, this code seems like a breath of fresh air as compared to the previous two code samples. No more nesting! No more pyramids of doom! No more jumping around! We can understand the entire sequence of events with just a single glance.

A developer who sees this code for the first time will easily be able to grasp the sequence of events and predict the impact of any change that needs to be made. This will reduce the probability of any bugs being introduced.

Callback problem #2: Inversion of control

With callbacks, the entire control of the execution of our async code is in the hands of the function/service/code to which we pass the callback as an argument.

For instance, in the above examples, we are wrapping our async code in an anonymous function and passing it as the success() callback to jQuery's ajax function. Now jQuery is a pretty stable library but for example, you are using a different third-party library and you send a callback and this library has a bug and it ends up either not calling your success() callback function or maybe calling it more than once.

This is probably never going to happen but imagine if it does happen. If this library is used instead of jQuery in the above payment transaction example, it can cause skipped or duplicate payments and can lead to some really angry customers. Not to mention it would be a nightmare for you or your dev team in trying to debug what or why this is happening.

This is known as inversion of control since we are losing control of the execution of a certain part of our own program i.e. the asynchronous code inside the callback.

With Promises, you're in control...

With promises, the control remains within our app. If we choose a 3rd-party library that supports promises, it will return a promise and we will wrap our async code in a then() handler and attach it to this promise. Now the execution of this code depends upon the whether the promise gets fulfilled or rejected, and the promise object resides within our own app so no more surrendering control to another service.

Also, we already know that promises can be either fulfilled or rejected only once and so our async code inside the fulfilled and rejected handlers will always be executed only once no matter what. So we don't have to worry about the payment issues we discussed above.

If and When...

Callbacks are great for events like a click event, where we need to do something when the event happens. The event can happen multiple times and we need to execute the same code that many times. But async operations are different because we are not concerned with when the async operation succeeds or fails. We are more interested in if it succeeds or fails so that we can execute code accordingly.

This is the basic difference between Promises and Async Callbacks i.e. their approach towards managing asynchronous operations. Async Callbacks are more interested in when an async operation started, succeeded or failed. Promises are only interested in the status of the async operation i.e. if the operation is still in progress or if it has succeeded or if it has failed.

More Power

We have already discussed the methods and static functions that the Promise API exposes which offer more control over managing async operations. These are things that are either not possible with async callbacks or require relatively complex implementations to be made possible.

So not only do Promises solve problems with callbacks, they introduce loads of new features and techniques for writing more manageable asynchronous code.

To Summarize...

When multiple async operations are involved, async callbacks start posing problems such as callback hell and inversion of control that make it harder for us devs to read, debug and maintain code.

Promises are a specific solution for managing asynchronous operations and don't suffer from any of the problems related with async callbacks. Instead, they bring more power in the form of Promise API methods and several other features.

It might be a bit difficult to wrap your head around promises at first but the more you use them, the more second nature they'll become and will seem just as simple and straightforward as callbacks. Moreover, most of the recent and new online tutorials and courses, libraries and their documentations, QnA forums, etc. have all started using promises in some shape, fashion or form so the sooner you get used to them, the better.

If you thought promises made code more readable, wait till you check out async-await. That is the topic of discussion in the final article in this series. See you there!

Resolved Promises and Promise Fates

Saurabh Misra — Mon, 12 Jul 2021 13:18:53 +0000

In the previous section, we came across the various static methods in the Promise API and how they can be used to return already settled promises and also work with multiple promises and asynchronous operations.

But I also promised(pun intended) that I'll let out a little secret about promises that I had being holding off on till now. Let's get straight to it!

In all the previous sections, have you noticed something fishy about the usage of the word resolve? For example, consider Promise.resolve(), if it returns an already fulfilled promise, why isn't it named something like Promise.fulfill()? Similarly, remember the 1st argument of the executor function? Although we can name it anything we want, it's standard to use the name resolve() for it. But again why is it not named fulfill() since all it does is change the state of the promise to fulfilled. Where did this word resolve come from?

Promise Fates

We know that a promise can be in one of the 3 states, pending, fulfilled and rejected. But it also has certain fates associated with it. These fates are resolved and unresolved and this is how the word resolve comes into play. So what decides whether a promise is resolved or unresolved? Let's find out.

So far, we have mostly played around with a single promise representing a single asynchronous operation. The then() handlers attached to this promise only consumed the response from the original promise and returned values like objects, strings, numbers or undefined. The promise returned from then() was fulfilled based on these values returned by its handlers.

fetch("https://api.github.com/users/saurabh-misra/repos")
    // returns an object
    .then( response => response.json() )
    // returns a string
    .then( repos => repos[2].name )
    // returns undefined
    .then( console.log )
    .catch( reason => console.error( reason ) );

/*
pomodoro-timer
*/

In the above example, the first then() returns an object and the returned promise is fulfilled with this object. The second then() returns a string and the returned promise is fulfilled with this string.

But what happens if we return a promise from inside the then() handler instead of a simple string or a number? Does the returned promise get fulfilled with this promise?

Let's consider an example where we have to make two network requests. The second network request needs some inputs returned by the first network request so the second one needs to happen after the first one is finished.

// fetch all repos
fetch("https://api.github.com/users/saurabh-misra/repos")
    .then( response => response.json() )
    // return the github URL of the 3rd repo in the list
    .then( repos => repos[2].url )
    // fetch details for this repo
    .then( repoUrl => fetch(repoUrl) )
    .then( response => response.json() )
    .then( repoInfo => {
        console.log("Name: ", repoInfo.name);
        console.log("Description: ", repoInfo.description);
    })
    .catch( error => console.log("Error: ", error) );

/*
Name:  pomodoro-timer
Description: A simple pomodoro timer web app 
that helps you focus on your work.
*/

The above example is an extension of the previous one. Similar to the previous one, the first fetch() call returns a list of all github repos for the particular github user. But instead of displaying the repo name, we choose a specific repo from this list and make a second fetch() call using the repo url to extract detailed information about that repo like repo name and description.

Let's refactor this for our convenience so that we break the chain into two representing both the fetch() calls.

var reposUrl = "https://api.github.com/users/saurabh-misra/repos";
// fetch all repos
var promiseFetchRepos = fetch(reposUrl)
    .then( response => response.json() )
    // return the github URL of the 3rd repo in the list
    .then( repos => repos[2].url );

// fetch details for the 3rd repo
var promiseFetchDetails = promiseFetchRepos
    .then( repoUrl => {
        var promiseSecondFetch = fetch(repoUrl);
        return promiseSecondFetch;
    });

promiseFetchDetails
    .then( response => response.json() )
    .then( repoInfo => {
        console.log("Name: ", repoInfo.name);
        console.log("Description: ", repoInfo.description);
    })
    .catch( error => console.log("Error: ", error) );

/*
Name:  pomodoro-timer
Description: A simple pomodoro timer web app 
that helps you focus on your work.
*/

Look at line number 12. Do you notice something you haven't seen before? The fulfilled handler returns a promise object, promiseSecondfetch which is returned by the second fetch() call. How does this affect promiseFetchDetails? If a string or a number was returned, promiseFetchDetails would have been fulfilled with that value. But in this case does it get fulfilled with the value as promiseSecondfetch? Nope.

The answer is that promiseFetchDetails will follow promiseSecondfetch. But what does that mean?

It's like you and your buddy went to the ice-cream store and you have to chose between vanilla and chocolate. Your buddy is trying to chose while you feel lazy and decide you'll have whatever he is having. So basically you'll just follow your buddy. While he's still deciding, you'll wait. If he decides to go with chocolate, you'll have chocolate. If he decides to go with vanilla, you'll have vanilla.

In the same way, promiseFetchDetails will surrender its own ability to fulfil or reject itself and instead lock on to the state of promiseSecondfetch. If promiseSecondfetch is pending, promiseFetchDetails will be pending. If promiseSecondfetch gets fulfilled with some value, promiseFetchDetails will also get fulfilled with the same value. If promiseSecondfetch gets rejected with some reason, promiseFetchDetails will also get rejected with the same reason. This behaviour is what makes promiseFetchDetails a resolved promise.

Resolved Promise

A resolved promise is a promise that is either settled or is following another promise. In both cases, trying to resolve or reject the promise will have no effect on it.

We have already seen that settled promises cannot be further fulfilled or rejected so that means all settled promises are resolved.

Unresolved Promises

On other hand, if trying to resolve or reject a promise does have an effect on it, then its known as an unresolved promise. In all our previous examples, the promises that we created were in the pending state initially. We either fulfilled them with a value or rejected them with a reason and it changed their state which makes them unresolved.

State and Fate Transitions

Let's drive this concept home by tracking the state and fate transitions of promiseFetchDetails from the previous example. When promiseFetchDetails is initialized by the then() call, it is initially in the pending state. At this point, its fate is unresolved as a return/error from any one of the handlers of its own then() call can resolve or reject it.

But when the fulfilled handler of then() is invoked, it returns a promise i.e. promiseSecondfetch. At this point, promiseFetchDetails surrenders its ability to resolve or reject on its own and starts following promiseSecondfetch. So both, promiseFetchDetails and promiseSecondfetch are in the pending state but now promiseFetchDetails's fate has transitioned to become a resolved promise. When promiseSecondfetch gets fulfilled a little while later, promiseFetchDetails also gets fulfilled with the same value. It still remains a resolved promise but now in the fulfilled state.

Resolved Promises using `Promise.resolve()`

We can similarly pass a promise object to Promise.resolve() instead of a simple string or number or in general a non-promise value.

var promise1 = Promise.resolve( 1 );
var promise2 = Promise.resolve( promise1 );
console.log( promise2 );

// Promise { <state>: "fulfilled", <value>: 1 }

In the above example, the 2nd Promise.resolve() is passed a promise object, promise1, which is why promise2 begins following promise1 and gets fulfilled with the same value as promise1.

Resolved Promises in the executor function

We can also specify a promise object as an input while calling resolve() in the executor function instead of a non-promise value.

var promise1 = Promise.resolve( 1 );

var promise2 = new Promise( resolve => {
    // async operation goes here...

    resolve( promise1 );
});

promise2.then( console.log );

// 1

In the above example, the resolve() call is passed a promise object, promise1 which results in promise2 following promise1 and getting fulfilled with the same value as promise1.

It all makes sense now... 💡

So this is why we were using the term resolve instead of fulfill because fulfill is specific to non-promise values but resolve is more generic and encompasses both promise and non-promise values.

Promise Unwrapping

Another terminology that you might read or hear about quite often is promise unwrapping. Its basically just another way to explain the resolved promise situation. When a promise is following another promise, the promise being followed is unwrapped and its contents are analyzed, meaning its state and its fulfilled value or rejected reason. The first promise then "assimilates" these contents and makes them its own. So in the examples we have seen so far, the then() handlers, Promise.resolve() and resolve() can all unwrap a promise object.

The curious case of `Promise.reject()` 🤔

So how does promise unwrapping work in Promise.reject()? Answer is...it doesn't. Yes that's right, Promise.reject() cannot unwrap promises which means the promise returned by Promise.reject() can never follow another promise.

var promise1 = Promise.resolve( 1 );
var promise2 = Promise.reject( promise1 );
console.log( promise2 );
/*
Promise { 
    <state>: "rejected", 
    <reason>: Promise { 
        <state>: "fulfilled", 
        <value>: 1 
    }
}

Uncaught (in promise) Promise { <state>: "fulfilled", <value>: 1 }
*/

In the above example, Promise.reject() does not unwrap promise1. promise2 does not follow promise1 and does not get resolved or rejected with a value/reason of 1. Instead it rejects with the reason as the entire promise1 object.

This seems weird at first but if you think about it, it is actually expected. Promise.reject() represents a failure situation where an error should be thrown. If Promise.reject() could unwrap promise1 in the example above, promise2 would get fulfilled with the value 1 which would silence the error that Promise.reject() was trying to throw in the first place.

The same thing happens for the reject() call in the executor function.

var promise1 = Promise.resolve( 1 );

var promise2 = new Promise( (resolve, reject) => {

    // async operation goes here...

    reject( promise1 );

});

promise2
    .catch( reason => console.log("Rejection reason: ", reason) );

/*
Rejection reason:  
Promise { <state>: "fulfilled", <value>: 1 }
*/

Here also, the reject() function does not unwrap promise1. It instead uses it as the rejection reason which is what is logged later in the catch() handler.

Resolved Promise Chain

We have seen how one promise can follow another promise but this can go on further. Like the 2nd promise can follow a 3rd promise which will in turn follow a 4th promise and so on. It will be equivalent to the first promise following the last promise in this chain of resolved promises.

var promise1 = Promise.resolve( 1 );
var promise2 = Promise.resolve( promise1 );
var promise3 = Promise.resolve( promise2 );
var promise4 = Promise.resolve( promise3 );

console.log( promise4 );

// Promise { <state>: "fulfilled", <value>: 1 }

In the above example, promise4 is the first promise that follows the 2nd one i.e. promise3 and so on till promise1 which resolves to 1.

What would happen if there was a Promise.reject() call in their somewhere?

var promise1 = Promise.resolve( 1 );
var promise2 = Promise.resolve( promise1 );
var promise3 = Promise.reject( promise2 );
var promise4 = Promise.resolve( promise3 );
var promise5 = Promise.resolve( promise4 );

console.log( promise5 );

/*
Promise { 
    <state>: "rejected", 
    <reason>: Promise { <state>: "fulfilled", <value>: 1 } 
}

Uncaught (in promise) 
Promise { <state>: "fulfilled", <value>: 1 } 
*/

In the above example, promise2 follows promise1 and gets fulfilled with a value of 1. Promise.reject() will be unable to unwrap promise2. So promise3 will reject with the entire promise2 object as the error reason. promise4 will follow promise3 and promise5 will in turn follow promise4 and both will attain the rejected state with the same reason as promise3.

What about `catch()`?

We have seen what happens when then() handlers return a promise but we have not talked about the behaviour when this happens inside catch() and finally() handlers.

Remember that catch is just a then() function with undefined as the fulfilled handler. So its behaviour is pretty much the same as then() which we have already seen but let's consider an example anyway.

var promise1 = Promise.resolve( 1 );
Promise.reject( "oh no!" )
    .catch( reason => promise1 )
    .then( console.log );

// 1

In the above example, the returned promise from catch() follows promise1 and gets fulfilled with the value of 1. This value is then passed to then()'s fulfilled handler which logs it to the console.

What about `finally()`?

finally() behaves differently than then() and catch() in this case. In Part III of this series, we discussed that the finally() handler is meant to do cleanup and not really supposed to return anything meaningful. It does return a promise but that is simply for the purpose of forming a promise chain. So its returned promise already follows the original promise on which it was invoked. Returning anything from the finally() handler has no effect on this behaviour. Let's see this in action.

var promise1 = Promise.resolve( 1 );
Promise.resolve( 2 )
    .finally( reason => promise1 )
    .then( console.log );

// 2

In the above example, the finally() handler returns promise1 but that is ignored. The returned promise from finally() is already locked on to the returned promise of the second Promise.resolve() which is fulfilled with the value 2. So the returned promise from finally() also gets fulfilled with the value 2 and not 1.

To summarize, the functions that unwrap promises are

then() and catch() handlers
Promise.resolve()
resolve() in the executor function

BUT, they can also unwrap a promise-like object or a thenable.

Oh no, not another jargon!😵

Sorry about that but I swear this is the last one...in this section! 🤷‍♂️

Thenables

Before promises arrived natively in JS, there were(and still are) many separate independent promise implementations in the form of third-party libraries for example Q, RSVP, etc. Even jQuery has its own custom implementation that they call deferreds. The name and the implementation might differ from library to library but the intention is the same, making asynchronous code behave like synchronous code.

The Promise functionalities these libraries expose are not native JS promises. They expose their own promise api on their custom promise-like objects. We call such non-native promises as thenables IF they adhere to certain rules from the Promise/A+ specification. This adherence makes it easier for native and non-native promise implementations to play along nicely with each other.

For example, imagine you were using native JS promises in your application but now your native promise code needs to interact with some third-party library code that returns a custom promise implementation. You'd prefer to make this interaction as seamless as possible or in other words, for convenience, you'd just like to stay in native promise land even while handling the response from the third-party library code. This is where thenables can make things easier for you. The Promise specification has defined a minimum set of requirements that an object has to fulfill in order to be considered a thenable. It states that a thenable is any object or a function that defines a then() method.

So this could be considered a promise-like object or thenable

// customPromise defines a `then()` method,
// so that makes it a thenable.
var customPromise = {
    then: function( onFulfilled, onRejected ) {

        // a very simple 'then' method implementation.

        // promise spec requires onFulfilled to be called asynchronously.
        setTimeout( () => onFulfilled( 1 ), 1000);
    }
};

Some of this code might seem familiar. Keep in mind that this code is an implementation of a custom promise and not usage. That is why we have a definition for the then() method whereas so far we have been calling it on a promise object.

So this is a custom promise object that implements a then() method. Since it follows the rules laid out by the spec, it will work seamlessly with native JS promises.

Now let's use this custom Promise object or thenable. Consider this scenario:

var thenable = {
    then: function( onFulfilled, onRejected ) {
        setTimeout( () => onFulfilled( 1 ), 1000);
    }
};

Promise.resolve()
    .then( () => customPromise )
    .then( console.log );

// 1

When JS encounters this custom promise object on line 8 as the return value from the then() fulfilled handler, it checks whether this object can be unwrapped. Since this is a thenable and defines a then() method and follows the Promise specification, JS will be able to unwrap it.

JS will treat the custom then() method of the thenable as an executor function. Just like its native counterpart, JS will pass in 2 arguments(like resolve() and reject()) to this custom then() method and will wait for either of them to be called. This means that the thenable will take on the pending state initially. Since the onFulfilled() handler is called after 1 second, the thenable will be considered fulfilled with whatever value the handler returns, in this case, 1.

This is how JS is able to cast the thenable into a native promise and is able to unwrap it so that the returned promise from our then() handler is able to follow this thenable just like it would follow a native promise object. Line 9 will log the fulfilled value i.e "1" which confirms that the returned promise from the first then() has successfully been resolved with the thenable.

Let's confirm what happens if the onRejected handler of the custom then() function is invoked. You can probably guess by now that it will reject the returned promise with the reason returned from the handler and you'd be right.

var customPromise = {
    then: function( onFulfilled, onRejected ) {
        setTimeout( () => onRejected( "oh no!" ), 1000);
    }
};

Promise.resolve()
    .then( () => customPromise )
    .catch( console.log );

// oh no!

To Summarize...

Promises, along with having a state also have certain fates associated with them which are resolved and unresolved.
Settled Promises and promises that follow other promises are resolved. Promises in the pending state that are not following any other promise are unresolved.
The functions that can unwrap promises or thenables are then() and catch() handlers, Promise.resolve() and resolve() in the executor function.
Promise.reject() and reject() in the executor function cannot unwrap promises/thenables. Also finally() ignores any promise returned from within its handler.
Thenables are promise-like objects that follow Promise/A+ specs and work seamlessly with native Promise API.

In the next section in this series, we are going to compare Promises with Callbacks and get a better idea of why and when we should use one over the other. See you there!

Static Methods in the Promise API

Saurabh Misra — Mon, 12 Jul 2021 13:03:56 +0000

In the previous section, we saw the various instance methods available on a promise object namely then(), catch() and finally() and how they can be chained together to form a promise chain.

Static Methods

In this section, we are going to explore the various static methods in the Promise API, how to use them and what benefits they bring to the table.

`Promise.resolve()`

The promise objects that we have created so far were always initially in the pending state and eventually became either fulfilled or rejected when we called resolve() or reject() inside the executor function. Promise.resolve() enables us to directly create a fulfilled promise object with the value that we pass to it.

// returns an already fulfilled promise
var promise = Promise.resolve( "fulfilled😇" );
console.log( promise );

// Promise { <state>: "fulfilled", <value>: "fulfilled😇" }

In the above example, promise directly attains the fulfilled state without ever being in the pending state.

Promise.resolve() comes in very handy when we want to quickly create a promise object without going through the whole constructor and executor function business. Just pass the value to Promise.resolve() as an input and you get back a promise object.

`Promise.reject()`

Similar to Promise.resolve(), this function enables us to directly create a rejected promise object rejected with the reason that we pass to it.

// returns an already rejected promise
var promise = Promise.reject( "something went wrong🤦‍♂️" );
console.log( promise );

/*
Promise { 
  <state>: "rejected", 
  <reason>: "something went wrong🤦‍♂️" 
}

Uncaught (in promise) something went wrong🤦‍♂️
*/

In the above example, promise directly attains the rejected state without ever being in the pending state.

`Promise.all()`

This is a very handy function for when we need to execute some asynchronous code only after a bunch of promises are finished executing. So in this case, we are not just waiting for one promise to be settled, we are waiting for one or more promises to be settled.

This function takes in 1 or more promises as inputs in the form of an iterable object or an array.

Wait...what's an iterable object?🤔

We all know that we can loop over or iterate upon arrays and even strings. We couldn't loop over JS objects in the same way though. But with ES6, we now have an iterable protocol which says that if an object is constructed in a certain way, it can be iterated upon like an array. I'm not going to go into the full details of what iterables are in this article but you can learn more about them here.

Ok back to Promise.all(). For convenience, we'll just use an array of promises as an input to Promise.all().

Promise.all() returns a new promise. This returned promise object gets fulfilled when all of the input promises fulfill. It gets rejected if any of the input promises gets rejected. This is what makes Promise.all() suitable for managing multiple asynchronous operations that are dependent on each other.

var promise1 = new Promise( (resolve, reject) => {
    setTimeout(() => {
        resolve( 1 );
    }, 1000);    
});
var promise2 = new Promise( (resolve, reject) => {
    setTimeout(() => {
        resolve( 2 );
    }, 2000);    
});
var returnedPromise = Promise.all([ promise1, promise2 ]);

// log returnedPromise before any of the promises settle
console.log( "Initially: ", returnedPromise );

// log returnedPromise after promise1 has settled
promise1.then( value => {
  console.log( "After promise1 settles: ", returnedPromise );
});

// log returnedPromise after promise2 has settled.
promise2.then( value => {
  console.log( "After promise2 settles: ", returnedPromise );
});


/*
Initially: Promise { <state>: "pending" }
After promise1 settles: Promise { <state>: "pending" }
After promise2 settles: Promise {
  <state>: "fulfilled",
  <value>: [ 1, 2 ] 
}
*/

In the above example, promise1 gets fulfilled after 1 second with a value of "1". But returnedPromise from Promise.all() doesn't get fulfilled yet. It waits for promise2 in its input array to be settled as well. When promise2 also gets fulfilled after 2 seconds with a value of "2", that is when returnedPromise gets fulfilled. The value that returnedPromise gets fulfilled with, is an array of the individual values that the input promises got fulfilled with, which in this case is [ 1, 2 ].

Let's consider an example where one of the promises gets rejected.

var promise1 = new Promise( (resolve, reject) => {
    setTimeout(() => {
        resolve( 1 );
    }, 1000);    
});
var promise2 = new Promise( (resolve, reject) => {
    setTimeout(() => {
        reject( "something went wrong🤦‍♂️" );
    }, 2000);    
});
var promise3 = new Promise( (resolve, reject) => {
    setTimeout(() => {
        resolve( 3 );
    }, 3000);    
});

var returnedPromise = Promise.all([ promise1, promise2, promise3 ]);

// log returnedPromise before any of the promises settle.
console.log( "Initially: ", returnedPromise );

// log returnedPromise after promise1 has settled
promise1.then( value => {
  console.log( "After promise1 settles: ", returnedPromise );
});

// log returnedPromise after promise2 settles.
promise2.catch( value => {
  console.log( "After promise2 settles: ", returnedPromise );
});

// log returnedPromise after promise3 settles.
promise3.then( value => {
  console.log( "After promise3 settles: ", returnedPromise );
});

/*
Initially: Promise { <state>: "pending" }

After promise1 settles: Promise { <state>: "pending" }

After promise2 settles: Promise { 
  <state>: "rejected", 
  <reason>: "something went wrong🤦‍♂️" 
}
Uncaught (in promise) something went wrong🤦‍♂️

After promise3 settles: Promise { 
  <state>: "rejected", 
  <reason>: "something went wrong🤦‍♂️" 
}
*/

In the above example, promise1 gets fulfilled after 1 second. At this point, returnedPromise stays in the pending state as expected waiting for promise2 and promise3 to settle as well. But promise2 gets rejected. This causes returnedPromise to be rejected as well with the same reason with which promise2 rejected.

Also, Promise.all() doesn't wait for promise3 to settle. As soon as it encounters a rejection in one of its input promises, Promise.all() will reject its returned promise which is why in promise-land, we say that Promise.all() short-circuits when an input promise is rejected.

n interesting scenario with Promise.all() is passing an empty array as an input. In this case, Promise.all() returns an already fulfilled promise with a blank array as the value.

var returnedPromise = Promise.all( [] );
console.log( returnedPromise );

// Promise { <state>: "fulfilled", <value>: [] }

In the previous examples, the returned promise was in the pending state initially and was later( or asynchronously) settled. In the above example, returnedPromise is already fulfilled i.e. it's fulfilled synchronously. This is the only case when Promise.all() synchronously returns a settled promise otherwise the returned promise is always settled asynchronously.

`Promise.allSettled()`

This function is very similar to Promise.all() and it picks up where Promise.all() left off. Promise.allSettled() will actually wait for the completion of all asynchronous operations meaning it will return a promise that will be settled only when each and every input promise has settled. Even if there is a rejection in one of the input promises, the returned promise will still wait for the rest of the them to be settled before finally being settled itself. This is what makes Promise.allSettled() suitable for managing multiple asynchronous operations that are not dependent on each other.

Promise.allSettled() also takes an interable or an array as an input and returns a new promise.

var promise1 = new Promise( (resolve, reject) => {
    setTimeout(() => {
        resolve( 1 );
    }, 1000);    
});
var promise2 = new Promise( (resolve, reject) => {
    setTimeout(() => {
        reject( "something went wrong🤦‍♂️" );
    }, 2000);    
});
var promise3 = new Promise( (resolve, reject) => {
    setTimeout(() => {
        resolve( 3 );
    }, 3000);    
});

var returnedPromise = Promise.allSettled([ promise1, promise2, promise3 ]);

// log returnedPromise before any of the promises settle.
console.log( "Initially: ", returnedPromise );

// log returnedPromise after promise1 has settled
promise1.then( value => {
  console.log( "After promise1 settles: ", returnedPromise );
});

// log returnedPromise after promise2 settles.
promise2.catch( value => {
  console.log( "After promise2 settles: ", returnedPromise );
});

// log returnedPromise after promise3 settles.
promise3.then( value => {
  console.log( "After promise3 settles: ", returnedPromise );
});

/*

Initially: Promise { <state>: "pending" }

After promise1 settles: Promise { <state>: "pending" }

After promise2 settles: Promise { <state>: "pending" }

After promise3 settles: Promise { 
  <state>: "fulfilled", 
  <value>: [
    { "status": "fulfilled", "value": 1 },
    { "status": "rejected", "reason": "something went wrong🤦‍♂️" },
    { "status": "fulfilled", "value": 3 }
  ]
}

*/

In the above example, notice that returnedPromise did not reject when promise2 rejected. Instead it waited till promise3 had settled. After all three promises settled, returnedPromise got fulfilled. Also note that the value with which returnedPromise is fulfilled is different than in the case of Promise.all(). Here, the fulfilled value is not an array of simple values with which the input promises were fulfilled. It is instead an array of objects that represent the state of each of the input promises in the same order. If the input promise was fulfilled, the object contains status and value properties and if the input promise was rejected, it contains status and the rejection reason.

So in the case of Promise.allSettled(), the returned promise will always be fulfilled. Even if all the input promises get rejected, the returned promise will still get fulfilled with an array of objects representing each rejected promise.

If we pass an empty array as an input to Promise.allSettled(), the behavior is similar to Promise.all() i.e. it returns (synchronously) an already fulfilled promise with value as a blank array. In all other cases, the returned promise will be in the pending state initially and will be settled asynchronously.

`Promise.race()`

This function does exactly what its name suggests, it treats its input promises as if they are in a race and the promise that gets settled first, wins. The victory here is that Promise.race() will not wait for the other promises to be settled. As soon as the first input promise gets settled, the returned promise from Promise.race() will be either fulfilled with the same value or rejected with the same reason as the first settled input promise.

Promise.race() also takes an interable or an array as an input and returns a new promise.

var promise1 = Promise.resolve( 1 );
var promise2 = new Promise( (resolve, reject) => {
    setTimeout(() => {
        resolve( 2 );
    }, 1000);    
});

var returnedPromise = Promise.race([ promise1, promise2 ]);

// after promise1 gets settled 
promise1.then( value => {
  console.log( "After promise1 settles: ", returnedPromise );
});

/*
After promise1 settles:  
Promise { <state>: "fulfilled", <value>: 1 }
*/

In the above example, since promise1 is already resolved, Promise.race() does not wait for the completion of promise2 and returnedPromise gets fulfilled with the same value as promise1.

If we replace Promise.resolve() with Promise.reject() in the above example, then promise1 will get rejected but will still be the first input promise to settle. So returnedPromise will get rejected with the same value as promise1.

If we pass an empty array to Promise.race(), the returned promise will stay in the pending state forever since there is no input promise that'll settle first, and in turn settle the returned promise.

`Promise.any()`

Note: Promise.any() is in the PROPOSAL stage and still not fully supported by browsers and platforms so I am not going to go into a lot of detail about it and will update this article when its properly supported at some point in the future. But I have included this just so you know that something like this is in the works and should be available soon.

This function is similar to Promise.race(), the only difference being that while Promise.race() waits for the first input promise to be settled, Promise.any() waits for the first input promise to be fulfilled. Once an input promise is fulfilled, Promise.any() will not wait for other promises to fulfill.

The returned promise will be fulfilled with the same value as the first input promise that fulfilled. Unlike Promise.race(), Promise.any() will ignore any input promises that reject until the first input promise fulfills. If no input promises fulfill or if all promises reject, Promise.any() will throw an AggregateError( a subclass of Error) which will group together all individual errors.

Promise Combinators

Together, Promise.all(), Promise.allSettled() and Promise.race()(also Promise.any() whenever it becomes available in the future) are referred to as Promise Combinators because they combine multiple promises and flatten them into a single promise that these functions return.

Hmm...interesting🤔

One peculiar behavior with these Promise combinators is that they accept non-promise values in the input array or iterable. So we can actually have something like this:

...
Promise.all([ "foo", promise, 2 ]);
...

Don't get confused about how the rules we have learnt above apply to such mixed inputs. Let's first see how our Promise combinators behave when we pass an array with such mixed inputs.

var returnedPromise1 = Promise.all([ "foo", Promise.resolve(1), 2 ]);
returnedPromise1.then( console.log );
// [ "foo", 1, 2 ]

var returnedPromise2 = Promise.allSettled([ "foo", Promise.resolve(1), 2 ]);
returnedPromise2.then( console.log );
/*
[
    { "status": "fulfilled", "value": "foo" },
    { "status": "fulfilled", "value": 1 },
    { "status": "fulfilled", "value": 2 }
]
*/

var returnedPromise3 = Promise.race([ "foo", Promise.resolve(1), 2 ]);
returnedPromise3.then( console.log );
// "foo"

Looking at the output, it seems that the literal values in the input arrays are being treated as promise objects fulfilled with those values. That is actually right. If we replace the literal values with Promise.resolve(), the behaviour will remain the same.

var returnedPromise1 = Promise.all([ 
  Promise.resolve( "foo" ), 
  Promise.resolve( 1 ), 
  Promise.resolve( 2 ) 
]);
returnedPromise1.then( console.log );
// [ "foo", 1, 2 ]

var returnedPromise2 = Promise.allSettled([ 
  Promise.resolve( "foo" ), 
  Promise.resolve( 1 ), 
  Promise.resolve( 2 ) 
]);
returnedPromise2.then( console.log );
/*
[
    { "status": "fulfilled", "value": "foo" },
    { "status": "fulfilled", "value": 1 },
    { "status": "fulfilled", "value": 2 }
]
*/

var returnedPromise3 = Promise.race([ 
  Promise.resolve( "foo" ), 
  Promise.resolve( 1 ), 
  Promise.resolve( 2 ) 
]);
returnedPromise3.then( console.log );
// "foo"

So in the end, all values in the input arrays can be thought of as simply promises and the rules we have learnt in the sections above apply to them in the same way.

In the next section in this series, I am going to reveal a peculiar truth about promises that I intentionally chose to hide from you till now. I hope I have stirred your curiosity. See you there!

Promise Chaining with then(), catch() & finally()

Saurabh Misra — Mon, 12 Jul 2021 12:54:21 +0000

In the previous section, we have learnt how to create Promises using the Promise() constructor. We also saw the various states a promise can be in as well as how to make the promise transition from pending to either fulfilled or rejected states.

Consuming Promises

This article is going to focus on how to consume promises. As I mentioned in the previous article that for the most part, you'll need to consume promise objects returned by Web APIs or third-party APIs. When I say consume I mean you'll need to configure the promise so that your success scenario code runs when the promise goes from pending to fulfilled and your failure scenario code runs when it transitions from pending to rejected.

Based on the examples we have seen in the previous section, you can visualize the promise object as kind of like a wrapper around an asynchronous operation. This wrapper exposes several API methods that enable us to run success/failure scenario scripts, perform error handling, manage multiple asynchronous operations and much more.

We have instance methods called on a particular promise object as well as static methods invoked directly on the Promise class. We'll focus on the instance methods in this article and tackle static methods in the next one.

There are 3 instance methods available on a promise object, they are then(), catch() and finally(). Let's look at them one by one.

The `then()` method

The promise object has a method called then() that lets you associate handlers to execute code when the promise is fulfilled or rejected. It accepts two functions as arguments. The first one acts as the handler for the fulfilled state and the other one for the rejected state.

Let's look at an example with the fulfilled scenario handler first.

var promise = new Promise( (resolve, reject) => {

    setTimeout(() => {
        resolve( "I am now fulfilled😇" );
    }, 1000);

});

var handleFulfilled = value => { console.log( value ); };
promise.then( handleFulfilled );

// I am now fulfilled😇

In the above example, then() will hook the handleFulfilled() handler to the promise object so that it gets invoked if the promise is fulfilled. Not only that but the handleFulfilled() function will also receive the value the promise is fulfilled with(the value we pass to the resolve() call) as an input. After the 1 second timeout, the promise transitions to the fulfilled state and handleFulfilled() gets called and logs the value we passed to the resolve() function onto the console.

Let's look at the same example with the failure scenario handler added as well.

var promise = new Promise( (resolve, reject) => {

    setTimeout(() => {
        reject( "something went wrong🤦‍♂️" );
    }, 1000);

});

var handleFulfilled = value => { console.log( value ); };
var handleRejected = reason => { console.log( reason ); };
promise.then( handleFulfilled, handleRejected );

// something went wrong🤦‍♂️

The handleRejected() function works like an error handler and catches the error thrown by reject(). The error reason we called reject() with, is passed to the handler as an input. In this case, after the 1 second timeout, the promise gets rejected and our handler is invoked. It simply logs the reason to the console and suppresses the error.

The then() method returns a new promise object. When the original promise gets settled and either of the two handlers are invoked, the eventual state of this returned promise depends upon what happens inside the handleFulfilled() and handleRejected() handlers.

Just like resolve() and reject() were responsible for changing the state of the original promise, handleFulfilled() and handleRejected() will be responsible for changing the state of the promise returned by then().

If either of these handlers return a value, the returned promise will get fulfilled with that value. If they don't return anything, the returned promise will get fulfilled with undefined. If either of these handlers throw an error, the returned promise will get rejected.

var origPromise = new Promise( (resolve, reject) => {

    setTimeout(() => {
        resolve( "original promise is fulfilled😇" );
    }, 1000);

});

var handleFulfilled = value => { 
  console.log( value ); 
  return "returned promise is also fulfilled😇😇";
};
var returnedPromise = origPromise.then( handleFulfilled );

// log the returned promise in the console 
// before the async op has completed.
console.log( "Returned Promise before:", returnedPromise );

// log the returned promise in the console 
// after the async op has completed.
setTimeout(() => {
  console.log( "Returned Promise after:", returnedPromise );
}, 2000);

/*
OUTPUT
Returned Promise before: Promise { <state>: "pending" }

original promise is fulfilled😇

Returned Promise after: Promise { 
    <state>: "fulfilled", 
    <value>: "returned promise is also fulfilled😇😇" 
  }
*/

In the above example, the then() method returns a new promise i.e returnedPromise. It initially remains in the pending state. When origPromise resolves after the 1 second timeout, the handleFulfilled()handler is invoked which returns a string. Since it returns a value, returnedPromise gets fulfilled with this value or string. We have a second setTimeout() on line 21 to log returnedPromise after 2 seconds i.e well after the 1 second timeout and after both promises have resolved.

What if there is an error in the fulfilled handler?

If in the above example, instead of returning a value, if an error occurs inside the handleFulfilled() handler, returnedPromise will be rejected with the error reason returned from handleFulfilled(). If no reason is specified, it'll be rejected with undefined.

var origPromise = new Promise( (resolve, reject) => {

    setTimeout(() => {
        resolve( "original promise is fulfilled😇" );
    }, 1000);

});

var handleFulfilled = value => { 
    console.log( value ); 
    throw("Something went wrong🤦‍♂️"); 
};
var returnedPromise = origPromise.then( handleFulfilled );

// log the returned promise in the console 
// before the async op has completed.
console.log( "Returned Promise before:", returnedPromise );

// log the returned promise in the console 
// after the async op has completed.
setTimeout(() => {
  console.log( "Returned Promise after:", returnedPromise );
}, 2000);

/*
OUTPUT
Returned Promise before: Promise { <state>: "pending" }

original promise is fulfilled😇

Uncaught (in promise) Something went wrong🤦‍♂️
Returned Promise after: Promise { 
        <state>: "rejected",
        <reason>: "Something went wrong🤦‍♂️" 
    }
*/

The same behaviour applies to the handleRejected() handler. If it returns a value, then returnedPromise will be fulfilled with that value. If an error occurs, returnedPromise will be rejected with the error reason.

Hmm...interesting!🤔

An interesting scenario is when we don't specify any handlers with the then() call. Yes, that's right! Both the input arguments to then() are optional. If we skip them, the returned promise will just mimic the original promise.

var origPromise = new Promise( (resolve, reject) => {

    setTimeout(() => {
        resolve( "original promise is fulfilled😇" );
    }, 1000);

});

var returnedPromise = origPromise.then();

// log the returned promise in the console 
// before the async op has completed.
console.log( "Returned Promise before:", returnedPromise );

// log the returned promise in the console 
// after the async op has completed.
setTimeout(() => {
  console.log( "Returned Promise after:", returnedPromise );
}, 2000);

/*
OUTPUT

Returned Promise before: Promise { <state>: "pending" }

Returned Promise after: Promise { 
        <state>: "fulfilled", 
        <value>: "original promise is fulfilled😇" 
    }
*/

In the above example, we have not passed any handlers to the then() method. This is why when origPromise gets fulfilled with a value, returnedPromise gets fulfilled with the same value.

If origPromise gets rejected with a reason, returnedPromise will get rejected with the same reason.

Promise Chaining⛓

The fact that then() returns a new promise is a powerful tool in the promise arsenal. We can attach then() methods one after the other forming a chain of then() methods. Each then() method's handler is executed in the order in which it was attached in the chain. The value returned by a then() method's handler is passed on to the handleFulfilled handler of the next then() method. An error thrown by a then() method's handler is caught by the first subsequent then() method further down in the chain that has a rejected handler defined. If no rejected handler is defined by any of the subsequent then() methods, then an uncaught exception will be thrown.

var thingsToBuyPromise = new Promise( (resolve, reject) => {

    setTimeout(() => {
        resolve( "Cheese🧀" );
    }, 1000);

});

thingsToBuyPromise
    // 1st
    .then( value => {
        console.log( "1. " + value ); // 1. Cheese🧀
        return "Milk🥛"; 
    })
    // 2nd
    .then( value => {
        console.log( "2. " + value ); // 2. Milk🥛
        return ("Butter🧈"); 
    })
    // 3rd
    .then( value => {
        console.log( "3. " + value ); // 3. Butter🧈
        throw( "Wait! I'm lactose intolerant🤦‍♂️" ); 
    })
    // 4th: catches error thrown by any of the above `then()`s.
    .then( undefined, reason => {
        console.log( reason );
        throw( "Cancel that list and make a new one!" );
    })
    // 5th: catches errors thrown only by the above `then()`.
    .then( undefined, reason => { 
        console.log( reason );
        return "Fruits🍎"; 
    })
    // 6th
    .then( value => {
        console.log( "1. " + value ); // 1. Fruits🍎
        return "Veggies🥕";
    })
    // 7th
    .then( value => {
        console.log( "2. " + value ); // 2. Veggies🥕
        return "That's it...";
    });
/* 

OUTPUT:

1. Cheese🧀
2. Milk🥛
3. Butter🧈
Wait! I'm lactose intolerant🤦‍♂️
Cancel that list and make a new one!
1. Fruits🍎
2. Veggies🥕

*/

In the above example, the thingsToBuyPromise gets fulfilled with the value "Cheese". This value is passed to the 1st then()'s fulfilled handler. This handler returns another value "Milk" which fulfils the returned promise from this 1st then(). This invokes the fulfilled handler of the 2nd then() which receives the value "Milk" and returns another value "Butter". This fulfills the 2nd then()'s returned promise. This in turn invokes the fulfilled handler of the 3rd then() which unfortunately throws an error. This error is caught by the rejected handler of the 4th then(). This then() also throws an error which is caught by the 5th then(). By now, you can probably guess how things progress.

Go ahead and remove the 4th and the 5th then() from the chain and see what happens. SPOILER ALERT!! The error thrown by the 3rd then() will result in an uncaught exception since there will be no rejected handler in any of the subsequent then() methods to catch the error. The 6th and 7th then()'s handlers won't be executed at all because of the error.

If you are wondering why we have set the fulfilled handler of the 4th and 5th then() to undefined in the above example, then its simply because we are only interested in catching errors in that part of the chain. In fact, the Promise API exposes a catch() method which does exactly that. Let's check it out!

The `catch()` method

This method, as its name suggests is used for catching errors. It works just like a then() without a fulfilled handler: then(undefined, handleRejected){...} . In fact, this is exactly how catch() internally operates i.e it calls a then() with the 1st argument as undefined and a rejected handler function as the 2nd argument. This handler function is the only input that catch() accepts.

The syntax looks like this:

var promise = new Promise( (resolve, reject) => {

    setTimeout(() => {
        reject( "something went wrong🤦‍♂️" );
    }, 1000);

});

var handleRejected = reason => { console.log(reason); }
promise.catch( handleRejected );

/* 
OUTPUT:
something went wrong🤦‍♂️
*/

Just like then(), catch() also returns a promise object and so just like then(), it can also be chained. Let's modify our chaining example to include a catch().

var thingsToBuyPromise = new Promise( (resolve, reject) => {

    setTimeout(() => {
        resolve( "Cheese🧀" );
    }, 1000);

});

thingsToBuyPromise
    // 1st
    .then( value => {
        console.log( "1. " + value ); // 1. Cheese🧀
        return "Milk🥛"; 
    })
    // 2nd
    .then( value => {
        console.log( "2. " + value ); // 2. Milk🥛
        return ("Butter🧈"); 
    })
    // 3rd
    .then( value => {
        console.log( "3. " + value ); // 3. Butter🧈
        throw( "Wait! I'm lactose intolerant🤦‍♂️" ); 
    })
    // 4th: catches error thrown by any of the above `then()`s.
    .catch( reason => {
        console.log( reason );
        throw( "Cancel that list and make a new one!" );
    })
    // 5th: catches errors thrown only by the above `then()`.
    .catch( reason => { 
        console.log( reason );
        return "Fruits🍎"; 
    })
    // 6th
    .then( value => {
        console.log( "1. " + value ); // 1. Fruits🍎
        return "Veggies🥕";
    })
    // 7th
    .then( value => {
        console.log( "2. " + value ); // 2. Veggies🥕
        return "That's it...";
    });
/* 

OUTPUT:

1. Cheese🧀
2. Milk🥛
3. Butter🧈
Wait! I'm lactose intolerant🤦‍♂️
Cancel that list and make a new one!
1. Fruits🍎
2. Veggies🥕

*/

All we have done is replace the 4th and 5th then() from the previous example with a catch(). The rest is exactly the same. But it is definitely more convenient and looks much cleaner this way without having to specify undefined anywhere.

We can have any number and combination of then() and catch() methods one after the other, in the promise chain.

So far we have learnt that the catch() method can catch errors that are:

thrown as a result of calling reject() in the executor function and
thrown inside handlers of any preceding then() or catch() methods higher up in the promise chain.

It can also catch any errors thrown directly inside the executor function before calling the resolve() or reject() functions. Consider the following example. We throw an error before calling resolve(). This rejects the promise with the reason specified in the error thrown. Since the promise is rejected, catch()'s handler gets invoked as expected.

var promise = new Promise( (resolve, reject) => {

    throw( "something went wrong🤦‍♂️" );
    resolve();

});

promise.catch(
    reason => { console.log( reason ); }
);

/* OUTPUT

something went wrong🤦‍♂️

*/

In the above example, if we replace resolve() with reject(), then the same thing will happen. The promise will get rejected with the reason specified in the error thrown instead of the reason passed to the reject() function.

Hmm...interesting🤔

However, if we throw an error after calling resolve() or reject(), then the error is silenced.

var promise = new Promise( (resolve, reject) => {

    resolve( "fulfilled😇" );
    throw( "something went wrong🤦‍♂️" ); // silenced

});

promise.then(    
    value => { // will be executed
        console.log( value ); 
    }, 
    reason => { // won't be executed
        console.log( reason ); 
    } 
);

/* OUTPUT

fulfilled😇

*/

This happens because as we have seen, throwing an error means changing the state of the promise to rejected. But we have already called resolve() and the promise has been fulfilled. Once settled, the state of the promise cannot change which is why the error is silenced. The same thing will happen if we use reject() instead of resolve() in the above example. The promise will be rejected with the reason passed to reject() and the thrown error will be silenced.

As a general rule of thumb, if you need to create a Promise object using the constructor, make sure calling resolve() or reject() is the last thing you do inside the executor function.

U Can't `catch()` this

Now that we know what kind of errors catch() is able to catch, there is one scenario where catch() won't work. It won't be able to catch errors that occur in your asynchronous code. Consider the following example:

var promise = new Promise( (resolve, reject) => {

    setTimeout(() => {
        // this is async code. Any errors thrown here will not be caught.
        throw( "something went wrong🤦‍♂️" );
        resolve( "fulfilled😇" );
    }, 1000);

});

var handleRejected = reason => { console.log(reason); };
// the rejected handler never gets invoked.
promise.catch( handleRejected ); 

/*
Uncaught something went wrong🤦‍♂️
*/

In the above example, an error occurs in the setTimeout() callback before we can call resolve() and fulfill the promise. It is not directly inside the executor function as we have seen in the previous examples. You can say that the promise is not aware about this error which is why this error is not caught by our catch() handler function and results in an uncaught exception.

So to summarize, catch() will only catch errors that are:

thrown directly inside the executor function before calling the resolve() or reject() functions
thrown as a result of calling reject() on the original promise and
thrown inside handlers of any preceding then() or catch() higher up in the promise chain.

But it won't catch errors that are thrown inside your asynchronous code.

The `finally()` method

If we have a catch() method, we are bound to have a finally() method as well. The main purpose with this method is to execute cleanup code that should be run irrespective of whether the promise was fulfilled or rejected.

For example, if we submit a form through AJAX and show a spinning icon to indicate that the process is in progress, irrespective of whether the AJAX request returns a success or error response, as soon as their is a response, we need to hide the spinning icon. So the code to hide the icon will go into the finally() method's handler. We could get away with placing this code in both the handlers in a then() but that would lead to duplication which is not good coding practice.

The finally() method accepts a single function as an input. But unlike the handlers in then() and catch(), finally()'s input function does not accept any arguments. This is because this function will be invoked for both, fulfilled and rejected states and it won't have a way to determine whether the value it receives is a fulfilled value or rejection error reason.

var promise = new Promise( (resolve, reject) => {

    setTimeout(() => {
        resolve( "fulfilled😇" );
    }, 1000);

});

var handleFinally = () => { 
    console.log( "finally handler invoked" ); 
}
promise.finally( handleFinally );

/* 
finally handler invoked
*/

Just like then(), finally() also returns a promise object so it can also be chained. But there are some differences between then() and finally() in the way the returned promise is settled.

var origPromise = new Promise( (resolve, reject) => { 
    resolve( "fulfilled😇" ); 
});

var handleFinally = () => "fulfilled by finally";

var returnedPromise = origPromise.finally( handleFinally );

// run after 1 second so that returnedPromise gets settled.
setTimeout( () => { 
    console.log( returnedPromise ); 
}, 1000 );

/* 
Promise { 
    <state>: "fulfilled", 
    <value>: "fulfilled😇" 
}
*/

In the previous examples that used then(), the returned promise from then() got fulfilled with the value returned from its handlers. But in the above example, returnedPromise from finally() gets fulfilled with the same value as origPromise and not with the value that its handler function returned. This is because just like the finally() input function does not accept any inputs, finally() is not expected to return anything as well. The expectation is that it'll perform some basic cleanup and not have any affect in the flow of information through the promise chain. This is why any value we return in the finally handler will be ignored.

But no matter how basic, where there is code, there is probability of an exception and finally() is no exception(see what I did there😎). So if an error occurs inside the finally() handler function, then returnedPromise will get rejected with the error reason.

var origPromise = new Promise( (resolve, reject) => { 
    resolve( "fulfilled" ); 
});

var handleFinally = () => { throw( "something went wrong🤦‍♂️" ) };

var returnedPromise = origPromise.finally( handleFinally );

// execute after 1 second so that returnedPromise gets settled.
setTimeout( () => { 
    console.log( returnedPromise ); 
}, 1000 );

/*
Uncaught (in promise) something went wrong🤦‍♂️
Promise { 
    <state>: "rejected", 
    <reason>: "something went wrong🤦‍♂️" 
}
*/

Technically, we can have any combination of then(), catch() and finally(), but a typical promise chain looks like this...

...
...
.then( handleFulfilled1 )
.then( handleFulfilled2 )
.then( handleFulfilled3 )
.catch( handleRejected )
.finally( handleSettled )

So basically, we process the response from the async operation and pass the required input to the next then() handler in the promise chain. We perform our error handling using catch() towards the end of the promise chain and at the end, we perform our cleanup using finally(). Also, in practice, its recommended to use then() for handling fulfillment and catch() for rejection scenarios. This is why we have not included the rejection handlers in the above then() calls.

Finishing Touches

I would like to end this tutorial with a more real-life example than the ones above. We are going to use the fetch() Web API(that uses promises) for making a network request to fetch some data and then run it through a promise chain and see what that looks like.

fetch("https://api.github.com/users/saurabh-misra/repos")
    // parse the JSON response into a JS object
    .then( response => response.json() )
    // log the name of one of the repos
    .then( repos => { 
        console.log( "Repo name: ", repos[2].name ); 
    })
    .catch( reason => console.error( reason ) )
    .finally( () => console.log( "all done" ) );

/*
Repo Name: pomodoro-timer
all done
*/

The 1st then() parses the response into a JS object and the 2nd logs the name of a specific repo on to the console. We have catch() in place if anything goes wrong and a finally() to perform any cleanup if we need to.

You can see the convenience that a promise chain brings to the table where each link in the chain serves a specific purpose and passes down information to the next link in the chain.

In the next article in this series, we are going to explore more Promise API superpowers courtesy of its static methods and how to manage multiple asynchronous operations with them. I'm sure you'll love it so see you there!

Promise States and Syntax

Saurabh Misra — Mon, 12 Jul 2021 12:42:29 +0000

In the previous article in this series, we learnt that asynchronous operations are executed by the environment or outside JS. So using callbacks, JS and in turn our code has had no way to interact with these operations while they were in progress or even after they had finished executing. All we could do is wrap our success and failure code in callback handlers and pass them to these operations and leave it upto them to invoke these handlers as and when they complete.

What is a Promise?

A promise is a special kind of JS object which represents an asynchronous operation. It's like a placeholder object that you can use instead of the actual response from the asynchronous operation while it's in progress. The promise object will make the response available to you as soon as the asynchronous operation completes. You can even interact with the promise object after the asynchronous operation is complete which is something that wasn't possible before.

Since a promise object is just like a regular JS object available immediately in our code, we can write code and interact with it synchronously. Imagine that! With promises, we can interact with asynchronous operations...synchronously!

Promises basically give synchronous superpowers to asynchronous operations. 🦸‍♂️

Promise States

Since an asynchronous operation can be either in progress, successfull or failed, Promises can also be in 3 corresponding states:

pending - means the asynchronous operation is in progress.
fulfilled - means the asynchronous operation has completed successfully.
rejected - means the asynchronous operation has failed.

You'll also hear the term settled with Promises. A Promise is said to be settled if it is either in the fulfilled or rejected state but not in the pending state. This is not actually a state of the promise but just a term used for convenience to mean that the promise is not pending.

Creating a Promise

We can create Promises by using the Promise() constructor. This constructor takes in a single argument which is a function called the executor function. The executor function, in turn, accepts two functions as inputs. The standard convention is to name these two functions as resolve() and reject(), however, you can name them whatever you like.

var executor = ( resolve, reject ) => {};
var promise = new Promise( executor );
console.log( promise );

// Promise { <state>: 'pending' }

The above bare-bones Promise creation statement creates a promise object in the initial pending state.

Resolving a Promise

The executor function houses the code that initiates an asynchronous operation. If this operation completes successfully, we invoke resolve() which changes the promise state from pending to fulfilled.

var promise = new Promise( (resolve, reject) => {

    setTimeout(() => {
        resolve();
        console.log( promise );
    }, 1000);

});

// Promise { <state>: "fulfilled", <value>: undefined }

In the above example, we initiate an asynchronous operation using a setTimeout() inside the executor function. When the timeout completes, we call resolve() to instruct the promise that the timeout has completed successfully. This will change the status of the Promise from pending to fulfilled so when the console.log() prints the promise, you can see that the state of the promise is now fulfilled.

A promise is always fulfilled with a value. Since we have not provided a value, it's fulfilled with undefined. If we provide a value as an input argument to resolve(), the promise will be fulfilled with that value.

var promise = new Promise( (resolve, reject) => {

    setTimeout(() => {
        resolve( "I am now fulfilled😇" );
        console.log( promise );
    }, 1000);

});

// Promise { <state>: "fulfilled", <value>: "I am now fulfilled😇" }

Rejecting a Promise

If the asynchronous operation fails, we invoke reject() inside the executor function which changes the state from pending to rejected. Similar to resolve(), if you don't specify a reason for this error, it'll be set as undefined.

var promise = new Promise( (resolve, reject) => {

    setTimeout(() => {
        reject();
        console.log( promise );
    }, 1000);

});

// Promise { <state>: "rejected", <reason>: undefined }
// Uncaught (in promise) undefined

If you do specify a reason as an input argument to reject(), then the promise will be rejected with that reason.

var promise = new Promise( (resolve, reject) => {

    setTimeout(() => {
        reject( "something went wrong...💩" );
        console.log( promise );
    }, 1000);

});

// Promise { <state>: "rejected", <reason>: "something went wrong...💩" }
// Uncaught (in promise) something went wrong...💩

Note: You don't have to worry about defining resolve() and reject(). The Promise constructor takes care of that internally. You only need to call these functions inside the executor function when necessary. Think about it like this, the promise object knows what to do when an asynchrounous operation succeeds or fails, meaning it knows what to do when you call resolve() or reject(). But it doesn't know when that happens and how to interpret completion as either success or failure. So we tell it that by calling resolve() on success and reject() on failure.

State change is a one-way street

Once the promise goes from the pending state to either fulfilled or rejected, it stays there...like...for good. It cannot go back to pending. Neither can a fulfilled promise be rejected or vice versa. A fulfilled promise cannot be fulfilled again and a rejected promise cannot be rejected again. This ensures that our program will run asynchronous code for either the success scenario or the failure scenario, but never both. It also ensures that the program will execute either of them only once. These are guarantees that we don't have with callbacks since we pass them away as arguments and have no control over how they are invoked.

So we know how to create promises using the Promise() constructor and how promises transition from one state to another. But in actual web development, you'll find yourself consuming promises already created by Web APIs or third party libraries much more often than creating them using the Promise() constructor. The Promise() constructor is mostly used for promisifying or wrapping older APIs(like we have done with setTimeout() in the previous examples) so that they return promises.

The next section will introduce you to methods for promise consumption like then() and catch() and how we can chain promises together to give more structure to our asynchronous code. See you there!

Asynchronous Programming in JavaScript

Saurabh Misra — Mon, 12 Jul 2021 12:25:23 +0000

Up until a few years ago, the server did most of the heavy lifting when it came to handling business logic. The client-side didn't do a lot except respond to user interactions, change something in the DOM every now and then and make the occassional AJAX request to process a form submission.

But things have changed a lot during the past couple of years with the JavaScript's evolution into a first-class programming language. Today, web apps have diversified into Single Page Applications or SPAs(think GMail) and Progressive Web Apps or PWAs(think Twitter) that are heavily powered by JavaScript. JavaScript usage is not limited to just building native-app like fluid UIs in web apps but extends to building APIs, mobile apps and even desktop apps.

So how is a single-threaded language like JavaScript able to contend with other more powerful multi-threaded programming languages(like C# or Java) in such a multitude of software development scenarios? The answer lies in JavaScript's unique way of handling concurrency and asynchronicity. With its growing popularity, its crucial that JS developers understand the tools for handling asynchronicity. Let's find out more!

Note: These series of articles mainly revolve around client-side JavaScript that runs in the browser. The core concepts, for the most part, also apply as-is to server-side JavaScript using NodeJS.

Synchronous JavaScript

Synchronous execution of code basically means executing code sequentially one statement at a time. A statement cannot be executed unless the statement before it has finished executing. This is termed as the blocking nature of synchronous code because the current operation blocks the execution of the next operation.

var first = "I'll be executed first";

var second = "I'll be executed next";

console.log("I'll be executed last");

In the above example, each statement will be executed in sequence after the previous has finished executing.

JavaScript is single-threaded meaning that the JavaScript process runs a single thread, called the main thread where our code is executed synchronously.

While the execution of the statements in the previous example happens almost instantaneously, operations such as network requests and timeouts could end up taking an indeterminate amount of time. If such operations are handled synchronously, they would freeze the browser which would pause all rendering and user interactions.

Consider the following example with an alert simulating such a time-consuming operation.

// simulate a time-consuming operation.
alert("I'm going to freeze this browser!😈");

console.log("Yayy! The alert is gone.🎉");

In the above example, the alert behaves synchronously and blocks the execution of the statement after it and freezes the browser window/tab until you click OK.

This is why JavaScript executes time consuming operations asynchronously so that the browser can continue rendering and accepting user inputs.

Asynchronous JavaScript

Asynchronous execution of code basically means that a certain part of your code will be executed at a later point in time after an asynchronous operation completes. An asynchronous operation is something that takes an unknown amount of time for completion eg. network requests, timeouts, etc. It can also be an event which can occur at any point in the future for example, user interaction events like button clicks which will then kick off the execution of some code inside the click event handler. While the asynchronous operation is in progress, your program need not wait for it to complete and can continue to run and so, is not blocked.

Let's consider the previous example with the blocking alert() replaced with setTimeout().

// asynchronous
setTimeout( function onTimeout() {
  console.log("I'll run asynchronously so I won't freeze anything.😇");
}, 1000); 

console.log("Woo hoo!! No more freezing!🎉");

/*
Woo hoo!! No more freezing!🎉

I'll run asynchronously so I won't freeze anything.😇
*/

Since setTimeout() is asynchronous, the program is not blocked and JS proceeds ahead to execute the statements that come after it. After the 1 second timeout, the asynchronous code inside the callback onTimeout() callback is executed. If setTimeout() was not asynchronous, the program would pause and the browser would freeze for a whole second just like in the previous example that used alert().

But if JavaScript is single-threaded and is executing some other program while the 1 second timer is in progress, who is keeping track of the time for setTimeout()? That is the job of the environment in which JS runs. On the client-side that environment is your browser while on the server-side, its NodeJS.

Whenever JS encounters the start of an asynchronous operation like a timeout or a network request, it signals the environment, and the environment takes over the charge of handling it. When the asynchronous operation completes, the environment signals JS which in turn executes asynchronous code.

So in the previous example, when JS initiates the timeout, it hands over the responsibility of keeping track of the time to the browser. JS also supplies a callback function, onTimeout(), that contains our asynchronous code. In the meantime, JS will keep executing other code. After 1 second, the browser will tell JS, "Hey! the timeout has completed so you should invoke this callback you gave me.".

Let's consider the scenario when we make a network request. We'll use the traditional XMLHttpRequest for this.

// asynchronous
var xhr = new XMLHttpRequest();
xhr.addEventListener("load", function onLoad() {
  console.log("I'll run asynchronously so I won't block anything.😇");
});
xhr.open("GET", "https://api.github.com/users/saurabh-misra");
xhr.send();

console.log("Woo hoo!! No more freezing!🎉");

/*
Woo hoo!! No more freezing!🎉

I'll run asynchronously so I won't block anything.😇
*/

Similar to the setTimeout() scenario, JS will initialize the network request and hand things over to the browser. It will also tell the browser to call the onLoad() function once the request is complete. The browser will take care of sending the request and waiting for the response. In the meantime, JS will continue to execute the rest of the program and will print the text provided to console.log(). When the request completes, the browser will tell JS to execute onLoad().

On the same lines, when we add a click event listener to a DOM element say a button, the code inside the handler is executed...you guessed it, asynchronously! Which means at a later point in time whenever the user clicks on the configured DOM element.

var btn = document.getElementById( "btn" );

// asynchronous
btn.addEventListener( "click", function onButtonClick(){
  console.log( "I'll run asynchronously so I won't block anything.😇" );
});

console.log("Woo hoo!! No more freezing!🎉");

/*
Woo hoo!! No more freezing!🎉

I'll run asynchronously so I won't block anything.😇
*/

Run in JSBin

In the above example, the JS engine instructs the environment to let it know whenever a click event occurs on the configured button element and passes it the onButtonClick() handler. When the user clicks the button at some point in the future, the browser informs the JS engine about it and tells it to invoke the handler.

So is JavaScript synchronous, asynchronous or both?

JavaScript is synchronous, period! By itself, it has no clue how to behave asynchronously or how to delay the execution of a part of your code. But it teams up with the browser/environment to do all kinds of asynchronous stuff. Sweet eh!

Our job as developers is to gracefully manage the state of our application while dealing with these asynchronous operations. We have a couple of options to achieve this. The first is to use the traditional Asynchronous Callbacks and the second are the new and powerful Promises made even more irresistible by Async/Await.

Asynchronous Callbacks

Asynchronous callbacks are basically just functions that wrap asynchronous code and are passed as input arguments to other functions that initiate asynchronous operations. In our previous examples, onTimeout(), onLoad() and onButtonClick() are all examples of asynchronous callbacks. The idea is that these functions will be called back when the asynchronous operation completes.

But remember that not all callbacks are asynchronous callbacks.

const cars = ['BMW', 'Mercedes', 'Audi'];

// synchronous
cars.forEach(function displayCar(car, index){
  console.log( (index+1) + '. ' + car );
});

/*
1. BMW
2. Mercedes
3. Audi
*/

In this example, displayCar() is passed in as an argument to the forEach() function. But forEach() is synchronous and does not initiate an asynchronous operation. So the code inside displayCar() is executed synchronously. So even though displayCar() is a callback function, it is not an asynchronous callback function.

So while all asynchronous callbacks are callbacks, not all callbacks are asynchronous.🤯

Traditional callbacks are adequate for simpler scenarios where only a few asynchronous operations need to be managed. But they prove incompetent in the increasingly complex scenarios JavaScript is used in nowadays.

Promises🤘

Promises have been introduced for the sole purpose of empowering JavaScript and enabling JavaScript developers to make asynchronous operations more manageable. We are going to go into a lot more detail and discuss Promise syntax and the benefits they bring to the table as compared to callbacks in the following sections.

DEV Community: Saurabh Misra

Using CommonJS Modules in NodeJS with module.exports and require() | Cheatsheet

Default Export

Named Exports

ES6 Modules Cheatsheet | Quick Reference Guide

DEFAULT EXPORT & IMPORT

NAMED EXPORT & IMPORT

IMPORT ALL

RENAMING EXPORTS & IMPORTS

MIXED EXPORT & IMPORT

RE-EXPORT USING export from ...

Serve a static HTML page using NodeJS and ExpressJS

Introduction

Tutorial Project Setup

Serve the HTML page

3 ways to upload files using NodeJS and Axios

Introduction

Tutorial Project Setup

Approach 1: Binary Upload

Approach #2: Multipart Uploads

Approach #3: Base64 uploads

Summary

Common Table Expressions(CTE) in SQL Server

What is a Common Table Expression?

Creating and Using a CTE

A CTE should be used immediately

Multiple CTEs

Recursive CTEs

1. Anchor member ⚓

2. Recursive Member 🔃

3. Termination condition 🛑

How it all works?

MAXRECURSION query hint

Multiple anchor and recursive members

A realistic example

References and Further Reading

Async-Await

async/await 🎉

async

await

Error handling

Replace promises with async/await(Example #1)

Replace promises with async-await(Example #2)

async/await and Paralell Async Operations

async/await and the Promise API

async/await and Thenables

async/await with class methods

To Summarize...

Promises vs Callbacks

Callback problem #1: Callback hell

So is the problem solved?

A Case Study

Callback problem #2: Inversion of control

With Promises, you're in control...

If and When...

More Power

To Summarize...

Resolved Promises and Promise Fates

Promise Fates

Resolved Promise

Unresolved Promises

State and Fate Transitions

Resolved Promises using Promise.resolve()

Resolved Promises in the executor function

It all makes sense now... 💡

Promise Unwrapping

The curious case of Promise.reject() 🤔

Resolved Promise Chain

What about catch()?

What about finally()?

Thenables

To Summarize...

Static Methods in the Promise API

Static Methods

Promise.resolve()

Promise.reject()

Promise.all()

Wait...what's an iterable object?🤔

Promise.allSettled()

Promise.race()

RE-EXPORT USING `export from ...`

`MAXRECURSION` query hint

`async`

`await`

Resolved Promises using `Promise.resolve()`

The curious case of `Promise.reject()` 🤔

What about `catch()`?

What about `finally()`?

`Promise.resolve()`

`Promise.reject()`

`Promise.all()`

`Promise.allSettled()`

`Promise.race()`

`Promise.any()`

The `then()` method

The `catch()` method

U Can't `catch()` this

The `finally()` method