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

package/docs/rules/return-await.mdx

@@ -1,339 +0,0 @@
----
-description: 'Enforce consistent awaiting of returned promises.'
----
-
-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/return-await** for documentation.
-
-In `async` functions, it is valid to return a promise-wrapped value or a value directly, both of which ultimately produce a promise with the same fulfillment value. Returning a value rather than a promise-wrapped value can have several subtle benefits:
-
-- Returning an awaited promise [improves stack trace information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await#improving_stack_trace).
-- When the `return` statement is in `try...catch`, awaiting the promise allows the promise's rejection to be caught instead of leaving the error to the caller.
-- Contrary to popular belief, `return await promise;` is [at least as fast as directly returning the promise](https://github.com/tc39/proposal-faster-promise-adoption).
-
-This rule enforces consistent handling of whether to await promises before returning them.
-
-:::info
-
-This rule used to be considered an extension of the (now-deprecated) ESLint core rule [`no-return-await`](https://eslint.org/docs/latest/rules/no-return-await#options).
-Without type information, the only situations that could be flagged by `no-return-await` were of neutral-to-negative value, which eventually led to its deprecation.
-In contrast, with access to type information, `@typescript-eslint/return-await` delivers enough positive value to earn it a spot in our strict preset.
-
-If you previously used `no-return-await`, this rule's `in-try-catch` option has the closest behavior to the `no-return-await` rule.
-
-:::
-
-## Options
-
-```ts
-type Options =
-  | 'in-try-catch'
-  | 'always'
-  | 'error-handling-correctness-only'
-  | 'never';
-
-const defaultOptions: Options = 'in-try-catch';
-```
-
-The options in this rule distinguish between "ordinary contexts" and "error-handling contexts".
-An error-handling context is anywhere where returning an unawaited promise would cause unexpected control flow regarding exceptions/rejections.
-See detailed examples in the sections for each option.
-
-- If you return a promise within a `try` block, it should be awaited in order to trigger subsequent `catch` or `finally` blocks as expected.
-- If you return a promise within a `catch` block, and there _is_ a `finally` block, it should be awaited in order to trigger the `finally` block as expected.
-- If you return a promise between a `using` or `await using` declaration and the end of its scope, it should be awaited, since it behaves equivalently to code wrapped in a `try` block followed by a `finally`.
-
-Ordinary contexts are anywhere else a promise may be returned.
-The choice of whether to await a returned promise in an ordinary context is mostly stylistic.
-
-With these terms defined, the options may be summarized as follows:
-
-|              Option               | Ordinary Context <br/> (stylistic preference 🎨) |        Error-Handling Context <br/> (catches bugs 🐛)        |                 Should I use this option?                  |
-| :-------------------------------: | :----------------------------------------------: | :----------------------------------------------------------: | :--------------------------------------------------------: |
-|             `always`              |             `return await promise;`              |                   `return await promise;`                    |                          ✅ Yes!                           |
-|          `in-try-catch`           |                `return promise;`                 |                   `return await promise;`                    |                          ✅ Yes!                           |
-| `error-handling-correctness-only` |                  don't care 🤷                   |                   `return await promise;`                    | 🟡 Okay to use, but the above options would be preferable. |
-|              `never`              |                `return promise;`                 | `return promise;` <br/> (⚠️ This behavior may be harmful ⚠️) |             ❌ No. This option is deprecated.              |
-
-### `in-try-catch`
-
-In error-handling contexts, the rule enforces that returned promises must be awaited.
-In ordinary contexts, the rule enforces that returned promises _must not_ be awaited.
-
-This is a good option if you prefer the shorter `return promise` form for stylistic reasons, wherever it's safe to use.
-
-Examples of code with `in-try-catch`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='"in-try-catch"'
-async function invalidInTryCatch1() {
-  try {
-    return Promise.reject('try');
-  } catch (e) {
-    // Doesn't execute due to missing await.
-  }
-}
-
-async function invalidInTryCatch2() {
-  try {
-    throw new Error('error');
-  } catch (e) {
-    // Unnecessary await; rejections here don't impact control flow.
-    return await Promise.reject('catch');
-  }
-}
-
-// Prints 'starting async work', 'cleanup', 'async work done'.
-async function invalidInTryCatch3() {
-  async function doAsyncWork(): Promise<void> {
-    console.log('starting async work');
-    await new Promise(resolve => setTimeout(resolve, 1000));
-    console.log('async work done');
-  }
-
-  try {
-    throw new Error('error');
-  } catch (e) {
-    // Missing await.
-    return doAsyncWork();
-  } finally {
-    console.log('cleanup');
-  }
-}
-
-async function invalidInTryCatch4() {
-  try {
-    throw new Error('error');
-  } catch (e) {
-    throw new Error('error2');
-  } finally {
-    // Unnecessary await; rejections here don't impact control flow.
-    return await Promise.reject('finally');
-  }
-}
-
-async function invalidInTryCatch5() {
-  return await Promise.resolve('try');
-}
-
-async function invalidInTryCatch6() {
-  return await 'value';
-}
-
-async function invalidInTryCatch7() {
-  using x = createDisposable();
-  return Promise.reject('using in scope');
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='"in-try-catch"'
-async function validInTryCatch1() {
-  try {
-    return await Promise.reject('try');
-  } catch (e) {
-    // Executes as expected.
-  }
-}
-
-async function validInTryCatch2() {
-  try {
-    throw new Error('error');
-  } catch (e) {
-    return Promise.reject('catch');
-  }
-}
-
-// Prints 'starting async work', 'async work done', 'cleanup'.
-async function validInTryCatch3() {
-  async function doAsyncWork(): Promise<void> {
-    console.log('starting async work');
-    await new Promise(resolve => setTimeout(resolve, 1000));
-    console.log('async work done');
-  }
-
-  try {
-    throw new Error('error');
-  } catch (e) {
-    return await doAsyncWork();
-  } finally {
-    console.log('cleanup');
-  }
-}
-
-async function validInTryCatch4() {
-  try {
-    throw new Error('error');
-  } catch (e) {
-    throw new Error('error2');
-  } finally {
-    return Promise.reject('finally');
-  }
-}
-
-async function validInTryCatch5() {
-  return Promise.resolve('try');
-}
-
-async function validInTryCatch6() {
-  return 'value';
-}
-
-async function validInTryCatch7() {
-  using x = createDisposable();
-  return await Promise.reject('using in scope');
-}
-```
-
-</TabItem>
-</Tabs>
-
-### `always`
-
-{/* insert option description */}
-
-Requires that all returned promises be awaited.
-
-This is a good option if you like the consistency of simply always awaiting promises, or prefer not having to consider the distinction between error-handling contexts and ordinary contexts.
-
-Examples of code with `always`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='"always"'
-async function invalidAlways1() {
-  try {
-    return Promise.resolve('try');
-  } catch (e) {}
-}
-
-async function invalidAlways2() {
-  return Promise.resolve('try');
-}
-
-async function invalidAlways3() {
-  return await 'value';
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='"always"'
-async function validAlways1() {
-  try {
-    return await Promise.resolve('try');
-  } catch (e) {}
-}
-
-async function validAlways2() {
-  return await Promise.resolve('try');
-}
-
-async function validAlways3() {
-  return 'value';
-}
-```
-
-</TabItem>
-</Tabs>
-
-### `error-handling-correctness-only`
-
-In error-handling contexts, the rule enforces that returned promises must be awaited.
-In ordinary contexts, the rule does not enforce any particular behavior around whether returned promises are awaited.
-
-This is a good option if you only want to benefit from rule's ability to catch control flow bugs in error-handling contexts, but don't want to enforce a particular style otherwise.
-
-:::info
-We recommend you configure either `in-try-catch` or `always` instead of this option.
-While the choice of whether to await promises outside of error-handling contexts is mostly stylistic, it's generally best to be consistent.
-:::
-
-Examples of additional correct code with `error-handling-correctness-only`:
-
-<Tabs>
-<TabItem value="✅ Correct">
-
-```ts option='"error-handling-correctness-only"'
-async function asyncFunction(): Promise<void> {
-  if (Math.random() < 0.5) {
-    return await Promise.resolve();
-  } else {
-    return Promise.resolve();
-  }
-}
-```
-
-</TabItem>
-</Tabs>
-
-### `never`
-
-{/* insert option description */}
-
-Disallows awaiting any returned promises.
-
-:::warning
-
-This option is deprecated and will be removed in a future major version of typescript-eslint.
-
-The `never` option introduces undesirable behavior in error-handling contexts.
-If you prefer to minimize returning awaited promises, consider instead using `in-try-catch` instead, which also generally bans returning awaited promises, but only where it is _safe_ not to await a promise.
-
-See more details at [typescript-eslint#9433](https://github.com/typescript-eslint/typescript-eslint/issues/9433).
-:::
-
-Examples of code with `never`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='"never"'
-async function invalidNever1() {
-  try {
-    return await Promise.resolve('try');
-  } catch (e) {}
-}
-
-async function invalidNever2() {
-  return await Promise.resolve('try');
-}
-
-async function invalidNever3() {
-  return await 'value';
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='"never"'
-async function validNever1() {
-  try {
-    return Promise.resolve('try');
-  } catch (e) {}
-}
-
-async function validNever2() {
-  return Promise.resolve('try');
-}
-
-async function validNever3() {
-  return 'value';
-}
-```
-
-</TabItem>
-</Tabs>
-
-{/* Intentionally Omitted: When Not To Use It */}

package/docs/rules/semi.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/sort-type-constituents.mdx

@@ -1,209 +0,0 @@
----
-description: 'Enforce constituents of a type union/intersection to be sorted alphabetically.'
----
-
-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/sort-type-constituents** for documentation.
-
-:::danger Deprecated
-This rule has been deprecated in favor of the [`perfectionist/sort-intersection-types`](https://perfectionist.dev/rules/sort-intersection-types) and [`perfectionist/sort-union-types`](https://perfectionist.dev/rules/sort-union-types) rules.
-
-See [Docs: Deprecate sort-type-constituents in favor of eslint-plugin-perfectionist](https://github.com/typescript-eslint/typescript-eslint/issues/8915) and [eslint-plugin: Feature freeze naming and sorting stylistic rules](https://github.com/typescript-eslint/typescript-eslint/issues/8792) for more information.
-:::
-
-Sorting union (`|`) and intersection (`&`) types can help:
-
-- keep your codebase standardized
-- find repeated types
-- reduce diff churn
-
-This rule reports on any types that aren't sorted alphabetically.
-
-> Types are sorted case-insensitively and treating numbers like a human would, falling back to character code sorting in case of ties.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-type T1 = B | A;
-
-type T2 = { b: string } & { a: string };
-
-type T3 = [1, 2, 4] & [1, 2, 3];
-
-type T4 =
-  | [1, 2, 4]
-  | [1, 2, 3]
-  | { b: string }
-  | { a: string }
-  | (() => void)
-  | (() => string)
-  | 'b'
-  | 'a'
-  | 'b'
-  | 'a'
-  | readonly string[]
-  | readonly number[]
-  | string[]
-  | number[]
-  | B
-  | A
-  | string
-  | any;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-type T1 = A | B;
-
-type T2 = { a: string } & { b: string };
-
-type T3 = [1, 2, 3] & [1, 2, 4];
-
-type T4 =
-  | A
-  | B
-  | number[]
-  | string[]
-  | any
-  | string
-  | readonly number[]
-  | readonly string[]
-  | 'a'
-  | 'a'
-  | 'b'
-  | 'b'
-  | (() => string)
-  | (() => void)
-  | { a: string }
-  | { b: string }
-  | [1, 2, 3]
-  | [1, 2, 4];
-```
-
-</TabItem>
-</Tabs>
-
-## Options
-
-### `caseSensitive`
-
-{/* insert option description */}
-
-Examples of code with `{ "caseSensitive": true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "caseSensitive": true }'
-type T = 'DeletedAt' | 'DeleteForever';
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "caseSensitive": true }'
-type T = 'DeleteForever' | 'DeletedAt';
-```
-
-</TabItem>
-</Tabs>
-
-### `checkIntersections`
-
-{/* insert option description */}
-
-Examples of code with `{ "checkIntersections": true }` (the default):
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "checkIntersections": true }'
-type ExampleIntersection = B & A;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "checkIntersections": true }'
-type ExampleIntersection = A & B;
-```
-
-</TabItem>
-</Tabs>
-
-### `checkUnions`
-
-{/* insert option description */}
-
-Examples of code with `{ "checkUnions": true }` (the default):
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "checkUnions": true }'
-type ExampleUnion = B | A;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "checkUnions": true }'
-type ExampleUnion = A | B;
-```
-
-</TabItem>
-</Tabs>
-
-### `groupOrder`
-
-{/* insert option description */}
-
-Each constituent of the type is placed into a group, and then the rule sorts alphabetically within each group.
-The ordering of groups is determined by this option.
-
-- `conditional` - Conditional types (`A extends B ? C : D`)
-- `function` - Function and constructor types (`() => void`, `new () => type`)
-- `import` - Import types (`import('path')`)
-- `intersection` - Intersection types (`A & B`)
-- `keyword` - Keyword types (`any`, `string`, etc)
-- `literal` - Literal types (`1`, `'b'`, `true`, etc)
-- `named` - Named types (`A`, `A['prop']`, `B[]`, `Array<C>`)
-- `object` - Object types (`{ a: string }`, `{ [key: string]: number }`)
-- `operator` - Operator types (`keyof A`, `typeof B`, `readonly C[]`)
-- `tuple` - Tuple types (`[A, B, C]`)
-- `union` - Union types (`A | B`)
-- `nullish` - `null` and `undefined`
-
-For example, configuring the rule with `{ "groupOrder": ["literal", "nullish" ]}`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "groupOrder": ["literal", "nullish" ]}'
-type ExampleGroup = null | 123;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "groupOrder": ["literal", "nullish" ]}'
-type ExampleGroup = 123 | null;
-```
-
-</TabItem>
-</Tabs>
-
-## 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, predictable order for intersection and union types.
-However, keep in mind that inconsistent style can harm readability in a project.

package/docs/rules/sort-type-union-intersection-members.mdx

@@ -1,16 +0,0 @@
----
-displayed_sidebar: rulesSidebar
----
-
-:::danger Deprecated
-
-This rule has been renamed to [`sort-type-constituents`](https://typescript-eslint.io/rules/sort-type-constituents).
-
-:::
-
-<!--
-This doc file has been left on purpose to help direct people to the replacement rule.
-
-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/space-before-blocks.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/space-before-function-paren.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/space-infix-ops.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. -->