@typescript-eslint/eslint-plugin 8.0.0-alpha.8 → 8.0.0

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

@@ -0,0 +1,63 @@
+---
+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
+
+- [`no-empty-object-type`](./no-empty-object-type.mdx)
+- [`no-restricted-types`](./no-restricted-types.mdx)
+- [`no-wrapper-object-types`](./no-wrapper-object-types.mdx)

package/docs/rules/no-unused-expressions.mdx

@@ -10,4 +10,44 @@ import TabItem from '@theme/TabItem';
 > See **https://typescript-eslint.io/rules/no-unused-expressions** for documentation.
 
 This rule extends the base [`eslint/no-unused-expressions`](https://eslint.org/docs/rules/no-unused-expressions) rule.
-It adds support for optional call expressions `x?.()`, and directive in module declarations.
+It supports TypeScript-specific expressions:
+
+- Marks directives in modules declarations (`"use strict"`, etc.) as not unused
+- Marks the following expressions as unused if their wrapped value expressions are unused:
+  - Assertion expressions: `x as number;`, `x!;`, `<number>x;`
+  - Instantiation expressions: `Set<number>;`
+
+Although the type expressions never have runtime side effects (that is, `x!;` is the same as `x;`), they can be used to assert types for testing purposes.
+
+## Examples
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+Set<number>;
+1 as number;
+window!;
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+function getSet() {
+  return Set;
+}
+
+// Funtion calls are allowed, so type expressions that wrap function calls are allowed
+getSet()<number>;
+getSet() as Set<unknown>;
+getSet()!;
+
+// Namespaces can have directives
+namespace A {
+  'use strict';
+}
+```
+
+</TabItem>
+</Tabs>

package/docs/rules/no-unused-vars.mdx

@@ -47,3 +47,8 @@ We generally recommend using `@typescript-eslint/no-unused-vars` to flag unused
 :::tip
 Editors such as VS Code will still generally "grey out" unused variables even if `noUnusedLocals` and `noUnusedParameters` are not enabled in a project.
 :::
+
+Also see similar rules provided by ESLint:
+
+- [`no-unused-private-class-members`](https://eslint.org/docs/latest/rules/no-unused-private-class-members)
+- [`no-unused-labels`](https://eslint.org/docs/latest/rules/no-unused-labels)

package/docs/rules/no-useless-template-literals.mdx

@@ -1,61 +1,5 @@
----
-description: 'Disallow unnecessary template literals.'
----
+:::danger Deprecated
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
+This rule has been renamed to [`no-unnecessary-template-expression`](./no-unnecessary-template-expression.mdx). See [#8544](https://github.com/typescript-eslint/typescript-eslint/issues/8544) for more information.
 
-> 🛑 This file is source code, not the primary documentation location! 🛑
->
-> See **https://typescript-eslint.io/rules/no-useless-template-literals** for documentation.
-
-This rule reports template literals that can be simplified to a normal string literal.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-const ab1 = `${'a'}${'b'}`;
-const ab2 = `a${'b'}`;
-
-const stringWithNumber = `${'1 + 1 = '}${2}`;
-
-const stringWithBoolean = `${'true is '}${true}`;
-
-const text = 'a';
-const wrappedText = `${text}`;
-
-declare const intersectionWithString: string & { _brand: 'test-brand' };
-const wrappedIntersection = `${intersectionWithString}`;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-const ab1 = 'ab';
-const ab2 = 'ab';
-
-const stringWithNumber = `1 + 1 = 2`;
-
-const stringWithBoolean = `true is true`;
-
-const text = 'a';
-const wrappedText = text;
-
-declare const intersectionWithString: string & { _brand: 'test-brand' };
-const wrappedIntersection = intersectionWithString;
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-When you want to allow string expressions inside template literals.
-
-## Related To
-
-- [`restrict-template-expressions`](./restrict-template-expressions.mdx)
+:::

package/docs/rules/no-var-requires.mdx

@@ -9,6 +9,12 @@ import TabItem from '@theme/TabItem';
 >
 > See **https://typescript-eslint.io/rules/no-var-requires** for documentation.
 
+:::danger Deprecated
+
+This rule has been deprecated in favour of the [`@typescript-eslint/no-require-imports`](./no-require-imports.mdx) rule.
+
+:::
+
 In other words, the use of forms such as `var foo = require("foo")` are banned. Instead use ES6 style imports or `import foo = require("foo")` imports.
 
 ## Examples

package/docs/rules/no-wrapper-object-types.mdx

@@ -0,0 +1,75 @@
+---
+description: 'Disallow using confusing built-in primitive class wrappers.'
+---
+
+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-wrapper-object-types** for documentation.
+
+TypeScript defines several confusing pairs of types that look very similar to each other, but actually mean different things: `boolean`/`Boolean`, `number`/`Number`, `string`/`String`, `bigint`/`BigInt`, `symbol`/`Symbol`, `object`/`Object`.
+In general, only the lowercase variant is appropriate to use.
+Therefore, this rule enforces that you only use the lowercase variant.
+
+JavaScript has [8 data types](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures) at runtime, and these are described in TypeScript by the lowercase types `undefined`, `null`, `boolean`, `number`, `string`, `bigint`, `symbol`, and `object`.
+
+As for the uppercase types, these are _structural types_ which describe JavaScript "wrapper" objects for each of the data types, such as [`Boolean`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) and [`Number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number).
+Additionally, due to the quirks of structural typing, the corresponding primitives are _also_ assignable to these uppercase types, since they have the same "shape".
+
+It is a universal best practice to work directly with the built-in primitives, like `0`, rather than objects that "look like" the corresponding primitive, like `new Number(0)`.
+
+- Primitives have the expected value semantics with `==` and `===` equality checks, whereas their object counterparts are compared by reference.
+  That is to say, `"str" === "str"` but `new String("str") !== new String("str")`.
+- Primitives have well-known behavior around truthiness/falsiness which is common to rely on, whereas all objects are truthy, regardless of the wrapped value (e.g. `new Boolean(false)` is truthy).
+- TypeScript only allows arithmetic operations (e.g. `x - y`) to be performed on numeric primitives, not objects.
+
+As a result, using the lowercase type names like `number` in TypeScript types instead of the uppercase names like `Number` is a better practice that describes code more accurately.
+
+Examples of code for this rule:
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+let myBigInt: BigInt;
+let myBoolean: Boolean;
+let myNumber: Number;
+let myString: String;
+let mySymbol: Symbol;
+
+let myObject: Object = 'allowed by TypeScript';
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+let myBigint: bigint;
+let myBoolean: boolean;
+let myNumber: number;
+let myString: string;
+let mySymbol: symbol;
+
+let myObject: object = "Type 'string' is not assignable to type 'object'.";
+```
+
+</TabItem>
+</Tabs>
+
+## When Not To Use It
+
+If your project is a rare one that intentionally deals with the class equivalents of primitives, it might not be worthwhile to use 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.
+
+## Further Reading
+
+- [MDN documentation on primitives](https://developer.mozilla.org/en-US/docs/Glossary/Primitive)
+- [MDN documentation on `string` primitives and `String` objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_primitives_and_string_objects)
+
+## Related To
+
+- [`no-empty-object-type`](./no-empty-object-type.mdx)
+- [`no-restricted-types`](./no-restricted-types.mdx)
+- [`no-unsafe-function-type`](./no-unsafe-function-type.mdx)

package/docs/rules/only-throw-error.mdx

@@ -14,6 +14,13 @@ The fundamental benefit of `Error` objects is that they automatically keep track
 
 This rule restricts what can be thrown as an exception.
 
+:::info[Migration from `no-throw-literal`]
+
+This rule was formerly known as `no-throw-literal`.
+The new name is a drop-in replacement with identical functionality.
+
+:::
+
 ## Examples
 
 This rule is aimed at maintaining consistency when throwing exception by disallowing to throw literals and other expressions which cannot possibly be an `Error` object.

package/docs/rules/prefer-readonly-parameter-types.mdx

@@ -142,11 +142,12 @@ interface Foo {
 
 Some complex types cannot easily be made readonly, for example the `HTMLElement` type or the `JQueryStatic` type from `@types/jquery`. This option allows you to globally disable reporting of such types.
 
-Each item must be one of:
+This option takes an array of type specifiers to ignore.
+Each item in the array must have one of the following forms:
 
-- A type defined in a file (`{from: "file", name: "Foo", path: "src/foo-file.ts"}` with `path` being an optional path relative to the project root directory)
-- A type from the default library (`{from: "lib", name: "Foo"}`)
-- A type from a package (`{from: "package", name: "Foo", package: "foo-lib"}`, this also works for types defined in a typings package).
+- A type defined in a file (`{ from: "file", name: "Foo", path: "src/foo-file.ts" }` with `path` being an optional path relative to the project root directory)
+- A type from the default library (`{ from: "lib", name: "Foo" }`)
+- A type from a package (`{ from: "package", name: "Foo", package: "foo-lib" }`, this also works for types defined in a typings package).
 
 Additionally, a type may be defined just as a simple string, which then matches the type independently of its origin.
 
@@ -401,3 +402,8 @@ function foo(arg: MyType) {}
 ## When Not To Use It
 
 If your project does not attempt to enforce strong immutability guarantees of parameters, you can avoid this rule.
+
+This rule is very strict on what it considers mutable.
+Many types that describe themselves as readonly are considered mutable because they have mutable properties such as arrays or tuples.
+To work around these limitations, you might need to use the rule's options.
+In particular, the [`allow` option](#allow) can explicitly mark a type as readonly.

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

@@ -9,6 +9,16 @@ import TabItem from '@theme/TabItem';
 >
 > 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.
 

package/docs/rules/require-await.mdx

@@ -1,5 +1,5 @@
 ---
-description: 'Disallow async functions which have no `await` expression.'
+description: 'Disallow async functions which do not return promises and have no `await` expression.'
 ---
 
 import Tabs from '@theme/Tabs';
@@ -10,7 +10,7 @@ import TabItem from '@theme/TabItem';
 > See **https://typescript-eslint.io/rules/require-await** for documentation.
 
 This rule extends the base [`eslint/require-await`](https://eslint.org/docs/rules/require-await) rule.
-It uses type information to add support for `async` functions that return a `Promise`.
+It uses type information to allow promise-returning functions to be marked as `async` without containing an `await` expression.
 
 ## Examples
 

package/docs/rules/restrict-template-expressions.mdx

@@ -10,7 +10,7 @@ import TabItem from '@theme/TabItem';
 > See **https://typescript-eslint.io/rules/restrict-template-expressions** for documentation.
 
 JavaScript automatically [converts an object to a string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion) in a string context, such as when concatenating it with a string using `+` or embedding it in a template literal using `${}`.
-The default `toString()` method of objects returns `"[object Object]"`, which is often not what was intended.
+The default `toString()` method of objects uses the format `"[object Object]"`, which is often not what was intended.
 This rule reports on values used in a template literal string that aren't strings, optionally allowing other data types that provide useful stringification results.
 
 :::note

package/docs/rules/return-await.mdx

@@ -1,5 +1,5 @@
 ---
-description: 'Enforce consistent returning of awaited values.'
+description: 'Enforce consistent awaiting of returned promises.'
 ---
 
 import Tabs from '@theme/Tabs';
@@ -9,30 +9,53 @@ import TabItem from '@theme/TabItem';
 >
 > See **https://typescript-eslint.io/rules/return-await** for documentation.
 
-Returning an awaited promise can make sense for better stack trace information as well as for consistent error handling (returned promises will not be caught in an async function try/catch).
-
 This rule builds on top of the [`eslint/no-return-await`](https://eslint.org/docs/rules/no-return-await) rule.
 It expands upon the base rule to add support for optionally requiring `return await` in certain cases.
 
-The extended rule is named `return-await` instead of `no-return-await` because the extended rule can enforce the positive or the negative. Additionally, while the core rule is now deprecated, the extended rule is still useful in many contexts.
+The extended rule is named `return-await` instead of `no-return-await` because the extended rule can enforce the positive or the negative. Additionally, while the core rule is now deprecated, the extended rule is still useful in many contexts:
+
+- 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 also 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).
 
 ## Options
 
 ```ts
-type Options = 'in-try-catch' | 'always' | 'never';
+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`
 
-Requires that a returned promise must be `await`ed in `try-catch-finally` blocks, and disallows it elsewhere.
-Specifically:
+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.
 
-- if you `return` a promise within a `try`, then it must be `await`ed.
-- if you `return` a promise within a `catch`, and there **_is no_** `finally`, then it **_must not_** be `await`ed.
-- if you `return` a promise within a `catch`, and there **_is a_** `finally`, then it **_must_** be `await`ed.
-- if you `return` a promise within a `finally`, then it **_must not_** be `await`ed.
+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`:
 
@@ -42,23 +65,34 @@ Examples of code with `in-try-catch`:
 ```ts option='"in-try-catch"'
 async function invalidInTryCatch1() {
   try {
-    return Promise.resolve('try');
-  } catch (e) {}
+    return Promise.reject('try');
+  } catch (e) {
+    // Doesn't execute due to missing await.
+  }
 }
 
 async function invalidInTryCatch2() {
   try {
     throw new Error('error');
   } catch (e) {
-    return await Promise.resolve('catch');
+    // 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) {
-    return Promise.resolve('catch');
+    // Missing await.
+    return doAsyncWork();
   } finally {
     console.log('cleanup');
   }
@@ -70,7 +104,8 @@ async function invalidInTryCatch4() {
   } catch (e) {
     throw new Error('error2');
   } finally {
-    return await Promise.resolve('finally');
+    // Unnecessary await; rejections here don't impact control flow.
+    return await Promise.reject('finally');
   }
 }
 
@@ -81,6 +116,11 @@ async function invalidInTryCatch5() {
 async function invalidInTryCatch6() {
   return await 'value';
 }
+
+async function invalidInTryCatch7() {
+  using x = createDisposable();
+  return Promise.reject('using in scope');
+}
 ```
 
 </TabItem>
@@ -89,23 +129,32 @@ async function invalidInTryCatch6() {
 ```ts option='"in-try-catch"'
 async function validInTryCatch1() {
   try {
-    return await Promise.resolve('try');
-  } catch (e) {}
+    return await Promise.reject('try');
+  } catch (e) {
+    // Executes as expected.
+  }
 }
 
 async function validInTryCatch2() {
   try {
     throw new Error('error');
   } catch (e) {
-    return Promise.resolve('catch');
+    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 Promise.resolve('catch');
+    return await doAsyncWork();
   } finally {
     console.log('cleanup');
   }
@@ -117,7 +166,7 @@ async function validInTryCatch4() {
   } catch (e) {
     throw new Error('error2');
   } finally {
-    return Promise.resolve('finally');
+    return Promise.reject('finally');
   }
 }
 
@@ -128,6 +177,11 @@ async function validInTryCatch5() {
 async function validInTryCatch6() {
   return 'value';
 }
+
+async function validInTryCatch7() {
+  using x = createDisposable();
+  return await Promise.reject('using in scope');
+}
 ```
 
 </TabItem>
@@ -135,7 +189,9 @@ async function validInTryCatch6() {
 
 ### `always`
 
-Requires that all returned promises are `await`ed.
+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`:
 
@@ -180,9 +236,49 @@ async function validAlways3() {
 </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`
 
-Disallows all `await`ing any returned promises.
+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`:
 

package/docs/rules/sort-type-constituents.mdx

@@ -9,6 +9,12 @@ import TabItem from '@theme/TabItem';
 >
 > 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
@@ -19,15 +25,6 @@ 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.
 
-:::note
-This rule is _feature frozen_: it will no longer receive new features such as new options.
-It still will accept bug and documentation fixes for its existing area of features.
-
-Stylistic rules that enforce naming and/or sorting conventions tend to grow incomprehensibly complex as increasingly obscure features are requested.
-This rule has reached the limit of what is reasonable for the typescript-eslint project to maintain.
-See [eslint-plugin: Feature freeze naming and sorting stylistic rules](https://github.com/typescript-eslint/typescript-eslint/issues/8792) for more information.
-:::
-
 ## Examples
 
 <Tabs>
@@ -97,6 +94,29 @@ type T4 =
 
 ## Options
 
+### `caseSensitive`
+
+Whether to sort using case sensitive string comparisons.
+
+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`
 
 Whether to check intersection types (`&`).