diff --git a/docs/rules/require-await.md b/docs/rules/require-await.md index 4f1e4441e08..2fb871cf139 100644 --- a/docs/rules/require-await.md +++ b/docs/rules/require-await.md @@ -1,6 +1,23 @@ # Disallow async functions which have no `await` expression (require-await) -Async functions which have no `await` expression may be the unintentional result of refactoring. +Asynchronous functions in JavaScript behave differently than other functions in two important ways: + +1. The return value is always a `Promise`. +2. You can use the `await` operator inside of them. + +The primary reason to use asynchronous functions is typically to use the `await` operator, such as this: + +```js +async function fetchData(processDataItem) { + const response = await fetch(DATA_URL); + const data = await response.json(); + + return data.map(processDataItem); +} +``` + +Asynchronous functions that don't use `await` might not need to be asynchronous functions and could be the unintentional result of refactoring. + ## Rule Details @@ -47,7 +64,22 @@ async function noop() {} ## When Not To Use It -If you don't want to notify async functions which have no `await` expression, then it's safe to disable this rule. +Asynchronous functions are designed to work with promises such that throwing an error will cause a promise's rejection handler (such as `catch()`) to be called. For example: + +```js +async function fail() { + throw new Error("Failure!"); +} + +fail().catch(error => { + console.log(error.message); +}); +``` + +In this case, the `fail()` function throws an error that is intended to be caught by the `catch()` handler assigned later. Converting the `fail()` function into a synchronous function would require the call to `fail()` to be refactored to use a `try-catch` statement instead of a promise. + +If you are throwing an error inside of an asynchronous function for this purpose, then you may want to disable this rule. + ## Related Rules