Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Update require-await docs with exception (fixes #9540) #11063

Merged
merged 3 commits into from Nov 9, 2018
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
36 changes: 34 additions & 2 deletions 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

Expand Down Expand Up @@ -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

Expand Down