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

package/docs/rules/strict-boolean-expressions.mdx

@@ -1,184 +0,0 @@
----
-description: 'Disallow certain types in boolean 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/strict-boolean-expressions** for documentation.
-
-Forbids usage of non-boolean types in expressions where a boolean is expected.
-`boolean` and `never` types are always allowed.
-Additional types which are considered safe in a boolean context can be configured via options.
-
-The following nodes are considered boolean expressions and their type is checked:
-
-- Argument to the logical negation operator (`!arg`).
-- The condition in a conditional expression (`cond ? x : y`).
-- Conditions for `if`, `for`, `while`, and `do-while` statements.
-- Operands of logical binary operators (`lhs || rhs` and `lhs && rhs`).
-  - Right-hand side operand is ignored when it's not a descendant of another boolean expression.
-    This is to allow usage of boolean operators for their short-circuiting behavior.
-- Asserted argument of an assertion function (`assert(arg)`).
-- Return type of array predicate functions such as `filter()`, `some()`, etc.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-// nullable numbers are considered unsafe by default
-declare const num: number | undefined;
-if (num) {
-  console.log('num is defined');
-}
-
-// nullable strings are considered unsafe by default
-declare const str: string | null;
-if (!str) {
-  console.log('str is empty');
-}
-
-// nullable booleans are considered unsafe by default
-function foo(bool?: boolean) {
-  if (bool) {
-    bar();
-  }
-}
-
-// `any`, unconstrained generics and unions of more than one primitive type are disallowed
-const foo = <T>(arg: T) => (arg ? 1 : 0);
-
-// always-truthy and always-falsy types are disallowed
-let obj = {};
-while (obj) {
-  obj = getObj();
-}
-
-// assertion functions without an `is` are boolean contexts.
-declare function assert(value: unknown): asserts value;
-let maybeString = Math.random() > 0.5 ? '' : undefined;
-assert(maybeString);
-
-// array predicates' return types are boolean contexts.
-['one', null].filter(x => x);
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```tsx
-// nullable values should be checked explicitly against null or undefined
-let num: number | undefined = 0;
-if (num != null) {
-  console.log('num is defined');
-}
-
-let str: string | null = null;
-if (str != null && !str) {
-  console.log('str is empty');
-}
-
-function foo(bool?: boolean) {
-  if (bool ?? false) {
-    bar();
-  }
-}
-
-// `any` types should be converted to boolean explicitly
-const foo = (arg: any) => (Boolean(arg) ? 1 : 0);
-```
-
-</TabItem>
-</Tabs>
-
-## Options
-
-### `allowString`
-
-{/* insert option description */}
-
-This can be safe because strings have only one falsy value (`""`).
-Set this to `false` if you prefer the explicit `str != ""` or `str.length > 0` style.
-
-### `allowNumber`
-
-{/* insert option description */}
-
-This can be safe because numbers have only two falsy values (`0` and `NaN`).
-Set this to `false` if you prefer the explicit `num != 0` and `!Number.isNaN(num)` style.
-
-### `allowNullableObject`
-
-{/* insert option description */}
-
-This can be safe because objects, functions, and symbols don't have falsy values.
-Set this to `false` if you prefer the explicit `obj != null` style.
-
-### `allowNullableBoolean`
-
-{/* insert option description */}
-
-This is unsafe because nullable booleans can be either `false` or nullish.
-Set this to `false` if you want to enforce explicit `bool ?? false` or `bool ?? true` style.
-Set this to `true` if you don't mind implicitly treating false the same as a nullish value.
-
-### `allowNullableString`
-
-{/* insert option description */}
-
-This is unsafe because nullable strings can be either an empty string or nullish.
-Set this to `true` if you don't mind implicitly treating an empty string the same as a nullish value.
-
-### `allowNullableNumber`
-
-{/* insert option description */}
-
-This is unsafe because nullable numbers can be either a falsy number or nullish.
-Set this to `true` if you don't mind implicitly treating zero or NaN the same as a nullish value.
-
-### `allowNullableEnum`
-
-{/* insert option description */}
-
-This is unsafe because nullable enums can be either a falsy number or nullish.
-Set this to `true` if you don't mind implicitly treating an enum whose value is zero the same as a nullish value.
-
-### `allowAny`
-
-{/* insert option description */}
-
-This is unsafe for because `any` allows any values and disables many type checking checks.
-Set this to `true` at your own risk.
-
-### `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 a lot less useful.
-
-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.
-
-## When Not To Use It
-
-If your project isn't likely to experience bugs from falsy non-boolean values being used in logical conditions, you can skip enabling this rule.
-
-Otherwise, this rule can be quite strict around requiring exact comparisons in logical checks.
-If you prefer more succinct checks over more precise boolean logic, this rule might not be for you.
-
-## Related To
-
-- [no-unnecessary-condition](./no-unnecessary-condition.mdx) - Similar rule which reports always-truthy and always-falsy values in conditions

package/docs/rules/switch-exhaustiveness-check.mdx

@@ -1,280 +0,0 @@
----
-description: 'Require switch-case statements to be exhaustive.'
----
-
-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/switch-exhaustiveness-check** for documentation.
-
-When working with union types or enums in TypeScript, it's common to want to write a `switch` statement intended to contain a `case` for each possible type in the union or the enum.
-However, if the union type or the enum changes, it's easy to forget to modify the cases to account for any new types.
-
-This rule reports when a `switch` statement over a value typed as a union of literals or as an enum is missing a case for any of those literal types and does not have a `default` clause.
-
-## Options
-
-### `allowDefaultCaseForExhaustiveSwitch`
-
-{/* insert option description */}
-
-If set to false, this rule will also report when a `switch` statement has a case for everything in a union and _also_ contains a `default` case. Thus, by setting this option to false, the rule becomes stricter.
-
-When a `switch` statement over a union type is exhaustive, a final `default` case would be a form of dead code.
-Additionally, if a new value is added to the union type and you're using [`considerDefaultExhaustiveForUnions`](#considerDefaultExhaustiveForUnions), a `default` would prevent the `switch-exhaustiveness-check` rule from reporting on the new case not being handled in the `switch` statement.
-
-#### `allowDefaultCaseForExhaustiveSwitch` Caveats
-
-It can sometimes be useful to include a redundant `default` case on an exhaustive `switch` statement if it's possible for values to have types not represented by the union type.
-For example, in applications that can have version mismatches between clients and servers, it's possible for a server running a newer software version to send a value not recognized by the client's older typings.
-
-If your project has a small number of intentionally redundant `default` cases, you might want to use an [inline ESLint disable comment](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1) for each of them.
-
-If your project has many intentionally redundant `default` cases, you may want to disable `allowDefaultCaseForExhaustiveSwitch` and use the [`default-case` core ESLint rule](https://eslint.org/docs/latest/rules/default-case) along with [a `satisfies never` check](https://www.typescriptlang.org/play?#code/C4TwDgpgBAYgTgVwJbCgXigcgIZjAGwkygB8sAjbAO2u0wG4AoRgMwSoGNgkB7KqBAGcI8ZMAAULRCgBcsacACUcwcDhIqAcygBvRlCiCA7ig4ALKJIWLd+g1A7ZhWXASJy99+3AjAEcfhw8QgApZA4iJi8AX2YvR2dMShoaTA87Lx8-AIpaGjCkCIYMqFiSgBMIFmwEfGB0rwMpMUNsbkEWJAhBKCoIADcIOCjGrP9A9gBrKh4jKgKikYNY5cZYoA).
-
-### `requireDefaultForNonUnion`
-
-{/* insert option description */}
-
-If set to true, this rule will also report when a `switch` statement switches over a non-union type (like a `number` or `string`, for example) and that `switch` statement does not have a `default` case. Thus, by setting this option to true, the rule becomes stricter.
-
-This is generally desirable so that `number` and `string` switches will be subject to the same exhaustive checks that your other switches are.
-
-Examples of additional **incorrect** code for this rule with `{ requireDefaultForNonUnion: true }`:
-
-```ts option='{ "requireDefaultForNonUnion": true }' showPlaygroundButton
-const value: number = Math.floor(Math.random() * 3);
-
-switch (value) {
-  case 0:
-    return 0;
-  case 1:
-    return 1;
-}
-```
-
-Since `value` is a non-union type it requires the switch case to have a default clause only with `requireDefaultForNonUnion` enabled.
-
-### `considerDefaultExhaustiveForUnions`
-
-{/* insert option description */}
-
-If set to true, a `switch` statement over a union type that includes a `default` case is considered exhaustive.
-Otherwise, the rule enforces explicitly handling every constituent of the union type with their own explicit `case`.
-Keeping this option disabled can be useful if you want to make sure every value added to the union receives explicit handling, with the `default` case reserved for reporting an error.
-
-Examples of additional **correct** code with `{ considerDefaultExhaustiveForUnions: true }`:
-
-```ts option='{ "considerDefaultExhaustiveForUnions": true }' showPlaygroundButton
-declare const literal: 'a' | 'b';
-
-switch (literal) {
-  case 'a':
-    break;
-  default:
-    break;
-}
-```
-
-### `defaultCaseCommentPattern`
-
-{/* insert option description */}
-
-Default: `/^no default$/iu`.
-
-It can sometimes be preferable to omit the default case for only some switch statements.
-For those situations, this rule can be given a pattern for a comment that's allowed to take the place of a `default:`.
-
-Examples of additional **correct** code with `{ defaultCaseCommentPattern: "^skip\\sdefault" }`:
-
-```ts option='{ "defaultCaseCommentPattern": "^skip default" }' showPlaygroundButton
-declare const value: 'a' | 'b';
-
-switch (value) {
-  case 'a':
-    break;
-  // skip default
-}
-```
-
-## Examples
-
-When the switch doesn't have exhaustive cases, either filling them all out or adding a default (if you have `considerDefaultExhaustiveForUnions` enabled) will address the rule's complaint.
-
-Here are some examples of code working with a union of literals:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-type Day =
-  | 'Monday'
-  | 'Tuesday'
-  | 'Wednesday'
-  | 'Thursday'
-  | 'Friday'
-  | 'Saturday'
-  | 'Sunday';
-
-declare const day: Day;
-let result = 0;
-
-switch (day) {
-  case 'Monday':
-    result = 1;
-    break;
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct (Exhaustive)">
-
-```ts
-type Day =
-  | 'Monday'
-  | 'Tuesday'
-  | 'Wednesday'
-  | 'Thursday'
-  | 'Friday'
-  | 'Saturday'
-  | 'Sunday';
-
-declare const day: Day;
-let result = 0;
-
-switch (day) {
-  case 'Monday':
-    result = 1;
-    break;
-  case 'Tuesday':
-    result = 2;
-    break;
-  case 'Wednesday':
-    result = 3;
-    break;
-  case 'Thursday':
-    result = 4;
-    break;
-  case 'Friday':
-    result = 5;
-    break;
-  case 'Saturday':
-    result = 6;
-    break;
-  case 'Sunday':
-    result = 7;
-    break;
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct (Defaulted)">
-
-```ts option='{ "considerDefaultExhaustiveForUnions": true }'
-// requires `considerDefaultExhaustiveForUnions` to be set to true
-
-type Day =
-  | 'Monday'
-  | 'Tuesday'
-  | 'Wednesday'
-  | 'Thursday'
-  | 'Friday'
-  | 'Saturday'
-  | 'Sunday';
-
-declare const day: Day;
-let result = 0;
-
-switch (day) {
-  case 'Monday':
-    result = 1;
-    break;
-  default:
-    result = 42;
-}
-```
-
-</TabItem>
-</Tabs>
-
-Likewise, here are some examples of code working with an enum:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-enum Fruit {
-  Apple,
-  Banana,
-  Cherry,
-}
-
-declare const fruit: Fruit;
-
-switch (fruit) {
-  case Fruit.Apple:
-    console.log('an apple');
-    break;
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct (Exhaustive)">
-
-```ts
-enum Fruit {
-  Apple,
-  Banana,
-  Cherry,
-}
-
-declare const fruit: Fruit;
-
-switch (fruit) {
-  case Fruit.Apple:
-    console.log('an apple');
-    break;
-
-  case Fruit.Banana:
-    console.log('a banana');
-    break;
-
-  case Fruit.Cherry:
-    console.log('a cherry');
-    break;
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct (Defaulted)">
-
-```ts option='{ "considerDefaultExhaustiveForUnions": true }'
-// requires `considerDefaultExhaustiveForUnions` to be set to true
-
-enum Fruit {
-  Apple,
-  Banana,
-  Cherry,
-}
-
-declare const fruit: Fruit;
-
-switch (fruit) {
-  case Fruit.Apple:
-    console.log('an apple');
-    break;
-
-  default:
-    console.log('a fruit');
-    break;
-}
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-If you don't frequently `switch` over union types or enums with many parts, or intentionally wish to leave out some parts, this rule may not be for you.

package/docs/rules/triple-slash-reference.mdx

@@ -1,129 +0,0 @@
----
-description: 'Disallow certain triple slash directives in favor of ES6-style import declarations.'
----
-
-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/triple-slash-reference** for documentation.
-
-TypeScript's `///` triple-slash references are a way to indicate that types from another module are available in a file.
-Use of triple-slash reference type directives is generally discouraged in favor of ECMAScript Module `import`s.
-This rule reports on the use of `/// <reference lib="..." />`, `/// <reference path="..." />`, or `/// <reference types="..." />` directives.
-
-## Options
-
-Any number of the three kinds of references can be specified as an option.
-Specifying `'always'` disables this lint rule for that kind of reference.
-
-### `lib`
-
-{/* insert option description */}
-
-When set to `'never'`, bans `/// <reference lib="..." />` and enforces using an `import` instead:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "lib": "never" }'
-/// <reference lib="code" />
-
-globalThis.value;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "lib": "never" }'
-import { value } from 'code';
-```
-
-</TabItem>
-</Tabs>
-
-### `path`
-
-{/* insert option description */}
-
-When set to `'never'`, bans `/// <reference path="..." />` and enforces using an `import` instead:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "path": "never" }'
-/// <reference path="code" />
-
-globalThis.value;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "path": "never" }'
-import { value } from 'code';
-```
-
-</TabItem>
-</Tabs>
-
-### `types`
-
-{/* insert option description */}
-
-When set to `'never'`, bans `/// <reference types="..." />` and enforces using an `import` instead:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "types": "never" }'
-/// <reference types="code" />
-
-globalThis.value;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "types": "never" }'
-import { value } from 'code';
-```
-
-</TabItem>
-</Tabs>
-
-The `types` option may alternately be given a `"prefer-import"` value.
-Doing so indicates the rule should only report if there is already an `import` from the same location:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "types": "prefer-import" }'
-/// <reference types="code" />
-
-import { valueA } from 'code';
-
-globalThis.valueB;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "types": "prefer-import" }'
-import { valueA, valueB } from 'code';
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-Most modern TypeScript projects generally use `import` statements to bring in types.
-It's rare to need a `///` triple-slash reference outside of auto-generated code.
-If your project is a rare one with one of those use cases, this rule might not be 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.
-
-## When Not To Use It
-
-If you want to use all flavors of triple slash reference directives.

package/docs/rules/type-annotation-spacing.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. -->