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

package/docs/rules/typedef.mdx

@@ -1,350 +0,0 @@
----
-description: 'Require type annotations in certain places.'
----
-
-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/typedef** for documentation.
-
-:::caution
-
-This is an old, deprecated rule.
-It will be removed in a future major version of typescript-eslint.
-
-Requiring type annotations unnecessarily can be cumbersome to maintain and generally reduces code readability.
-TypeScript is often better at inferring types than easily written type annotations would allow.
-
-**Instead of enabling `typedef`, it is generally recommended to use the `--noImplicitAny` and `--strictPropertyInitialization` compiler options to enforce type annotations only when useful.**
-
-:::
-
-TypeScript cannot always infer types for all places in code.
-Some locations require type annotations for their types to be inferred.
-
-This rule can enforce type annotations in locations regardless of whether they're required.
-This is typically used to maintain consistency for element types that sometimes require them.
-
-```ts
-class ContainsText {
-  // There must be a type annotation here to infer the type
-  delayedText: string;
-
-  // `typedef` requires a type annotation here to maintain consistency
-  immediateTextExplicit: string = 'text';
-
-  // This is still a string type because of its initial value
-  immediateTextImplicit = 'text';
-}
-```
-
-> To enforce type definitions existing on call signatures, use [`explicit-function-return-type`](./explicit-function-return-type.mdx), or [`explicit-module-boundary-types`](./explicit-module-boundary-types.mdx).
-
-## Options
-
-For example, with the following configuration:
-
-```json
-{
-  "rules": {
-    "@typescript-eslint/typedef": [
-      "error",
-      {
-        "arrowParameter": true,
-        "variableDeclaration": true
-      }
-    ]
-  }
-}
-```
-
-- Type annotations on arrow function parameters are required
-- Type annotations on variables are required
-
-### `arrayDestructuring`
-
-{/* insert option description */}
-
-Examples of code with `{ "arrayDestructuring": true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "arrayDestructuring": true }'
-const [a] = [1];
-const [b, c] = [1, 2];
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "arrayDestructuring": true }'
-const [a]: number[] = [1];
-const [b]: [number] = [2];
-const [c, d]: [boolean, string] = [true, 'text'];
-
-for (const [key, val] of new Map([['key', 1]])) {
-}
-```
-
-</TabItem>
-</Tabs>
-
-### `arrowParameter`
-
-{/* insert option description */}
-
-Examples of code with `{ "arrowParameter": true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "arrowParameter": true }'
-const logsSize = size => console.log(size);
-
-['hello', 'world'].map(text => text.length);
-
-const mapper = {
-  map: text => text + '...',
-};
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "arrowParameter": true }'
-const logsSize = (size: number) => console.log(size);
-
-['hello', 'world'].map((text: string) => text.length);
-
-const mapper = {
-  map: (text: string) => text + '...',
-};
-```
-
-</TabItem>
-</Tabs>
-
-### `memberVariableDeclaration`
-
-{/* insert option description */}
-
-Examples of code with `{ "memberVariableDeclaration": true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "memberVariableDeclaration": true }'
-class ContainsText {
-  delayedText;
-  immediateTextImplicit = 'text';
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "memberVariableDeclaration": true }'
-class ContainsText {
-  delayedText: string;
-  immediateTextImplicit: string = 'text';
-}
-```
-
-</TabItem>
-</Tabs>
-
-### `objectDestructuring`
-
-{/* insert option description */}
-
-Examples of code with `{ "objectDestructuring": true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "objectDestructuring": true }'
-const { length } = 'text';
-const [b, c] = Math.random() ? [1, 2] : [3, 4];
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "objectDestructuring": true }'
-const { length }: { length: number } = 'text';
-const [b, c]: [number, number] = Math.random() ? [1, 2] : [3, 4];
-
-for (const { key, val } of [{ key: 'key', val: 1 }]) {
-}
-```
-
-</TabItem>
-</Tabs>
-
-### `parameter`
-
-{/* insert option description */}
-
-Examples of code with `{ "parameter": true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "parameter": true }'
-function logsSize(size): void {
-  console.log(size);
-}
-
-const doublesSize = function (size): number {
-  return size * 2;
-};
-
-const divider = {
-  curriesSize(size): number {
-    return size;
-  },
-  dividesSize: function (size): number {
-    return size / 2;
-  },
-};
-
-class Logger {
-  log(text): boolean {
-    console.log('>', text);
-    return true;
-  }
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "parameter": true }'
-function logsSize(size: number): void {
-  console.log(size);
-}
-
-const doublesSize = function (size: number): number {
-  return size * 2;
-};
-
-const divider = {
-  curriesSize(size: number): number {
-    return size;
-  },
-  dividesSize: function (size: number): number {
-    return size / 2;
-  },
-};
-
-class Logger {
-  log(text: boolean): boolean {
-    console.log('>', text);
-    return true;
-  }
-}
-```
-
-</TabItem>
-</Tabs>
-
-### `propertyDeclaration`
-
-{/* insert option description */}
-
-Examples of code with `{ "propertyDeclaration": true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "propertyDeclaration": true }'
-type Members = {
-  member;
-  otherMember;
-};
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "propertyDeclaration": true }'
-type Members = {
-  member: boolean;
-  otherMember: string;
-};
-```
-
-</TabItem>
-</Tabs>
-
-### `variableDeclaration`
-
-{/* insert option description */}
-
-Examples of code with `{ "variableDeclaration": true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "variableDeclaration": true }'
-const text = 'text';
-let initialText = 'text';
-let delayedText;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "variableDeclaration": true }'
-const text: string = 'text';
-let initialText: string = 'text';
-let delayedText: string;
-```
-
-</TabItem>
-</Tabs>
-
-### `variableDeclarationIgnoreFunction`
-
-{/* insert option description */}
-
-Examples of code with `{ "variableDeclaration": true, "variableDeclarationIgnoreFunction": true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "variableDeclaration": true, "variableDeclarationIgnoreFunction": true }'
-const text = 'text';
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "variableDeclaration": true, "variableDeclarationIgnoreFunction": true }'
-const a = (): void => {};
-const b = function (): void {};
-const c: () => void = (): void => {};
-
-class Foo {
-  a = (): void => {};
-  b = function (): void {};
-  c: () => void = (): void => {};
-}
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-If you are using stricter TypeScript compiler options, particularly `--noImplicitAny` and/or `--strictPropertyInitialization`, you likely don't need this rule.
-
-In general, if you do not consider the cost of writing unnecessary type annotations reasonable, then do not use this rule.
-
-## Further Reading
-
-- [TypeScript Type System](https://basarat.gitbooks.io/typescript/docs/types/type-system.html)
-- [Type Inference](https://www.typescriptlang.org/docs/handbook/type-inference.html)

package/docs/rules/unbound-method.mdx

@@ -1,114 +0,0 @@
----
-description: 'Enforce unbound methods are called with their expected scope.'
----
-
-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/unbound-method** for documentation.
-
-Class method functions don't preserve the class scope when passed as standalone variables ("unbound").
-If your function does not access `this`, [you can annotate it with `this: void`](https://www.typescriptlang.org/docs/handbook/2/functions.html#declaring-this-in-a-function), or consider using an arrow function instead.
-Otherwise, passing class methods around as values can remove type safety by failing to capture `this`.
-
-This rule reports when a class method is referenced in an unbound manner.
-
-:::note Tip
-If you're working with `jest`, you can use [`eslint-plugin-jest`'s version of this rule](https://github.com/jest-community/eslint-plugin-jest/blob/main/docs/rules/unbound-method.md) to lint your test files, which knows when it's ok to pass an unbound method to `expect` calls.
-:::
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-class MyClass {
-  public log(): void {
-    console.log(this);
-  }
-}
-
-const instance = new MyClass();
-
-// This logs the global scope (`window`/`global`), not the class instance
-const myLog = instance.log;
-myLog();
-
-// This log might later be called with an incorrect scope
-const { log } = instance;
-
-// arith.double may refer to `this` internally
-const arith = {
-  double(x: number): number {
-    return x * 2;
-  },
-};
-const { double } = arith;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-class MyClass {
-  public logUnbound(): void {
-    console.log(this);
-  }
-
-  public logBound = () => console.log(this);
-}
-
-const instance = new MyClass();
-
-// logBound will always be bound with the correct scope
-const { logBound } = instance;
-logBound();
-
-// .bind and lambdas will also add a correct scope
-const dotBindLog = instance.logUnbound.bind(instance);
-const innerLog = () => instance.logUnbound();
-
-// arith.double explicitly declares that it does not refer to `this` internally
-const arith = {
-  double(this: void, x: number): number {
-    return x * 2;
-  },
-};
-const { double } = arith;
-```
-
-</TabItem>
-</Tabs>
-
-## Options
-
-### `ignoreStatic`
-
-{/* insert option description */}
-
-Examples of **correct** code for this rule with `{ ignoreStatic: true }`:
-
-```ts option='{ "ignoreStatic": true }' showPlaygroundButton
-class OtherClass {
-  static log() {
-    console.log(OtherClass);
-  }
-}
-
-// With `ignoreStatic`, statics are assumed to not rely on a particular scope
-const { log } = OtherClass;
-
-log();
-```
-
-## When Not To Use It
-
-If your project dynamically changes `this` scopes around in a way TypeScript has difficulties modeling, this rule may not be viable to use.
-For example, some functions have an additional parameter for specifying the `this` context, such as `Reflect.apply`, and array methods like `Array.prototype.map`.
-This semantic is not easily expressed by TypeScript.
-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.
-
-If you're wanting to use `toBeCalled` and similar matches in `jest` tests, you can disable this rule for your test files in favor of [`eslint-plugin-jest`'s version of this rule](https://github.com/jest-community/eslint-plugin-jest/blob/main/docs/rules/unbound-method.mdx).

package/docs/rules/unified-signatures.mdx

@@ -1,132 +0,0 @@
----
-description: 'Disallow two overloads that could be unified into one with a union or an optional/rest 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/unified-signatures** for documentation.
-
-Function overload signatures are a TypeScript way to define a function that can be called in multiple very different ways.
-Overload signatures add syntax and theoretical bloat, so it's generally best to avoid using them when possible.
-Switching to union types and/or optional or rest parameters can often avoid the need for overload signatures.
-
-This rule reports when function overload signatures can be replaced by a single function signature.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-function x(x: number): void;
-function x(x: string): void;
-```
-
-```ts
-function y(): void;
-function y(...x: number[]): void;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-function x(x: number | string): void;
-```
-
-```ts
-function y(...x: number[]): void;
-```
-
-```ts
-// This rule won't check overload signatures with different rest parameter types.
-// See https://github.com/microsoft/TypeScript/issues/5077
-function f(...a: number[]): void;
-function f(...a: string[]): void;
-```
-
-</TabItem>
-</Tabs>
-
-## Options
-
-### `ignoreDifferentlyNamedParameters`
-
-{/* insert option description */}
-
-Examples of code for this rule with `ignoreDifferentlyNamedParameters`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "ignoreDifferentlyNamedParameters": true }'
-function f(a: number): void;
-function f(a: string): void;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "ignoreDifferentlyNamedParameters": true }'
-function f(a: number): void;
-function f(b: string): void;
-```
-
-</TabItem>
-</Tabs>
-
-### `ignoreOverloadsWithDifferentJSDoc`
-
-{/* insert option description */}
-
-Examples of code for this rule with `ignoreOverloadsWithDifferentJSDoc`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "ignoreOverloadsWithDifferentJSDoc": true }'
-declare function f(x: string): void;
-declare function f(x: boolean): void;
-/**
- * @deprecate
- */
-declare function f(x: number): void;
-/**
- * @deprecate
- */
-declare function f(x: null): void;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "ignoreOverloadsWithDifferentJSDoc": true }'
-declare function f(x: string): void;
-/**
- * This signature does something else.
- */
-declare function f(x: boolean): void;
-/**
- * @async
- */
-declare function f(x: number): void;
-/**
- * @deprecate
- */
-declare function f(x: null): void;
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-This is purely a stylistic rule to help with readability of function signature overloads.
-You can turn it off if you don't want to consistently keep them next to each other and unified.
-
-## Related To
-
-- [`adjacent-overload-signatures`](./adjacent-overload-signatures.mdx)

package/docs/rules/use-unknown-in-catch-callback-variable.mdx

@@ -1,97 +0,0 @@
----
-description: 'Enforce typing arguments in Promise rejection callbacks as `unknown`.'
----
-
-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/use-unknown-in-catch-callback-variable** for documentation.
-
-This rule enforces that you always use the `unknown` type for the parameter of a Promise rejection callback.
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-Promise.reject(new Error('I will reject!')).catch(err => {
-  console.log(err);
-});
-
-Promise.reject(new Error('I will reject!')).catch((err: any) => {
-  console.log(err);
-});
-
-Promise.reject(new Error('I will reject!')).catch((err: Error) => {
-  console.log(err);
-});
-
-Promise.reject(new Error('I will reject!')).then(
-  result => {
-    console.log(result);
-  },
-  err => {
-    console.log(err);
-  },
-);
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-Promise.reject(new Error('I will reject!')).catch((err: unknown) => {
-  console.log(err);
-});
-```
-
-</TabItem>
-</Tabs>
-
-The reason for this rule is to enable programmers to impose constraints on `Promise` error handling analogously to what TypeScript provides for ordinary exception handling.
-
-For ordinary exceptions, TypeScript treats the `catch` variable as `any` by default. However, `unknown` would be a more accurate type, so TypeScript [introduced the `useUnknownInCatchVariables` compiler option](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-4.html#defaulting-to-the-unknown-type-in-catch-variables---useunknownincatchvariables) to treat the `catch` variable as `unknown` instead.
-
-```ts
-try {
-  throw x;
-} catch (err) {
-  // err has type 'any' with useUnknownInCatchVariables: false
-  // err has type 'unknown' with useUnknownInCatchVariables: true
-}
-```
-
-The Promise analog of the `try-catch` block, [`Promise.prototype.catch()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch), is not affected by the `useUnknownInCatchVariables` compiler option, and its "`catch` variable" will always have the type `any`.
-
-```ts
-Promise.reject(x).catch(err => {
-  // err has type 'any' regardless of `useUnknownInCatchVariables`
-});
-```
-
-However, you can still provide an explicit type annotation, which lets you achieve the same effect as the `useUnknownInCatchVariables` option does for synchronous `catch` variables.
-
-```ts
-Promise.reject(x).catch((err: unknown) => {
-  // err has type 'unknown'
-});
-```
-
-:::info
-There is actually a way to have the `catch()` and `then()` callback variables use the `unknown` type _without_ an explicit type annotation at the call sites, but it has the drawback that it involves overriding global type declarations.
-For example, the library [better-TypeScript-lib](https://github.com/uhyo/better-typescript-lib) sets this up globally for your project (see [the relevant lines in the better-TypeScript-lib source code](https://github.com/uhyo/better-typescript-lib/blob/c294e177d1cc2b1d1803febf8192a4c83a1fe028/lib/lib.es5.d.ts#L635) for details on how).
-
-For further reading on this, you may also want to look into
-[the discussion in the proposal for this rule](https://github.com/typescript-eslint/typescript-eslint/issues/7526#issuecomment-1690600813) and [this TypeScript issue on typing catch callback variables as unknown](https://github.com/microsoft/TypeScript/issues/45602).
-:::
-
-## When Not To Use It
-
-If your codebase is not yet able to enable `useUnknownInCatchVariables`, it likely would be similarly difficult to enable this rule.
-
-If you have modified the global type declarations in order to make `then()` and `catch()` callbacks use the `unknown` type without an explicit type annotation, you do not need this rule.
-
-## Related To
-
-- [Avoiding `any`s with Linting and TypeScript](/blog/avoiding-anys)