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

   1 ---
   2 title: no-return-await
   3 rule_type: suggestion
   4 further_reading:
   5 - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function
   6 - https://jakearchibald.com/2017/await-vs-return-vs-return-await/
   7 ---
   8
   9
  10 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.
  11
  12 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.
  13
  14 ## Rule Details
  15
  16 This rule aims to prevent a likely common performance hazard due to a lack of understanding of the semantics of `async function`.
  17
  18 Examples of **incorrect** code for this rule:
  19
  20 ::: incorrect
  21
  22 ```js
  23 /*eslint no-return-await: "error"*/
  24
  25 async function foo() {
  26     return await bar();
  27 }
  28 ```
  29
  30 :::
  31
  32 Examples of **correct** code for this rule:
  33
  34 ::: correct
  35
  36 ```js
  37 /*eslint no-return-await: "error"*/
  38
  39 async function foo() {
  40     return bar();
  41 }
  42
  43 async function foo() {
  44     await bar();
  45     return;
  46 }
  47
  48 // This is essentially the same as `return await bar();`, but the rule checks only `await` in `return` statements
  49 async function foo() {
  50     const x = await bar();
  51     return x;
  52 }
  53
  54 // In this example the `await` is necessary to be able to catch errors thrown from `bar()`
  55 async function foo() {
  56     try {
  57         return await bar();
  58     } catch (error) {}
  59 }
  60 ```
  61
  62 :::
  63
  64 ## When Not To Use It
  65
  66 There are a few reasons you might want to turn this rule off:
  67
  68 * If you want to use `await` to denote a value that is a thenable
  69 * If you do not want the performance benefit of avoiding `return await`
  70 * If you want the functions to show up in stack traces (useful for debugging purposes)