Skip to main content

use-unknown-in-catch-callback-variable

Enforce typing arguments in .catch() callbacks as unknown.

🔒

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

🔧

Some problems reported by this rule are automatically fixable by the --fix ESLint command line option.

💡

Some problems reported by this rule are manually fixable by editor suggestions.

💭

This rule requires type information to run.

This rule enforces that you always use the unknown type for the parameter of a Promise.prototype.catch() callback.

Promise.reject(new Error('I will reject!')).catch(err => {
  console.log(err);
});

Promise.reject(new Error('I will reject!')).catch((err: any) => {
  console.log(err);
});

Promise.reject(new Error('I will reject!')).catch((err: Error) => {
  console.log(err);
});
Open in Playground

The reason for this rule is to enable programmers to impose constraints on Promise error handling analogously to what TypeScript provides for ordinary exception handling.

For ordinary exceptions, TypeScript treats the catch variable as any by default. However, unknown would be a more accurate type, so TypeScript introduced the useUnknownInCatchVariables compiler option to treat the catch variable as unknown instead.

try {
  throw x;
} catch (err) {
  // err has type 'any' with useUnknownInCatchVariables: false
  // err has type 'unknown' with useUnknownInCatchVariables: true
}

The Promise analog of the try-catch block, Promise.prototype.catch(), is not affected by the useUnknownInCatchVariables compiler option, and its "catch variable" will always have the type any.

Promise.reject(x).catch(err => {
  // err has type 'any' regardless of `useUnknownInCatchVariables`
});

However, you can still provide an explicit type annotation, which lets you achieve the same effect as the useUnknownInCatchVariables option does for synchronous catch variables.

Promise.reject(x).catch((err: unknown) => {
  // err has type 'unknown'
});
info

There is actually a way to have the catch() callback variable use the unknown type without an explicit type annotation at the call sites, but it has the drawback that it involves overriding global type declarations. For example, the library better-TypeScript-lib sets this up globally for your project (see the relevant lines in the better-TypeScript-lib source code for details on how).

For further reading on this, you may also want to look into the discussion in the proposal for this rule and this TypeScript issue on typing catch callback variables as unknown.

.eslintrc.cjs
module.exports = {
  "rules": {
    "@typescript-eslint/use-unknown-in-catch-callback-variable": "error"
  }
};

Try this rule in the playground ↗

Options​

This rule is not configurable.

When Not To Use It​

If your codebase is not yet able to enable useUnknownInCatchVariables, it likely would be similarly difficult to enable this rule.

If you have modified the global type declarations in order to make catch() callbacks use the unknown type without an explicit type annotation, you do not need this rule.

Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. See Performance Troubleshooting if you experience performance degredations after enabling type checked rules.

Resources​