[pve-eslint.git] / eslint / docs / rules / prefer-promise-reject-errors.md

# require using Error objects as Promise rejection reasons (prefer-promise-reject-errors)

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.

## Rule Details

This rule aims to ensure that Promises are only rejected with `Error` objects.

## Options

This rule takes one optional object argument:

* `allowEmptyReject: true` (`false` by default) allows calls to `Promise.reject()` with no arguments.

Examples of **incorrect** code for this rule:

```js
/*eslint prefer-promise-reject-errors: "error"*/

Promise.reject("something bad happened");

Promise.reject(5);

Promise.reject();

new Promise(function(resolve, reject) {
  reject("something bad happened");
});

new Promise(function(resolve, reject) {
  reject();
});

```

Examples of **correct** code for this rule:

```js
/*eslint prefer-promise-reject-errors: "error"*/

Promise.reject(new Error("something bad happened"));

Promise.reject(new TypeError("something bad happened"));

new Promise(function(resolve, reject) {
  reject(new Error("something bad happened"));
});

var foo = getUnknownValue();
Promise.reject(foo);
```

Examples of **correct** code for this rule with the `allowEmptyReject: true` option:

```js
/*eslint prefer-promise-reject-errors: ["error", {"allowEmptyReject": true}]*/

Promise.reject();

new Promise(function(resolve, reject) {
  reject();
});
```

## Known Limitations

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.

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.

## When Not To Use It

If you're using custom non-error values as Promise rejection reasons, you can turn off this rule.

## Further Reading

* [`no-throw-literal`](https://eslint.org/docs/rules/no-throw-literal)
* [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)
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)