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

package/package.json

@@ -1,16 +1,15 @@
 {
   "name": "@typescript-eslint/eslint-plugin",
-  "version": "8.33.1-alpha.5",
+  "version": "8.33.1",
   "description": "TypeScript plugin for ESLint",
   "files": [
     "dist",
     "!*.tsbuildinfo",
-    "docs",
     "index.d.ts",
     "raw-plugin.d.ts",
     "rules.d.ts",
     "package.json",
-    "README.md",
+    "./README.md",
     "LICENSE"
   ],
   "type": "commonjs",
@@ -61,10 +60,10 @@
   },
   "dependencies": {
     "@eslint-community/regexpp": "^4.10.0",
-    "@typescript-eslint/scope-manager": "8.33.1-alpha.5",
-    "@typescript-eslint/type-utils": "8.33.1-alpha.5",
-    "@typescript-eslint/utils": "8.33.1-alpha.5",
-    "@typescript-eslint/visitor-keys": "8.33.1-alpha.5",
+    "@typescript-eslint/scope-manager": "8.33.1",
+    "@typescript-eslint/type-utils": "8.33.1",
+    "@typescript-eslint/utils": "8.33.1",
+    "@typescript-eslint/visitor-keys": "8.33.1",
     "graphemer": "^1.4.0",
     "ignore": "^7.0.0",
     "natural-compare": "^1.4.0",
@@ -73,8 +72,8 @@
   "devDependencies": {
     "@types/mdast": "^4.0.3",
     "@types/natural-compare": "*",
-    "@typescript-eslint/rule-schema-to-typescript-types": "8.33.1-alpha.5",
-    "@typescript-eslint/rule-tester": "8.33.1-alpha.5",
+    "@typescript-eslint/rule-schema-to-typescript-types": "8.33.1",
+    "@typescript-eslint/rule-tester": "8.33.1",
     "@vitest/coverage-v8": "^3.1.3",
     "ajv": "^6.12.6",
     "cross-fetch": "*",
@@ -94,7 +93,7 @@
     "vitest": "^3.1.3"
   },
   "peerDependencies": {
-    "@typescript-eslint/parser": "^8.33.1-alpha.5",
+    "@typescript-eslint/parser": "^8.33.1",
     "eslint": "^8.57.0 || ^9.0.0",
     "typescript": ">=4.8.4 <5.9.0"
   },

package/docs/rules/README.md

@@ -1,57 +0,0 @@
----
-title: Overview
-sidebar_label: Overview
-pagination_next: null
-pagination_prev: null
-slug: /
----
-
-`@typescript-eslint/eslint-plugin` includes over 100 rules that detect best practice violations, bugs, and/or stylistic issues specifically for TypeScript code. All of our rules are listed below.
-
-:::tip
-Instead of enabling rules one by one, we recommend using one of [our pre-defined configs](/users/configs) to enable a large set of recommended rules.
-:::
-
-## Rules
-
-The rules are listed in alphabetical order. You can optionally filter them based on these categories:
-
-import RulesTable from "@site/src/components/RulesTable";
-
-<RulesTable />
-
-## Filtering
-
-### Config Group (⚙️)
-
-"Config Group" refers to the [pre-defined config](/users/configs) that includes the rule. Extending from a configuration preset allow for enabling a large set of recommended rules all at once.
-
-### Metadata
-
-- `🔧 fixable` refers to whether the rule contains an [ESLint `--fix` auto-fixer](https://eslint.org/docs/latest/use/command-line-interface#--fix).
-- `💡 has suggestions` refers to whether the rule contains an ESLint suggestion fixer.
-  - Sometimes, it is not safe to automatically fix the code with an auto-fixer. But in these cases, we often have a good guess of what the correct fix should be, and we can provide it as a suggestion to the developer.
-- `💭 requires type information` refers to whether the rule requires [typed linting](/getting-started/typed-linting).
-- `🧱 extension rule` means that the rule is an extension of an [core ESLint rule](https://eslint.org/docs/latest/rules) (see [Extension Rules](#extension-rules)).
-- `💀 deprecated rule` means that the rule should no longer be used and will be removed from the plugin in a future version.
-
-## Extension Rules
-
-Some core ESLint rules do not support TypeScript syntax: either they crash, ignore the syntax, or falsely report against it.
-In these cases, we create what we call an "extension rule": a rule within our plugin that has the same functionality, but also supports TypeScript.
-
-Extension rules generally completely replace the base rule from ESLint core.
-If the base rule is enabled in a config you extend from, you'll need to disable the base rule:
-
-```js
-module.exports = {
-  extends: ['eslint:recommended'],
-  rules: {
-    // Note: you must disable the base rule as it can report incorrect errors
-    'no-unused-vars': 'off',
-    '@typescript-eslint/no-unused-vars': 'error',
-  },
-};
-```
-
-[Search for `🧱 extension rule`s](?=extension#rules) in this page to see all extension rules.

package/docs/rules/TEMPLATE.md

@@ -1,36 +0,0 @@
----
-description: '<Description from rule metadata here>'
----
-
-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/RULE_NAME_REPLACEME** for documentation.
-
-## Examples
-
-To fill out: tell us more about this rule.
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-// To fill out: incorrect code
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-// To fill out: correct code
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-To fill out: why wouldn't you want to use this rule?
-For example if this rule requires a feature released in a certain TS version.

package/docs/rules/adjacent-overload-signatures.mdx

@@ -1,105 +0,0 @@
----
-description: 'Require that function overload signatures be consecutive.'
----
-
-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/adjacent-overload-signatures** for documentation.
-
-Function overload signatures represent multiple ways a function can be called, potentially with different return types.
-It's typical for an interface or type alias describing a function to place all overload signatures next to each other.
-If Signatures placed elsewhere in the type are easier to be missed by future developers reading the code.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-declare namespace Foo {
-  export function foo(s: string): void;
-  export function foo(n: number): void;
-  export function bar(): void;
-  export function foo(sn: string | number): void;
-}
-
-type Foo = {
-  foo(s: string): void;
-  foo(n: number): void;
-  bar(): void;
-  foo(sn: string | number): void;
-};
-
-interface Foo {
-  foo(s: string): void;
-  foo(n: number): void;
-  bar(): void;
-  foo(sn: string | number): void;
-}
-
-class Foo {
-  foo(s: string): void;
-  foo(n: number): void;
-  bar(): void {}
-  foo(sn: string | number): void {}
-}
-
-export function foo(s: string): void;
-export function foo(n: number): void;
-export function bar(): void;
-export function foo(sn: string | number): void;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-declare namespace Foo {
-  export function foo(s: string): void;
-  export function foo(n: number): void;
-  export function foo(sn: string | number): void;
-  export function bar(): void;
-}
-
-type Foo = {
-  foo(s: string): void;
-  foo(n: number): void;
-  foo(sn: string | number): void;
-  bar(): void;
-};
-
-interface Foo {
-  foo(s: string): void;
-  foo(n: number): void;
-  foo(sn: string | number): void;
-  bar(): void;
-}
-
-class Foo {
-  foo(s: string): void;
-  foo(n: number): void;
-  foo(sn: string | number): void {}
-  bar(): void {}
-}
-
-export function bar(): void;
-export function foo(s: string): void;
-export function foo(n: number): void;
-export function foo(sn: string | number): void;
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-It can sometimes be useful to place overload signatures alongside other meaningful parts of a type.
-For example, if each of a function's overloads corresponds to a different property, you might wish to put each overloads next to its corresponding property.
-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
-
-- [`unified-signatures`](./unified-signatures.mdx)

package/docs/rules/array-type.mdx

@@ -1,126 +0,0 @@
----
-description: 'Require consistently using either `T[]` or `Array<T>` for arrays.'
----
-
-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/array-type** for documentation.
-
-TypeScript provides two equivalent ways to define an array type: `T[]` and `Array<T>`.
-The two styles are functionally equivalent.
-Using the same style consistently across your codebase makes it easier for developers to read and understand array types.
-
-## Options
-
-The default config will enforce that all mutable and readonly arrays use the `'array'` syntax.
-
-### `"array"`
-
-Always use `T[]` or `readonly T[]` for all array types.
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "default": "array" }'
-const x: Array<string> = ['a', 'b'];
-const y: ReadonlyArray<string> = ['a', 'b'];
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "default": "array" }'
-const x: string[] = ['a', 'b'];
-const y: readonly string[] = ['a', 'b'];
-```
-
-</TabItem>
-</Tabs>
-
-### `"generic"`
-
-Always use `Array<T>`, `ReadonlyArray<T>`, or `Readonly<Array<T>>` for all array types.
-`readonly T[]` will be modified to `ReadonlyArray<T>` and `Readonly<T[]>` will be modified to `Readonly<Array<T>>`.
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "default": "generic" }'
-const x: string[] = ['a', 'b'];
-const y: readonly string[] = ['a', 'b'];
-const z: Readonly<string[]> = ['a', 'b'];
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "default": "generic" }'
-const x: Array<string> = ['a', 'b'];
-const y: ReadonlyArray<string> = ['a', 'b'];
-const z: Readonly<Array<string>> = ['a', 'b'];
-```
-
-</TabItem>
-</Tabs>
-
-### `"array-simple"`
-
-Use `T[]` or `readonly T[]` for simple types (i.e. types which are just primitive names or type references).
-Use `Array<T>` or `ReadonlyArray<T>` for all other types (union types, intersection types, object types, function types, etc).
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "default": "array-simple" }'
-const a: (string | number)[] = ['a', 'b'];
-const b: { prop: string }[] = [{ prop: 'a' }];
-const c: (() => void)[] = [() => {}];
-const d: Array<MyType> = ['a', 'b'];
-const e: Array<string> = ['a', 'b'];
-const f: ReadonlyArray<string> = ['a', 'b'];
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "default": "array-simple" }'
-const a: Array<string | number> = ['a', 'b'];
-const b: Array<{ prop: string }> = [{ prop: 'a' }];
-const c: Array<() => void> = [() => {}];
-const d: MyType[] = ['a', 'b'];
-const e: string[] = ['a', 'b'];
-const f: readonly string[] = ['a', 'b'];
-```
-
-</TabItem>
-</Tabs>
-
-## Combination Matrix
-
-This matrix lists all possible option combinations and their expected results for different types of Arrays.
-
-| defaultOption  | readonlyOption | Array with simple type | Array with non simple type | Readonly array with simple type | Readonly array with non simple type |
-| -------------- | -------------- | ---------------------- | -------------------------- | ------------------------------- | ----------------------------------- |
-| `array`        |                | `number[]`             | `(Foo & Bar)[]`            | `readonly number[]`             | `readonly (Foo & Bar)[]`            |
-| `array`        | `array`        | `number[]`             | `(Foo & Bar)[]`            | `readonly number[]`             | `readonly (Foo & Bar)[]`            |
-| `array`        | `array-simple` | `number[]`             | `(Foo & Bar)[]`            | `readonly number[]`             | `ReadonlyArray<Foo & Bar>`          |
-| `array`        | `generic`      | `number[]`             | `(Foo & Bar)[]`            | `ReadonlyArray<number>`         | `ReadonlyArray<Foo & Bar>`          |
-| `array-simple` |                | `number[]`             | `Array<Foo & Bar>`         | `readonly number[]`             | `ReadonlyArray<Foo & Bar>`          |
-| `array-simple` | `array`        | `number[]`             | `Array<Foo & Bar>`         | `readonly number[]`             | `readonly (Foo & Bar)[]`            |
-| `array-simple` | `array-simple` | `number[]`             | `Array<Foo & Bar>`         | `readonly number[]`             | `ReadonlyArray<Foo & Bar>`          |
-| `array-simple` | `generic`      | `number[]`             | `Array<Foo & Bar>`         | `ReadonlyArray<number>`         | `ReadonlyArray<Foo & Bar>`          |
-| `generic`      |                | `Array<number>`        | `Array<Foo & Bar>`         | `ReadonlyArray<number>`         | `ReadonlyArray<Foo & Bar>`          |
-| `generic`      | `array`        | `Array<number>`        | `Array<Foo & Bar>`         | `readonly number[]`             | `readonly (Foo & Bar)[]`            |
-| `generic`      | `array-simple` | `Array<number>`        | `Array<Foo & Bar>`         | `readonly number[]`             | `ReadonlyArray<Foo & Bar>`          |
-| `generic`      | `generic`      | `Array<number>`        | `Array<Foo & Bar>`         | `ReadonlyArray<number>`         | `ReadonlyArray<Foo & Bar>`          |
-
-## When Not To Use It
-
-This rule is purely a stylistic rule for maintaining consistency in your project.
-You can turn it off if you don't want to keep a consistent style for array types.
-
-However, keep in mind that inconsistent style can harm readability in a project.
-We recommend picking a single option for this rule that works best for your project.

package/docs/rules/await-thenable.mdx

@@ -1,184 +0,0 @@
----
-description: 'Disallow awaiting a value that is not a Thenable.'
----
-
-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/await-thenable** for documentation.
-
-A "Thenable" value is an object which has a `then` method, such as a Promise.
-The [`await` keyword](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await) is generally used to retrieve the result of calling a Thenable's `then` method.
-
-If the `await` keyword is used on a value that is not a Thenable, the value is directly resolved, but will still pause execution until the next microtask.
-While doing so is valid JavaScript, it is often a programmer error, such as forgetting to add parenthesis to call a function that returns a Promise.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-await 'value';
-
-const createValue = () => 'value';
-await createValue();
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-await Promise.resolve('value');
-
-const createValue = async () => 'value';
-await createValue();
-```
-
-</TabItem>
-</Tabs>
-
-## Async Iteration (`for await...of` Loops)
-
-This rule also inspects [`for await...of` statements](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of), and reports if the value being iterated over is not async-iterable.
-
-:::info[Why does the rule report on `for await...of` loops used on an array of Promises?]
-
-While `for await...of` can be used with synchronous iterables, and it will await each promise produced by the iterable, it is inadvisable to do so.
-There are some tiny nuances that you may want to consider.
-
-The biggest difference between using `for await...of` and using `for...of` (apart from awaiting each result yourself) is error handling.
-When an error occurs within the loop body, `for await...of` does _not_ close the original sync iterable, while `for...of` does.
-For detailed examples of this, see the [MDN documentation on using `for await...of` with sync-iterables](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of#iterating_over_sync_iterables_and_generators).
-
-Also consider whether you need sequential awaiting at all. Using `for await...of` may obscure potential opportunities for concurrent processing, such as those reported by [`no-await-in-loop`](https://eslint.org/docs/latest/rules/no-await-in-loop). Consider instead using one of the [promise concurrency methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#promise_concurrency) for better performance.
-
-:::
-
-### Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-async function syncIterable() {
-  const arrayOfValues = [1, 2, 3];
-  for await (const value of arrayOfValues) {
-    console.log(value);
-  }
-}
-
-async function syncIterableOfPromises() {
-  const arrayOfPromises = [
-    Promise.resolve(1),
-    Promise.resolve(2),
-    Promise.resolve(3),
-  ];
-  for await (const promisedValue of arrayOfPromises) {
-    console.log(promisedValue);
-  }
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-async function syncIterable() {
-  const arrayOfValues = [1, 2, 3];
-  for (const value of arrayOfValues) {
-    console.log(value);
-  }
-}
-
-async function syncIterableOfPromises() {
-  const arrayOfPromises = [
-    Promise.resolve(1),
-    Promise.resolve(2),
-    Promise.resolve(3),
-  ];
-  for (const promisedValue of await Promise.all(arrayOfPromises)) {
-    console.log(promisedValue);
-  }
-}
-
-async function validUseOfForAwaitOnAsyncIterable() {
-  async function* yieldThingsAsynchronously() {
-    yield 1;
-    await new Promise(resolve => setTimeout(resolve, 1000));
-    yield 2;
-  }
-
-  for await (const promisedValue of yieldThingsAsynchronously()) {
-    console.log(promisedValue);
-  }
-}
-```
-
-</TabItem>
-</Tabs>
-
-## Explicit Resource Management (`await using` Statements)
-
-This rule also inspects [`await using` statements](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management).
-If the disposable being used is not async-disposable, an `await using` statement is unnecessary.
-
-### Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-function makeSyncDisposable(): Disposable {
-  return {
-    [Symbol.dispose](): void {
-      // Dispose of the resource
-    },
-  };
-}
-
-async function shouldNotAwait() {
-  await using resource = makeSyncDisposable();
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-function makeSyncDisposable(): Disposable {
-  return {
-    [Symbol.dispose](): void {
-      // Dispose of the resource
-    },
-  };
-}
-
-async function shouldNotAwait() {
-  using resource = makeSyncDisposable();
-}
-
-function makeAsyncDisposable(): AsyncDisposable {
-  return {
-    async [Symbol.asyncDispose](): Promise<void> {
-      // Dispose of the resource asynchronously
-    },
-  };
-}
-
-async function shouldAwait() {
-  await using resource = makeAsyncDisposable();
-}
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-If you want to allow code to `await` non-Promise values.
-For example, if your framework is in transition from one style of asynchronous code to another, it may be useful to include `await`s unnecessarily.
-This is generally not preferred but can sometimes be useful for visual consistency.
-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.