Promises are objects that represent the eventual completion or failure of an asynchronous operation. They provide a way to handle asynchronous
operations in a more organized and manageable manner. To use await, you need to ensure that you are calling a function or an expression
that returns a promise.
The reason await should only be used on a promise is that it expects the operand to be a promise object. When you use
await, it waits for the promise to be resolved or rejected and then returns the resolved value or throws the rejection reason,
respectively. If the operand of await is not a promise, awaiting it is redundant and might not have been the developer’s intent.
If you try to use await on a non-promise value, such as a regular object or a primitive type, it will not pause the execution of the
function because there is no asynchronous behavior involved. Instead, await will convert the value to a resolved promise, and waits for
it.
const x = 42;
await x; // Noncompliant: x is a number, not a promise
You should only use await on promises because it is designed to handle asynchronous operations and works in conjunction with the
Promise API to provide a clean and intuitive way to write asynchronous code in JavaScript.
const x = Promise.resolve(42);
await x;
When calling a function that returns a promise as the last expression, you might forget to return it, especially if you refactored your code from a
single-expression arrow function.
function foo() {
Promise.resolve(42);
}
async function bar() {
await foo(); // Noncompliant
}
Make sure that you return the promise.
function foo() {
return Promise.resolve(42);
}
async function bar() {
await foo(); // Compliant
}
Exceptions
The rule does not raise issues if you are awaiting a function whose definition contains JSdoc with @returns or @return
tags. This is due to JSdoc often mistakenly declaring a returning type without mentioning that it is resolved by a promise. For example:
async function foo () {
await bar(); // Compliant
}
/**
* @return {number}
*/
async function bar () {
return 42;
}
