Skip to main content

prefer-promise-reject-errors

Require using Error objects as Promise rejection reasons.

✅

Extending "plugin:@typescript-eslint/recommended-type-checked" in an ESLint configuration enables this rule.

💭

This rule requires type information to run, which comes with performance tradeoffs.

🧱

This is an "extension" rule that replaces a core ESLint rule to work with TypeScript. See Rules > Extension Rules.

This rule extends the base prefer-promise-reject-errors rule from ESLint core. It uses type information to enforce that Promises are only rejected with Error objects.

Examples​

Promise.reject('error');

const err = new Error();
Promise.reject('an ' + err);

new Promise((resolve, reject) => reject('error'));

new Promise((resolve, reject) => {
  const err = new Error();
  reject('an ' + err);
});
Open in Playground

How to Use​

eslint.config.mjs
export default defineConfig({
  rules: {
    // Note: you must disable the base rule as it can report incorrect errors
    "prefer-promise-reject-errors": "off",
    "@typescript-eslint/prefer-promise-reject-errors": "error"
  }
});

Try this rule in the playground ↗

Options​

See eslint/prefer-promise-reject-errors's options.

This rule adds the following options:

interface Options {
  /**
   * Type specifiers that can be used as Promise rejection reasons.
   */
  allow?: (
    | {
        from: 'file';
        name: string[] | string;
        path?: string;
      }
    | {
        from: 'lib';
        name: string[] | string;
      }
    | {
        from: 'package';
        name: string[] | string;
        package: string;
      }
    | string
  )[];

  /**
   * Whether to always allow throwing values typed as `any`.
   */
  allowThrowingAny?: boolean;

  /**
   * Whether to always allow throwing values typed as `unknown`.
   */
  allowThrowingUnknown?: boolean;
}

const defaultOptions: Options = {
  allow: [],
  allowThrowingAny: false,
  allowThrowingUnknown: false,
};

allow​

Type specifiers that can be used as Promise rejection reasons. Default: [].

This option takes the shared TypeOrValueSpecifier format. It can be useful for rejecting with error types defined by libraries that do not extend Error.

Examples of code for this rule with:

{
  "allow": [{ "from": "file", "name": "CustomError" }],
}
class CustomError /* does NOT extend Error */ {
  // ...
}

Promise.reject(new CustomError());
Open in Playground

allowThrowingAny​

Whether to always allow throwing values typed as any. Default: false.

Examples of correct code with { allowThrowingAny: true }:

declare const value: any;

Promise.reject(value);
Open in Playground

allowThrowingUnknown​

Whether to always allow throwing values typed as unknown. Default: false.

Examples of correct code with { allowThrowingUnknown: true }:

declare const value: unknown;

Promise.reject(value);
Open in Playground

When Not To Use It​

Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting.

See Troubleshooting > Linting with Type Information > Performance if you experience performance degradations after enabling type checked rules.

Resources​

Taken with ❤️ from ESLint core.