@typescript-eslint/eslint-plugin 6.0.0-alpha.99 → 6.0.0

package/docs/rules/no-duplicate-type-constituents.md

@@ -0,0 +1,61 @@
+---
+description: 'Disallow duplicate constituents of union or intersection types.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-duplicate-type-constituents** for documentation.
+
+TypeScript supports types ("constituents") within union and intersection types being duplicates of each other.
+However, developers typically expect each constituent to be unique within its intersection or union.
+Duplicate values make the code overly verbose and generally reduce readability.
+
+## Rule Details
+
+This rule disallows duplicate union or intersection constituents.
+We consider types to be duplicate if they evaluate to the same result in the type system.
+For example, given `type A = string` and `type T = string | A`, this rule would flag that `A` is the same type as `string`.
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+type T1 = 'A' | 'A';
+
+type T2 = A | A | B;
+
+type T3 = { a: string } & { a: string };
+
+type T4 = [1, 2, 3] | [1, 2, 3];
+
+type StringA = string;
+type StringB = string;
+type T5 = StringA | StringB;
+```
+
+### ✅ Correct
+
+```ts
+type T1 = 'A' | 'B';
+
+type T2 = A | B | C;
+
+type T3 = { a: string } & { b: string };
+
+type T4 = [1, 2, 3] | [1, 2, 3, 4];
+
+type StringA = string;
+type NumberB = number;
+type T5 = StringA | NumberB;
+```
+
+## Options
+
+### `ignoreIntersections`
+
+When set to true, duplicate checks on intersection type constituents are ignored.
+
+### `ignoreUnions`
+
+When set to true, duplicate checks on union type constituents are ignored.

package/docs/rules/no-unnecessary-boolean-literal-compare.md

@@ -115,16 +115,16 @@ if (!(someNullCondition ?? true)) {
 
 ## Fixer
 
-|           Comparison           | Fixer Output                    | Notes                                                                               |
-| :----------------------------: | ------------------------------- | ----------------------------------------------------------------------------------- |
-|     `booleanVar === true`      | `booleanVar`                    |                                                                                     |
-|     `booleanVar !== true`      | `!booleanVar`                   |                                                                                     |
-|     `booleanVar === false`     | `!booleanVar`                   |                                                                                     |
-|     `booleanVar !== false`     | `booleanVar`                    |                                                                                     |
-| `nullableBooleanVar === true`  | `nullableBooleanVar`            | Only checked/fixed if the `allowComparingNullableBooleansToTrue` option is `false`  |
-| `nullableBooleanVar !== true`  | `!nullableBooleanVar`           | Only checked/fixed if the `allowComparingNullableBooleansToTrue` option is `false`  |
-| `nullableBooleanVar === false` | `nullableBooleanVar ?? true`    | Only checked/fixed if the `allowComparingNullableBooleansToFalse` option is `false` |
-| `nullableBooleanVar !== false` | `!(nullableBooleanVar ?? true)` | Only checked/fixed if the `allowComparingNullableBooleansToFalse` option is `false` |
+|            Comparison             | Fixer Output                    | Notes                                                                               |
+| :-------------------------------: | ------------------------------- | ----------------------------------------------------------------------------------- |
+|       `booleanVar === true`       | `booleanVar`                    |                                                                                     |
+|       `booleanVar !== true`       | `!booleanVar`                   |                                                                                     |
+|      `booleanVar === false`       | `!booleanVar`                   |                                                                                     |
+|      `booleanVar !== false`       | `booleanVar`                    |                                                                                     |
+|   `nullableBooleanVar === true`   | `nullableBooleanVar`            | Only checked/fixed if the `allowComparingNullableBooleansToTrue` option is `false`  |
+|   `nullableBooleanVar !== true`   | `!nullableBooleanVar`           | Only checked/fixed if the `allowComparingNullableBooleansToTrue` option is `false`  |
+| `!(nullableBooleanVar === false)` | `nullableBooleanVar ?? true`    | Only checked/fixed if the `allowComparingNullableBooleansToFalse` option is `false` |
+| `!(nullableBooleanVar !== false)` | `!(nullableBooleanVar ?? true)` | Only checked/fixed if the `allowComparingNullableBooleansToFalse` option is `false` |
 
 ## Not To Use It
 

package/docs/rules/no-unnecessary-type-constraint.md

@@ -7,8 +7,8 @@ description: 'Disallow unnecessary constraints on generic types.'
 > See **https://typescript-eslint.io/rules/no-unnecessary-type-constraint** for documentation.
 
 Generic type parameters (`<T>`) in TypeScript may be "constrained" with an [`extends` keyword](https://www.typescriptlang.org/docs/handbook/generics.html#generic-constraints).
-When no `extends` is provided, type parameters default a constraint to `any`.
-It is therefore redundant to `extend` from `any`.
+When no `extends` is provided, type parameters default a constraint to `unknown`.
+It is therefore redundant to `extend` from `any` or `unknown`.
 
 ## Examples
 
@@ -19,8 +19,12 @@ It is therefore redundant to `extend` from `any`.
 ```ts
 interface FooAny<T extends any> {}
 
+interface FooUnknown<T extends unknown> {}
+
 type BarAny<T extends any> = {};
 
+type BarUnknown<T extends unknown> = {};
+
 class BazAny<T extends any> {
   quxAny<U extends any>() {}
 }

package/docs/rules/no-unsafe-enum-comparison.md

@@ -0,0 +1,77 @@
+---
+description: 'Disallow comparing an enum value with a non-enum value.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-unsafe-enum-comparison** for documentation.
+
+The TypeScript compiler can be surprisingly lenient when working with enums.
+For example, it will allow you to compare enum values against numbers even though they might not have any type overlap:
+
+```ts
+enum Fruit {
+  Apple,
+  Banana,
+}
+
+declare let fruit: Fruit;
+
+fruit === 999; // No error
+```
+
+This rule flags when an enum typed value is compared to a non-enum `number`.
+
+## Examples
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+enum Fruit {
+  Apple,
+}
+
+declare let fruit: Fruit;
+
+fruit === 999;
+```
+
+```ts
+enum Vegetable {
+  Asparagus = 'asparagus',
+}
+
+declare let vegetable: Vegetable;
+
+vegetable === 'asparagus';
+```
+
+### ✅ Correct
+
+```ts
+enum Fruit {
+  Apple,
+}
+
+declare let fruit: Fruit;
+
+fruit === Fruit.Banana;
+```
+
+```ts
+enum Vegetable {
+  Asparagus = 'asparagus',
+}
+
+declare let vegetable: Vegetable;
+
+vegetable === Vegetable.Asparagus;
+```
+
+<!--/tabs-->
+
+## When Not To Use It
+
+If you don't mind number and/or literal string constants being compared against enums, you likely don't need this rule.

package/docs/rules/prefer-includes.md

@@ -57,7 +57,7 @@ const userDefined: {
 
 str.includes(value);
 array.includes(value);
-readonlyArray.includes(value);
+!readonlyArray.includes(value);
 typedArray.includes(value);
 maybe?.includes('');
 userDefined.includes(value);

package/docs/rules/prefer-nullish-coalescing.md

@@ -142,6 +142,29 @@ a ?? (b && c && d);
 
 **_NOTE:_** Errors for this specific case will be presented as suggestions (see below), instead of fixes. This is because it is not always safe to automatically convert `||` to `??` within a mixed logical expression, as we cannot tell the intended precedence of the operator. Note that by design, `??` requires parentheses when used with `&&` or `||` in the same expression.
 
+### `ignorePrimitives`
+
+If you would like to ignore certain primitive types that can be falsy then you may pass an object containing a boolean value for each primitive:
+
+- `string: true`, ignores `null` or `undefined` unions with `string` (default: false).
+- `number: true`, ignores `null` or `undefined` unions with `number` (default: false).
+- `bigint: true`, ignores `null` or `undefined` unions with `bigint` (default: false).
+- `boolean: true`, ignores `null` or `undefined` unions with `boolean` (default: false).
+
+Incorrect code for `ignorePrimitives: { string: true }`, and correct code for `ignorePrimitives: { string: false }`:
+
+```ts
+const foo: string | undefined = 'bar';
+foo || 'a string';
+```
+
+Correct code for `ignorePrimitives: { string: true }`:
+
+```ts
+const foo: string | undefined = 'bar';
+foo ?? 'a string';
+```
+
 ## When Not To Use It
 
 If you are not using TypeScript 3.7 (or greater), then you will not be able to use this rule, as the operator is not supported.

package/docs/rules/prefer-optional-chain.md

@@ -57,13 +57,204 @@ foo?.a?.b?.c?.d?.e;
 
 <!--/tabs-->
 
-:::note
-There are a few edge cases where this rule will false positive. Use your best judgement when evaluating reported errors.
-:::
+## Options
+
+In the context of the descriptions below a "loose boolean" operand is any operand that implicitly coerces the value to a boolean.
+Specifically the argument of the not operator (`!loose`) or a bare value in a logical expression (`loose && looser`).
+
+### `allowPotentiallyUnsafeFixesThatModifyTheReturnTypeIKnowWhatImDoing`
+
+When this option is `true`, the rule will not provide an auto-fixer for cases where the return type of the expression would change. For example for the expression `!foo || foo.bar` the return type of the expression is `true | T`, however for the equivalent optional chain `foo?.bar` the return type of the expression is `undefined | T`. Thus changing the code from a logical expression to an optional chain expression has altered the type of the expression.
+
+In some cases this distinction _may_ matter - which is why these fixers are considered unsafe - they may break the build! For example in the following code:
+
+```ts
+declare const foo: { bar: boolean } | null | undefined;
+declare function acceptsBoolean(arg: boolean): void;
+
+// ✅ typechecks succesfully as the expression only returns `boolean`
+acceptsBoolean(foo != null && foo.bar);
+
+// ❌ typechecks UNSUCCESSFULLY as the expression returns `boolean | undefined`
+acceptsBoolean(foo != null && foo.bar);
+```
+
+This style of code isn't super common - which means having this option set to `true` _should_ be safe in most codebases. However we default it to `false` due to its unsafe nature. We have provided this option for convenience because it increases the autofix cases covered by the rule. If you set option to `true` the onus is entirely on you and your team to ensure that each fix is correct and safe and that it does not break the build.
+
+When this option is `false` unsafe cases will have suggestion fixers provided instead of auto-fixers - meaning you can manually apply the fix using your IDE tooling.
+
+### `checkAny`
+
+When this option is `true` the rule will check operands that are typed as `any` when inspecting "loose boolean" operands.
+
+<!--tabs-->
+
+#### ❌ Incorrect for `checkAny: true`
+
+```ts
+declare const thing: any;
+
+thing && thing.toString();
+```
+
+#### ✅ Correct for `checkAny: false`
+
+```ts
+declare const thing: any;
+
+thing && thing.toString();
+```
+
+<!--/tabs-->
+
+### `checkUnknown`
+
+When this option is `true` the rule will check operands that are typed as `unknown` when inspecting "loose boolean" operands.
+
+<!--tabs-->
+
+#### ❌ Incorrect for `checkUnknown: true`
+
+```ts
+declare const thing: unknown;
+
+thing && thing.toString();
+```
+
+#### ✅ Correct for `checkUnknown: false`
+
+```ts
+declare const thing: unknown;
+
+thing && thing.toString();
+```
+
+<!--/tabs-->
+
+### `checkString`
+
+When this option is `true` the rule will check operands that are typed as `string` when inspecting "loose boolean" operands.
+
+<!--tabs-->
+
+#### ❌ Incorrect for `checkString: true`
+
+```ts
+declare const thing: string;
+
+thing && thing.toString();
+```
+
+#### ✅ Correct for `checkString: false`
+
+```ts
+declare const thing: string;
+
+thing && thing.toString();
+```
+
+<!--/tabs-->
+
+### `checkNumber`
+
+When this option is `true` the rule will check operands that are typed as `number` when inspecting "loose boolean" operands.
+
+<!--tabs-->
+
+#### ❌ Incorrect for `checkNumber: true`
+
+```ts
+declare const thing: number;
+
+thing && thing.toString();
+```
+
+#### ✅ Correct for `checkNumber: false`
+
+```ts
+declare const thing: number;
+
+thing && thing.toString();
+```
+
+<!--/tabs-->
+
+### `checkBoolean`
+
+When this option is `true` the rule will check operands that are typed as `boolean` when inspecting "loose boolean" operands.
+
+<!--tabs-->
+
+#### ❌ Incorrect for `checkBoolean: true`
+
+```ts
+declare const thing: boolean;
+
+thing && thing.toString();
+```
+
+#### ✅ Correct for `checkBoolean: false`
+
+```ts
+declare const thing: boolean;
+
+thing && thing.toString();
+```
+
+<!--/tabs-->
+
+### `checkBigInt`
+
+When this option is `true` the rule will check operands that are typed as `bigint` when inspecting "loose boolean" operands.
+
+<!--tabs-->
+
+#### ❌ Incorrect for `checkBigInt: true`
+
+```ts
+declare const thing: bigint;
+
+thing && thing.toString();
+```
+
+#### ✅ Correct for `checkBigInt: false`
+
+```ts
+declare const thing: bigint;
+
+thing && thing.toString();
+```
+
+<!--/tabs-->
+
+### `requireNullish`
+
+When this option is `true` the rule will skip operands that are not typed with `null` and/or `undefined` when inspecting "loose boolean" operands.
+
+<!--tabs-->
+
+#### ❌ Incorrect for `requireNullish: true`
+
+```ts
+declare const thing1: string | null;
+thing1 && thing1.toString();
+```
+
+#### ✅ Correct for `requireNullish: true`
+
+```ts
+declare const thing1: string | null;
+thing1?.toString();
+
+declare const thing2: string;
+thing2 && thing2.toString();
+```
+
+<!--/tabs-->
 
 ## When Not To Use It
 
-If you don't mind using more explicit `&&`s, you don't need this rule.
+If you don't mind using more explicit `&&`s/`||`s, you don't need this rule.
 
 ## Further Reading
 

package/docs/rules/require-await.md

@@ -20,5 +20,3 @@ async function returnsPromise1() {
 
 const returnsPromise2 = () => returnsPromise1();
 ```
-
-## How to Use

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

@@ -18,70 +18,180 @@ This rule reports when a `+` operation combines two values of different types, o
 ### ❌ Incorrect
 
 ```ts
-var foo = '5.5' + 5;
-var foo = 1n + 1;
+let foo = '5.5' + 5;
+let foo = 1n + 1;
 ```
 
 ### ✅ Correct
 
 ```ts
-var foo = parseInt('5.5', 10) + 10;
-var foo = 1n + 1n;
+let foo = parseInt('5.5', 10) + 10;
+let foo = 1n + 1n;
 ```
 
 ## Options
 
-### `checkCompoundAssignments`
+:::caution
+We generally recommend against using these options, as they limit which varieties of incorrect `+` usage can be checked.
+This in turn severely limits the validation that the rule can do to ensure that resulting strings and numbers are correct.
+
+Safer alternatives to using the `allow*` options include:
+
+- Using variadic forms of logging APIs to avoid needing to `+` values.
+  ```ts
+  // Remove this line
+  console.log('The result is ' + true);
+  // Add this line
+  console.log('The result is', true);
+  ```
+- Using `.toFixed()` to coerce numbers to well-formed string representations:
+  ```ts
+  const number = 1.123456789;
+  const result = 'The number is ' + number.toFixed(2);
+  // result === 'The number is 1.12'
+  ```
+- Calling `.toString()` on other types to mark explicit and intentional string coercion:
+  ```ts
+  const arg = '11';
+  const regex = /[0-9]/;
+  const result =
+    'The result of ' +
+    regex.toString() +
+    '.test("' +
+    arg +
+    '") is ' +
+    regex.test(arg).toString();
+  // result === 'The result of /[0-9]/.test("11") is true'
+  ```
+
+:::
 
-Examples of code for this rule with `{ checkCompoundAssignments: true }`:
+### `allowAny`
+
+Examples of code for this rule with `{ allowAny: true }`:
 
 <!--tabs-->
 
 #### ❌ Incorrect
 
 ```ts
-/*eslint @typescript-eslint/restrict-plus-operands: ["error", { "checkCompoundAssignments": true }]*/
+let fn = (a: number, b: []) => a + b;
+let fn = (a: string, b: []) => a + b;
+```
 
-let foo: string | undefined;
-foo += 'some data';
+#### ✅ Correct
 
-let bar: string = '';
-bar += 0;
+```ts
+let fn = (a: number, b: any) => a + b;
+let fn = (a: string, b: any) => a + b;
+```
+
+### `allowBoolean`
+
+Examples of code for this rule with `{ allowBoolean: true }`:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+let fn = (a: number, b: unknown) => a + b;
+let fn = (a: string, b: unknown) => a + b;
 ```
 
 #### ✅ Correct
 
 ```ts
-/*eslint @typescript-eslint/restrict-plus-operands: ["error", { "checkCompoundAssignments": true }]*/
+let fn = (a: number, b: boolean) => a + b;
+let fn = (a: string, b: boolean) => a + b;
+```
 
-let foo: number = 0;
-foo += 1;
+### `allowNullish`
 
-let bar = '';
-bar += 'test';
+Examples of code for this rule with `{ allowNullish: true }`:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+let fn = (a: number, b: unknown) => a + b;
+let fn = (a: number, b: never) => a + b;
+let fn = (a: string, b: unknown) => a + b;
+let fn = (a: string, b: never) => a + b;
 ```
 
-### `allowAny`
+#### ✅ Correct
 
-Examples of code for this rule with `{ allowAny: true }`:
+```ts
+let fn = (a: number, b: undefined) => a + b;
+let fn = (a: number, b: null) => a + b;
+let fn = (a: string, b: undefined) => a + b;
+let fn = (a: string, b: null) => a + b;
+```
+
+### `allowNumberAndString`
+
+Examples of code for this rule with `{ allowNumberAndString: true }`:
 
 <!--tabs-->
 
 #### ❌ Incorrect
 
 ```ts
-var fn = (a: any, b: boolean) => a + b;
-var fn = (a: any, b: []) => a + b;
-var fn = (a: any, b: {}) => a + b;
+let fn = (a: number, b: unknown) => a + b;
+let fn = (a: number, b: never) => a + b;
 ```
 
 #### ✅ Correct
 
 ```ts
-var fn = (a: any, b: any) => a + b;
-var fn = (a: any, b: string) => a + b;
-var fn = (a: any, b: bigint) => a + b;
-var fn = (a: any, b: number) => a + b;
+let fn = (a: number, b: string) => a + b;
+let fn = (a: number, b: number | string) => a + b;
+```
+
+### `allowRegExp`
+
+Examples of code for this rule with `{ allowRegExp: true }`:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+let fn = (a: number, b: RegExp) => a + b;
+```
+
+#### ✅ Correct
+
+```ts
+let fn = (a: string, b: RegExp) => a + b;
+```
+
+### `skipCompoundAssignments`
+
+Examples of code for this rule with `{ skipCompoundAssignments: true }`:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+let foo: string | undefined;
+foo += 'some data';
+
+let bar: string = '';
+bar += 0;
+```
+
+#### ✅ Correct
+
+```ts
+let foo: number = 0;
+foo += 1;
+
+let bar = '';
+bar += 'test';
 ```
 
 ## When Not To Use It

package/docs/rules/restrict-template-expressions.md

@@ -6,9 +6,19 @@ description: 'Enforce template literal expressions to be of `string` type.'
 >
 > See **https://typescript-eslint.io/rules/restrict-template-expressions** for documentation.
 
-JavaScript will call `toString()` on an object when it is converted to a string, such as when `+` adding to a string or in `${}` template literals.
-The default Object `.toString()` returns `"[object Object]"`, which is often not what was intended.
-This rule reports on values used in a template literal string that aren't primitives and don't define a more useful `.toString()` method.
+JavaScript automatically [converts an object to a string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion) in a string context, such as when concatenating it with a string using `+` or embedding it in a template literal using `${}`.
+The default `toString()` method of objects returns `"[object Object]"`, which is often not what was intended.
+This rule reports on values used in a template literal string that aren't strings, numbers, or BigInts, optionally allowing other data types that provide useful stringification results.
+
+:::note
+
+This rule intentionally does not allow objects with a custom `toString()` method to be used in template literals, because the stringification result may not be user-friendly.
+
+For example, arrays have a custom [`toString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toString) method, which only calls `join()` internally, which joins the array elements with commas. This means that (1) array elements are not necessarily stringified to useful results (2) the commas don't have spaces after them, making the result not user-friendly. The best way to format arrays is to use [`Intl.ListFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat), which even supports adding the "and" conjunction where necessary.
+You must explicitly call `object.toString()` if you want to use this object in a template literal.
+The [`no-base-to-string`](./no-base-to-string.md) rule can be used to guard this case against producing `"[object Object]"` by accident.
+
+:::
 
 ## Examples
 
@@ -47,6 +57,8 @@ const msg1 = `arg = ${arg}`;
 const msg2 = `arg = ${arg || 'zero'}`;
 ```
 
+This option controls both numbers and BigInts.
+
 ### `allowBoolean`
 
 Examples of additional **correct** code for this rule with `{ allowBoolean: true }`: