@typescript-eslint/eslint-plugin 7.2.1-alpha.1 → 7.2.1-alpha.3

package/docs/rules/{typedef.md → typedef.mdx}

@@ -2,6 +2,9 @@
 description: 'Require type annotations in certain places.'
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 > 🛑 This file is source code, not the primary documentation location! 🛑
 >
 > See **https://typescript-eslint.io/rules/typedef** for documentation.
@@ -25,7 +28,7 @@ class ContainsText {
 }
 ```
 
-> To enforce type definitions existing on call signatures, use [`explicit-function-return-type`](./explicit-function-return-type.md), or [`explicit-module-boundary-types`](./explicit-module-boundary-types.md).
+> To enforce type definitions existing on call signatures, use [`explicit-function-return-type`](./explicit-function-return-type.mdx), or [`explicit-module-boundary-types`](./explicit-module-boundary-types.mdx).
 
 :::caution
 
@@ -63,16 +66,16 @@ Whether to enforce type annotations on variables declared using array destructur
 
 Examples of code with `{ "arrayDestructuring": true }`:
 
-<!--tabs-->
-
-#### ❌ Incorrect
+<Tabs>
+<TabItem value="❌ Incorrect">
 
 ```ts option='{ "arrayDestructuring": true }'
 const [a] = [1];
 const [b, c] = [1, 2];
 ```
 
-#### ✅ Correct
+</TabItem>
+<TabItem value="✅ Correct">
 
 ```ts option='{ "arrayDestructuring": true }'
 const [a]: number[] = [1];
@@ -83,15 +86,17 @@ for (const [key, val] of new Map([['key', 1]])) {
 }
 ```
 
+</TabItem>
+</Tabs>
+
 ### `arrowParameter`
 
 Whether to enforce type annotations for parameters of arrow functions.
 
 Examples of code with `{ "arrowParameter": true }`:
 
-<!--tabs-->
-
-#### ❌ Incorrect
+<Tabs>
+<TabItem value="❌ Incorrect">
 
 ```ts option='{ "arrowParameter": true }'
 const logsSize = size => console.log(size);
@@ -103,7 +108,8 @@ const mapper = {
 };
 ```
 
-#### ✅ Correct
+</TabItem>
+<TabItem value="✅ Correct">
 
 ```ts option='{ "arrowParameter": true }'
 const logsSize = (size: number) => console.log(size);
@@ -115,15 +121,17 @@ const mapper = {
 };
 ```
 
+</TabItem>
+</Tabs>
+
 ### `memberVariableDeclaration`
 
 Whether to enforce type annotations on member variables of classes.
 
 Examples of code with `{ "memberVariableDeclaration": true }`:
 
-<!--tabs-->
-
-#### ❌ Incorrect
+<Tabs>
+<TabItem value="❌ Incorrect">
 
 ```ts option='{ "memberVariableDeclaration": true }'
 class ContainsText {
@@ -132,7 +140,8 @@ class ContainsText {
 }
 ```
 
-#### ✅ Correct
+</TabItem>
+<TabItem value="✅ Correct">
 
 ```ts option='{ "memberVariableDeclaration": true }'
 class ContainsText {
@@ -141,22 +150,25 @@ class ContainsText {
 }
 ```
 
+</TabItem>
+</Tabs>
+
 ### `objectDestructuring`
 
 Whether to enforce type annotations on variables declared using object destructuring.
 
 Examples of code with `{ "objectDestructuring": true }`:
 
-<!--tabs-->
-
-#### ❌ Incorrect
+<Tabs>
+<TabItem value="❌ Incorrect">
 
 ```ts option='{ "objectDestructuring": true }'
 const { length } = 'text';
 const [b, c] = Math.random() ? [1, 2] : [3, 4];
 ```
 
-#### ✅ Correct
+</TabItem>
+<TabItem value="✅ Correct">
 
 ```ts option='{ "objectDestructuring": true }'
 const { length }: { length: number } = 'text';
@@ -166,15 +178,17 @@ for (const { key, val } of [{ key: 'key', val: 1 }]) {
 }
 ```
 
+</TabItem>
+</Tabs>
+
 ### `parameter`
 
 Whether to enforce type annotations for parameters of functions and methods.
 
 Examples of code with `{ "parameter": true }`:
 
-<!--tabs-->
-
-#### ❌ Incorrect
+<Tabs>
+<TabItem value="❌ Incorrect">
 
 ```ts option='{ "parameter": true }'
 function logsSize(size): void {
@@ -202,7 +216,8 @@ class Logger {
 }
 ```
 
-#### ✅ Correct
+</TabItem>
+<TabItem value="✅ Correct">
 
 ```ts option='{ "parameter": true }'
 function logsSize(size: number): void {
@@ -230,15 +245,17 @@ class Logger {
 }
 ```
 
+</TabItem>
+</Tabs>
+
 ### `propertyDeclaration`
 
 Whether to enforce type annotations for properties of interfaces and types.
 
 Examples of code with `{ "propertyDeclaration": true }`:
 
-<!--tabs-->
-
-#### ❌ Incorrect
+<Tabs>
+<TabItem value="❌ Incorrect">
 
 ```ts option='{ "propertyDeclaration": true }'
 type Members = {
@@ -247,7 +264,8 @@ type Members = {
 };
 ```
 
-#### ✅ Correct
+</TabItem>
+<TabItem value="✅ Correct">
 
 ```ts option='{ "propertyDeclaration": true }'
 type Members = {
@@ -256,15 +274,17 @@ type Members = {
 };
 ```
 
+</TabItem>
+</Tabs>
+
 ### `variableDeclaration`
 
 Whether to enforce type annotations for variable declarations, excluding array and object destructuring.
 
 Examples of code with `{ "variableDeclaration": true }`:
 
-<!--tabs-->
-
-#### ❌ Incorrect
+<Tabs>
+<TabItem value="❌ Incorrect">
 
 ```ts option='{ "variableDeclaration": true }'
 const text = 'text';
@@ -272,7 +292,8 @@ let initialText = 'text';
 let delayedText;
 ```
 
-#### ✅ Correct
+</TabItem>
+<TabItem value="✅ Correct">
 
 ```ts option='{ "variableDeclaration": true }'
 const text: string = 'text';
@@ -280,21 +301,24 @@ let initialText: string = 'text';
 let delayedText: string;
 ```
 
+</TabItem>
+</Tabs>
+
 ### `variableDeclarationIgnoreFunction`
 
 Ignore variable declarations for non-arrow and arrow functions.
 
 Examples of code with `{ "variableDeclaration": true, "variableDeclarationIgnoreFunction": true }`:
 
-<!--tabs-->
-
-#### ❌ Incorrect
+<Tabs>
+<TabItem value="❌ Incorrect">
 
 ```ts option='{ "variableDeclaration": true, "variableDeclarationIgnoreFunction": true }'
 const text = 'text';
 ```
 
-#### ✅ Correct
+</TabItem>
+<TabItem value="✅ Correct">
 
 ```ts option='{ "variableDeclaration": true, "variableDeclarationIgnoreFunction": true }'
 const a = (): void => {};
@@ -308,6 +332,9 @@ class Foo {
 }
 ```
 
+</TabItem>
+</Tabs>
+
 ## When Not To Use It
 
 If you are using stricter TypeScript compiler options, particularly `--noImplicitAny` and/or `--strictPropertyInitialization`, you likely don't need this rule.

package/docs/rules/{unbound-method.md → unbound-method.mdx}

@@ -2,6 +2,9 @@
 description: 'Enforce unbound methods are called with their expected scope.'
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 > 🛑 This file is source code, not the primary documentation location! 🛑
 >
 > See **https://typescript-eslint.io/rules/unbound-method** for documentation.
@@ -13,14 +16,13 @@ Otherwise, passing class methods around as values can remove type safety by fail
 This rule reports when a class method is referenced in an unbound manner.
 
 :::note Tip
-If you're working with `jest`, you can use [`eslint-plugin-jest`'s version of this rule](https://github.com/jest-community/eslint-plugin-jest/blob/main/docs/rules/unbound-method.md) to lint your test files, which knows when it's ok to pass an unbound method to `expect` calls.
+If you're working with `jest`, you can use [`eslint-plugin-jest`'s version of this rule](https://github.com/jest-community/eslint-plugin-jest/blob/main/docs/rules/unbound-method.mdx) to lint your test files, which knows when it's ok to pass an unbound method to `expect` calls.
 :::
 
 ## Examples
 
-<!--tabs-->
-
-### ❌ Incorrect
+<Tabs>
+<TabItem value="❌ Incorrect">
 
 ```ts
 class MyClass {
@@ -47,7 +49,8 @@ const arith = {
 const { double } = arith;
 ```
 
-### ✅ Correct
+</TabItem>
+<TabItem value="✅ Correct">
 
 ```ts
 class MyClass {
@@ -77,6 +80,9 @@ const arith = {
 const { double } = arith;
 ```
 
+</TabItem>
+</Tabs>
+
 ## Options
 
 ### `ignoreStatic`
@@ -102,4 +108,4 @@ If your project dynamically changes `this` scopes around in a way TypeScript has
 One likely difficult pattern is if your code intentionally waits to bind methods after use, such as by passing a `scope: this` along with the method.
 You might consider using [ESLint disable comments](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1) for those specific situations instead of completely disabling this rule.
 
-If you're wanting to use `toBeCalled` and similar matches in `jest` tests, you can disable this rule for your test files in favor of [`eslint-plugin-jest`'s version of this rule](https://github.com/jest-community/eslint-plugin-jest/blob/main/docs/rules/unbound-method.md).
+If you're wanting to use `toBeCalled` and similar matches in `jest` tests, you can disable this rule for your test files in favor of [`eslint-plugin-jest`'s version of this rule](https://github.com/jest-community/eslint-plugin-jest/blob/main/docs/rules/unbound-method.mdx).

package/docs/rules/{unified-signatures.md → unified-signatures.mdx}

@@ -2,6 +2,9 @@
 description: 'Disallow two overloads that could be unified into one with a union or an optional/rest parameter.'
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 > 🛑 This file is source code, not the primary documentation location! 🛑
 >
 > See **https://typescript-eslint.io/rules/unified-signatures** for documentation.
@@ -14,9 +17,8 @@ This rule reports when function overload signatures can be replaced by a single
 
 ## Examples
 
-<!--tabs-->
-
-### ❌ Incorrect
+<Tabs>
+<TabItem value="❌ Incorrect">
 
 ```ts
 function x(x: number): void;
@@ -28,7 +30,8 @@ function y(): void;
 function y(...x: number[]): void;
 ```
 
-### ✅ Correct
+</TabItem>
+<TabItem value="✅ Correct">
 
 ```ts
 function x(x: number | string): void;
@@ -45,28 +48,34 @@ function f(...a: number[]): void;
 function f(...a: string[]): void;
 ```
 
+</TabItem>
+</Tabs>
+
 ## Options
 
 ### `ignoreDifferentlyNamedParameters`
 
 Examples of code for this rule with `ignoreDifferentlyNamedParameters`:
 
-<!--tabs-->
-
-### ❌ Incorrect
+<Tabs>
+<TabItem value="❌ Incorrect">
 
 ```ts option='{ "ignoreDifferentlyNamedParameters": true }'
 function f(a: number): void;
 function f(a: string): void;
 ```
 
-### ✅ Correct
+</TabItem>
+<TabItem value="✅ Correct">
 
 ```ts option='{ "ignoreDifferentlyNamedParameters": true }'
 function f(a: number): void;
 function f(b: string): void;
 ```
 
+</TabItem>
+</Tabs>
+
 ## When Not To Use It
 
 This is purely a stylistic rule to help with readability of function signature overloads.
@@ -74,4 +83,4 @@ You can turn it off if you don't want to consistently keep them next to each oth
 
 ## Related To
 
-- [`adjacent-overload-signatures`](./adjacent-overload-signatures.md)
+- [`adjacent-overload-signatures`](./adjacent-overload-signatures.mdx)

package/docs/rules/use-unknown-in-catch-callback-variable.mdx

@@ -0,0 +1,84 @@
+---
+description: 'Enforce typing arguments in `.catch()` callbacks as `unknown`.'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/use-unknown-in-catch-callback-variable** for documentation.
+
+This rule enforces that you always use the `unknown` type for the parameter of a `Promise.prototype.catch()` callback.
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+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);
+});
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+Promise.reject(new Error('I will reject!')).catch((err: unknown) => {
+  console.log(err);
+});
+```
+
+</TabItem>
+</Tabs>
+
+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](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-4.html#defaulting-to-the-unknown-type-in-catch-variables---useunknownincatchvariables) to treat the `catch` variable as `unknown` instead.
+
+```ts
+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()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch), is not affected by the `useUnknownInCatchVariables` compiler option, and its "`catch` variable" will always have the type `any`.
+
+```ts
+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.
+
+```ts
+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](https://github.com/uhyo/better-typescript-lib) sets this up globally for your project (see [the relevant lines in the better-TypeScript-lib source code](https://github.com/uhyo/better-typescript-lib/blob/c294e177d1cc2b1d1803febf8192a4c83a1fe028/lib/lib.es5.d.ts#L635) for details on how).
+
+For further reading on this, you may also want to look into
+[the discussion in the proposal for this rule](https://github.com/typescript-eslint/typescript-eslint/issues/7526#issuecomment-1690600813) and [this TypeScript issue on typing catch callback variables as unknown](https://github.com/microsoft/TypeScript/issues/45602).
+:::
+
+## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typescript-eslint/eslint-plugin",
-  "version": "7.2.1-alpha.1",
+  "version": "7.2.1-alpha.3",
   "description": "TypeScript plugin for ESLint",
   "files": [
     "dist",
@@ -28,7 +28,7 @@
     }
   },
   "engines": {
-    "node": "^16.0.0 || >=18.0.0"
+    "node": "^18.18.0 || >=20.0.0"
   },
   "repository": {
     "type": "git",
@@ -61,10 +61,10 @@
   },
   "dependencies": {
     "@eslint-community/regexpp": "^4.5.1",
-    "@typescript-eslint/scope-manager": "7.2.1-alpha.1",
-    "@typescript-eslint/type-utils": "7.2.1-alpha.1",
-    "@typescript-eslint/utils": "7.2.1-alpha.1",
-    "@typescript-eslint/visitor-keys": "7.2.1-alpha.1",
+    "@typescript-eslint/scope-manager": "7.2.1-alpha.3",
+    "@typescript-eslint/type-utils": "7.2.1-alpha.3",
+    "@typescript-eslint/utils": "7.2.1-alpha.3",
+    "@typescript-eslint/visitor-keys": "7.2.1-alpha.3",
     "debug": "^4.3.4",
     "graphemer": "^1.4.0",
     "ignore": "^5.2.4",
@@ -76,8 +76,8 @@
     "@types/debug": "*",
     "@types/marked": "*",
     "@types/natural-compare": "*",
-    "@typescript-eslint/rule-schema-to-typescript-types": "7.2.1-alpha.1",
-    "@typescript-eslint/rule-tester": "7.2.1-alpha.1",
+    "@typescript-eslint/rule-schema-to-typescript-types": "7.2.1-alpha.3",
+    "@typescript-eslint/rule-tester": "7.2.1-alpha.3",
     "ajv": "^6.12.6",
     "chalk": "^5.3.0",
     "cross-env": "^7.0.3",