Dirk Harriman Banner Image


Notes Javascript - Asynchronous Functionality

Sub Menu Here



Asynchronous Functionality


The await operator is used to wait for a Promise and get its fulfillment value. It can only be used inside an async function or at the top level of a module.

await expression

expression is a Promise, a thenable object, or any value to wait for.


The fulfillment value of the promise or thenable object, or, if the expression is not thenable, the expression's own value.


Throws the rejection reason if the promise or thenable object is rejected.


await is usually used to unwrap promises by passing a Promise as the expression. Using await pauses the execution of its surrounding async function until the promise is settled (that is, fulfilled or rejected). When execution resumes, the value of the await expression becomes that of the fulfilled promise.

If the promise is rejected, the await expression throws the rejected value. The function containing the await expression will appear in the stack trace of the error. Otherwise, if the rejected promise is not awaited or is immediately returned, the caller function will not appear in the stack trace.

The expression is resolved in the same way as Promise.resolve(): it's always converted to a native Promise and then awaited. If the expression is a:

Even when the used promise is already fulfilled, the async function's execution still pauses until the next tick. In the meantime, the caller of the async function resumes execution. See example below.

Because await is only valid inside async functions and modules, which themselves are asynchronous and return promises, the await expression never blocks the main thread and only defers execution of code that actually depends on the result, i.e. anything after the await expression.


The async function declaration declares an async function where the await keyword is permitted within the function body. The async and await keywords enable asynchronous, promise-based behavior to be written in a cleaner style, avoiding the need to explicitly configure promise chains.
Async functions may also be defined as expressions.

function resolveAfter2Seconds() { return new Promise(resolve => { setTimeout(() => { resolve('resolved'); }, 2000); }); } async function asyncCall() { console.log('calling'); const result = await resolveAfter2Seconds(); console.log(result); // Expected output: "resolved" } asyncCall();
async function name(param0) { statements } async function name(param0, param1) { statements } async function name(param0, param1, /* ... ,*/ paramN) { statements }
name The function's name.
param The name of an argument to be passed to the function.
statements The statements comprising the body of the function. The await mechanism may be used.


A Promise which will be resolved with the value returned by the async function, or rejected with an exception thrown from, or uncaught within, the async function.


Async functions can contain zero or more await expressions. Await expressions make promise-returning functions behave as though they're synchronous by suspending execution until the returned promise is fulfilled or rejected. The resolved value of the promise is treated as the return value of the await expression. Use of async and await enables the use of ordinary try / catch blocks around asynchronous code.

Note: The await keyword is only valid inside async functions within regular JavaScript code. If you use it outside of an async function's body, you will get a SyntaxError.
await can be used on its own with JavaScript modules.

Note: The purpose of async/await is to simplify the syntax necessary to consume promise-based APIs. The behavior of async/await is similar to combining generators and promises.

Async functions always return a promise. If the return value of an async function is not explicitly a promise, it will be implicitly wrapped in a promise.

For example, consider the following code:

async function foo() { return 1; }

It is similar to:

function foo() { return Promise.resolve(1); }
Note: Even though the return value of an async function behaves as if it's wrapped in a Promise.resolve, they are not equivalent.
An async function will return a different reference, whereas Promise.resolve returns the same reference if the given value is a promise.
It can be a problem when you want to check the equality of a promise and a return value of an async function.
const p = new Promise((res, rej) => { res(1); }); async function asyncReturn() { return p; } function basicReturn() { return Promise.resolve(p); } console.log(p === basicReturn()); // true console.log(p === asyncReturn()); // false