@typescript-eslint/eslint-plugin 7.0.0-alpha.0 → 7.0.0

package/docs/rules/prefer-promise-reject-errors.md

@@ -0,0 +1,50 @@
+---
+description: 'Require using Error objects as Promise rejection reasons.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/prefer-promise-reject-errors** for documentation.
+
+This rule extends the base [`eslint/prefer-promise-reject-errors`](https://eslint.org/docs/rules/prefer-promise-reject-errors) rule.
+It uses type information to enforce that `Promise`s are only rejected with `Error` objects.
+
+## Examples
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+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);
+});
+```
+
+### ✅ Correct
+
+```ts
+Promise.reject(new Error());
+
+class CustomError extends Error {
+  // ...
+}
+Promise.reject(new CustomError());
+
+new Promise((resolve, reject) => reject(new Error()));
+
+new Promise((resolve, reject) => {
+  class CustomError extends Error {
+    // ...
+  }
+  return reject(new CustomError());
+});
+```

package/docs/rules/prefer-readonly-parameter-types.md

@@ -57,7 +57,7 @@ interface Foo {
 interface Foo {
   new (arg: string[]): void;
 }
-const x = { foo(arg: string[]): void; };
+const x = { foo(arg: string[]): void {} };
 function foo(arg: string[]);
 type Foo = (arg: string[]) => void;
 interface Foo {
@@ -91,7 +91,7 @@ interface CustomFunction {
 }
 function custom2(arg: CustomFunction) {}
 
-function union(arg: readonly string[] | ReadonlyArray<number[]>) {}
+function union(arg: readonly string[] | ReadonlyArray<number>) {}
 
 function primitive1(arg: string) {}
 function primitive2(arg: number) {}
@@ -105,8 +105,11 @@ function primitive9(arg: string | number | undefined) {}
 
 function fnSig(arg: () => void) {}
 
-enum Foo { a, b }
-function enum(arg: Foo) {}
+enum Foo {
+  a,
+  b,
+}
+function enumArg(arg: Foo) {}
 
 function symb1(arg: symbol) {}
 const customSymbol = Symbol('a');
@@ -119,7 +122,7 @@ interface Foo {
 interface Foo {
   new (arg: readonly string[]): void;
 }
-const x = { foo(arg: readonly string[]): void; };
+const x = { foo(arg: readonly string[]): void {} };
 function foo(arg: readonly string[]);
 type Foo = (arg: readonly string[]) => void;
 interface Foo {
@@ -158,7 +161,7 @@ Examples of code for this rule with:
 
 #### ❌ Incorrect
 
-```ts
+```ts option='{"allow":["$",{"source":"file","name":"Foo"},{"source":"lib","name":"HTMLElement"},{"from":"package","name":"Bar","package":"bar-lib"}]}'
 interface ThisIsMutable {
   prop: string;
 }
@@ -172,12 +175,17 @@ interface WrapperWithOther {
   otherProp: string;
 }
 
-function fn1(arg: ThisIsMutable) {} // Incorrect because ThisIsMutable is not readonly
-function fn2(arg: Wrapper) {} // Incorrect because Wrapper.sub is not readonly
-function fn3(arg: WrapperWithOther) {} // Incorrect because WrapperWithOther.otherProp is not readonly and not in the allowlist
+// Incorrect because ThisIsMutable is not readonly
+function fn1(arg: ThisIsMutable) {}
+
+// Incorrect because Wrapper.sub is not readonly
+function fn2(arg: Wrapper) {}
+
+// Incorrect because WrapperWithOther.otherProp is not readonly and not in the allowlist
+function fn3(arg: WrapperWithOther) {}
 ```
 
-```ts
+```ts option='{"allow":["$",{"source":"file","name":"Foo"},{"source":"lib","name":"HTMLElement"},{"from":"package","name":"Bar","package":"bar-lib"}]}'
 import { Foo } from 'some-lib';
 import { Bar } from 'incorrect-lib';
 
@@ -185,14 +193,19 @@ interface HTMLElement {
   prop: string;
 }
 
-function fn1(arg: Foo) {} // Incorrect because Foo is not a local type
-function fn2(arg: HTMLElement) {} // Incorrect because HTMLElement is not from the default library
-function fn3(arg: Bar) {} // Incorrect because Bar is not from "bar-lib"
+// Incorrect because Foo is not a local type
+function fn1(arg: Foo) {}
+
+// Incorrect because HTMLElement is not from the default library
+function fn2(arg: HTMLElement) {}
+
+// Incorrect because Bar is not from "bar-lib"
+function fn3(arg: Bar) {}
 ```
 
 #### ✅ Correct
 
-```ts
+```ts option='{"allow":["$",{"source":"file","name":"Foo"},{"source":"lib","name":"HTMLElement"},{"from":"package","name":"Bar","package":"bar-lib"}]}'
 interface Foo {
   prop: string;
 }
@@ -202,26 +215,35 @@ interface Wrapper {
   readonly otherProp: string;
 }
 
-function fn1(arg: Foo) {} // Works because Foo is allowed
-function fn2(arg: Wrapper) {} // Works even when Foo is nested somewhere in the type, with other properties still being checked
+// Works because Foo is allowed
+function fn1(arg: Foo) {}
+
+// Works even when Foo is nested somewhere in the type, with other properties still being checked
+function fn2(arg: Wrapper) {}
 ```
 
-```ts
+```ts option='{"allow":["$",{"source":"file","name":"Foo"},{"source":"lib","name":"HTMLElement"},{"from":"package","name":"Bar","package":"bar-lib"}]}'
 import { Bar } from 'bar-lib';
 
 interface Foo {
   prop: string;
 }
 
-function fn1(arg: Foo) {} // Works because Foo is a local type
-function fn2(arg: HTMLElement) {} // Works because HTMLElement is from the default library
-function fn3(arg: Bar) {} // Works because Bar is from "bar-lib"
+// Works because Foo is a local type
+function fn1(arg: Foo) {}
+
+// Works because HTMLElement is from the default library
+function fn2(arg: HTMLElement) {}
+
+// Works because Bar is from "bar-lib"
+function fn3(arg: Bar) {}
 ```
 
-```ts
+```ts option='{"allow":["$",{"source":"file","name":"Foo"},{"source":"lib","name":"HTMLElement"},{"from":"package","name":"Bar","package":"bar-lib"}]}'
 import { Foo } from './foo';
 
-function fn(arg: Foo) {} // Works because Foo is still a local type - it has to be in the same package
+// Works because Foo is still a local type - it has to be in the same package
+function fn(arg: Foo) {}
 ```
 
 ### `checkParameterProperties`
@@ -235,7 +257,7 @@ Examples of code for this rule with `{checkParameterProperties: true}`:
 
 #### ❌ Incorrect
 
-```ts
+```ts option='{ "checkParameterProperties": true }'
 class Foo {
   constructor(private paramProp: string[]) {}
 }
@@ -243,7 +265,7 @@ class Foo {
 
 #### ✅ Correct
 
-```ts
+```ts option='{ "checkParameterProperties": true }'
 class Foo {
   constructor(private paramProp: readonly string[]) {}
 }
@@ -253,7 +275,7 @@ class Foo {
 
 Examples of **correct** code for this rule with `{checkParameterProperties: false}`:
 
-```ts
+```ts option='{ "checkParameterProperties": false }' showPlaygroundButton
 class Foo {
   constructor(
     private paramProp1: string[],
@@ -272,7 +294,7 @@ Examples of code for this rule with `{ignoreInferredTypes: true}`:
 
 #### ❌ Incorrect
 
-```ts
+```ts option='{ "ignoreInferredTypes": true }'
 import { acceptsCallback, CallbackOptions } from 'external-dependency';
 
 acceptsCallback((options: CallbackOptions) => {});
@@ -281,7 +303,7 @@ acceptsCallback((options: CallbackOptions) => {});
 <details>
 <summary>external-dependency.d.ts</summary>
 
-```ts
+```ts option='{ "ignoreInferredTypes": true }'
 export interface CallbackOptions {
   prop: string;
 }
@@ -295,7 +317,7 @@ export const acceptsCallback: AcceptsCallback;
 
 #### ✅ Correct
 
-```ts
+```ts option='{ "ignoreInferredTypes": true }'
 import { acceptsCallback } from 'external-dependency';
 
 acceptsCallback(options => {});
@@ -304,7 +326,7 @@ acceptsCallback(options => {});
 <details>
 <summary>external-dependency.d.ts</summary>
 
-```ts
+```ts option='{ "ignoreInferredTypes": true }'
 export interface CallbackOptions {
   prop: string;
 }
@@ -326,7 +348,7 @@ Examples of code for this rule with `{treatMethodsAsReadonly: false}`:
 
 #### ❌ Incorrect
 
-```ts
+```ts option='{ "treatMethodsAsReadonly": false }'
 type MyType = {
   readonly prop: string;
   method(): string; // note: this method is mutable
@@ -336,7 +358,7 @@ function foo(arg: MyType) {}
 
 #### ✅ Correct
 
-```ts
+```ts option='{ "treatMethodsAsReadonly": false }'
 type MyType = Readonly<{
   prop: string;
   method(): string;
@@ -354,10 +376,14 @@ function bar(arg: MyOtherType) {}
 
 Examples of **correct** code for this rule with `{treatMethodsAsReadonly: true}`:
 
-```ts
+```ts option='{ "treatMethodsAsReadonly": true }' showPlaygroundButton
 type MyType = {
   readonly prop: string;
   method(): string; // note: this method is mutable
 };
 function foo(arg: MyType) {}
 ```
+
+## When Not To Use It
+
+If your project does not attempt to enforce strong immutability guarantees of parameters, you can avoid this rule.

package/docs/rules/prefer-readonly.md

@@ -6,7 +6,7 @@ description: "Require private members to be marked as `readonly` if they're neve
 >
 > See **https://typescript-eslint.io/rules/prefer-readonly** for documentation.
 
-Member variables with the privacy `private` are never permitted to be modified outside of their declaring class.
+Private member variables (whether using the `private` modifier or private `#` fields) are never permitted to be modified outside of their declaring class.
 If that class never modifies their value, they may safely be marked as `readonly`.
 
 This rule reports on private members are marked as `readonly` if they're never modified outside of the constructor.
@@ -22,6 +22,7 @@ class Container {
   // These member variables could be marked as readonly
   private neverModifiedMember = true;
   private onlyModifiedInConstructor: number;
+  #neverModifiedPrivateField = 3;
 
   public constructor(
     onlyModifiedInConstructor: number,
@@ -49,6 +50,13 @@ class Container {
   public mutate() {
     this.modifiedLater = 'mutated';
   }
+
+  // This is modified later on by the class
+  #modifiedLaterPrivateField = 'unchanged';
+
+  public mutatePrivateField() {
+    this.#modifiedLaterPrivateField = 'mutated';
+  }
 }
 ```
 
@@ -60,7 +68,10 @@ You may pass `"onlyInlineLambdas": true` as a rule option within an object to re
 
 ```jsonc
 {
-  "@typescript-eslint/prefer-readonly": ["error", { "onlyInlineLambdas": true }]
+  "@typescript-eslint/prefer-readonly": [
+    "error",
+    { "onlyInlineLambdas": true },
+  ],
 }
 ```
 
@@ -70,7 +81,7 @@ Example of code for the `{ "onlyInlineLambdas": true }` options:
 
 #### ❌ Incorrect
 
-```ts
+```ts option='{ "onlyInlineLambdas": true }'
 class Container {
   private onClick = () => {
     /* ... */
@@ -80,8 +91,12 @@ class Container {
 
 #### ✅ Correct
 
-```ts
+```ts option='{ "onlyInlineLambdas": true }'
 class Container {
   private neverModifiedPrivate = 'unchanged';
 }
 ```
+
+## When Not To Use It
+
+If you aren't trying to enforce strong immutability guarantees, this rule may be too restrictive for your project.

package/docs/rules/prefer-reduce-type-parameter.md

@@ -55,4 +55,6 @@ It will suggest instead pass the asserted type to `Array#reduce` as a generic ty
 
 ## When Not To Use It
 
-If you don't want to use typechecking in your linting, you can't use this rule.
+This rule can sometimes be difficult to work around when creating objects using a `.reduce`.
+See [[prefer-reduce-type-parameter] unfixable reporting #3440](https://github.com/typescript-eslint/typescript-eslint/issues/3440) for more details.
+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.

package/docs/rules/prefer-string-starts-ends-with.md

@@ -54,4 +54,5 @@ foo.endsWith('bar');
 
 ## When Not To Use It
 
-If you don't mind that style, you can turn this rule off safely.
+If you don't mind which style of string checking is used, you can turn this rule off safely.
+However, keep in mind that inconsistent style can harm readability in a project.

package/docs/rules/prefer-ts-expect-error.md

@@ -63,6 +63,7 @@ const isOptionEnabled = (key: string): boolean => {
 ## When Not To Use It
 
 If you are compiling against multiple versions of TypeScript and using `@ts-ignore` to ignore version-specific type errors, this rule might get in your way.
+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.
 
 ## Further Reading
 

package/docs/rules/promise-function-async.md

@@ -57,3 +57,76 @@ async function functionReturnsUnionWithPromiseImplicitly(p: boolean) {
   return p ? 'value' : Promise.resolve('value');
 }
 ```
+
+## Options
+
+### `allowAny`
+
+Whether to ignore functions that return `any` and `unknown`.
+If you want additional safety, consider turning this option off, as it makes the rule less able to catch incorrect Promise behaviors.
+
+Examples of code with `{ "allowAny": false }`:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts option='{ "allowAny": false }'
+const returnsAny = () => ({}) as any;
+```
+
+#### ✅ Correct
+
+```ts option='{ "allowAny": false }'
+const returnsAny = async () => ({}) as any;
+```
+
+### `allowedPromiseNames`
+
+For projects that use constructs other than the global built-in `Promise` for asynchronous code.
+This option allows specifying string names of classes or interfaces that cause a function to be checked as well.
+
+Examples of code with `{ "allowedPromiseNames": ["Bluebird"] }`:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts option='{ "allowedPromiseNames": ["Bluebird"] }'
+import { Bluebird } from 'bluebird';
+
+const returnsBluebird = () => new Bluebird(() => {});
+```
+
+#### ✅ Correct
+
+```ts option='{ "allowedPromiseNames": ["Bluebird"] }'
+import { Bluebird } from 'bluebird';
+
+const returnsBluebird = async () => new Bluebird(() => {});
+```
+
+### `checkArrowFunctions`
+
+Whether to check arrow functions.
+`true` by default, but can be set to `false` to ignore them.
+
+### `checkFunctionDeclarations`
+
+Whether to check standalone function declarations.
+`true` by default, but can be set to `false` to ignore them.
+
+### `checkFunctionExpressions`
+
+Whether to check inline function expressions.
+`true` by default, but can be set to `false` to ignore them.
+
+### `checkMethodDeclarations`
+
+Whether to check methods on classes and object literals
+`true` by default, but can be set to `false` to ignore them.
+
+## When Not To Use It
+
+This rule can be difficult to enable on projects that use APIs which require functions to always be `async`.
+You might consider using [ESLint disable comments](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1) along with filing issues on your dependencies for those specific situations instead of completely disabling this rule.

package/docs/rules/quotes.md

@@ -6,7 +6,5 @@ description: 'Enforce the consistent use of either backticks, double, or single
 >
 > See **https://typescript-eslint.io/rules/quotes** for documentation.
 
-## Examples
-
 This rule extends the base [`eslint/quotes`](https://eslint.org/docs/rules/quotes) rule.
 It adds support for TypeScript features which allow quoted names, but not backtick quoted names.

package/docs/rules/require-array-sort-compare.md

@@ -1,12 +1,12 @@
 ---
-description: 'Require `Array#sort` calls to always provide a `compareFunction`.'
+description: 'Require `Array#sort` and `Array#toSorted` calls to always provide a `compareFunction`.'
 ---
 
 > 🛑 This file is source code, not the primary documentation location! 🛑
 >
 > See **https://typescript-eslint.io/rules/require-array-sort-compare** for documentation.
 
-When called without a compare function, `Array#sort()` converts all non-undefined array elements into strings and then compares said strings based off their UTF-16 code units [[ECMA specification](https://www.ecma-international.org/ecma-262/9.0/#sec-sortcompare)].
+When called without a compare function, `Array#sort()` and `Array#toSorted()` converts all non-undefined array elements into strings and then compares said strings based off their UTF-16 code units [[ECMA specification](https://www.ecma-international.org/ecma-262/9.0/#sec-sortcompare)].
 
 The result is that elements are sorted alphabetically, regardless of their type.
 For example, when sorting numbers, this results in a "10 before 2" order:
@@ -15,11 +15,11 @@ For example, when sorting numbers, this results in a "10 before 2" order:
 [1, 2, 3, 10, 20, 30].sort(); //→ [1, 10, 2, 20, 3, 30]
 ```
 
-This rule reports on any call to the `Array#sort()` method that doesn't provide a `compare` argument.
+This rule reports on any call to the sort methods that do not provide a `compare` argument.
 
 ## Examples
 
-This rule aims to ensure all calls of the native `Array#sort` method provide a `compareFunction`, while ignoring calls to user-defined `sort` methods.
+This rule aims to ensure all calls of the native sort methods provide a `compareFunction`, while ignoring calls to user-defined methods.
 
 <!--tabs-->
 
@@ -57,7 +57,7 @@ Examples of code for this rule with `{ ignoreStringArrays: true }`:
 
 #### ❌ Incorrect
 
-```ts
+```ts option='{ "ignoreStringArrays": true }'
 const one = 1;
 const two = 2;
 const three = 3;
@@ -66,7 +66,7 @@ const three = 3;
 
 #### ✅ Correct
 
-```ts
+```ts option='{ "ignoreStringArrays": true }'
 const one = '1';
 const two = '2';
 const three = '3';
@@ -75,4 +75,4 @@ const three = '3';
 
 ## When Not To Use It
 
-If you understand the language specification enough, and/or only ever sort arrays in a string-like manner, you can turn this rule off safely.
+If you intentionally want your arrays to be always sorted in a string-like manner, you can turn this rule off safely.

package/docs/rules/require-await.md

@@ -6,11 +6,11 @@ description: 'Disallow async functions which have no `await` expression.'
 >
 > See **https://typescript-eslint.io/rules/require-await** for documentation.
 
-## Examples
-
 This rule extends the base [`eslint/require-await`](https://eslint.org/docs/rules/require-await) rule.
 It uses type information to add support for `async` functions that return a `Promise`.
 
+## Examples
+
 Examples of **correct** code for this rule:
 
 ```ts

package/docs/rules/restrict-plus-operands.md

@@ -18,15 +18,15 @@ This rule reports when a `+` operation combines two values of different types, o
 ### ❌ Incorrect
 
 ```ts
-let foo = '5.5' + 5;
 let foo = 1n + 1;
+let fn = (a: string, b: never) => a + b;
 ```
 
 ### ✅ Correct
 
 ```ts
-let foo = parseInt('5.5', 10) + 10;
 let foo = 1n + 1n;
+let fn = (a: string, b: string) => a + b;
 ```
 
 ## Options
@@ -74,14 +74,14 @@ Examples of code for this rule with `{ allowAny: true }`:
 
 #### ❌ Incorrect
 
-```ts
+```ts option='{ "allowAny": true }'
 let fn = (a: number, b: []) => a + b;
 let fn = (a: string, b: []) => a + b;
 ```
 
 #### ✅ Correct
 
-```ts
+```ts option='{ "allowAny": true }'
 let fn = (a: number, b: any) => a + b;
 let fn = (a: string, b: any) => a + b;
 ```
@@ -94,14 +94,14 @@ Examples of code for this rule with `{ allowBoolean: true }`:
 
 #### ❌ Incorrect
 
-```ts
+```ts option='{ "allowBoolean": true }'
 let fn = (a: number, b: unknown) => a + b;
 let fn = (a: string, b: unknown) => a + b;
 ```
 
 #### ✅ Correct
 
-```ts
+```ts option='{ "allowBoolean": true }'
 let fn = (a: number, b: boolean) => a + b;
 let fn = (a: string, b: boolean) => a + b;
 ```
@@ -114,7 +114,7 @@ Examples of code for this rule with `{ allowNullish: true }`:
 
 #### ❌ Incorrect
 
-```ts
+```ts option='{ "allowNullish": true }'
 let fn = (a: number, b: unknown) => a + b;
 let fn = (a: number, b: never) => a + b;
 let fn = (a: string, b: unknown) => a + b;
@@ -123,7 +123,7 @@ let fn = (a: string, b: never) => a + b;
 
 #### ✅ Correct
 
-```ts
+```ts option='{ "allowNullish": true }'
 let fn = (a: number, b: undefined) => a + b;
 let fn = (a: number, b: null) => a + b;
 let fn = (a: string, b: undefined) => a + b;
@@ -138,14 +138,14 @@ Examples of code for this rule with `{ allowNumberAndString: true }`:
 
 #### ❌ Incorrect
 
-```ts
+```ts option='{ "allowNumberAndString": true }'
 let fn = (a: number, b: unknown) => a + b;
 let fn = (a: number, b: never) => a + b;
 ```
 
 #### ✅ Correct
 
-```ts
+```ts option='{ "allowNumberAndString": true }'
 let fn = (a: number, b: string) => a + b;
 let fn = (a: number, b: number | string) => a + b;
 ```
@@ -158,25 +158,25 @@ Examples of code for this rule with `{ allowRegExp: true }`:
 
 #### ❌ Incorrect
 
-```ts
+```ts option='{ "allowRegExp": true }'
 let fn = (a: number, b: RegExp) => a + b;
 ```
 
 #### ✅ Correct
 
-```ts
+```ts option='{ "allowRegExp": true }'
 let fn = (a: string, b: RegExp) => a + b;
 ```
 
 ### `skipCompoundAssignments`
 
-Examples of code for this rule with `{ skipCompoundAssignments: true }`:
+Examples of code for this rule with `{ skipCompoundAssignments: false }`:
 
 <!--tabs-->
 
 #### ❌ Incorrect
 
-```ts
+```ts option='{ "skipCompoundAssignments": true }'
 let foo: string | undefined;
 foo += 'some data';
 
@@ -186,7 +186,7 @@ bar += 0;
 
 #### ✅ Correct
 
-```ts
+```ts option='{ "skipCompoundAssignments": true }'
 let foo: number = 0;
 foo += 1;
 
@@ -196,7 +196,7 @@ bar += 'test';
 
 ## When Not To Use It
 
-If you don't mind `"[object Object]"` in your strings, then you will not need this rule.
+If you don't mind a risk of `"[object Object]"` or incorrect type coercions in your values, then you will not need this rule.
 
 ## Related To