eslint/docs/rules/prefer-promise-reject-errors.md

   1 # require using Error objects as Promise rejection reasons (prefer-promise-reject-errors)
   2
   3 It is considered good practice to only pass instances of the built-in `Error` object to the `reject()` function for user-defined errors in Promises. `Error` objects automatically store a stack trace, which can be used to debug an error by determining where it came from. If a Promise is rejected with a non-`Error` value, it can be difficult to determine where the rejection occurred.
   4
   5 ## Rule Details
   6
   7 This rule aims to ensure that Promises are only rejected with `Error` objects.
   8
   9 ## Options
  10
  11 This rule takes one optional object argument:
  12
  13 * `allowEmptyReject: true` (`false` by default) allows calls to `Promise.reject()` with no arguments.
  14
  15 Examples of **incorrect** code for this rule:
  16
  17 ```js
  18 /*eslint prefer-promise-reject-errors: "error"*/
  19
  20 Promise.reject("something bad happened");
  21
  22 Promise.reject(5);
  23
  24 Promise.reject();
  25
  26 new Promise(function(resolve, reject) {
  27   reject("something bad happened");
  28 });
  29
  30 new Promise(function(resolve, reject) {
  31   reject();
  32 });
  33
  34 ```
  35
  36 Examples of **correct** code for this rule:
  37
  38 ```js
  39 /*eslint prefer-promise-reject-errors: "error"*/
  40
  41 Promise.reject(new Error("something bad happened"));
  42
  43 Promise.reject(new TypeError("something bad happened"));
  44
  45 new Promise(function(resolve, reject) {
  46   reject(new Error("something bad happened"));
  47 });
  48
  49 var foo = getUnknownValue();
  50 Promise.reject(foo);
  51 ```
  52
  53 Examples of **correct** code for this rule with the `allowEmptyReject: true` option:
  54
  55 ```js
  56 /*eslint prefer-promise-reject-errors: ["error", {"allowEmptyReject": true}]*/
  57
  58 Promise.reject();
  59
  60 new Promise(function(resolve, reject) {
  61   reject();
  62 });
  63 ```
  64
  65 ## Known Limitations
  66
  67 Due to the limits of static analysis, this rule cannot guarantee that you will only reject Promises with `Error` objects. While the rule will report cases where it can guarantee that the rejection reason is clearly not an `Error`, it will not report cases where there is uncertainty about whether a given reason is an `Error`. For more information on this caveat, see the [similar limitations](no-throw-literal.md#known-limitations) in the `no-throw-literal` rule.
  68
  69 To avoid conflicts between rules, this rule does not report non-error values used in `throw` statements in async functions, even though these lead to Promise rejections. To lint for these cases, use the [`no-throw-literal`](https://eslint.org/docs/rules/no-throw-literal) rule.
  70
  71 ## When Not To Use It
  72
  73 If you're using custom non-error values as Promise rejection reasons, you can turn off this rule.
  74
  75 ## Further Reading
  76
  77 * [`no-throw-literal`](https://eslint.org/docs/rules/no-throw-literal)
  78 * [Warning: a promise was rejected with a non-error](http://bluebirdjs.com/docs/warning-explanations.html#warning-a-promise-was-rejected-with-a-non-error)