eslint/docs/src/rules/require-await.md

   1 ---
   2 title: require-await
   3 rule_type: suggestion
   4 related_rules:
   5 - require-yield
   6 ---
   7
   8
   9 Asynchronous functions in JavaScript behave differently than other functions in two important ways:
  10
  11 1. The return value is always a `Promise`.
  12 2. You can use the `await` operator inside of them.
  13
  14 The primary reason to use asynchronous functions is typically to use the `await` operator, such as this:
  15
  16 ```js
  17 async function fetchData(processDataItem) {
  18     const response = await fetch(DATA_URL);
  19     const data = await response.json();
  20
  21     return data.map(processDataItem);
  22 }
  23 ```
  24
  25 Asynchronous functions that don't use `await` might not need to be asynchronous functions and could be the unintentional result of refactoring.
  26
  27 Note: this rule ignores async generator functions. This is because generators yield rather than return a value and async generators might yield all the values of another async generator without ever actually needing to use await.
  28
  29 ## Rule Details
  30
  31 This rule warns async functions which have no `await` expression.
  32
  33 Examples of **incorrect** code for this rule:
  34
  35 ::: incorrect
  36
  37 ```js
  38 /*eslint require-await: "error"*/
  39
  40 async function foo() {
  41     doSomething();
  42 }
  43
  44 bar(async () => {
  45     doSomething();
  46 });
  47 ```
  48
  49 :::
  50
  51 Examples of **correct** code for this rule:
  52
  53 ::: correct
  54
  55 ```js
  56 /*eslint require-await: "error"*/
  57
  58 async function foo() {
  59     await doSomething();
  60 }
  61
  62 bar(async () => {
  63     await doSomething();
  64 });
  65
  66 function foo() {
  67     doSomething();
  68 }
  69
  70 bar(() => {
  71     doSomething();
  72 });
  73
  74 // Allow empty functions.
  75 async function noop() {}
  76 ```
  77
  78 :::
  79
  80 ## When Not To Use It
  81
  82 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:
  83
  84 ```js
  85 async function fail() {
  86     throw new Error("Failure!");
  87 }
  88
  89 fail().catch(error => {
  90     console.log(error.message);
  91 });
  92 ```
  93
  94 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.
  95
  96 If you are throwing an error inside of an asynchronous function for this purpose, then you may want to disable this rule.