@typescript-eslint/eslint-plugin 8.0.0-alpha.5 → 8.0.0-alpha.51

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

@@ -127,19 +127,18 @@ Examples of code for this rule with `checksVoidReturn: true`:
 
 ```ts option='{ "checksVoidReturn": true }'
 [1, 2, 3].forEach(async value => {
-  await doSomething(value);
+  await fetch(`/${value}`);
 });
 
-new Promise(async (resolve, reject) => {
-  await doSomething();
+new Promise<void>(async (resolve, reject) => {
+  await fetch('/');
   resolve();
 });
 
-const eventEmitter = new EventEmitter();
-eventEmitter.on('some-event', async () => {
-  synchronousCall();
-  await doSomething();
-  otherSynchronousCall();
+document.addEventListener('click', async () => {
+  console.log('synchronous call');
+  await fetch('/');
+  console.log('synchronous call');
 });
 ```
 
@@ -169,8 +168,7 @@ new Promise((resolve, reject) => {
 });
 
 // Name the async wrapper to call it later
-const eventEmitter = new EventEmitter();
-eventEmitter.on('some-event', () => {
+document.addEventListener('click', () => {
   const handler = async () => {
     await doSomething();
     otherSynchronousCall();
@@ -210,30 +208,30 @@ Examples of code for this rule with `checksSpreads: true`:
 <TabItem value="❌ Incorrect">
 
 ```ts option='{ "checksSpreads": true }'
-const getData = () => someAsyncOperation({ myArg: 'foo' });
+const getData = () => fetch('/');
 
-return { foo: 42, ...getData() };
+console.log({ foo: 42, ...getData() });
 
-const getData2 = async () => {
-  await someAsyncOperation({ myArg: 'foo' });
+const awaitData = async () => {
+  await fetch('/');
 };
 
-return { foo: 42, ...getData2() };
+console.log({ foo: 42, ...awaitData() });
 ```
 
 </TabItem>
 <TabItem value="✅ Correct">
 
 ```ts option='{ "checksSpreads": true }'
-const getData = () => someAsyncOperation({ myArg: 'foo' });
+const getData = () => fetch('/');
 
-return { foo: 42, ...(await getData()) };
+console.log({ foo: 42, ...(await getData()) });
 
-const getData2 = async () => {
-  await someAsyncOperation({ myArg: 'foo' });
+const awaitData = async () => {
+  await fetch('/');
 };
 
-return { foo: 42, ...(await getData2()) };
+console.log({ foo: 42, ...(await awaitData()) });
 ```
 
 </TabItem>

package/docs/rules/no-require-imports.mdx

@@ -38,7 +38,7 @@ import * as lib3 from 'lib3';
 
 ### `allow`
 
-A array of strings. These strings will be compiled into regular expressions with the `u` flag and be used to test against the imported path. A common use case is to allow importing `package.json`. This is because `package.json` commonly lives outside of the TS root directory, so statically importing it would lead to root directory conflicts, especially with `resolveJsonModule` enabled. You can also use it to allow importing any JSON if your environment doesn't support JSON modules, or use it for other cases where `import` statements cannot work.
+An array of strings. These strings will be compiled into regular expressions with the `u` flag and be used to test against the imported path. A common use case is to allow importing `package.json`. This is because `package.json` commonly lives outside of the TS root directory, so statically importing it would lead to root directory conflicts, especially with `resolveJsonModule` enabled. You can also use it to allow importing any JSON if your environment doesn't support JSON modules, or use it for other cases where `import` statements cannot work.
 
 With `{allow: ['/package\\.json$']}`:
 
@@ -59,6 +59,33 @@ console.log(require('../package.json').version);
 </TabItem>
 </Tabs>
 
+### `allowAsImport`
+
+When set to `true`, the `import x = require(...)` declaration won't be reported.
+This is useful if you use certain module options that require strict CommonJS interop semantics.
+
+With `{allowAsImport: true}`:
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts option='{ "allowAsImport": true }'
+var foo = require('foo');
+const foo = require('foo');
+let foo = require('foo');
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts option='{ "allowAsImport": true }'
+import foo = require('foo');
+import foo from 'foo';
+```
+
+</TabItem>
+</Tabs>
+
 ## When Not To Use It
 
 If your project frequently uses older CommonJS `require`s, then this rule might not be applicable to you.

package/docs/rules/no-restricted-types.mdx

@@ -0,0 +1,71 @@
+---
+description: 'Disallow certain types.'
+---
+
+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/no-restricted-types** for documentation.
+
+It can sometimes be useful to ban specific types from being used in type annotations.
+For example, a project might be migrating from using one type to another, and want to ban references to the old type.
+
+This rule can be configured to ban a list of specific types and can suggest alternatives.
+Note that it does not ban the corresponding runtime objects from being used.
+
+## Options
+
+### `types`
+
+An object whose keys are the types you want to ban, and the values are error messages.
+
+The type can either be a type name literal (`OldType`) or a a type name with generic parameter instantiation(s) (`OldType<MyArgument>`).
+
+The values can be:
+
+- A string, which is the error message to be reported; or
+- `false` to specifically un-ban this type (useful when you are using `extendDefaults`); or
+- An object with the following properties:
+  - `message: string`: the message to display when the type is matched.
+  - `fixWith?: string`: a string to replace the banned type with when the fixer is run. If this is omitted, no fix will be done.
+  - `suggest?: string[]`: a list of suggested replacements for the banned type.
+
+Example configuration:
+
+```jsonc
+{
+  "@typescript-eslint/no-restricted-types": [
+    "error",
+    {
+      "types": {
+        // add a custom message to help explain why not to use it
+        "OldType": "Don't use OldType because it is unsafe",
+
+        // add a custom message, and tell the plugin how to fix it
+        "OldAPI": {
+          "message": "Use NewAPI instead",
+          "fixWith": "NewAPI",
+        },
+
+        // add a custom message, and tell the plugin how to suggest a fix
+        "SoonToBeOldAPI": {
+          "message": "Use NewAPI instead",
+          "suggest": ["NewAPIOne", "NewAPITwo"],
+        },
+      },
+    },
+  ],
+}
+```
+
+## When Not To Use It
+
+If you have no need to ban specific types from being used in type annotations, you don't need this rule.
+
+## Related To
+
+- [`no-empty-object-type`](./no-empty-object-type.mdx)
+- [`no-unsafe-function-type`](./no-unsafe-function-type.mdx)
+- [`no-wrapper-object-types`](./no-wrapper-object-types.mdx)

package/docs/rules/no-type-alias.mdx

@@ -19,7 +19,7 @@ TypeScript type aliases are a commonly necessary language feature; banning it al
 :::note
 
 If you want to ban certain classifications of type aliases, consider using [`no-restricted-syntax`](https://eslint.org/docs/latest/rules/no-restricted-syntax).
-See [Troubleshooting & FAQs](/troubleshooting#how-can-i-ban-specific-language-feature).
+See [Troubleshooting & FAQs](/troubleshooting/faqs/general#how-can-i-ban-specific-language-feature).
 
 :::
 

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

@@ -114,11 +114,11 @@ if (someNullCondition !== false) {
 
 ```ts option='{ "allowComparingNullableBooleansToFalse": false }'
 declare const someUndefinedCondition: boolean | undefined;
-if (someUndefinedCondition ?? true) {
+if (!(someUndefinedCondition ?? true)) {
 }
 
 declare const someNullCondition: boolean | null;
-if (!(someNullCondition ?? true)) {
+if (someNullCondition ?? true) {
 }
 ```
 
@@ -127,16 +127,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` |
 
 ## When Not To Use It
 

package/docs/rules/no-unnecessary-parameter-property-assignment.mdx

@@ -0,0 +1,42 @@
+---
+description: 'Disallow unnecessary assignment of constructor property 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/no-unnecessary-parameter-property-assignment** for documentation.
+
+[TypeScript's parameter properties](https://www.typescriptlang.org/docs/handbook/2/classes.html#parameter-properties) allow creating and initializing a member in one place.
+Therefore, in most cases, it is not necessary to assign parameter properties of the same name to members within a constructor.
+
+## Examples
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+class Foo {
+  constructor(public bar: string) {
+    this.bar = bar;
+  }
+}
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+class Foo {
+  constructor(public bar: string) {}
+}
+```
+
+</TabItem>
+</Tabs>
+
+## When Not To Use It
+
+If you don't use parameter properties, you can ignore this rule.

package/docs/rules/no-unnecessary-template-expression.mdx

@@ -0,0 +1,85 @@
+---
+description: 'Disallow unnecessary template expressions.'
+---
+
+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/no-unnecessary-template-expression** for documentation.
+
+This rule reports template literals that contain substitution expressions (also variously referred to as embedded expressions or string interpolations) that are unnecessary and can be simplified.
+
+:::info[Migration from `no-useless-template-literals`]
+
+This rule was formerly known as [`no-useless-template-literals`](./no-useless-template-literals.mdx).
+The new name is a drop-in replacement with identical functionality.
+
+:::
+
+## Examples
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+// Static values can be incorporated into the surrounding template.
+
+const ab1 = `${'a'}${'b'}`;
+const ab2 = `a${'b'}`;
+
+const stringWithNumber = `${'1 + 1 = '}${2}`;
+
+const stringWithBoolean = `${'true is '}${true}`;
+
+// Some simple expressions that are already strings
+// can be rewritten without a template at all.
+
+const text = 'a';
+const wrappedText = `${text}`;
+
+declare const intersectionWithString: string & { _brand: 'test-brand' };
+const wrappedIntersection = `${intersectionWithString}`;
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+// Static values can be incorporated into the surrounding template.
+
+const ab1 = `ab`;
+const ab2 = `ab`;
+
+const stringWithNumber = `1 + 1 = 2`;
+
+const stringWithBoolean = `true is true`;
+
+// Some simple expressions that are already strings
+// can be rewritten without a template at all.
+
+const text = 'a';
+const wrappedText = text;
+
+declare const intersectionWithString: string & { _brand: 'test-brand' };
+const wrappedIntersection = intersectionWithString;
+```
+
+</TabItem>
+</Tabs>
+
+:::info
+This rule does not aim to flag template literals without substitution expressions that could have been written as an ordinary string.
+That is to say, this rule will not help you turn `` `this` `` into `"this"`.
+If you are looking for such a rule, you can configure the [`@stylistic/ts/quotes`](https://eslint.style/rules/ts/quotes) rule to do this.
+:::
+
+## When Not To Use It
+
+When you want to allow string expressions inside template literals.
+
+## Related To
+
+- [`restrict-template-expressions`](./restrict-template-expressions.mdx)
+- [`@stylistic/ts/quotes`](https://eslint.style/rules/ts/quotes)

package/docs/rules/no-unnecessary-type-parameters.mdx

@@ -0,0 +1,115 @@
+---
+description: 'Disallow type parameters that only appear once.'
+---
+
+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/no-unnecessary-type-parameters** for documentation.
+
+This rule forbids type parameters that only appear once in a function, method, or class definition.
+
+Type parameters relate two types.
+If a type parameter only appears once, then it is not relating anything.
+It can usually be replaced with explicit types such as `unknown`.
+
+At best unnecessary type parameters make code harder to read.
+At worst they can be used to disguise unsafe type assertions.
+
+:::warning Early Stage
+This rule was recently added to typescript-eslint and still considered experimental.
+It might change significantly between minor versions.
+Please try it out and give us feedback!
+:::
+
+## Examples
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+function second<A, B>(a: A, b: B): B {
+  return b;
+}
+
+function parseJSON<T>(input: string): T {
+  return JSON.parse(input);
+}
+
+function printProperty<T, K extends keyof T>(obj: T, key: K) {
+  console.log(obj[key]);
+}
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+function second<B>(a: unknown, b: B): B {
+  return b;
+}
+
+function parseJSON(input: string): unknown {
+  return JSON.parse(input);
+}
+
+function printProperty<T>(obj: T, key: keyof T) {
+  console.log(obj[key]);
+}
+
+// T appears twice: in the type of arg and as the return type
+function identity<T>(arg: T): T {
+  return arg;
+}
+
+// T appears twice: "keyof T" and in the inferred return type (T[K]).
+// K appears twice: "key: K" and in the inferred return type (T[K]).
+function getProperty<T, K extends keyof T>(obj: T, key: K) {
+  return obj[key];
+}
+```
+
+</TabItem>
+</Tabs>
+
+## Limitations
+
+Note that this rule allows any type parameter that is used multiple times, even if those uses are via a type argument.
+For example, the following `T` is used multiple times by virtue of being in an `Array`, even though its name only appears once after declaration:
+
+```ts
+declare function createStateHistory<T>(): T[];
+```
+
+This is because the type parameter `T` relates multiple methods in the `T[]` together, making it used more than once.
+
+Therefore, this rule won't report on type parameters used as a type argument.
+That includes type arguments given to global types such as `Array` (including the `T[]` shorthand and in tuples), `Map`, and `Set`.
+
+## When Not To Use It
+
+This rule will report on functions that use type parameters solely to test types, for example:
+
+```ts
+function assertType<T>(arg: T) {}
+
+assertType<number>(123);
+assertType<number>('abc');
+//                 ~~~~~
+// Argument of type 'string' is not assignable to parameter of type 'number'.
+```
+
+If you're using this pattern then you'll want to disable this rule on files that test types.
+
+## Further Reading
+
+- TypeScript handbook: [Type Parameters Should Appear Twice](https://microsoft.github.io/TypeScript-New-Handbook/everything/#type-parameters-should-appear-twice)
+- Effective TypeScript: [The Golden Rule of Generics](https://effectivetypescript.com/2020/08/12/generics-golden-rule/)
+
+## Related To
+
+- eslint-plugin-etc's [`no-misused-generics`](https://github.com/cartant/eslint-plugin-etc/blob/main/docs/rules/no-misused-generics.md)
+- wotan's [`no-misused-generics`](https://github.com/fimbullinter/wotan/blob/master/packages/mimir/docs/no-misused-generics.md)
+- DefinitelyTyped-tools' [`no-unnecessary-generics`](https://github.com/microsoft/DefinitelyTyped-tools/blob/main/packages/eslint-plugin/docs/rules/no-unnecessary-generics.md)

package/docs/rules/no-unsafe-function-type.mdx

@@ -0,0 +1,63 @@
+---
+description: 'Disallow using the unsafe built-in Function type.'
+---
+
+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/no-unsafe-function-type** for documentation.
+
+TypeScript's built-in `Function` type allows being called with any number of arguments and returns type `any`.
+`Function` also allows classes or plain objects that happen to possess all properties of the `Function` class.
+It's generally better to specify function parameters and return types with the function type syntax.
+
+"Catch-all" function types include:
+
+- `() => void`: a function that has no parameters and whose return is ignored
+- `(...args: never) => unknown`: a "top type" for functions that can be assigned any function type, but can't be called
+
+Examples of code for this rule:
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+let noParametersOrReturn: Function;
+noParametersOrReturn = () => {};
+
+let stringToNumber: Function;
+stringToNumber = (text: string) => text.length;
+
+let identity: Function;
+identity = value => value;
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+let noParametersOrReturn: () => void;
+noParametersOrReturn = () => {};
+
+let stringToNumber: (text: string) => number;
+stringToNumber = text => text.length;
+
+let identity: <T>(value: T) => T;
+identity = value => value;
+```
+
+</TabItem>
+</Tabs>
+
+## When Not To Use It
+
+If your project is still onboarding to TypeScript, it might be difficult to fully replace all unsafe `Function` types with more precise function types.
+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.
+
+## Related To
+
+- [`no-empty-object-type`](./no-empty-object-type.mdx)
+- [`no-restricted-types`](./no-restricted-types.mdx)
+- [`no-wrapper-object-types`](./no-wrapper-object-types.mdx)

package/docs/rules/no-unused-expressions.mdx

@@ -10,4 +10,44 @@ import TabItem from '@theme/TabItem';
 > See **https://typescript-eslint.io/rules/no-unused-expressions** for documentation.
 
 This rule extends the base [`eslint/no-unused-expressions`](https://eslint.org/docs/rules/no-unused-expressions) rule.
-It adds support for optional call expressions `x?.()`, and directive in module declarations.
+It supports TypeScript-specific expressions:
+
+- Marks directives in modules declarations (`"use strict"`, etc.) as not unused
+- Marks the following expressions as unused if their wrapped value expressions are unused:
+  - Assertion expressions: `x as number;`, `x!;`, `<number>x;`
+  - Instantiation expressions: `Set<number>;`
+
+Although the type expressions never have runtime side effects (that is, `x!;` is the same as `x;`), they can be used to assert types for testing purposes.
+
+## Examples
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+Set<number>;
+1 as number;
+window!;
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+function getSet() {
+  return Set;
+}
+
+// Funtion calls are allowed, so type expressions that wrap function calls are allowed
+getSet()<number>;
+getSet() as Set<unknown>;
+getSet()!;
+
+// Namespaces can have directives
+namespace A {
+  'use strict';
+}
+```
+
+</TabItem>
+</Tabs>

package/docs/rules/no-unused-vars.mdx

@@ -47,3 +47,8 @@ We generally recommend using `@typescript-eslint/no-unused-vars` to flag unused
 :::tip
 Editors such as VS Code will still generally "grey out" unused variables even if `noUnusedLocals` and `noUnusedParameters` are not enabled in a project.
 :::
+
+Also see similar rules provided by ESLint:
+
+- [`no-unused-private-class-members`](https://eslint.org/docs/latest/rules/no-unused-private-class-members)
+- [`no-unused-labels`](https://eslint.org/docs/latest/rules/no-unused-labels)

package/docs/rules/no-useless-template-literals.mdx

@@ -1,61 +1,5 @@
----
-description: 'Disallow unnecessary template literals.'
----
+:::danger Deprecated
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
+This rule has been renamed to [`no-unnecessary-template-expression`](./no-unnecessary-template-expression.mdx). See [#8544](https://github.com/typescript-eslint/typescript-eslint/issues/8544) for more information.
 
-> 🛑 This file is source code, not the primary documentation location! 🛑
->
-> See **https://typescript-eslint.io/rules/no-useless-template-literals** for documentation.
-
-This rule reports template literals that can be simplified to a normal string literal.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-const ab1 = `${'a'}${'b'}`;
-const ab2 = `a${'b'}`;
-
-const stringWithNumber = `${'1 + 1 = '}${2}`;
-
-const stringWithBoolean = `${'true is '}${true}`;
-
-const text = 'a';
-const wrappedText = `${text}`;
-
-declare const intersectionWithString: string & { _brand: 'test-brand' };
-const wrappedIntersection = `${intersectionWithString}`;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-const ab1 = 'ab';
-const ab2 = 'ab';
-
-const stringWithNumber = `1 + 1 = 2`;
-
-const stringWithBoolean = `true is true`;
-
-const text = 'a';
-const wrappedText = text;
-
-declare const intersectionWithString: string & { _brand: 'test-brand' };
-const wrappedIntersection = intersectionWithString;
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-When you want to allow string expressions inside template literals.
-
-## Related To
-
-- [`restrict-template-expressions`](./restrict-template-expressions.mdx)
+:::