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

package/docs/rules/no-unsafe-assignment.mdx

@@ -1,101 +0,0 @@
----
-description: 'Disallow assigning a value with type `any` to variables and properties.'
----
-
-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-assignment** 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.
-Assigning an `any` typed value to a variable can be hard to pick up on, particularly if it leaks in from an external library.
-
-This rule disallows assigning `any` to a variable, and assigning `any[]` to an array destructuring.
-
-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 assign `Set<any>` to a variable declared as `Set<string>`.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-const x = 1 as any,
-  y = 1 as any;
-const [x] = 1 as any;
-const [x] = [] as any[];
-const [x] = [1 as any];
-[x] = [1] as [any];
-
-function foo(a = 1 as any) {}
-class Foo {
-  constructor(private a = 1 as any) {}
-}
-class Foo {
-  private a = 1 as any;
-}
-
-// generic position examples
-const x: Set<string> = new Set<any>();
-const x: Map<string, string> = new Map<string, any>();
-const x: Set<string[]> = new Set<any[]>();
-const x: Set<Set<Set<string>>> = new Set<Set<Set<any>>>();
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-const x = 1,
-  y = 1;
-const [x] = [1];
-[x] = [1] as [number];
-
-function foo(a = 1) {}
-class Foo {
-  constructor(private a = 1) {}
-}
-class Foo {
-  private a = 1;
-}
-
-// generic position examples
-const x: Set<string> = new Set<string>();
-const x: Map<string, string> = new Map<string, string>();
-const x: Set<string[]> = new Set<string[]>();
-const x: Set<Set<Set<string>>> = new Set<Set<Set<string>>>();
-```
-
-</TabItem>
-</Tabs>
-
-There are cases where the rule allows assignment of `any` to `unknown`.
-
-Example of `any` to `unknown` assignment that are allowed:
-
-```ts showPlaygroundButton
-const x: unknown = y as any;
-const x: unknown[] = y as any[];
-const x: Set<unknown> = y as Set<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-argument`](./no-unsafe-argument.mdx)
-- [`no-unsafe-call`](./no-unsafe-call.mdx)
-- [`no-unsafe-member-access`](./no-unsafe-member-access.mdx)
-- [`no-unsafe-return`](./no-unsafe-return.mdx)

package/docs/rules/no-unsafe-call.mdx

@@ -1,120 +0,0 @@
----
-description: 'Disallow calling 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-call** 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 an `any`-typed value as a function creates a potential type safety hole and source of bugs in your codebase.
-
-This rule disallows calling any value that is typed as `any`.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-declare const anyVar: any;
-declare const nestedAny: { prop: any };
-
-anyVar();
-anyVar.a.b();
-
-nestedAny.prop();
-nestedAny.prop['a']();
-
-new anyVar();
-new nestedAny.prop();
-
-anyVar`foo`;
-nestedAny.prop`foo`;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-declare const typedVar: () => void;
-declare const typedNested: { prop: { a: () => void } };
-
-typedVar();
-typedNested.prop.a();
-
-(() => {})();
-
-new Map();
-
-String.raw`foo`;
-```
-
-</TabItem>
-</Tabs>
-
-## The Unsafe `Function` Type
-
-The `Function` type is behaves almost identically to `any` when called, so this rule also disallows calling values of type `Function`.
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-const f: Function = () => {};
-f();
-```
-
-</TabItem>
-</Tabs>
-
-Note that whereas [no-unsafe-function-type](./no-unsafe-function-type.mdx) helps prevent the _creation_ of `Function` types, this rule helps prevent the unsafe _use_ of `Function` types, which may creep into your codebase without explicitly referencing the `Function` type at all.
-See, for example, the following code:
-
-```ts
-function callUnsafe(maybeFunction: unknown): string {
-  if (typeof maybeFunction === 'function') {
-    // TypeScript allows this, but it's completely unsound.
-    return maybeFunction('call', 'with', 'any', 'args');
-  }
-  // etc
-}
-```
-
-In this sort of situation, beware that there is no way to guarantee with runtime checks that a value is safe to call.
-If you _really_ want to call a value whose type you don't know, your best best is to use a `try`/`catch` and suppress any TypeScript or linter errors that get in your way.
-
-```ts
-function callSafe(maybeFunction: unknown): void {
-  try {
-    // intentionally unsound type assertion
-    (maybeFunction as () => unknown)();
-  } catch (e) {
-    console.error(
-      'Function either could not be called or threw an error when called: ',
-      e,
-    );
-  }
-}
-```
-
-## 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-argument`](./no-unsafe-argument.mdx)
-- [`no-unsafe-assignment`](./no-unsafe-assignment.mdx)
-- [`no-unsafe-member-access`](./no-unsafe-member-access.mdx)
-- [`no-unsafe-return`](./no-unsafe-return.mdx)

package/docs/rules/no-unsafe-declaration-merging.mdx

@@ -1,65 +0,0 @@
----
-description: 'Disallow unsafe declaration merging.'
----
-
-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-declaration-merging** for documentation.
-
-TypeScript's "declaration merging" supports merging separate declarations with the same name.
-
-Declaration merging between classes and interfaces is unsafe.
-The TypeScript compiler doesn't check whether properties are initialized, which can lead to TypeScript not detecting code that will cause runtime errors.
-
-```ts
-interface Foo {
-  nums: number[];
-}
-
-class Foo {}
-
-const foo = new Foo();
-
-foo.nums.push(1); // Runtime Error: Cannot read properties of undefined.
-```
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-interface Foo {}
-
-class Foo {}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-interface Foo {}
-class Bar implements Foo {}
-
-namespace Baz {}
-namespace Baz {}
-enum Baz {}
-
-namespace Qux {}
-function Qux() {}
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-If your project intentionally defines classes and interfaces with unsafe declaration merging patterns, this rule might not be for you.
-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
-
-- [Declaration Merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html)

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

@@ -1,98 +0,0 @@
----
-description: 'Disallow comparing an enum value with a non-enum value.'
----
-
-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-enum-comparison** for documentation.
-
-The TypeScript compiler can be surprisingly lenient when working with enums.
-While overt safety problems with enums were [resolved in TypeScript 5.0](https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/#all-enums-are-union-enums), some logical pitfalls remain permitted.
-For example, it is allowed to compare enum values against non-enum values:
-
-```ts
-enum Vegetable {
-  Asparagus = 'asparagus',
-}
-
-declare const vegetable: Vegetable;
-
-vegetable === 'asparagus'; // No error
-```
-
-The above code snippet should instead be written as `vegetable === Vegetable.Asparagus`.
-Allowing non-enums in comparisons subverts the point of using enums in the first place.
-By enforcing comparisons with properly typed enums:
-
-- It makes a codebase more resilient to enum members changing values.
-- It allows for code IDEs to use the "Rename Symbol" feature to quickly rename an enum.
-- It aligns code to the proper enum semantics of referring to them by name and treating their values as implementation details.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-enum Fruit {
-  Apple,
-}
-
-declare let fruit: Fruit;
-
-// bad - comparison between enum and explicit value instead of named enum member
-fruit === 0;
-
-enum Vegetable {
-  Asparagus = 'asparagus',
-}
-
-declare let vegetable: Vegetable;
-
-// bad - comparison between enum and explicit value instead of named enum member
-vegetable === 'asparagus';
-
-declare let anyString: string;
-
-// bad - comparison between enum and non-enum value
-anyString === Vegetable.Asparagus;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-enum Fruit {
-  Apple,
-}
-
-declare let fruit: Fruit;
-
-fruit === Fruit.Apple;
-
-enum Vegetable {
-  Asparagus = 'asparagus',
-}
-
-declare let vegetable: Vegetable;
-
-vegetable === Vegetable.Asparagus;
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-If you don't mind enums being treated as a namespaced bag of values, rather than opaque identifiers, you likely don't need this rule.
-
-Sometimes, you may want to ingest a value from an API or user input, then use it as an enum throughout your application.
-While validating the input, it may be appropriate to disable the rule.
-Alternately, you might consider making use of a validation library like [Zod](https://zod.dev/?id=native-enums).
-See further discussion of this topic in [#8557](https://github.com/typescript-eslint/typescript-eslint/issues/8557).
-
-Finally, in the rare case of relying on an third party enums that are only imported as `type`s, it may be difficult to adhere to 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.

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

@@ -1,65 +0,0 @@
----
-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
-
-- [Avoiding `any`s with Linting and TypeScript](/blog/avoiding-anys)
-- [`no-empty-object-type`](./no-empty-object-type.mdx)
-- [`no-restricted-types`](./no-restricted-types.mdx)
-- [`no-unsafe-call`](./no-unsafe-call.mdx)
-- [`no-wrapper-object-types`](./no-wrapper-object-types.mdx)

package/docs/rules/no-unsafe-member-access.mdx

@@ -1,81 +0,0 @@
----
-description: 'Disallow member access on 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-member-access** 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.
-Accessing a member of an `any`-typed value creates a potential type safety hole and source of bugs in your codebase.
-
-This rule disallows member access on any variable that is typed as `any`.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-declare const anyVar: any;
-declare const nestedAny: { prop: any };
-
-anyVar.a;
-anyVar.a.b;
-anyVar['a'];
-anyVar['a']['b'];
-
-nestedAny.prop.a;
-nestedAny.prop['a'];
-
-const key = 'a';
-nestedAny.prop[key];
-
-// Using an any to access a member is unsafe
-const arr = [1, 2, 3];
-arr[anyVar];
-nestedAny[anyVar];
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-declare const properlyTyped: { prop: { a: string } };
-
-properlyTyped.prop.a;
-properlyTyped.prop['a'];
-
-const key = 'a';
-properlyTyped.prop[key];
-
-const arr = [1, 2, 3];
-arr[1];
-let idx = 1;
-arr[idx];
-arr[idx++];
-```
-
-</TabItem>
-</Tabs>
-
-## 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-argument`](./no-unsafe-argument.mdx)
-- [`no-unsafe-assignment`](./no-unsafe-assignment.mdx)
-- [`no-unsafe-call`](./no-unsafe-call.mdx)
-- [`no-unsafe-return`](./no-unsafe-return.mdx)

package/docs/rules/no-unsafe-return.mdx

@@ -1,126 +0,0 @@
----
-description: 'Disallow returning a value with type `any` from a function.'
----
-
-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-return** 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.
-Returning an `any`-typed value from a function creates a potential type safety hole and source of bugs in your codebase.
-
-This rule disallows returning `any` or `any[]` from a function and returning `Promise<any>` from an async function.
-
-This rule also compares generic type argument types to ensure you don't return an unsafe `any` in a generic position to a function that's expecting a specific type.
-For example, it will error if you return `Set<any>` from a function declared as returning `Set<string>`.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-function foo1() {
-  return 1 as any;
-}
-function foo2() {
-  return Object.create(null);
-}
-const foo3 = () => {
-  return 1 as any;
-};
-const foo4 = () => Object.create(null);
-
-function foo5() {
-  return [] as any[];
-}
-function foo6() {
-  return [] as Array<any>;
-}
-function foo7() {
-  return [] as readonly any[];
-}
-function foo8() {
-  return [] as Readonly<any[]>;
-}
-const foo9 = () => {
-  return [] as any[];
-};
-const foo10 = () => [] as any[];
-
-const foo11 = (): string[] => [1, 2, 3] as any[];
-
-async function foo13() {
-  return Promise.resolve({} as any);
-}
-
-// generic position examples
-function assignability1(): Set<string> {
-  return new Set<any>([1]);
-}
-type TAssign = () => Set<string>;
-const assignability2: TAssign = () => new Set<any>([true]);
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-function foo1() {
-  return 1;
-}
-function foo2() {
-  return Object.create(null) as Record<string, unknown>;
-}
-
-const foo3 = () => [];
-const foo4 = () => ['a'];
-
-async function foo5() {
-  return Promise.resolve(1);
-}
-
-function assignability1(): Set<string> {
-  return new Set<string>(['foo']);
-}
-type TAssign = () => Set<string>;
-const assignability2: TAssign = () => new Set(['foo']);
-```
-
-</TabItem>
-</Tabs>
-
-There are cases where the rule allows to return `any` to `unknown`.
-
-Examples of `any` to `unknown` return that are allowed:
-
-```ts showPlaygroundButton
-function foo1(): unknown {
-  return JSON.parse(singleObjString); // Return type for JSON.parse is any.
-}
-
-function foo2(): unknown[] {
-  return [] 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-argument`](./no-unsafe-argument.mdx)
-- [`no-unsafe-assignment`](./no-unsafe-assignment.mdx)
-- [`no-unsafe-call`](./no-unsafe-call.mdx)
-- [`no-unsafe-member-access`](./no-unsafe-member-access.mdx)