]>
Commit | Line | Data |
---|---|---|
eb39fafa DC |
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 | ||
eb39fafa DC |
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) |