eslint/docs/rules/no-return-await.md

   1 # Disallows unnecessary `return await` (no-return-await)
   2
   3 Using `return await` inside an `async function` keeps the current function in the call stack until the Promise that is being awaited has resolved, at the cost of an extra microtask before resolving the outer Promise. `return await` can also be used in a try/catch statement to catch errors from another function that returns a Promise.
   4
   5 You can avoid the extra microtask by not awaiting the return value, with the trade off of the function no longer being a part of the stack trace if an error is thrown asynchronously from the Promise being returned. This can make debugging more difficult.
   6
   7 ## Rule Details
   8
   9 This rule aims to prevent a likely common performance hazard due to a lack of understanding of the semantics of `async function`.
  10
  11 Examples of **incorrect** code for this rule:
  12
  13 ```js
  14 /*eslint no-return-await: "error"*/
  15
  16 async function foo() {
  17     return await bar();
  18 }
  19 ```
  20
  21 Examples of **correct** code for this rule:
  22
  23 ```js
  24 /*eslint no-return-await: "error"*/
  25
  26 async function foo() {
  27     return bar();
  28 }
  29
  30 async function foo() {
  31     await bar();
  32     return;
  33 }
  34
  35 // This is essentially the same as `return await bar();`, but the rule checks only `await` in `return` statements
  36 async function foo() {
  37     const x = await bar();
  38     return x;
  39 }
  40
  41 // In this example the `await` is necessary to be able to catch errors thrown from `bar()`
  42 async function foo() {
  43     try {
  44         return await bar();
  45     } catch (error) {}
  46 }
  47 ```
  48
  49 ## When Not To Use It
  50
  51 There are a few reasons you might want to turn this rule off:
  52
  53 - If you want to use `await` to denote a value that is a thenable
  54 - If you do not want the performance benefit of avoiding `return await`
  55 - If you want the functions to show up in stack traces (useful for debugging purposes)
  56
  57 ## Further Reading
  58
  59 [`async function` on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function)
  60
  61 [`await vs return vs return await` by Jake Archibald](https://jakearchibald.com/2017/await-vs-return-vs-return-await/)