@typescript-eslint/eslint-plugin 8.0.0-alpha.6 → 8.0.0-alpha.60

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

@@ -0,0 +1,109 @@
+---
+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.
+
+## 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)
+:::

package/docs/rules/no-var-requires.mdx

@@ -9,6 +9,12 @@ import TabItem from '@theme/TabItem';
 >
 > See **https://typescript-eslint.io/rules/no-var-requires** for documentation.
 
+:::danger Deprecated
+
+This rule has been deprecated in favour of the [`@typescript-eslint/no-require-imports`](./no-require-imports.mdx) rule.
+
+:::
+
 In other words, the use of forms such as `var foo = require("foo")` are banned. Instead use ES6 style imports or `import foo = require("foo")` imports.
 
 ## Examples

package/docs/rules/no-wrapper-object-types.mdx

@@ -0,0 +1,75 @@
+---
+description: 'Disallow using confusing built-in primitive class wrappers.'
+---
+
+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-wrapper-object-types** for documentation.
+
+TypeScript defines several confusing pairs of types that look very similar to each other, but actually mean different things: `boolean`/`Boolean`, `number`/`Number`, `string`/`String`, `bigint`/`BigInt`, `symbol`/`Symbol`, `object`/`Object`.
+In general, only the lowercase variant is appropriate to use.
+Therefore, this rule enforces that you only use the lowercase variant.
+
+JavaScript has [8 data types](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures) at runtime, and these are described in TypeScript by the lowercase types `undefined`, `null`, `boolean`, `number`, `string`, `bigint`, `symbol`, and `object`.
+
+As for the uppercase types, these are _structural types_ which describe JavaScript "wrapper" objects for each of the data types, such as [`Boolean`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) and [`Number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number).
+Additionally, due to the quirks of structural typing, the corresponding primitives are _also_ assignable to these uppercase types, since they have the same "shape".
+
+It is a universal best practice to work directly with the built-in primitives, like `0`, rather than objects that "look like" the corresponding primitive, like `new Number(0)`.
+
+- Primitives have the expected value semantics with `==` and `===` equality checks, whereas their object counterparts are compared by reference.
+  That is to say, `"str" === "str"` but `new String("str") !== new String("str")`.
+- Primitives have well-known behavior around truthiness/falsiness which is common to rely on, whereas all objects are truthy, regardless of the wrapped value (e.g. `new Boolean(false)` is truthy).
+- TypeScript only allows arithmetic operations (e.g. `x - y`) to be performed on numeric primitives, not objects.
+
+As a result, using the lowercase type names like `number` in TypeScript types instead of the uppercase names like `Number` is a better practice that describes code more accurately.
+
+Examples of code for this rule:
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+let myBigInt: BigInt;
+let myBoolean: Boolean;
+let myNumber: Number;
+let myString: String;
+let mySymbol: Symbol;
+
+let myObject: Object = 'allowed by TypeScript';
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+let myBigint: bigint;
+let myBoolean: boolean;
+let myNumber: number;
+let myString: string;
+let mySymbol: symbol;
+
+let myObject: object = "Type 'string' is not assignable to type 'object'.";
+```
+
+</TabItem>
+</Tabs>
+
+## When Not To Use It
+
+If your project is a rare one that intentionally deals with the class equivalents of primitives, it might not be worthwhile to use this rule.
+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
+
+- [MDN documentation on primitives](https://developer.mozilla.org/en-US/docs/Glossary/Primitive)
+- [MDN documentation on `string` primitives and `String` objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_primitives_and_string_objects)
+
+## Related To
+
+- [`no-empty-object-type`](./no-empty-object-type.mdx)
+- [`no-restricted-types`](./no-restricted-types.mdx)
+- [`no-unsafe-function-type`](./no-unsafe-function-type.mdx)

package/docs/rules/only-throw-error.mdx

@@ -14,6 +14,13 @@ The fundamental benefit of `Error` objects is that they automatically keep track
 
 This rule restricts what can be thrown as an exception.
 
+:::info[Migration from `no-throw-literal`]
+
+This rule was formerly known as `no-throw-literal`.
+The new name is a drop-in replacement with identical functionality.
+
+:::
+
 ## Examples
 
 This rule is aimed at maintaining consistency when throwing exception by disallowing to throw literals and other expressions which cannot possibly be an `Error` object.

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

@@ -142,11 +142,12 @@ interface Foo {
 
 Some complex types cannot easily be made readonly, for example the `HTMLElement` type or the `JQueryStatic` type from `@types/jquery`. This option allows you to globally disable reporting of such types.
 
-Each item must be one of:
+This option takes an array of type specifiers to ignore.
+Each item in the array must have one of the following forms:
 
-- A type defined in a file (`{from: "file", name: "Foo", path: "src/foo-file.ts"}` with `path` being an optional path relative to the project root directory)
-- A type from the default library (`{from: "lib", name: "Foo"}`)
-- A type from a package (`{from: "package", name: "Foo", package: "foo-lib"}`, this also works for types defined in a typings package).
+- A type defined in a file (`{ from: "file", name: "Foo", path: "src/foo-file.ts" }` with `path` being an optional path relative to the project root directory)
+- A type from the default library (`{ from: "lib", name: "Foo" }`)
+- A type from a package (`{ from: "package", name: "Foo", package: "foo-lib" }`, this also works for types defined in a typings package).
 
 Additionally, a type may be defined just as a simple string, which then matches the type independently of its origin.
 
@@ -401,3 +402,8 @@ 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.
+
+This rule is very strict on what it considers mutable.
+Many types that describe themselves as readonly are considered mutable because they have mutable properties such as arrays or tuples.
+To work around these limitations, you might need to use the rule's options.
+In particular, the [`allow` option](#allow) can explicitly mark a type as readonly.

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

@@ -9,6 +9,16 @@ import TabItem from '@theme/TabItem';
 >
 > See **https://typescript-eslint.io/rules/prefer-ts-expect-error** for documentation.
 
+:::danger Deprecated
+
+This rule has been deprecated in favor of [`@typescript-eslint/ban-ts-comment`](./ban-ts-comment.mdx).
+This rule (`@typescript-eslint/prefer-ts-expect-error`) will be removed in a future major version of typescript-eslint.
+
+When it was first created, `@typescript-eslint/ban-ts-comment` rule was only responsible for suggesting to remove `@ts-ignore` directive.
+It was later updated to suggest replacing `@ts-ignore` with `@ts-expect-error` directive, so that it replaces `@typescript-eslint/prefer-ts-expect-error` entirely.
+
+:::
+
 TypeScript allows you to suppress all errors on a line by placing a comment starting with `@ts-ignore` or `@ts-expect-error` immediately before the erroring line.
 The two directives work the same, except `@ts-expect-error` causes a type error if placed before a line that's not erroring in the first place.
 

package/docs/rules/require-await.mdx

@@ -1,5 +1,5 @@
 ---
-description: 'Disallow async functions which have no `await` expression.'
+description: 'Disallow async functions which do not return promises and have no `await` expression.'
 ---
 
 import Tabs from '@theme/Tabs';
@@ -10,7 +10,7 @@ import TabItem from '@theme/TabItem';
 > See **https://typescript-eslint.io/rules/require-await** for documentation.
 
 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`.
+It uses type information to allow promise-returning functions to be marked as `async` without containing an `await` expression.
 
 ## Examples
 

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

@@ -10,7 +10,7 @@ import TabItem from '@theme/TabItem';
 > See **https://typescript-eslint.io/rules/restrict-template-expressions** for documentation.
 
 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.
+The default `toString()` method of objects uses the format `"[object Object]"`, which is often not what was intended.
 This rule reports on values used in a template literal string that aren't strings, optionally allowing other data types that provide useful stringification results.
 
 :::note