@typescript-eslint/eslint-plugin 8.33.1-alpha.5 → 8.33.1

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

@@ -1,85 +0,0 @@
----
-description: 'Disallow type arguments that are equal to the default.'
----
-
-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-arguments** for documentation.
-
-Type parameters in TypeScript may specify a default value.
-For example:
-
-```ts
-function f<T = number>(/* ... */) {
-  // ...
-}
-```
-
-It is redundant to provide an explicit type parameter equal to that default: e.g. calling `f<number>(...)`.
-This rule reports when an explicitly specified type argument is the default for that type parameter.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-function f<T = number>() {}
-f<number>();
-```
-
-```ts
-function g<T = number, U = string>() {}
-g<string, string>();
-```
-
-```ts
-class C<T = number> {}
-new C<number>();
-
-class D extends C<number> {}
-```
-
-```ts
-interface I<T = number> {}
-class Impl implements I<number> {}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-function f<T = number>() {}
-f();
-f<string>();
-```
-
-```ts
-function g<T = number, U = string>() {}
-g<string>();
-g<number, number>();
-```
-
-```ts
-class C<T = number> {}
-new C();
-new C<string>();
-
-class D extends C {}
-class D extends C<string> {}
-```
-
-```ts
-interface I<T = number> {}
-class Impl implements I<string> {}
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-If you prefer explicitly specifying type parameters even when they are equal to the default, you can skip this rule.

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

@@ -1,97 +0,0 @@
----
-description: 'Disallow type assertions that do not change the type of an expression.'
----
-
-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-assertion** for documentation.
-
-TypeScript can be told an expression is a different type than expected using `as` type assertions.
-Leaving `as` assertions in the codebase increases visual clutter and harms code readability, so it's generally best practice to remove them if they don't change the type of an expression.
-This rule reports when a type assertion does not change the type of an expression.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-const foo = 3;
-const bar = foo!;
-```
-
-```ts
-const foo = <number>(3 + 5);
-```
-
-```ts
-type Foo = number;
-const foo = <Foo>(3 + 5);
-```
-
-```ts
-type Foo = number;
-const foo = (3 + 5) as Foo;
-```
-
-```ts
-function foo(x: number): number {
-  return x!; // unnecessary non-null
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-const foo = <number>3;
-```
-
-```ts
-const foo = 3 as number;
-```
-
-```ts
-let foo = 'foo' as const;
-```
-
-```ts
-function foo(x: number | undefined): number {
-  return x!;
-}
-```
-
-</TabItem>
-</Tabs>
-
-## Options
-
-### `checkLiteralConstAssertions`
-
-{/* insert option description */}
-
-With `@typescript-eslint/no-unnecessary-type-assertion: ["error", { checkLiteralConstAssertions: true }]`, the following is **incorrect** code:
-
-```ts option='{ "checkLiteralConstAssertions": true }' showPlaygroundButton
-const foo = 'foo' as const;
-```
-
-See [#8721 False positives for "as const" assertions (issue comment)](https://github.com/typescript-eslint/typescript-eslint/issues/8721#issuecomment-2145291966) for more information on this option.
-
-### `typesToIgnore`
-
-{/* insert option description */}
-
-With `@typescript-eslint/no-unnecessary-type-assertion: ["error", { typesToIgnore: ['Foo'] }]`, the following is **correct** code:
-
-```ts option='{ "typesToIgnore": ["Foo"] }' showPlaygroundButton
-type Foo = 3;
-const foo: Foo = 3;
-```
-
-## When Not To Use It
-
-If you don't care about having no-op type assertions in your code, then you can turn off this rule.

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

@@ -1,61 +0,0 @@
----
-description: 'Disallow unnecessary constraints on generic 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-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 `unknown`.
-It is therefore redundant to `extend` from `any` or `unknown`.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```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>() {}
-}
-
-const QuuxAny = <T extends any>() => {};
-
-function QuuzAny<T extends any>() {}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-interface Foo<T> {}
-
-type Bar<T> = {};
-
-class Baz<T> {
-  qux<U>() {}
-}
-
-const Quux = <T>() => {};
-
-function Quuz<T>() {}
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-If you don't care about the specific styles of your type constraints, or never use them in the first place, then you will not need this rule.

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

@@ -1,79 +0,0 @@
----
-description: 'Disallow conversion idioms when they do not change the type or value of the expression.'
----
-
-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-conversion** for documentation.
-
-JavaScript provides several commonly used idioms to convert values to a specific type:
-
-- Primitive coercion (e.g. `Boolean(value)`, `String(value)`): using a built-in primitive function
-- String concatenation (e.g. `value + ''`): turning a value into a string
-- Unary coercion (e.g. `+value`, `!!value`): using a built-in operator
-- The `.toString()` method defined on many types
-
-These conversions are unnecessary if the value is already of that type.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-String('123');
-'123'.toString();
-'' + '123';
-'123' + '';
-
-Number(123);
-+123;
-~~123;
-
-Boolean(true);
-!!true;
-
-BigInt(BigInt(1));
-
-let str = '123';
-str += '';
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-function foo(bar: string | number) {
-  String(bar);
-  bar.toString();
-  '' + bar;
-  bar + '';
-
-  Number(bar);
-  +bar;
-  ~~bar;
-
-  Boolean(bar);
-  !!bar;
-
-  BigInt(1);
-
-  bar += '';
-}
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-If you don't care about having no-op type conversions in your code, then you can turn off this rule.
-If you have types which are not accurate, then this rule might cause you to remove conversions that you actually do need.
-
-## Related To
-
-- [no-unnecessary-type-assertion](./no-unnecessary-type-assertion.mdx)
-- [no-useless-template-literals](./no-useless-template-literals.mdx)

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

@@ -1,255 +0,0 @@
----
-description: "Disallow type parameters that aren't used multiple times."
----
-
-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 aren't used multiple times in a function, method, or class definition.
-
-Type parameters relate two types.
-If a type parameter is only used 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
-This rule was recently added, and has a surprising amount of hidden complexity compared to most of our rules. If you encounter unexpected behavior with it, please check closely the [Limitations](#limitations) and [FAQ](#faq) sections below and our [issue tracker](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+no-unnecessary-type-parameters).
-If you don't see your case covered, please [reach out to us](https://typescript-eslint.io/contributing/issues)!
-:::
-
-## 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 `T[]` (`Array<T>`) together, making it used more than once.
-
-Therefore, this rule won't report on type parameters used as a type argument.
-This includes type arguments provided to global types such as `Array`, `Map`, and `Set` that have multiple methods and properties that can change values based on the type parameter.
-
-On the other hand, readonly and fixed array-likes such as `readonly T[]`, `ReadonlyArray`, and tuples such as `[T]` are special cases that are specifically reported on when used as input types, or as `readonly` output types.
-The following example will be reported because `T` is used only once as type argument for the `ReadonlyArray` global type:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-declare function length<T>(array: ReadonlyArray<T>): number;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-declare function length(array: ReadonlyArray<unknown>): number;
-```
-
-</TabItem>
-</Tabs>
-
-## FAQ
-
-### The return type is only used as an input, so why isn't the rule reporting?
-
-One common reason that this might be the case is when the return type is not specified explicitly.
-The rule uses uses type information to count implicit usages of the type parameter in the function signature, including in the inferred return type.
-For example, the following function...
-
-```ts
-function identity<T>(arg: T) {
-  return arg;
-}
-```
-
-...implicitly has a return type of `T`. Therefore, the type parameter `T` is used twice, and the rule will not report this function.
-
-For other reasons the rule might not be reporting, be sure to check the [Limitations section](#limitations) and other FAQs.
-
-### I'm using the type parameter inside the function, so why is the rule reporting?
-
-You might be surprised to that the rule reports on a function like this:
-
-```ts
-function log<T extends string>(string1: T): void {
-  const string2: T = string1;
-  console.log(string2);
-}
-```
-
-After all, the type parameter `T` relates the input `string1` and the local variable `string2`, right?
-However, this usage is unnecessary, since we can achieve the same results by replacing all usages of the type parameter with its constraint.
-That is to say, the function can always be rewritten as:
-
-```ts
-function log(string1: string): void {
-  const string2: string = string1;
-  console.log(string2);
-}
-```
-
-Therefore, this rule only counts usages of a type parameter in the _signature_ of a function, method, or class, but not in the implementation. See also [#9735](https://github.com/typescript-eslint/typescript-eslint/issues/9735)
-
-### Why am I getting TypeScript errors saying "Object literal may only specify known properties" after removing an unnecessary type parameter?
-
-Suppose you have a situation like the following, which will trigger the rule to report.
-
-```ts
-interface SomeProperties {
-  foo: string;
-}
-
-// T is only used once, so the rule will report.
-function serialize<T extends SomeProperties>(x: T): string {
-  return JSON.stringify(x);
-}
-
-serialize({ foo: 'bar', anotherProperty: 'baz' });
-```
-
-If we remove the unnecessary type parameter, we'll get an error:
-
-```ts
-function serialize(x: SomeProperties): string {
-  return JSON.stringify(x);
-}
-
-// TS Error: Object literal may only specify known properties, and 'anotherProperty' does not exist in type 'SomeProperties'.
-serialize({ foo: 'bar', anotherProperty: 'baz' });
-```
-
-This is because TypeScript figures it's _usually_ an error to explicitly provide excess properties in a location that expects a specific type.
-See [the TypeScript handbook's section on excess property checks](https://www.typescriptlang.org/docs/handbook/2/objects.html#excess-property-checks) for further discussion.
-
-To resolve this, you have two approaches to choose from.
-
-1. If it doesn't make sense to accept excess properties in your function, you'll want to fix the errors at the call sites. Usually, you can simply remove any excess properties where the function is called.
-2. Otherwise, if you do want your function to accept excess properties, you can modify the parameter type in order to allow excess properties explicitly by using an [index signature](https://www.typescriptlang.org/docs/handbook/2/objects.html#index-signatures):
-
-   ```ts
-   interface SomeProperties {
-     foo: string;
-
-     // This allows any other properties.
-     // You may wish to make these types more specific according to your use case.
-     [key: PropertKey]: unknown;
-   }
-
-   function serialize(x: SomeProperties): string {
-     return JSON.stringify(x);
-   }
-
-   // No error!
-   serialize({ foo: 'bar', anotherProperty: 'baz' });
-   ```
-
-Which solution is appropriate is a case-by-case decision, depending on the intended use case of your function.
-
-### I have a complex scenario that is reported by the rule, but I can't see how to remove the type parameter. What should I do?
-
-Sometimes, you may be able to rewrite the code by reaching for some niche TypeScript features, such as [the `NoInfer<T>` utility type](https://www.typescriptlang.org/docs/handbook/utility-types.html#noinfertype) (see [#9751](https://github.com/typescript-eslint/typescript-eslint/issues/9751)).
-
-But, quite possibly, you've hit an edge case where the type is being used in a subtle way that the rule doesn't account for.
-For example, the following arcane code is a way of testing whether two types are equal, and will be reported by the rule (see [#9709](https://github.com/typescript-eslint/typescript-eslint/issues/9709)):
-
-{/* prettier-ignore */}
-```ts
-type Compute<A> = A extends Function ? A : { [K in keyof A]: Compute<A[K]> };
-type Equal<X, Y> =
-  (<T1>() => T1 extends Compute<X> ? 1 : 2) extends
-    (<T2>() => T2 extends Compute<Y> ? 1 : 2)
-  ? true
-  : false;
-```
-
-In this case, the function types created within the `Equal` type are never expected to be assigned to; they're just created for the purpose of type system manipulations.
-This usage is not what the rule is intended to analyze.
-
-Use eslint-disable comments as appropriate to suppress the rule in these kinds of cases.
-
-{/* TODO - include an FAQ entry regarding instantiation expressions once the conversation in https://github.com/typescript-eslint/typescript-eslint/pull/9536#discussion_r1705850744 is done */}
-
-## 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-argument.mdx

@@ -1,98 +0,0 @@
----
-description: 'Disallow calling a function with a value with type `any`.'
----
-
-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-argument** for documentation.
-
-The `any` type in TypeScript is a dangerous "escape hatch" from the type system.
-Using `any` disables many type checking rules and is generally best used only as a last resort or when prototyping code.
-
-Despite your best intentions, the `any` type can sometimes leak into your codebase.
-Calling a function with an `any` typed argument creates a potential safety hole and source of bugs.
-
-This rule disallows calling a function with `any` in its arguments.
-That includes spreading arrays or tuples with `any` typed elements as function arguments.
-
-This rule also compares generic type argument types to ensure you don't pass an unsafe `any` in a generic position to a receiver that's expecting a specific type.
-For example, it will error if you pass `Set<any>` as an argument to a parameter declared as `Set<string>`.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-declare function foo(arg1: string, arg2: number, arg3: string): void;
-
-const anyTyped = 1 as any;
-
-foo(...anyTyped);
-foo(anyTyped, 1, 'a');
-
-const anyArray: any[] = [];
-foo(...anyArray);
-
-const tuple1 = ['a', anyTyped, 'b'] as const;
-foo(...tuple1);
-
-const tuple2 = [1] as const;
-foo('a', ...tuple2, anyTyped);
-
-declare function bar(arg1: string, arg2: number, ...rest: string[]): void;
-const x = [1, 2] as [number, ...number[]];
-bar('a', ...x, anyTyped);
-
-declare function baz(arg1: Set<string>, arg2: Map<string, string>): void;
-baz(new Set<any>(), new Map<any, string>());
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-declare function foo(arg1: string, arg2: number, arg3: string): void;
-
-foo('a', 1, 'b');
-
-const tuple1 = ['a', 1, 'b'] as const;
-foo(...tuple1);
-
-declare function bar(arg1: string, arg2: number, ...rest: string[]): void;
-const array: string[] = ['a'];
-bar('a', 1, ...array);
-
-declare function baz(arg1: Set<string>, arg2: Map<string, string>): void;
-baz(new Set<string>(), new Map<string, string>());
-```
-
-</TabItem>
-</Tabs>
-
-There are cases where the rule allows passing an argument of `any` to `unknown`.
-
-Example of `any` to `unknown` assignment that are allowed:
-
-```ts showPlaygroundButton
-declare function foo(arg1: unknown, arg2: Set<unknown>, arg3: unknown[]): void;
-foo(1 as any, new Set<any>(), [] as any[]);
-```
-
-## When Not To Use It
-
-If your codebase has many existing `any`s or areas of unsafe code, it may be difficult to enable this rule.
-It may be easier to skip the `no-unsafe-*` rules pending increasing type safety in unsafe areas of your project.
-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
-
-- [Avoiding `any`s with Linting and TypeScript](/blog/avoiding-anys)
-- [`no-explicit-any`](./no-explicit-any.mdx)
-- [`no-unsafe-assignment`](./no-unsafe-assignment.mdx)
-- [`no-unsafe-call`](./no-unsafe-call.mdx)
-- [`no-unsafe-member-access`](./no-unsafe-member-access.mdx)
-- [`no-unsafe-return`](./no-unsafe-return.mdx)