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

package/docs/rules/prefer-nullish-coalescing.mdx

@@ -1,349 +0,0 @@
----
-description: 'Enforce using the nullish coalescing operator instead of logical assignments or chaining.'
----
-
-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-nullish-coalescing** for documentation.
-
-The `??` nullish coalescing runtime operator allows providing a default value when dealing with `null` or `undefined`.
-Because the nullish coalescing operator _only_ coalesces when the original value is `null` or `undefined`, it is much safer than relying upon logical OR operator chaining `||`, which coalesces on any _falsy_ value.
-
-This rule reports when you may consider replacing:
-
-- An `||` operator with `??`
-- An `||=` operator with `??=`
-- Ternary expressions (`?:`) that are equivalent to `||` or `??` with `??`
-- Assignment expressions (`=`) that can be safely replaced by `??=`
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-declare const a: string | null;
-declare const b: string | null;
-
-const c = a || b;
-
-declare let foo: { a: string } | null;
-declare function makeFoo(): { a: string };
-
-function lazyInitializeFooByTruthiness() {
-  if (!foo) {
-    foo = makeFoo();
-  }
-}
-
-function lazyInitializeFooByNullCheck() {
-  if (foo == null) {
-    foo = makeFoo();
-  }
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-declare const a: string | null;
-declare const b: string | null;
-
-const c = a ?? b;
-
-declare let foo: { a: string } | null;
-declare function makeFoo(): { a: string };
-
-function lazyInitializeFoo() {
-  foo ??= makeFoo();
-}
-```
-
-</TabItem>
-</Tabs>
-
-:::caution
-This rule will not work as expected if [`strictNullChecks`](https://www.typescriptlang.org/tsconfig#strictNullChecks) is not enabled.
-:::
-
-## Options
-
-### `ignoreTernaryTests`
-
-{/* insert option description */}
-
-Examples of code for this rule with `{ ignoreTernaryTests: false }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "ignoreTernaryTests": false }'
-declare const a: any;
-a !== undefined && a !== null ? a : 'a string';
-a === undefined || a === null ? 'a string' : a;
-a == undefined ? 'a string' : a;
-a == null ? 'a string' : a;
-
-declare const b: string | undefined;
-b !== undefined ? b : 'a string';
-b === undefined ? 'a string' : b;
-b ? b : 'a string';
-!b ? 'a string' : b;
-
-declare const c: string | null;
-c !== null ? c : 'a string';
-c === null ? 'a string' : c;
-c ? c : 'a string';
-!c ? 'a string' : c;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "ignoreTernaryTests": false }'
-declare const a: any;
-a ?? 'a string';
-
-declare const b: string | undefined;
-b ?? 'a string';
-
-declare const c: string | null;
-c ?? 'a string';
-```
-
-</TabItem>
-</Tabs>
-
-### `ignoreIfStatements`
-
-{/* insert option description */}
-
-Examples of code for this rule with `{ ignoreIfStatements: false }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "ignoreIfStatements": false }'
-declare let foo: { a: string } | null;
-declare function makeFoo(): { a: string };
-
-function lazyInitializeFoo1() {
-  if (!foo) {
-    foo = makeFoo();
-  }
-}
-
-function lazyInitializeFoo2() {
-  if (!foo) foo = makeFoo();
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "ignoreIfStatements": false }'
-declare let foo: { a: string } | null;
-declare function makeFoo(): { a: string };
-
-function lazyInitializeFoo1() {
-  foo ??= makeFoo();
-}
-
-function lazyInitializeFoo2() {
-  foo ??= makeFoo();
-}
-```
-
-</TabItem>
-</Tabs>
-
-### `ignoreConditionalTests`
-
-{/* insert option description */}
-
-Generally expressions within conditional tests intentionally use the falsy fallthrough behavior of the logical or operator, meaning that fixing the operator to the nullish coalesce operator could cause bugs.
-
-If you're looking to enforce stricter conditional tests, you should consider using the `strict-boolean-expressions` rule.
-
-Examples of code for this rule with `{ ignoreConditionalTests: false }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "ignoreConditionalTests": false }'
-declare let a: string | null;
-declare const b: string | null;
-
-if (a || b) {
-}
-if ((a ||= b)) {
-}
-while (a || b) {}
-while ((a ||= b)) {}
-do {} while (a || b);
-for (let i = 0; a || b; i += 1) {}
-a || b ? true : false;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "ignoreConditionalTests": false }'
-declare let a: string | null;
-declare const b: string | null;
-
-if (a ?? b) {
-}
-if ((a ??= b)) {
-}
-while (a ?? b) {}
-while ((a ??= b)) {}
-do {} while (a ?? b);
-for (let i = 0; a ?? b; i += 1) {}
-(a ?? b) ? true : false;
-```
-
-</TabItem>
-</Tabs>
-
-### `ignoreMixedLogicalExpressions`
-
-{/* insert option description */}
-
-Generally expressions within mixed logical expressions intentionally use the falsy fallthrough behavior of the logical or operator, meaning that fixing the operator to the nullish coalesce operator could cause bugs.
-
-If you're looking to enforce stricter conditional tests, you should consider using the `strict-boolean-expressions` rule.
-
-Examples of code for this rule with `{ ignoreMixedLogicalExpressions: false }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "ignoreMixedLogicalExpressions": false }'
-declare let a: string | null;
-declare const b: string | null;
-declare const c: string | null;
-declare const d: string | null;
-
-a || (b && c);
-a ||= b && c;
-(a && b) || c || d;
-a || (b && c) || d;
-a || (b && c && d);
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "ignoreMixedLogicalExpressions": false }'
-declare let a: string | null;
-declare const b: string | null;
-declare const c: string | null;
-declare const d: string | null;
-
-a ?? (b && c);
-a ??= b && c;
-(a && b) ?? c ?? d;
-a ?? (b && c) ?? d;
-a ?? (b && c && d);
-```
-
-</TabItem>
-</Tabs>
-
-**_NOTE:_** Errors for this specific case will be presented as suggestions (see below), instead of fixes. This is because it is not always safe to automatically convert `||` to `??` within a mixed logical expression, as we cannot tell the intended precedence of the operator. Note that by design, `??` requires parentheses when used with `&&` or `||` in the same expression.
-
-### `ignorePrimitives`
-
-{/* insert option description */}
-
-If you would like to ignore expressions containing operands of certain primitive types that can be falsy then you may pass an object containing a boolean value for each primitive:
-
-- `string: true`, ignores `null` or `undefined` unions with `string` (default: `false`).
-- `number: true`, ignores `null` or `undefined` unions with `number` (default: `false`).
-- `bigint: true`, ignores `null` or `undefined` unions with `bigint` (default: `false`).
-- `boolean: true`, ignores `null` or `undefined` unions with `boolean` (default: `false`).
-
-Examples of code for this rule with `{ ignorePrimitives: { string: false } }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "ignorePrimitives": { "string": false } }'
-declare const foo: string | undefined;
-
-foo || 'a string';
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "ignorePrimitives": { "string": false } }'
-declare const foo: string | undefined;
-
-foo ?? 'a string';
-```
-
-</TabItem>
-</Tabs>
-
-Also, if you would like to ignore all primitives types, you can set `ignorePrimitives: true`. It is equivalent to `ignorePrimitives: { string: true, number: true, bigint: true, boolean: true }`.
-
-### `ignoreBooleanCoercion`
-
-{/* insert option description */}
-
-Examples of code for this rule with `{ ignoreBooleanCoercion: false }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "ignoreBooleanCoercion": false }'
-declare const a: string | true | undefined;
-declare const b: string | boolean | undefined;
-
-const x = Boolean(a || b);
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "ignoreBooleanCoercion": false }'
-declare const a: string | true | undefined;
-declare const b: string | boolean | undefined;
-
-const x = Boolean(a ?? b);
-```
-
-</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.
-
-## When Not To Use It
-
-If you are not using TypeScript 3.7 (or greater), then you will not be able to use this rule, as the operator is not supported.
-
-## Further Reading
-
-- [TypeScript 3.7 Release Notes](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html)
-- [Nullish Coalescing Operator Proposal](https://github.com/tc39/proposal-nullish-coalescing/)
-- [`logical-assignment-operators`](https://eslint.org/docs/latest/rules/logical-assignment-operators)

package/docs/rules/prefer-optional-chain.mdx

@@ -1,304 +0,0 @@
----
-description: 'Enforce using concise optional chain expressions instead of chained logical ands, negated logical ors, or empty objects.'
----
-
-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-optional-chain** for documentation.
-
-`?.` optional chain expressions provide `undefined` if an object is `null` or `undefined`.
-Because the optional chain operator _only_ chains when the property value is `null` or `undefined`, it is much safer than relying upon logical AND operator chaining `&&`; which chains on any _truthy_ value.
-It is also often less code to use `?.` optional chaining than `&&` truthiness checks.
-
-This rule reports on code where an `&&` operator can be safely replaced with `?.` optional chaining.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-foo && foo.a && foo.a.b && foo.a.b.c;
-foo && foo['a'] && foo['a'].b && foo['a'].b.c;
-foo && foo.a && foo.a.b && foo.a.b.method && foo.a.b.method();
-
-// With empty objects
-(((foo || {}).a || {}).b || {}).c;
-(((foo || {})['a'] || {}).b || {}).c;
-
-// With negated `or`s
-!foo || !foo.bar;
-!foo || !foo[bar];
-!foo || !foo.bar || !foo.bar.baz || !foo.bar.baz();
-
-// this rule also supports converting chained strict nullish checks:
-foo &&
-  foo.a != null &&
-  foo.a.b !== null &&
-  foo.a.b.c != undefined &&
-  foo.a.b.c.d !== undefined &&
-  foo.a.b.c.d.e;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-foo?.a?.b?.c;
-foo?.['a']?.b?.c;
-foo?.a?.b?.method?.();
-
-foo?.a?.b?.c?.d?.e;
-
-!foo?.bar;
-!foo?.[bar];
-!foo?.bar?.baz?.();
-```
-
-</TabItem>
-</Tabs>
-
-## Options
-
-In the context of the descriptions below a "loose boolean" operand is any operand that implicitly coerces the value to a boolean.
-Specifically the argument of the not operator (`!loose`) or a bare value in a logical expression (`loose && looser`).
-
-### `allowPotentiallyUnsafeFixesThatModifyTheReturnTypeIKnowWhatImDoing`
-
-{/* insert option description */}
-
-When this option is `true`, the rule will provide an auto-fixer for cases where the return type of the expression would change. For example for the expression `!foo || foo.bar` the return type of the expression is `true | T`, however for the equivalent optional chain `foo?.bar` the return type of the expression is `undefined | T`. Thus changing the code from a logical expression to an optional chain expression has altered the type of the expression.
-
-In some cases this distinction _may_ matter - which is why these fixers are considered unsafe - they may break the build! For example in the following code:
-
-```ts option='{ "allowPotentiallyUnsafeFixesThatModifyTheReturnTypeIKnowWhatImDoing": true }' showPlaygroundButton
-declare const foo: { bar: boolean } | null | undefined;
-declare function acceptsBoolean(arg: boolean): void;
-
-// ✅ typechecks succesfully as the expression only returns `boolean`
-acceptsBoolean(foo != null && foo.bar);
-
-// ❌ typechecks UNSUCCESSFULLY as the expression returns `boolean | undefined`
-acceptsBoolean(foo?.bar);
-```
-
-This style of code isn't super common - which means having this option set to `true` _should_ be safe in most codebases. However we default it to `false` due to its unsafe nature. We have provided this option for convenience because it increases the autofix cases covered by the rule. If you set option to `true` the onus is entirely on you and your team to ensure that each fix is correct and safe and that it does not break the build.
-
-When this option is `false` unsafe cases will have suggestion fixers provided instead of auto-fixers - meaning you can manually apply the fix using your IDE tooling.
-
-### `checkAny`
-
-{/* insert option description */}
-
-Examples of code for this rule with `{ checkAny: true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "checkAny": true }'
-declare const thing: any;
-
-thing && thing.toString();
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "checkAny": true }'
-declare const thing: any;
-
-thing?.toString();
-```
-
-</TabItem>
-</Tabs>
-
-### `checkUnknown`
-
-{/* insert option description */}
-
-Examples of code for this rule with `{ checkUnknown: true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "checkUnknown": true }'
-declare const thing: unknown;
-
-thing && thing.toString();
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "checkUnknown": true }'
-declare const thing: unknown;
-
-thing?.toString();
-```
-
-</TabItem>
-</Tabs>
-
-### `checkString`
-
-{/* insert option description */}
-
-Examples of code for this rule with `{ checkString: true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "checkString": true }'
-declare const thing: string;
-
-thing && thing.toString();
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "checkString": true }'
-declare const thing: string;
-
-thing?.toString();
-```
-
-</TabItem>
-</Tabs>
-
-### `checkNumber`
-
-{/* insert option description */}
-
-Examples of code for this rule with `{ checkNumber: true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "checkNumber": true }'
-declare const thing: number;
-
-thing && thing.toString();
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "checkNumber": true }'
-declare const thing: number;
-
-thing?.toString();
-```
-
-</TabItem>
-</Tabs>
-
-### `checkBoolean`
-
-{/* insert option description */}
-
-:::note
-
-This rule intentionally ignores the following case:
-
-```ts
-declare const x: false | { a: string };
-x && x.a;
-!x || x.a;
-```
-
-The boolean expression narrows out the non-nullish falsy cases - so converting the chain to `x?.a` would introduce a type error.
-
-:::
-
-Examples of code for this rule with `{ checkBoolean: true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "checkBoolean": true }'
-declare const thing: true;
-
-thing && thing.toString();
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "checkBoolean": true }'
-declare const thing: true;
-
-thing?.toString();
-```
-
-</TabItem>
-</Tabs>
-
-### `checkBigInt`
-
-{/* insert option description */}
-
-Examples of code for this rule with `{ checkBigInt: true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "checkBigInt": true }'
-declare const thing: bigint;
-
-thing && thing.toString();
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "checkBigInt": true }'
-declare const thing: bigint;
-
-thing?.toString();
-```
-
-</TabItem>
-</Tabs>
-
-### `requireNullish`
-
-{/* insert option description */}
-
-Examples of code for this rule with `{ requireNullish: true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "requireNullish": true }'
-declare const thing1: string | null;
-thing1 && thing1.toString();
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "requireNullish": true }'
-declare const thing1: string | null;
-thing1?.toString();
-
-declare const thing2: string;
-thing2 && thing2.toString();
-```
-
-</TabItem>
-</Tabs>
-
-## 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.
-
-## Further Reading
-
-- [TypeScript 3.7 Release Notes](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html)
-- [Optional Chaining Proposal](https://github.com/tc39/proposal-optional-chaining/)