# require-rejects
Requires a (non-standard) `@rejects` tag be added for detectable `Promise`
rejections.
## Options
A single options object has the following properties.
### contexts
Set this to an array of strings representing the AST context
(or objects with optional `context` and `comment` properties) where you wish
the rule to be applied.
`context` defaults to `any` and `comment` defaults to no specific comment context.
Overrides the default contexts (`ArrowFunctionExpression`, `FunctionDeclaration`,
`FunctionExpression`).
### exemptedBy
Array of tags (e.g., `['type']`) whose presence on the
document block avoids the need for a `@rejects`. Defaults to an array
with `abstract`, `virtual`, and `type`. If you set this array, it will overwrite the default,
so be sure to add back those tags if you wish their presence to cause
exemption of the rule.
|||
|---|---|
|Context|everywhere|
|Tags|``|
|Recommended|false|
|Settings||
|Options|`contexts`, `exemptedBy`|
## Failing examples
The following patterns are considered problems:
````ts
/**
*
*/
async function quux () {
throw new Error('abc');
}
// Message: Promise-rejecting function requires `@rejects` tag
/**
*
*/
const quux = async () => {
throw new Error('abc');
};
// Message: Promise-rejecting function requires `@rejects` tag
/**
*
*/
const quux = async function () {
throw new Error('abc');
};
// Message: Promise-rejecting function requires `@rejects` tag
/**
*
*/
async function quux () {
try {
await sthAsync();
} catch (err) {
if (cond) {
throw err;
}
}
}
// Message: Promise-rejecting function requires `@rejects` tag
/**
*
*/
function quux () {
return new Promise((resolve, reject) => {
reject(new Error('abc'));
});
}
// Message: Promise-rejecting function requires `@rejects` tag
/**
*
*/
async function quux () {
if (cond) {
throw new Error('abc');
}
}
// Message: Promise-rejecting function requires `@rejects` tag
/**
*
*/
async function quux () {
function inner () {
if (cond) {
throw new Error('abc');
}
}
inner();
}
// Message: Promise-rejecting function requires `@rejects` tag
/**
*
*/
async function quux () {
return Promise.reject(new Error('abc'));
}
// Message: Promise-rejecting function requires `@rejects` tag
/**
*
*/
function quux () {
if (cond) {
return Promise.reject(new Error('abc'));
}
}
// Message: Promise-rejecting function requires `@rejects` tag
/**
*
*/
async function quux () {
for (let i = 0; i < 10; i++) {
if (i > 5) {
throw new Error('abc');
}
}
}
// Message: Promise-rejecting function requires `@rejects` tag
/**
*
*/
async function quux () {
while (cond) {
throw new Error('abc');
}
}
// Message: Promise-rejecting function requires `@rejects` tag
/**
*
*/
async function quux () {
switch (val) {
case 1:
throw new Error('abc');
case 2:
break;
}
}
// Message: Promise-rejecting function requires `@rejects` tag
/**
*
*/
async function quux () {
const arr = [1, 2, 3];
for (const item of arr) {
if (item > 2) {
throw new Error('abc');
}
}
}
// Message: Promise-rejecting function requires `@rejects` tag
/**
*
*/
async function quux () {
const obj = {a: 1, b: 2};
for (const key in obj) {
if (key === 'a') {
throw new Error('abc');
}
}
}
// Message: Promise-rejecting function requires `@rejects` tag
/**
*
*/
async function quux () {
do {
throw new Error('abc');
} while (cond);
}
// Message: Promise-rejecting function requires `@rejects` tag
/**
*
*/
async function quux () {
label: {
throw new Error('abc');
}
}
// Message: Promise-rejecting function requires `@rejects` tag
/**
*
*/
async function quux () {
try {
doSomething();
} finally {
throw new Error('cleanup failed');
}
}
// Message: Promise-rejecting function requires `@rejects` tag
````
## Passing examples
The following patterns are not considered problems:
````ts
/**
* @rejects {Error}
*/
async function quux () {
throw new Error('abc');
}
/**
* @abstract
*/
async function quux () {
throw new Error('abc');
}
/**
*
*/
function quux () {
return 42;
}
/**
*
*/
async function quux () {
return await sthAsync();
}
/**
*
*/
async function quux () {
if (cond) {
return;
}
}
/**
*
*/
async function quux () {
const obj = new SomeClass();
}
/**
*
*/
function quux () {
const p = new Promise(someVariable);
}
/**
*
*/
function quux () {
return new Promise(someVariable);
}
/**
*
*/
async function quux () {
someFunction();
}
/**
*
*/
async function quux () {
try {
doSomething();
} catch (err) {
console.error(err);
}
}
/**
*
*/
async function quux () {
try {
throw new Error('wholly caught');
} catch (err) {
console.error(err);
}
}
/**
*
*/
async function quux () {
if (cond) {
doSomething();
} else {
doOtherThing();
}
}
/**
* @callback MyCallback
*/
// "jsdoc/require-rejects": ["error"|"warn", {"contexts":["any"]}]
/**
*
*/
async function quux () {
throw new Error('abc');
}
// Settings: {"jsdoc":{"tagNamePreference":{"rejects":false}}}
/** @param bar Something. */
export function foo(bar: string): void {
throw new Error(`some error: ${bar}`);
}
````