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

package/docs/rules/prefer-regexp-exec.mdx

@@ -1,52 +0,0 @@
----
-description: 'Enforce `RegExp#exec` over `String#match` if no global flag is provided.'
----
-
-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/prefer-regexp-exec** for documentation.
-
-`String#match` is defined to work the same as `RegExp#exec` when the regular expression does not include the `g` flag.
-Keeping to consistently using one of the two can help improve code readability.
-
-This rule reports when a `String#match` call can be replaced with an equivalent `RegExp#exec`.
-
-> `RegExp#exec` may also be slightly faster than `String#match`; this is the reason to choose it as the preferred usage.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-'something'.match(/thing/);
-
-'some things are just things'.match(/thing/);
-
-const text = 'something';
-const search = /thing/;
-text.match(search);
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-/thing/.exec('something');
-
-'some things are just things'.match(/thing/g);
-
-const text = 'something';
-const search = /thing/;
-search.exec(text);
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-If you prefer consistent use of `String#match` for both with `g` flag and without it, you can turn this rule off.

package/docs/rules/prefer-return-this-type.mdx

@@ -1,93 +0,0 @@
----
-description: 'Enforce that `this` is used when only `this` type is returned.'
----
-
-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/prefer-return-this-type** for documentation.
-
-[Method chaining](https://en.wikipedia.org/wiki/Method_chaining) is a common pattern in OOP languages and TypeScript provides a special [polymorphic `this` type](https://www.typescriptlang.org/docs/handbook/2/classes.html#this-types) to facilitate it.
-Class methods that explicitly declare a return type of the class name instead of `this` make it harder for extending classes to call that method: the returned object will be typed as the base class, not the derived class.
-
-This rule reports when a class method declares a return type of that class name instead of `this`.
-
-```ts
-class Animal {
-  eat(): Animal {
-    //   ~~~~~~
-    // Either removing this type annotation or replacing
-    // it with `this` would remove the type error below.
-    console.log("I'm moving!");
-    return this;
-  }
-}
-
-class Cat extends Animal {
-  meow(): Cat {
-    console.log('Meow~');
-    return this;
-  }
-}
-
-const cat = new Cat();
-cat.eat().meow();
-//        ~~~~
-// Error: Property 'meow' does not exist on type 'Animal'.
-// because `eat` returns `Animal` and not all animals meow.
-```
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-class Foo {
-  f1(): Foo {
-    return this;
-  }
-  f2 = (): Foo => {
-    return this;
-  };
-  f3(): Foo | undefined {
-    return Math.random() > 0.5 ? this : undefined;
-  }
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-class Foo {
-  f1(): this {
-    return this;
-  }
-  f2() {
-    return this;
-  }
-  f3 = (): this => {
-    return this;
-  };
-  f4 = () => {
-    return this;
-  };
-}
-
-class Base {}
-class Derived extends Base {
-  f(): Base {
-    return this;
-  }
-}
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-If you don't use method chaining or explicit return values, you can safely turn this rule off.

package/docs/rules/prefer-string-starts-ends-with.mdx

@@ -1,84 +0,0 @@
----
-description: 'Enforce using `String#startsWith` and `String#endsWith` over other equivalent methods of checking substrings.'
----
-
-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/prefer-string-starts-ends-with** for documentation.
-
-There are multiple ways to verify if a string starts or ends with a specific string, such as `foo.indexOf('bar') === 0`.
-As of ES2015, the most common way in JavaScript is to use `String#startsWith` and `String#endsWith`.
-Keeping to those methods consistently helps with code readability.
-
-This rule reports when a string method can be replaced safely with `String#startsWith` or `String#endsWith`.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-declare const foo: string;
-
-// starts with
-foo[0] === 'b';
-foo.charAt(0) === 'b';
-foo.indexOf('bar') === 0;
-foo.slice(0, 3) === 'bar';
-foo.substring(0, 3) === 'bar';
-foo.match(/^bar/) != null;
-/^bar/.test(foo);
-
-// ends with
-foo[foo.length - 1] === 'b';
-foo.charAt(foo.length - 1) === 'b';
-foo.lastIndexOf('bar') === foo.length - 3;
-foo.slice(-3) === 'bar';
-foo.substring(foo.length - 3) === 'bar';
-foo.match(/bar$/) != null;
-/bar$/.test(foo);
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-declare const foo: string;
-
-// starts with
-foo.startsWith('bar');
-
-// ends with
-foo.endsWith('bar');
-```
-
-</TabItem>
-</Tabs>
-
-## Options
-
-### `allowSingleElementEquality`
-
-{/* insert option description */}
-
-If switched to `'always'`, the rule will allow equality checks against the first or last character in a string.
-This can be preferable in projects that don't deal with special character encodings and prefer a more succinct style.
-
-The following code is considered incorrect by default, but is allowed with `allowSingleElementEquality: 'always'`:
-
-```ts option='{ "allowSingleElementEquality": "always" }' showPlaygroundButton
-declare const text: string;
-
-text[0] === 'a';
-text[0] === text[0].toUpperCase();
-text[0] === text[1];
-text[text.length - 1] === 'b';
-```
-
-## When Not To Use It
-
-If you don't mind which style of string checking is used, you can turn this rule off safely.
-However, keep in mind that inconsistent style can harm readability in a project.

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

@@ -1,86 +0,0 @@
----
-description: 'Enforce using `@ts-expect-error` over `@ts-ignore`.'
----
-
-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/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.
-
-This means it's easy for `@ts-ignore`s to be forgotten about, and remain in code even after the error they were suppressing is fixed.
-This is dangerous, as if a new error arises on that line it'll be suppressed by the forgotten about `@ts-ignore`, and so be missed.
-
-## Examples
-
-This rule reports any usage of `@ts-ignore`, including a fixer to replace with `@ts-expect-error`.
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-// @ts-ignore
-const str: string = 1;
-
-/**
- * Explaining comment
- *
- * @ts-ignore */
-const multiLine: number = 'value';
-
-/** @ts-ignore */
-const block: string = 1;
-
-const isOptionEnabled = (key: string): boolean => {
-  // @ts-ignore: if key isn't in globalOptions it'll be undefined which is false
-  return !!globalOptions[key];
-};
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-// @ts-expect-error
-const str: string = 1;
-
-/**
- * Explaining comment
- *
- * @ts-expect-error */
-const multiLine: number = 'value';
-
-/** @ts-expect-error */
-const block: string = 1;
-
-const isOptionEnabled = (key: string): boolean => {
-  // @ts-expect-error: if key isn't in globalOptions it'll be undefined which is false
-  return !!globalOptions[key];
-};
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-If you are compiling against multiple versions of TypeScript and using `@ts-ignore` to ignore version-specific type errors, this rule might get in your way.
-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
-
-- [Original Implementing PR](https://github.com/microsoft/TypeScript/pull/36014)

package/docs/rules/promise-function-async.mdx

@@ -1,143 +0,0 @@
----
-description: 'Require any function or method that returns a Promise to be marked async.'
----
-
-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/promise-function-async** for documentation.
-
-Ensures that each function is only capable of:
-
-- returning a rejected promise, or
-- throwing an Error object.
-
-In contrast, non-`async`, `Promise`-returning functions are technically capable of either.
-Code that handles the results of those functions will often need to handle both cases, which can get complex.
-This rule's practice removes a requirement for creating code to handle both cases.
-
-> When functions return unions of `Promise` and non-`Promise` types implicitly, it is usually a mistake—this rule flags those cases. If it is intentional, make the return type explicitly to allow the rule to pass.
-
-## Examples
-
-Examples of code for this rule
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-const arrowFunctionReturnsPromise = () => Promise.resolve('value');
-
-function functionReturnsPromise() {
-  return Promise.resolve('value');
-}
-
-function functionReturnsUnionWithPromiseImplicitly(p: boolean) {
-  return p ? 'value' : Promise.resolve('value');
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-const arrowFunctionReturnsPromise = async () => Promise.resolve('value');
-
-async function functionReturnsPromise() {
-  return Promise.resolve('value');
-}
-
-// An explicit return type that is not Promise means this function cannot be made async, so it is ignored by the rule
-function functionReturnsUnionWithPromiseExplicitly(
-  p: boolean,
-): string | Promise<string> {
-  return p ? 'value' : Promise.resolve('value');
-}
-
-async function functionReturnsUnionWithPromiseImplicitly(p: boolean) {
-  return p ? 'value' : Promise.resolve('value');
-}
-```
-
-</TabItem>
-</Tabs>
-
-## Options
-
-### `allowAny`
-
-{/* insert option description */}
-
-If you want additional safety, consider turning this option off, as it makes the rule less able to catch incorrect Promise behaviors.
-
-Examples of code with `{ "allowAny": false }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "allowAny": false }'
-const returnsAny = () => ({}) as any;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "allowAny": false }'
-const returnsAny = async () => ({}) as any;
-```
-
-</TabItem>
-</Tabs>
-
-### `allowedPromiseNames`
-
-{/* insert option description */}
-
-For projects that use constructs other than the global built-in `Promise` for asynchronous code.
-This option allows specifying string names of classes or interfaces that cause a function to be checked as well.
-
-Examples of code with `{ "allowedPromiseNames": ["Bluebird"] }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "allowedPromiseNames": ["Bluebird"] }'
-class Bluebird {}
-
-const returnsBluebird = () => new Bluebird(() => {});
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "allowedPromiseNames": ["Bluebird"] }'
-class Bluebird {}
-
-const returnsBluebird = async () => new Bluebird(() => {});
-```
-
-</TabItem>
-</Tabs>
-
-### `checkArrowFunctions`
-
-{/* insert option description */}
-
-### `checkFunctionDeclarations`
-
-{/* insert option description */}
-
-### `checkFunctionExpressions`
-
-{/* insert option description */}
-
-### `checkMethodDeclarations`
-
-{/* insert option description */}
-
-## When Not To Use It
-
-This rule can be difficult to enable on projects that use APIs which require functions to always be `async`.
-You might consider using [ESLint disable comments](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1) along with filing issues on your dependencies for those specific situations instead of completely disabling this rule.

package/docs/rules/quotes.md

@@ -1,15 +0,0 @@
----
-displayed_sidebar: rulesSidebar
----
-
-:::danger Deprecated
-
-This rule has been moved to the [ESLint stylistic plugin](https://eslint.style).
-See [#8072](https://github.com/typescript-eslint/typescript-eslint/issues/8072) and [#8074](https://github.com/typescript-eslint/typescript-eslint/issues/8074) for more information.
-
-:::
-
-<!-- This doc file has been left on purpose to help direct people to the stylistic plugin.
-
-Note that there is no actual way to get to this page in the normal navigation,
-so end-users will only be able to get to this page from the search bar. -->

package/docs/rules/related-getter-setter-pairs.mdx

@@ -1,61 +0,0 @@
----
-description: 'Enforce that `get()` types should be assignable to their equivalent `set()` 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/related-getter-setter-pairs** for documentation.
-
-TypeScript allows defining different types for a `get` parameter and its corresponding `set` return.
-Prior to TypeScript 4.3, the types had to be identical.
-From TypeScript 4.3 to 5.0, the `get` type had to be a subtype of the `set` type.
-As of TypeScript 5.1, the types may be completely unrelated as long as there is an explicit type annotation.
-
-Defining drastically different types for a `get` and `set` pair can be confusing.
-It means that assigning a property to itself would not work:
-
-```ts
-// Assumes box.value's get() return is assignable to its set() parameter
-box.value = box.value;
-```
-
-This rule reports cases where a `get()` and `set()` have the same name, but the `get()`'s type is not assignable to the `set()`'s.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-interface Box {
-  get value(): string;
-  set value(newValue: number);
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-interface Box {
-  get value(): string;
-  set value(newValue: string);
-}
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-If your project needs to model unusual relationships between data, such as older DOM types, this rule may not be useful 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
-
-- [MDN documentation on `get`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get)
-- [MDN documentation on `set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set)
-- [TypeScript 5.1 Release Notes > Unrelated Types for Getters and Setters](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-1.html#unrelated-types-for-getters-and-setters)

package/docs/rules/require-array-sort-compare.mdx

@@ -1,89 +0,0 @@
----
-description: 'Require `Array#sort` and `Array#toSorted` calls to always provide a `compareFunction`.'
----
-
-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/require-array-sort-compare** for documentation.
-
-When called without a compare function, `Array#sort()` and `Array#toSorted()` converts all non-undefined array elements into strings and then compares said strings based off their UTF-16 code units [[ECMA specification](https://www.ecma-international.org/ecma-262/9.0/#sec-sortcompare)].
-
-The result is that elements are sorted alphabetically, regardless of their type.
-For example, when sorting numbers, this results in a "10 before 2" order:
-
-```ts
-[1, 2, 3, 10, 20, 30].sort(); //→ [1, 10, 2, 20, 3, 30]
-```
-
-This rule reports on any call to the sort methods that do not provide a `compare` argument.
-
-## Examples
-
-This rule aims to ensure all calls of the native sort methods provide a `compareFunction`, while ignoring calls to user-defined methods.
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-const array: any[];
-const stringArray: string[];
-
-array.sort();
-
-// String arrays should be sorted using `String#localeCompare`.
-stringArray.sort();
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-const array: any[];
-const userDefinedType: { sort(): void };
-
-array.sort((a, b) => a - b);
-array.sort((a, b) => a.localeCompare(b));
-
-userDefinedType.sort();
-```
-
-</TabItem>
-</Tabs>
-
-## Options
-
-### `ignoreStringArrays`
-
-{/* insert option description */}
-
-Examples of code for this rule with `{ ignoreStringArrays: true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "ignoreStringArrays": true }'
-const one = 1;
-const two = 2;
-const three = 3;
-[one, two, three].sort();
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "ignoreStringArrays": true }'
-const one = '1';
-const two = '2';
-const three = '3';
-[one, two, three].sort();
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-If you intentionally want your arrays to be always sorted in a string-like manner, you can turn this rule off safely.

package/docs/rules/require-await.mdx

@@ -1,53 +0,0 @@
----
-description: 'Disallow async functions which do not return promises and have no `await` 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/require-await** for documentation.
-
-It uses type information to allow promise-returning functions to be marked as `async` without containing an `await` expression.
-
-:::note
-`yield` expressions in [async generator functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function*) behave differently from sync generator functions (they unwrap promises), so the base rule never checks async generator functions. On the other hand, our rule uses type information and can detect async generator functions that both never use `await` and always yield non-promise values.
-:::
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-async function returnNumber() {
-  return 1;
-}
-
-async function* asyncGenerator() {
-  yield 1;
-}
-
-const num = returnNumber();
-const callAsyncGenerator = () => asyncGenerator();
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-function returnNumber() {
-  return 1;
-}
-
-function* syncGenerator() {
-  yield 1;
-}
-
-const num = returnNumber();
-const callSyncGenerator = () => syncGenerator();
-```
-
-</TabItem>
-</Tabs>