@typescript-eslint/eslint-plugin 6.15.0 → 6.17.0

package/docs/rules/no-misused-promises.md

@@ -17,7 +17,7 @@ See [`no-floating-promises`](./no-floating-promises.md) for detecting unhandled
 
 ## Options
 
-### `"checksConditionals"`
+### `checksConditionals`
 
 If you don't want to check conditionals, you can configure the rule with `"checksConditionals": false`:
 
@@ -73,7 +73,7 @@ while (await promise) {
 
 <!--/tabs-->
 
-### `"checksVoidReturn"`
+### `checksVoidReturn`
 
 Likewise, if you don't want to check functions that return promises where a void return is
 expected, your configuration will look like this:
@@ -182,7 +182,7 @@ eventEmitter.on('some-event', () => {
 
 <!--/tabs-->
 
-### `"checksSpreads"`
+### `checksSpreads`
 
 If you don't want to check object spreads, you can add this configuration:
 

package/docs/rules/no-parameter-properties.md

@@ -0,0 +1,12 @@
+:::danger Deprecated
+
+This rule has been deprecated in favour of the [`parameter-properties`](https://typescript-eslint.io/rules/parameter-properties/) rule.
+
+:::
+
+<!--
+This doc file has been left on purpose to help direct people to the replacement rule.
+
+Note that there is no actual way to get to this page in the normal navigation,
+so end-users will only be able to get to this page from the search bar.
+-->

package/docs/rules/no-shadow.md

@@ -28,25 +28,31 @@ const defaultOptions: Options = {
 
 ### `ignoreTypeValueShadow`
 
-When set to `true`, the rule will ignore the case when you name a type the same as a variable.
-
-TypeScript allows types and variables to shadow one-another. This is generally safe because you cannot use variables in type locations without a `typeof` operator, so there's little risk of confusion.
+When set to `true`, the rule will ignore the case when you name a type the same as a variable. This is generally safe because you cannot use variables in type locations without a `typeof` operator, so there's little risk of confusion.
 
 Examples of **correct** code with `{ ignoreTypeValueShadow: true }`:
 
 ```ts option='{ "ignoreTypeValueShadow": true }' showPlaygroundButton
 type Foo = number;
-const Foo = 1;
-
 interface Bar {
   prop: number;
 }
-const Bar = 'test';
+
+function f() {
+  const Foo = 1;
+  const Bar = 'test';
+}
 ```
 
+:::note
+
+_Shadowing_ specifically refers to two identical identifiers that are in different, nested scopes. This is different from _redeclaration_, which is when two identical identifiers are in the same scope. Redeclaration is covered by the [`no-redeclare`](./no-redeclare.md) rule instead.
+
+:::
+
 ### `ignoreFunctionTypeParameterNameValueShadow`
 
-When set to `true`, the rule will ignore the case when you name a function type argument the same as a variable.
+When set to `true`, the rule will ignore the case when you name a parameter in a function type the same as a variable.
 
 Each of a function type's arguments creates a value variable within the scope of the function type. This is done so that you can reference the type later using the `typeof` operator:
 

package/docs/rules/no-this-alias.md

@@ -33,6 +33,75 @@ setTimeout(() => {
 
 ## Options
 
+### `allowDestructuring`
+
+It can sometimes be useful to destructure properties from a class instance, such as retrieving multiple properties from the instance in one of its methods.
+`allowDestructuring` allows those destructures and is `true` by default.
+You can explicitly disallow them by setting `allowDestructuring` to `false`.
+
+Examples of code for the `{ "allowDestructuring": false }` option:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts option='{ "allowDestructuring": false }'
+class ComponentLike {
+  props: unknown;
+  state: unknown;
+
+  render() {
+    const { props, state } = this;
+
+    console.log(props);
+    console.log(state);
+  }
+}
+```
+
+#### ✅ Correct
+
+```ts option='{ "allowDestructuring": false }'
+class ComponentLike {
+  props: unknown;
+  state: unknown;
+
+  render() {
+    console.log(this.props);
+    console.log(this.state);
+  }
+}
+```
+
+### `allowedNames`
+
+`no-this-alias` can alternately be used to allow only a specific list of names as `this` aliases.
+We recommend against this except as a transitory step towards fixing all rule violations.
+
+Examples of code for the `{ "allowedNames": ["self"] }` option:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts option='{ "allowedNames": ["self"] }'
+class Example {
+  method() {
+    const that = this;
+  }
+}
+```
+
+#### ✅ Correct
+
+```ts option='{ "allowedNames": ["self"] }'
+class Example {
+  method() {
+    const self = this;
+  }
+}
+```
+
 ## When Not To Use It
 
 If your project is structured in a way that it needs to assign `this` to variables, this rule is likely not for you.

package/docs/rules/no-unnecessary-condition.md

@@ -101,8 +101,7 @@ You might consider using [ESLint disable comments](https://eslint.org/docs/lates
 This rule has a known edge case of triggering on conditions that were modified within function calls (as side effects).
 It is due to limitations of TypeScript's type narrowing.
 See [#9998](https://github.com/microsoft/TypeScript/issues/9998) for details.
-
-We recommend upcasting the variable with a [type assertion](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#type-assertions).
+We recommend using a [type assertion](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#type-assertions) in those cases.
 
 ```ts
 let condition = false as boolean;

package/docs/rules/parameter-properties.md

@@ -19,7 +19,7 @@ It may take an options object containing either or both of:
 - `"allow"`: allowing certain kinds of properties to be ignored
 - `"prefer"`: either `"class-property"` _(default)_ or `"parameter-property"`
 
-### `"allow"`
+### `allow`
 
 If you would like to ignore certain kinds of properties then you may pass an object containing `"allow"` as an array of any of the following options:
 
@@ -45,7 +45,7 @@ For example, to ignore `public` properties:
 }
 ```
 
-### `"prefer"`
+### `prefer`
 
 By default, the rule prefers class property (`"class-property"`).
 You can switch it to instead preferring parameter property with (`"parameter-property"`).

package/docs/rules/prefer-literal-enum-member.md

@@ -61,7 +61,9 @@ enum Valid {
 
 ## Options
 
-- `allowBitwiseExpressions` set to `true` will allow you to use bitwise expressions in enum initializer (Default: `false`).
+### `allowBitwiseExpressions`
+
+When set to `true` will allow you to use bitwise expressions in enum initializer (default: `false`).
 
 Examples of code for the `{ "allowBitwiseExpressions": true }` option:
 

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

@@ -167,6 +167,16 @@ foo ?? 'a string';
 
 Also, if you would like to ignore all primitives types, you can set `ignorePrimitives: true`. It is equivalent to `ignorePrimitives: { string: true, number: true, bigint: true, boolean: true }`.
 
+### `allowRuleToRunWithoutStrictNullChecksIKnowWhatIAmDoing`
+
+If this is set to `false`, then the rule will error on every file whose `tsconfig.json` does _not_ have the `strictNullChecks` compiler option (or `strict`) set to `true`.
+
+Without `strictNullChecks`, TypeScript essentially erases `undefined` and `null` from the types. This means when this rule inspects the types from a variable, **it will not be able to tell that the variable might be `null` or `undefined`**, which essentially makes this rule useless.
+
+You should be using `strictNullChecks` to ensure complete type-safety in your codebase.
+
+If for some reason you cannot turn on `strictNullChecks`, but still want to use this rule - you can use this option to allow it - but know that the behavior of this rule is _undefined_ with the compiler option turned off. We will not accept bug reports if you are using this option.
+
 ## 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-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 {

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

@@ -58,6 +58,74 @@ async function functionReturnsUnionWithPromiseImplicitly(p: boolean) {
 }
 ```
 
+## 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`.

package/docs/rules/sort-type-constituents.md

@@ -82,6 +82,46 @@ type T4 =
 
 ## Options
 
+### `checkIntersections`
+
+Whether to check intersection types (`&`).
+
+Examples of code with `{ "checkIntersections": true }` (the default):
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts option='{ "checkIntersections": true }'
+type ExampleIntersection = B & A;
+```
+
+#### ✅ Correct
+
+```ts option='{ "checkIntersections": true }'
+type ExampleIntersection = A & B;
+```
+
+### `checkUnions`
+
+Whether to check union types (`|`).
+
+Examples of code with `{ "checkUnions": true }` (the default):
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts option='{ "checkUnions": true }'
+type ExampleUnion = B | A;
+```
+
+#### ✅ Correct
+
+```ts option='{ "checkUnions": true }'
+type ExampleUnion = A | B;
+```
+
 ### `groupOrder`
 
 Each constituent of the type is placed into a group, and then the rule sorts alphabetically within each group.
@@ -100,6 +140,22 @@ The ordering of groups is determined by this option.
 - `union` - Union types (`A | B`)
 - `nullish` - `null` and `undefined`
 
+For example, configuring the rule with `{ "groupOrder": ["literal", "nullish" ]}`:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts option='{ "groupOrder": ["literal", "nullish" ]}'
+type ExampleGroup = null | 123;
+```
+
+#### ✅ Correct
+
+```ts option='{ "groupOrder": ["literal", "nullish" ]}'
+type ExampleGroup = 123 | null;
+```
+
 ## When Not To Use It
 
 This rule is purely a stylistic rule for maintaining consistency in your project.

package/docs/rules/switch-exhaustiveness-check.md

@@ -6,12 +6,51 @@ description: 'Require switch-case statements to be exhaustive.'
 >
 > See **https://typescript-eslint.io/rules/switch-exhaustiveness-check** for documentation.
 
-When working with union types or enums in TypeScript, it's common to want to write a `switch` statement intended to contain a `case` for each constituent (possible type in the union or the enum).
+When working with union types or enums in TypeScript, it's common to want to write a `switch` statement intended to contain a `case` for each possible type in the union or the enum.
 However, if the union type or the enum changes, it's easy to forget to modify the cases to account for any new types.
 
 This rule reports when a `switch` statement over a value typed as a union of literals or as an enum is missing a case for any of those literal types and does not have a `default` clause.
 
-There is also an option to check the exhaustiveness of switches on non-union types by requiring a default clause.
+## Options
+
+### `"allowDefaultCaseForExhaustiveSwitch"`
+
+Defaults to true. If set to false, this rule will also report when a `switch` statement has a case for everything in a union and _also_ contains a `default` case. Thus, by setting this option to false, the rule becomes stricter.
+
+When a `switch` statement over a union type is exhaustive, a final `default` case would be a form of dead code.
+Additionally, if a new value is added to the union type, a `default` would prevent the `switch-exhaustiveness-check` rule from reporting on the new case not being handled in the `switch` statement.
+
+#### `"allowDefaultCaseForExhaustiveSwitch"` Caveats
+
+It can sometimes be useful to include a redundant `default` case on an exhaustive `switch` statement if it's possible for values to have types not represented by the union type.
+For example, in applications that can have version mismatches between clients and servers, it's possible for a server running a newer software version to send a value not recognized by the client's older typings.
+
+If your project has a small number of intentionally redundant `default` cases, you might want to use an [inline ESLint disable comment](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1) for each of them.
+
+If your project has many intentionally redundant `default` cases, you may want to disable `allowDefaultCaseForExhaustiveSwitch` and use the [`default-case` core ESLint rule](https://eslint.org/docs/latest/rules/default-case) along with [a `satisfies never` check](https://www.typescriptlang.org/play?#code/C4TwDgpgBAYgTgVwJbCgXigcgIZjAGwkygB8sAjbAO2u0wG4AoRgMwSoGNgkB7KqBAGcI8ZMAAULRCgBcsacACUcwcDhIqAcygBvRlCiCA7ig4ALKJIWLd+g1A7ZhWXASJy99+3AjAEcfhw8QgApZA4iJi8AX2YvR2dMShoaTA87Lx8-AIpaGjCkCIYMqFiSgBMIFmwEfGB0rwMpMUNsbkEWJAhBKCoIADcIOCjGrP9A9gBrKh4jKgKikYNY5cZYoA).
+
+### `requireDefaultForNonUnion`
+
+Defaults to false. It set to true, this rule will also report when a `switch` statement switches over a non-union type (like a `number` or `string`, for example) and that `switch` statement does not have a `default` case. Thus, by setting this option to true, the rule becomes stricter.
+
+This is generally desirable so that `number` and `string` switches will be subject to the same exhaustive checks that your other switches are.
+
+Examples of additional **incorrect** code for this rule with `{ requireDefaultForNonUnion: true }`:
+
+```ts option='{ "requireDefaultForNonUnion": true }' showPlaygroundButton
+const value: number = Math.floor(Math.random() * 3);
+
+switch (value) {
+  case 0:
+    return 0;
+  case 1:
+    return 1;
+}
+```
+
+Since `value` is a non-union type it requires the switch case to have a default clause only with `requireDefaultForNonUnion` enabled.
+
+<!--/tabs-->
 
 ## Examples
 
@@ -181,27 +220,6 @@ switch (fruit) {
 
 <!--/tabs-->
 
-## Options
-
-### `requireDefaultForNonUnion`
-
-Examples of additional **incorrect** code for this rule with `{ requireDefaultForNonUnion: true }`:
-
-```ts option='{ "requireDefaultForNonUnion": true }' showPlaygroundButton
-const value: number = Math.floor(Math.random() * 3);
-
-switch (value) {
-  case 0:
-    return 0;
-  case 1:
-    return 1;
-}
-```
-
-Since `value` is a non-union type it requires the switch case to have a default clause only with `requireDefaultForNonUnion` enabled.
-
-<!--/tabs-->
-
 ## When Not To Use It
 
 If you don't frequently `switch` over union types or enums with many parts, or intentionally wish to leave out some parts, this rule may not be for you.

package/docs/rules/triple-slash-reference.md

@@ -8,46 +8,94 @@ description: 'Disallow certain triple slash directives in favor of ES6-style imp
 
 TypeScript's `///` triple-slash references are a way to indicate that types from another module are available in a file.
 Use of triple-slash reference type directives is generally discouraged in favor of ECMAScript Module `import`s.
-This rule reports on the use of `/// <reference path="..." />`, `/// <reference types="..." />`, or `/// <reference lib="..." />` directives.
+This rule reports on the use of `/// <reference lib="..." />`, `/// <reference path="..." />`, or `/// <reference types="..." />` directives.
 
 ## Options
 
-With `{ "path": "never", "types": "never", "lib": "never" }` options set, the following will all be **incorrect** usage:
+Any number of the three kinds of references can be specified as an option.
+Specifying `'always'` disables this lint rule for that kind of reference.
 
-```ts option='{ "path": "never", "types": "never", "lib": "never" }' showPlaygroundButton
-/// <reference path="foo" />
-/// <reference types="bar" />
-/// <reference lib="baz" />
+### `lib`
+
+When set to `'never'`, bans `/// <reference lib="..." />` and enforces using an `import` instead:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts option='{ "lib": "never" }'
+/// <reference lib="code" />
+
+globalThis.value;
+```
+
+#### ✅ Correct
+
+```ts option='{ "lib": "never" }'
+import { value } from 'code';
+```
+
+### `path`
+
+When set to `'never'`, bans `/// <reference path="..." />` and enforces using an `import` instead:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts option='{ "path": "never" }'
+/// <reference path="code" />
+
+globalThis.value;
 ```
 
-Examples of **incorrect** code for the `{ "types": "prefer-import" }` option. Note that these are only errors when **both** styles are used for the **same** module:
+#### ✅ Correct
 
-```ts option='{ "types": "prefer-import" }' showPlaygroundButton
-/// <reference types="foo" />
-import * as foo from 'foo';
+```ts option='{ "path": "never" }'
+import { value } from 'code';
 ```
 
-```ts option='{ "types": "prefer-import" }' showPlaygroundButton
-/// <reference types="foo" />
-import foo = require('foo');
+### `types`
+
+When set to `'never'`, bans `/// <reference types="..." />` and enforces using an `import` instead:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts option='{ "types": "never" }'
+/// <reference types="code" />
+
+globalThis.value;
 ```
 
-With `{ "path": "always", "types": "always", "lib": "always" }` options set, the following will all be **correct** usage:
+#### ✅ Correct
 
-```ts option='{ "path": "always", "types": "always", "lib": "always" }' showPlaygroundButton
-/// <reference path="foo" />
-/// <reference types="bar" />
-/// <reference lib="baz" />
+```ts option='{ "types": "never" }'
+import { value } from 'code';
 ```
 
-Examples of **correct** code for the `{ "types": "prefer-import" }` option:
+<!-- /tabs -->
 
-```ts option='{ "types": "prefer-import" }' showPlaygroundButton
-import * as foo from 'foo';
+The `types` option may alternately be given a `"prefer-import"` value.
+Doing so indicates the rule should only report if there is already an `import` from the same location:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts option='{ "types": "prefer-import" }'
+/// <reference types="code" />
+
+import { valueA } from 'code';
+
+globalThis.valueB;
 ```
 
-```ts option='{ "types": "prefer-import" }' showPlaygroundButton
-import foo = require('foo');
+#### ✅ Correct
+
+```ts option='{ "types": "prefer-import" }'
+import { valueA, valueB } from 'code';
 ```
 
 ## When Not To Use It

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typescript-eslint/eslint-plugin",
-  "version": "6.15.0",
+  "version": "6.17.0",
   "description": "TypeScript plugin for ESLint",
   "files": [
     "dist",
@@ -57,10 +57,10 @@
   },
   "dependencies": {
     "@eslint-community/regexpp": "^4.5.1",
-    "@typescript-eslint/scope-manager": "6.15.0",
-    "@typescript-eslint/type-utils": "6.15.0",
-    "@typescript-eslint/utils": "6.15.0",
-    "@typescript-eslint/visitor-keys": "6.15.0",
+    "@typescript-eslint/scope-manager": "6.17.0",
+    "@typescript-eslint/type-utils": "6.17.0",
+    "@typescript-eslint/utils": "6.17.0",
+    "@typescript-eslint/visitor-keys": "6.17.0",
     "debug": "^4.3.4",
     "graphemer": "^1.4.0",
     "ignore": "^5.2.4",
@@ -73,8 +73,8 @@
     "@types/debug": "*",
     "@types/marked": "*",
     "@types/natural-compare": "*",
-    "@typescript-eslint/rule-schema-to-typescript-types": "6.15.0",
-    "@typescript-eslint/rule-tester": "6.15.0",
+    "@typescript-eslint/rule-schema-to-typescript-types": "6.17.0",
+    "@typescript-eslint/rule-tester": "6.17.0",
     "ajv": "^6.12.6",
     "chalk": "^5.3.0",
     "cross-fetch": "*",
@@ -103,5 +103,5 @@
     "type": "opencollective",
     "url": "https://opencollective.com/typescript-eslint"
   },
-  "gitHead": "6128a02cb15d500fe22fe265c83e4d7a73ae52c3"
+  "gitHead": "e566a5dda347470b8ced3cc301b7e4d3e7ed721b"
 }