A guide to async/await in TypeScript

Editor’s note: This article was last updated by Oyinkansola Awosan on 15 February 2024 to include information about error handling with try/catch blocks and higher-order functions, as well as to feature TypeScript’s Awaited type.

If you’re reading this blog, you probably have some familiarity with asynchronous programming in JavaScript, and you may be wondering how it works in TypeScript.

Asynchronous programming is a way of writing code that can carry out tasks independently of each other, not needing one task to be completed before another gets started. When you think of asynchronous programming, think of multitasking and effective time management.

Introduction to async/await in TypeScript

TypeScript is a superset of JavaScript, so async/await works the same, but with some extra goodies and type safety. TypeScript enables you to ensure type safety for the expected result and even check for type errors, which helps you detect bugs earlier in the development process.

async/await is essentially a syntactic sugar for promises, which is to say that the async/await keyword is a wrapper over promises. An async function always returns a promise. Even if you omit the Promise keyword, the compiler will wrap your function in an immediately resolved promise.

Here’s an example:

//Snippet 1
const myAsynFunction = async (url: string): Promise<T> => {
    const { data } = await fetch(url)
    return data
}

//Snippet 2
const immediatelyResolvedPromise = (url: string) => {
    const resultPromise = new Promise((resolve, reject) => {
        resolve(fetch(url))
    })
    return  resultPromise
}

Although they look different, the code snippets above are more or less equivalent.

async/await simply enables you to write the code more synchronously and unwraps the promise within the same line of code for you. This is powerful when you’re dealing with complex asynchronous patterns.

To get the most out of the async/await syntax, you’ll need a basic understanding of promises.

What is a promise in TypeScript?

In JavaScript, a “promise” refers to the expectation that something will happen at a particular time, enabling your app to use the result of that future event to perform certain other tasks.

To demonstrate what I mean, I’ll break down a real-world example and translate it into pseudocode, followed by the actual TypeScript code.

Let’s say I have a lawn to mow. I contact a mowing company that promises to mow my lawn in a couple of hours. In turn, I promise to pay them immediately afterward, provided the lawn is properly mowed.

Can you spot the pattern? The first obvious thing to note is that the second event relies entirely on the previous one. If the first event’s promise is fulfilled, the next event’s will be executed. The promise in that event is then either fulfilled, rejected, or remains pending.

Let’s look at this sequence step by step and then explore its code:

The promise syntax

Before we write out the full code, it makes sense to examine the syntax for a promise — specifically, an example of a promise that resolves into a string.

We declared a promise with the new + Promise keyword, which takes in the resolve and reject arguments. Now let’s write a promise for the flow chart above:

// I send a request to the company. This is synchronous
// company replies with a promise
const angelMowersPromise = new Promise<string>((resolve, reject) => {
    // a resolved promise after certain hours
    setTimeout(() => {
        resolve('We finished mowing the lawn')
    }, 100000) // resolves after 100,000ms
    reject("We couldn't mow the lawn")
})

const myPaymentPromise = new Promise<Record<string, number | string>>((resolve, reject) => {
    // a resolved promise with  an object of 1000 Euro payment
    // and a thank you message
    setTimeout(() => {
        resolve({
            amount: 1000,
            note: 'Thank You',
        })
    }, 100000)
    // reject with 0 Euro and an unstatisfatory note
    reject({
        amount: 0,
        note: 'Sorry Lawn was not properly Mowed',
    })
})

In the code above, we declared both the company’s promises and our promises. The company promise is either resolved after 100,000ms or rejected. A Promise is always in one of three states: resolved if there is no error, rejected if an error is encountered, or pending if the promise has been neither rejected nor fulfilled. In our case, it falls within the 100000ms period.

But how can we execute the task sequentially and synchronously? That’s where the then keyword comes in. Without it, the functions simply run in the order in which they resolve.

Sequential execution with .then

Now we can chain the promises, which allows them to run in sequence with .then. This functions like a normal human language — do this and then that and then that, and so on.

The code below will run the angelMowersPromise. If there is no error, it’ll run the myPaymentPromise. If there is an error in either of the two promises, it’ll be caught in the catch block:

angelMowersPromise
    .then(() => myPaymentPromise.then(res => console.log(res)))
    .catch(error => console.log(error))

Now let’s look at a more technical example. A common task in frontend programming is to make network requests and respond to the results accordingly.

Below is a request to fetch a list of employees from a remote server:

const api =  'http://dummy.restapiexample.com/api/v1/employees'
   fetch(api)
    .then(response => response.json())
    .then(employees => employees.forEach(employee => console.log(employee.id)) // logs all employee id
    .catch(error => console.log(error.message))) // logs any error from the promise

There may be times when you need numerous promises to execute in parallel or sequence. Constructs such as Promise.all or Promise.race are especially helpful in these scenarios.

For example, imagine that you need to fetch a list of 1,000 GitHub users, and then make an additional request with the ID to fetch avatars for each of them. You don’t necessarily want to wait for each user in the sequence; you just need all the fetched avatars. We’ll examine this in more detail later when we discuss Promise.all.

Now that you have a fundamental grasp of promises, let’s look at the async/await syntax.

Understanding async/await

The async/await syntax simplifies working with promises in JavaScript. It provides an easy interface to read and write promises in a way that makes them appear synchronous.

An async/await will always return a Promise. Even if you omit the Promise keyword, the compiler will wrap the function in an immediately resolved Promise. This enables you to treat the return value of an async function as a Promise, which is useful when you need to resolve numerous asynchronous functions.

As the name implies, async always goes hand in hand with await. That is, you can only await inside an async function. The async function informs the compiler that this is an asynchronous function.

If we convert the promises from above, the syntax looks like this:

const myAsync = async (): Promise<Record<string, number | string>> => {
    await angelMowersPromise
    const response = await myPaymentPromise
    return response
}

As you can immediately see, this looks more readable and appears synchronous. We told the compiler on line 3 to await the execution of angelMowersPromise before doing anything else. Then, we return the response from the myPaymentPromise.

You may have noticed that we omitted error handling. We could do this with the catch block after the .then in a promise. But what happens if we encounter an error? That leads us to try/catch.

Error handling with try/catch

We’ll refer to the employee fetching example to see the error handling in action, as it is likely to encounter an error over a network request.

Let’s say, for example, that the server is down, or perhaps we sent a malformed request. We need to pause execution to prevent our program from crashing. The syntax will look like this:

interface Employee {
    id: number
    employee_name: string
    employee_salary: number
    employee_age: number
    profile_image: string
}
const fetchEmployees = async (): Promise<Array<Employee> | string> => {
    const api = 'http://dummy.restapiexample.com/api/v1/employees'
    try {
        const response = await fetch(api)
        const { data } = await response.json()
        return data
    } catch (error) {
        if (error) {
            return error.message
        }
    }
}

We initiated the function as an async function. We expect the return value to be either an array of employees or a string of error messages. Therefore, the type of promise is Promise<Array<Employee> | string>.

Inside the try block are the expressions we expect the function to run if there are no errors. Meanwhile, the catch block captures any errors that arise. In that case, we’d just return the message property of the error object.

The beauty of this is that any error that first occurs within the try block is thrown and caught in the catch block. An uncaught exception can lead to hard-to-debug code or even break the entire program.

Error handling using higher-order functions

While traditional try/catch blocks are effective for catching errors at the local level, they can become repetitive and clutter the main business logic when used too frequently. This is where higher-order functions come into play.

A higher-order function is a function that takes one or more functions as arguments or returns a function. In the context of error handling, a higher-order function can wrap an asynchronous function (async function) and handle any errors it might throw, thereby abstracting the try/catch logic away from the core business logic.

The main idea behind using higher-order functions for error handling in async/await is to create a wrapper function that takes an async function as an argument along with any parameters that the async function might need. Inside this wrapper, we implement a try/catch block. This approach allows us to handle errors in a centralized manner, making the code cleaner and more maintainable.

Let’s refer to the employee fetching example:

interface Employee {
    id: number;
    employee_name: string;
    employee_salary: number;
    employee_age: number;
    profile_image: string;
}

// Async function to fetch employee data
async function fetchEmployees(apiUrl: string): Promise<Employee[]> {
    const response = await fetch(apiUrl);
    const data = await response.json();
    return data;
}

// Wrapped version of fetchEmployees using the higher-order function
const safeFetchEmployees = (url: string) => handleAsyncErrors(fetchEmployees, url);

// Example API URL
const api = 'http://dummy.restapiexample.com/api/v1/employees';

// Using the wrapped function to fetch employees
safeFetchEmployees(api)
    .then(data => {
        if (data) {
            console.log("Fetched employee data:", data);
        } else {
            console.log("Failed to fetch employee data.");
        }
    })
    .catch(err => {
        // This catch block might be redundant, depending on your error handling strategy within the higher-order function
        console.error("Error in safeFetchEmployees:", err);
    });

In this example, the safeFetchEmployees function uses the handleAsyncErrors higher-order function to wrap the original fetchEmployees function.

This setup automatically handles any errors that might occur during the API call, logging them and returning null to indicate an error state. The consumer of safeFetchEmployees can then check if the returned value is null to determine if the operation was successful or if an error occurred.

Concurrent execution with Promise.all

As mentioned earlier, there are times when we need promises to execute in parallel.

Let’s look at an example from our employee API. Say we first need to fetch all employees, then fetch their names, and then generate an email from the names. Obviously, we’ll need to execute the functions in a synchronous manner and also in parallel so that one doesn’t block the other.

In this case, we would make use of Promise.all. According to Mozilla, “Promise.all is typically used after having started multiple asynchronous tasks to run concurrently and having created promises for their results so that one can wait for all the tasks being finished.”

In pseudocode, we’d have something like this:

• Fetch all users => /employee
• Wait for all user data. Extract the id from each user. Fetch each user => /employee/{id}
• Generate an email for each user from their username

const baseApi = 'https://reqres.in/api/users?page=1'
const userApi = 'https://reqres.in/api/user'

const fetchAllEmployees = async (url: string): Promise<Employee[]> => {
    const response = await fetch(url)
    const { data } = await response.json()
    return data
}

const fetchEmployee = async (url: string, id: number): Promise<Record<string, string>> => {
    const response = await fetch(`${url}/${id}`)
    const { data } = await response.json()
    return data
}
const generateEmail = (name: string): string => {
    return `${name.split(' ').join('.')}@company.com`
}

const runAsyncFunctions = async () => {
    try {
        const employees = await fetchAllEmployees(baseApi)
        Promise.all(
            employees.map(async user => {
                const userName = await fetchEmployee(userApi, user.id)
                const emails = generateEmail(userName.name)
                return emails
            })
        )
    } catch (error) {
        console.log(error)
    }
}
runAsyncFunctions()

In the above code, fetchEmployees fetches all the employees from the baseApi. We await the response, convert it to JSON, and then return the converted data.

The most important concept to keep in mind is how we sequentially executed the code line by line inside the async function with the await keyword. We’d get an error if we tried to convert data to JSON that has not been fully awaited. The same concept applies to fetchEmployee, except that we’d only fetch a single employee. The more interesting part is the runAsyncFunctions, where we run all the async functions concurrently.

First, wrap all the methods within runAsyncFunctions inside a try/catch block. Next, await the result of fetching all the employees. We need the id of each employee to fetch their respective data, but what we ultimately need is information about the employees.

This is where we can call upon Promise.all to handle all the Promises concurrently. Each fetchEmployee Promise is executed concurrently for all the employees. The awaited data from the employees’ information is then used to generate an email for each employee with the generateEmail function.

In the case of an error, it propagates as usual, from the failed promise to Promise.all, and then becomes an exception we can catch inside the catch block.

The Awaited type

Awaited is a utility type that models operations like await in async functions. It unwraps the resolved value of a promise, discarding the promise itself, and works recursively, thereby removing any nested promise layers as well.

Awaited is the type of value that you expect to get after awaiting a promise. It helps your code understand that once you use await, you’re not dealing with a promise anymore, but with the actual data you wanted.

Here’s the basic syntax:

type MyPromise = Promise<string>;
type AwaitedType = Awaited<MyPromise>; // AwaitedType will be 'string'

The awaited type does not exactly model the .then method in promises, however, Awaited can be relevant when using .then in async functions. If you use await inside a .then callback, Awaited helps infer the type of the awaited value, avoiding the need for additional type annotations.

Awaited can help clarify the type of data and awaitedValue in async functions, even when using .then for promise chaining. However, it doesn’t replace the functionality of .then itself.

Key takeaways

async and await enable us to write asynchronous code in a way that looks and behaves like synchronous code. This makes the code much easier to read, write, and understand.

Here are some some key concepts to keep in mind as you’re working on your next asynchronous project in TypeScript:

• await only works inside an async function
• The function marked with the async keyword always returns a Promise
• If the return value inside async doesn’t return a Promise, it will be wrapped in an immediately resolved Promise
• Execution is paused when an await keyword is encountered until a Promise is completed
• await will either return a result from a fulfilled Promise or throw an exception from a rejected Promise