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

package/docs/rules/no-unnecessary-boolean-literal-compare.mdx

@@ -1,165 +0,0 @@
----
-description: 'Disallow unnecessary equality comparisons against boolean literals.'
----
-
-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-unnecessary-boolean-literal-compare** for documentation.
-
-Comparing boolean values to boolean literals is unnecessary: those comparisons result in the same booleans.
-Using the boolean values directly, or via a unary negation (`!value`), is more concise and clearer.
-
-This rule ensures that you do not include unnecessary comparisons with boolean literals.
-A comparison is considered unnecessary if it checks a boolean literal against any variable with just the `boolean` type.
-A comparison is **_not_** considered unnecessary if the type is a union of booleans (`string | boolean`, `SomeObject | boolean`, etc.).
-
-## Examples
-
-:::note
-Throughout this page, only strict equality (`===` and `!==`) are used in the examples.
-However, the implementation of the rule does not distinguish between strict and loose equality.
-Any example below that uses `===` would be treated the same way if `==` was used, and `!==` would be treated the same way if `!=` was used.
-:::
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-declare const someCondition: boolean;
-if (someCondition === true) {
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-declare const someCondition: boolean;
-if (someCondition) {
-}
-
-declare const someObjectBoolean: boolean | Record<string, unknown>;
-if (someObjectBoolean === true) {
-}
-
-declare const someStringBoolean: boolean | string;
-if (someStringBoolean === true) {
-}
-```
-
-</TabItem>
-</Tabs>
-
-## Options
-
-This rule always checks comparisons between a boolean variable and a boolean
-literal. Comparisons between nullable boolean variables and boolean literals
-are **not** checked by default.
-
-### `allowComparingNullableBooleansToTrue`
-
-{/* insert option description */}
-
-Examples of code for this rule with `{ allowComparingNullableBooleansToTrue: false }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "allowComparingNullableBooleansToTrue": false }'
-declare const someUndefinedCondition: boolean | undefined;
-if (someUndefinedCondition === true) {
-}
-
-declare const someNullCondition: boolean | null;
-if (someNullCondition !== true) {
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "allowComparingNullableBooleansToTrue": false }'
-declare const someUndefinedCondition: boolean | undefined;
-if (someUndefinedCondition) {
-}
-
-declare const someNullCondition: boolean | null;
-if (!someNullCondition) {
-}
-```
-
-</TabItem>
-</Tabs>
-
-### `allowComparingNullableBooleansToFalse`
-
-{/* insert option description */}
-
-Examples of code for this rule with `{ allowComparingNullableBooleansToFalse: false }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "allowComparingNullableBooleansToFalse": false }'
-declare const someUndefinedCondition: boolean | undefined;
-if (someUndefinedCondition === false) {
-}
-
-declare const someNullCondition: boolean | null;
-if (someNullCondition !== false) {
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "allowComparingNullableBooleansToFalse": false }'
-declare const someUndefinedCondition: boolean | undefined;
-if (!(someUndefinedCondition ?? true)) {
-}
-
-declare const someNullCondition: boolean | null;
-if (someNullCondition ?? true) {
-}
-```
-
-</TabItem>
-</Tabs>
-
-### `allowRuleToRunWithoutStrictNullChecksIKnowWhatIAmDoing`
-
-:::danger Deprecated
-
-This option will be removed in the next major version of typescript-eslint.
-
-:::
-
-{/* insert option description */}
-
-Without `strictNullChecks`, TypeScript essentially erases `undefined` and `null` from the types. This means when this rule inspects the types from a variable, **it will not be able to tell that the variable might be `null` or `undefined`**, which essentially makes this rule useless.
-
-You should be using `strictNullChecks` to ensure complete type-safety in your codebase.
-
-If for some reason you cannot turn on `strictNullChecks`, but still want to use this rule - you can use this option to allow it - but know that the behavior of this rule is _undefined_ with the compiler option turned off. We will not accept bug reports if you are using this option.
-
-## Fixer
-
-|           Comparison           | Fixer Output                    | Notes                                                                               |
-| :----------------------------: | ------------------------------- | ----------------------------------------------------------------------------------- |
-|     `booleanVar === true`      | `booleanVar`                    |                                                                                     |
-|     `booleanVar !== true`      | `!booleanVar`                   |                                                                                     |
-|     `booleanVar === false`     | `!booleanVar`                   |                                                                                     |
-|     `booleanVar !== false`     | `booleanVar`                    |                                                                                     |
-| `nullableBooleanVar === true`  | `nullableBooleanVar`            | Only checked/fixed if the `allowComparingNullableBooleansToTrue` option is `false`  |
-| `nullableBooleanVar !== true`  | `!nullableBooleanVar`           | Only checked/fixed if the `allowComparingNullableBooleansToTrue` option is `false`  |
-| `nullableBooleanVar === false` | `!(nullableBooleanVar ?? true)` | Only checked/fixed if the `allowComparingNullableBooleansToFalse` option is `false` |
-| `nullableBooleanVar !== false` | `nullableBooleanVar ?? true`    | Only checked/fixed if the `allowComparingNullableBooleansToFalse` option is `false` |
-
-## When Not To Use It
-
-Do not use this rule when `strictNullChecks` is disabled.
-ESLint is not able to distinguish between `false` and `undefined` or `null` values.
-This can cause unintended code changes when using autofix.

package/docs/rules/no-unnecessary-condition.mdx

@@ -1,293 +0,0 @@
----
-description: 'Disallow conditionals where the type is always truthy or always falsy.'
----
-
-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-unnecessary-condition** for documentation.
-
-Any expression being used as a condition must be able to evaluate as truthy or falsy in order to be considered "necessary".
-Conversely, any expression that always evaluates to truthy or always evaluates to falsy, as determined by the type of the expression, is considered unnecessary and will be flagged by this rule.
-
-The following expressions are checked:
-
-- Arguments to the `&&`, `||` and `?:` (ternary) operators
-- Conditions for `if`, `for`, `while`, and `do-while` statements
-- `case`s in `switch` statements
-- Base values of optional chain expressions
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-function head<T>(items: T[]) {
-  // items can never be nullable, so this is unnecessary
-  if (items) {
-    return items[0].toUpperCase();
-  }
-}
-
-function foo(arg: 'bar' | 'baz') {
-  // arg is never nullable or empty string, so this is unnecessary
-  if (arg) {
-  }
-}
-
-function bar<T>(arg: string) {
-  // arg can never be nullish, so ?. is unnecessary
-  return arg?.length;
-}
-
-// Checks array predicate return types, where possible
-[
-  [1, 2],
-  [3, 4],
-].filter(t => t); // number[] is always truthy
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-function head<T>(items: T[]) {
-  // Necessary, since items.length might be 0
-  if (items.length) {
-    return items[0].toUpperCase();
-  }
-}
-
-function foo(arg: string) {
-  // Necessary, since arg might be ''.
-  if (arg) {
-  }
-}
-
-function bar(arg?: string | null) {
-  // Necessary, since arg might be nullish
-  return arg?.length;
-}
-
-[0, 1, 2, 3].filter(t => t); // number can be truthy or falsy
-```
-
-</TabItem>
-</Tabs>
-
-## Options
-
-### `allowConstantLoopConditions`
-
-{/* insert option description */}
-
-#### `'never'`
-
-Disallow constant conditions in loops. Same as `false`.
-
-Example of incorrect code for `{ allowConstantLoopConditions: 'never' }`:
-
-```ts option='{ "allowConstantLoopConditions": "never" }' showPlaygroundButton
-while (true) {
-  // ...
-}
-
-for (; true; ) {
-  // ...
-}
-
-do {
-  // ...
-} while (true);
-```
-
-#### `'always'`
-
-Allow constant conditions in loops. Same as `true`.
-
-Example of correct code for `{ allowConstantLoopConditions: 'always' }`:
-
-```ts option='{ "allowConstantLoopConditions": "always" }' showPlaygroundButton
-while (true) {
-  // ...
-}
-
-for (; true; ) {
-  // ...
-}
-
-do {
-  // ...
-} while (true);
-```
-
-#### `'only-allowed-literals'`
-
-Permit idiomatic constant literal conditions in `while` loop conditions.
-
-Specifically, `true`, `false`, `0`, and `1` are allowed despite always being truthy or falsy, as these are common patterns and are not likely to represent developer errors.
-
-Example of correct code for `{ allowConstantLoopConditions: 'only-allowed-literals' }`:
-
-```ts option='{ "allowConstantLoopConditions": "only-allowed-literals" }' showPlaygroundButton
-while (true) {
-  // ...
-}
-```
-
-Example of incorrect code for `{ allowConstantLoopConditions: 'only-allowed-literals' }`:
-
-```ts option='{ "allowConstantLoopConditions": "only-allowed-literals" }' showPlaygroundButton
-// `alwaysTrue` has the type of `true` (which isn't allowed)
-// as only the literal value of `true` is allowed.
-
-declare const alwaysTrue: true;
-
-while (alwaysTrue) {
-  // ...
-}
-
-// not even a variable that references the value of `true` is allowed, only
-// the literal value of `true` used directly.
-
-const thisIsTrue = true;
-
-while (thisIsTrue) {
-  // ...
-}
-```
-
-### `checkTypePredicates`
-
-{/* insert option description */}
-
-Example of additional incorrect code with `{ checkTypePredicates: true }`:
-
-```ts option='{ "checkTypePredicates": true }' showPlaygroundButton
-function assert(condition: unknown): asserts condition {
-  if (!condition) {
-    throw new Error('Condition is falsy');
-  }
-}
-
-assert(false); // Unnecessary; condition is always falsy.
-
-const neverNull = {};
-assert(neverNull); // Unnecessary; condition is always truthy.
-
-function isString(value: unknown): value is string {
-  return typeof value === 'string';
-}
-
-declare const s: string;
-
-// Unnecessary; s is always a string.
-if (isString(s)) {
-}
-
-function assertIsString(value: unknown): asserts value is string {
-  if (!isString(value)) {
-    throw new Error('Value is not a string');
-  }
-}
-
-assertIsString(s); // Unnecessary; s is always a string.
-```
-
-Whether this option makes sense for your project may vary.
-Some projects may intentionally use type predicates to ensure that runtime values do indeed match the types according to TypeScript, especially in test code.
-Often, it makes sense to use eslint-disable comments in these cases, with a comment indicating why the condition should be checked at runtime, despite appearing unnecessary.
-However, in some contexts, it may be more appropriate to keep this option disabled entirely.
-
-### `allowRuleToRunWithoutStrictNullChecksIKnowWhatIAmDoing`
-
-{/* insert option description */}
-
-:::danger Deprecated
-This option will be removed in the next major version of typescript-eslint.
-:::
-
-If this is set to `false`, then the rule will error on every file whose `tsconfig.json` does _not_ have the `strictNullChecks` compiler option (or `strict`) set to `true`.
-
-Without `strictNullChecks`, TypeScript essentially erases `undefined` and `null` from the types. This means when this rule inspects the types from a variable, **it will not be able to tell that the variable might be `null` or `undefined`**, which essentially makes this rule useless.
-
-You should be using `strictNullChecks` to ensure complete type-safety in your codebase.
-
-If for some reason you cannot turn on `strictNullChecks`, but still want to use this rule - you can use this option to allow it - but know that the behavior of this rule is _undefined_ with the compiler option turned off. We will not accept bug reports if you are using this option.
-
-## Limitations
-
-This rule is powered by TypeScript types, therefore, if the types do not match match the runtime behavior, the rule may report inaccurately.
-This can happen in several commonplace scenarios.
-
-### Possibly-undefined indexed access
-
-By default, TypeScript optimistically assumes that indexed access will always return a value.
-This means that cases like the following will be erroneously flagged as unnecessary conditions:
-
-```ts showPlaygroundButton
-const array: string[] = [];
-const firstElement = array[0];
-// false positive
-if (firstElement != null) {
-  // ...
-}
-
-const record: Record<string, string> = {};
-const someValue = record.someKey;
-// false positive
-if (someValue != null) {
-  // ...
-}
-```
-
-To get pessimistic, but correct, types for these cases, you can use TypeScript's [`noUncheckedIndexedAccess` compiler option](https://www.typescriptlang.org/tsconfig/#noUncheckedIndexedAccess), though this is often unwieldy in real-world usage.
-Another workaround is to use `array.at(0)` (which is always possibly-undefined) to indicate array access that may be out-of-bounds.
-Otherwise, a disable comment will often make sense for these kinds of cases.
-
-### Values modified within function calls
-
-The following code will be erroneously flagged as unnecessary, even though the condition is modified within the function call.
-
-```ts showPlaygroundButton
-let condition = false;
-
-const f = () => {
-  condition = Math.random() > 0.5;
-};
-f();
-
-if (condition) {
-  // ...
-}
-```
-
-This occurs due to limitations of TypeScript's type narrowing.
-See [microsoft/TypeScript#9998](https://github.com/microsoft/TypeScript/issues/9998) for details.
-We recommend using a [type assertion](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#type-assertions) in these cases, like so:
-
-```ts showPlaygroundButton
-let condition = false as boolean;
-
-const f = () => {
-  condition = Math.random() > 0.5;
-};
-f();
-
-if (condition) {
-  // ...
-}
-```
-
-## When Not To Use It
-
-If your project is not accurately typed, such as if it's in the process of being converted to TypeScript or is susceptible to [trade-offs in control flow analysis](https://github.com/Microsoft/TypeScript/issues/9998), it may be difficult to enable this rule for particularly non-type-safe areas of code.
-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
-
-- ESLint: [no-constant-condition](https://eslint.org/docs/rules/no-constant-condition) - `no-unnecessary-condition` is essentially a stronger version of `no-constant-condition`, but requires type information.
-- [strict-boolean-expressions](./strict-boolean-expressions.mdx) - a more opinionated version of `no-unnecessary-condition`. `strict-boolean-expressions` enforces a specific code style, while `no-unnecessary-condition` is about correctness.

package/docs/rules/no-unnecessary-parameter-property-assignment.mdx

@@ -1,42 +0,0 @@
----
-description: 'Disallow unnecessary assignment of constructor property 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/no-unnecessary-parameter-property-assignment** for documentation.
-
-[TypeScript's parameter properties](https://www.typescriptlang.org/docs/handbook/2/classes.html#parameter-properties) allow creating and initializing a member in one place.
-Therefore, in most cases, it is not necessary to assign parameter properties of the same name to members within a constructor.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-class Foo {
-  constructor(public bar: string) {
-    this.bar = bar;
-  }
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-class Foo {
-  constructor(public bar: string) {}
-}
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-If you don't use parameter properties, you can ignore this rule.

package/docs/rules/no-unnecessary-qualifier.mdx

@@ -1,57 +0,0 @@
----
-description: 'Disallow unnecessary namespace qualifiers.'
----
-
-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-unnecessary-qualifier** for documentation.
-
-Members of TypeScript enums and namespaces are generally retrieved as qualified property lookups: e.g. `Enum.member`.
-However, when accessed within their parent enum or namespace, the qualifier is unnecessary: e.g. just `member` instead of `Enum.member`.
-This rule reports when an enum or namespace qualifier is unnecessary.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-enum A {
-  B,
-  C = A.B,
-}
-```
-
-```ts
-namespace A {
-  export type B = number;
-  const x: A.B = 3;
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-enum A {
-  B,
-  C = B,
-}
-```
-
-```ts
-namespace A {
-  export type B = number;
-  const x: B = 3;
-}
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-If you explicitly prefer to use fully qualified names, such as for explicitness, then you don't need to use this rule.

package/docs/rules/no-unnecessary-template-expression.mdx

@@ -1,108 +0,0 @@
----
-description: 'Disallow unnecessary template expressions.'
----
-
-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-unnecessary-template-expression** for documentation.
-
-This rule reports template literals that contain substitution expressions (also variously referred to as embedded expressions or string interpolations) that are unnecessary and can be simplified.
-
-:::info[Migration from `no-useless-template-literals`]
-
-This rule was formerly known as [`no-useless-template-literals`](./no-useless-template-literals.mdx).
-The new name is a drop-in replacement with identical functionality.
-
-:::
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-// Static values can be incorporated into the surrounding template.
-
-const ab1 = `${'a'}${'b'}`;
-const ab2 = `a${'b'}`;
-type AB1 = `${'A'}${'B'}`;
-type AB2 = `A${'B'}`;
-
-const stringWithNumber = `${'1 + 1 = '}${2}`;
-
-const stringWithBoolean = `${'true is '}${true}`;
-
-// Some simple expressions that are already strings
-// can be rewritten without a template at all.
-
-const text = 'a';
-const wrappedText = `${text}`;
-type Text = 'A';
-type WrappedText = `${Text}`;
-
-declare const intersectionWithString: string & { _brand: 'test-brand' };
-const wrappedIntersection = `${intersectionWithString}`;
-type IntersectionWithString = string & { _brand: 'test-brand' };
-type WrappedIntersection = `${IntersectionWithString}`;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-// Static values can be incorporated into the surrounding template.
-
-const ab1 = `ab`;
-const ab2 = `ab`;
-type AB = `AB`;
-
-// Transforming enum members into string unions using template literals is allowed.
-enum ABC {
-  A = 'A',
-  B = 'B',
-  C = 'C',
-}
-type ABCUnion = `${ABC}`;
-type A = `${ABC.A}`;
-
-// Interpolating type parameters is allowed.
-type TextUtil<T extends string> = `${T}`;
-
-const stringWithNumber = `1 + 1 = 2`;
-
-const stringWithBoolean = `true is true`;
-
-// Some simple expressions that are already strings
-// can be rewritten without a template at all.
-
-const text = 'a';
-const wrappedText = text;
-type Text = 'A';
-type WrappedText = Text;
-
-declare const intersectionWithString: string & { _brand: 'test-brand' };
-const wrappedIntersection = intersectionWithString;
-type IntersectionWithString = string & { _brand: 'test-brand' };
-type WrappedIntersection = IntersectionWithString;
-```
-
-</TabItem>
-</Tabs>
-
-:::info
-This rule does not aim to flag template literals without substitution expressions that could have been written as an ordinary string.
-That is to say, this rule will not help you turn `` `this` `` into `"this"`.
-If you are looking for such a rule, you can configure the [`@stylistic/ts/quotes`](https://eslint.style/rules/ts/quotes) rule to do this.
-:::
-
-## When Not To Use It
-
-When you want to allow string expressions inside template literals.
-
-## Related To
-
-- [`restrict-template-expressions`](./restrict-template-expressions.mdx)
-- [`@stylistic/ts/quotes`](https://eslint.style/rules/ts/quotes)