xo 0.52.3 → 0.53.0

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/prefer-namespace-keyword.md

@@ -6,12 +6,35 @@ description: 'Require using `namespace` keyword over `module` keyword to declare
 >
 > See **https://typescript-eslint.io/rules/prefer-namespace-keyword** for documentation.
 
-In an effort to prevent further confusion between custom TypeScript modules and the new ES2015 modules, starting
-with TypeScript `v1.5` the keyword `namespace` is now the preferred way to declare custom TypeScript modules.
+TypeScript historically allowed a form of code organization called "custom modules" (`module Example {}`), later renamed to "namespaces" (`namespace Example`).
 
-## Rule Details
+Namespaces are an outdated way to organize TypeScript code.
+ES2015 module syntax is now preferred (`import`/`export`).
 
-This rule aims to standardize the way modules are declared.
+For projects still using custom modules / namespaces, it's preferred to refer to them as namespaces.
+This rule reports when the `module` keyword is used instead of `namespace`.
+
+> This rule does not report on the use of TypeScript module declarations to describe external APIs (`declare module 'foo' {}`).
+
+## Examples
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+module Example {}
+```
+
+### ✅ Correct
+
+```ts
+namespace Example {}
+
+declare module 'foo' {}
+```
+
+<!--/tabs-->
 
 ## When Not To Use It
 

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/prefer-nullish-coalescing.md

@@ -6,65 +6,17 @@ description: 'Enforce using the nullish coalescing operator instead of logical c
 >
 > See **https://typescript-eslint.io/rules/prefer-nullish-coalescing** for documentation.
 
-TypeScript 3.7 added support for the nullish coalescing operator.
-This operator allows you to safely cascade a value when dealing with `null` or `undefined`.
+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.
 
-```ts
-function myFunc(foo: string | null) {
-  return foo ?? 'a string';
-}
-
-// is equivalent to
-
-function myFunc(foo: string | null) {
-  return foo !== null && foo !== undefined ? foo : 'a string';
-}
-```
-
-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:
-
-```ts
-const emptyString = '';
-
-const nullish1 = emptyString ?? 'unsafe';
-const logical1 = emptyString || 'unsafe';
+This rule reports when an `||` operator can be safely replaced with a `??`.
 
-// nullish1 === ''
-// logical1 === 'unsafe'
-
-declare const nullString: string | null;
-
-const nullish2 = nullString ?? 'safe';
-const logical2 = nullString || 'safe';
-
-// nullish2 === 'safe'
-// logical2 === 'safe'
-```
-
-## Rule Details
-
-This rule aims enforce the usage of the safer operator.
+:::caution
+This rule will not work as expected if [`strictNullChecks`](https://www.typescriptlang.org/tsconfig#strictNullChecks) is not enabled.
+:::
 
 ## Options
 
-```ts
-type Options = [
-  {
-    ignoreTernaryTests?: boolean;
-    ignoreConditionalTests?: boolean;
-    ignoreMixedLogicalExpressions?: boolean;
-  },
-];
-
-const defaultOptions = [
-  {
-    ignoreTernaryTests: true;
-    ignoreConditionalTests: true,
-    ignoreMixedLogicalExpressions: true,
-  },
-];
-```
-
 ### `ignoreTernaryTests`
 
 Setting this option to `true` (the default) will cause the rule to ignore any ternary expressions that could be simplified by using the nullish coalescing operator.

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/prefer-optional-chain.md

@@ -1,60 +1,18 @@
 ---
-description: 'Enforce using concise optional chain expressions instead of chained logical ands.'
+description: 'Enforce using concise optional chain expressions instead of chained logical ands, negated logical ors, or empty objects.'
 ---
 
 > 🛑 This file is source code, not the primary documentation location! 🛑
 >
 > See **https://typescript-eslint.io/rules/prefer-optional-chain** for documentation.
 
-TypeScript 3.7 added support for the optional chain operator.
-This operator allows you to safely access properties and methods on objects when they are potentially `null` or `undefined`.
-
-```ts
-type T = {
-  a?: {
-    b?: {
-      c: string;
-      method?: () => void;
-    };
-  };
-};
-
-function myFunc(foo: T | null) {
-  return foo?.a?.b?.c;
-}
-// is roughly equivalent to
-function myFunc(foo: T | null) {
-  return foo && foo.a && foo.a.b && foo.a.b.c;
-}
-// or
-function myFunc(foo: T | null) {
-  return (((foo || {}).a || {}).b || {}).c;
-}
-
-function myFunc(foo: T | null) {
-  return foo?.['a']?.b?.c;
-}
-// is roughly equivalent to
-function myFunc(foo: T | null) {
-  return foo && foo['a'] && foo['a'].b && foo['a'].b.c;
-}
-
-function myFunc(foo: T | null) {
-  return foo?.a?.b?.method?.();
-}
-// is roughly equivalent to
-function myFunc(foo: T | null) {
-  return foo && foo.a && foo.a.b && foo.a.b.method && foo.a.b.method();
-}
-```
-
+`?.` 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.
 
-## Rule Details
+This rule reports on code where an `&&` operator can be safely replaced with `?.` optional chaining.
 
-This rule aims enforce the usage of the safer operator.
-
-Examples of code for this rule:
+## Examples
 
 <!--tabs-->
 
@@ -65,9 +23,15 @@ 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 &&
@@ -85,13 +49,21 @@ foo?.['a']?.b?.c;
 foo?.a?.b?.method?.();
 
 foo?.a?.b?.c?.d?.e;
+
+!foo?.bar;
+!foo?.[bar];
+!foo?.bar?.baz?.();
 ```
 
-**Note:** there are a few edge cases where this rule will false positive. Use your best judgement when evaluating reported errors.
+<!--/tabs-->
+
+:::note
+There are a few edge cases where this rule will false positive. Use your best judgement when evaluating reported errors.
+:::
 
 ## 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.
+If you don't mind using more explicit `&&`s, you don't need this rule.
 
 ## Further Reading
 

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/prefer-readonly-parameter-types.md

@@ -10,8 +10,6 @@ Mutating function arguments can lead to confusing, hard to debug behavior.
 Whilst it's easy to implicitly remember to not modify function arguments, explicitly typing arguments as readonly provides clear contract to consumers.
 This contract makes it easier for a consumer to reason about if a function has side-effects.
 
-## Rule Details
-
 This rule allows you to enforce that function parameters resolve to readonly types.
 A type is considered readonly if:
 
@@ -21,7 +19,7 @@ A type is considered readonly if:
 - it is a readonly tuple type whose elements are all considered readonly.
 - it is an object type whose properties are all marked as readonly, and whose values are all considered readonly.
 
-Examples of code for this rule:
+## Examples
 
 <!--tabs-->
 

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/prefer-readonly.md

@@ -6,14 +6,12 @@ description: "Require private members to be marked as `readonly` if they're neve
 >
 > See **https://typescript-eslint.io/rules/prefer-readonly** for documentation.
 
-This rule enforces that private members are marked as `readonly` if they're never modified outside of the constructor.
-
-## Rule Details
-
 Member variables with the privacy `private` are never permitted to be modified outside of their declaring class.
 If that class never modifies their value, they may safely be marked as `readonly`.
 
-Examples of code for this rule:
+This rule reports on private members are marked as `readonly` if they're never modified outside of the constructor.
+
+## Examples
 
 <!--tabs-->
 

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/prefer-reduce-type-parameter.md

@@ -12,18 +12,16 @@ Since these values are empty, their types are not usable:
 - `[]` has type `never[]`, which can't have items pushed into it as nothing is type `never`
 - `{}` has type `{}`, which doesn't have an index signature and so can't have properties added to it
 
-A common solution to this problem is to cast the initial value. While this will work, it's not the most optimal
-solution as casting has subtle effects on the underlying types that can allow bugs to slip in.
+A common solution to this problem is to use an `as` assertion on the initial value.
+While this will work, it's not the most optimal solution as type assertions have subtle effects on the underlying types that can allow bugs to slip in.
 
-A better (and lesser known) solution is to pass the type in as a generic parameter to `Array#reduce` explicitly.
+A better solution is to pass the type in as a generic type argument to `Array#reduce` explicitly.
 This means that TypeScript doesn't have to try to infer the type, and avoids the common pitfalls that come with casting.
 
-## Rule Details
+This rule looks for calls to `Array#reduce`, and reports if an initial value is being passed & asserted.
+It will suggest instead pass the asserted type to `Array#reduce` as a generic type argument.
 
-This rule looks for calls to `Array#reduce`, and warns if an initial value is being passed & casted,
-suggesting instead to pass the cast type to `Array#reduce` as its generic parameter.
-
-Examples of code for this rule:
+## Examples
 
 <!--tabs-->
 

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/prefer-regexp-exec.md

@@ -6,19 +6,14 @@ description: 'Enforce `RegExp#exec` over `String#match` if no global flag is pro
 >
 > See **https://typescript-eslint.io/rules/prefer-regexp-exec** for documentation.
 
-As `String#match` is defined to be the same as `RegExp#exec` when the regular expression does not include the `g` flag, prefer a consistent usage.
+`String#match` is defined to work the same as `RegExp#exec` when the regular expression does not include the `g` flag.
+Keeping to consistently using one of the two can help improve code readability.
 
-## Rule Details
+This rule reports when a `String#match` call can be replaced with an equivalent `RegExp#exec`.
 
-This rule is aimed at enforcing a consistent way to apply regular expressions to strings.
+> `RegExp#exec` may also be slightly faster than `String#match`; this is the reason to choose it as the preferred usage.
 
-From [`String#match` on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match):
-
-> If the regular expression does not include the g flag, returns the same result as `RegExp.exec()`.
-
-`RegExp#exec` may also be slightly faster than `String#match`; this is the reason to choose it as the preferred usage.
-
-Examples of code for this rule:
+## Examples
 
 <!--tabs-->
 
@@ -48,4 +43,4 @@ search.exec(text);
 
 ## When Not To Use It
 
-If you prefer consistent use of `String#match` for both, with `g` flag and without it, you can turn this rule off.
+If you prefer consistent use of `String#match` for both with `g` flag and without it, you can turn this rule off.

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/prefer-return-this-type.md

@@ -6,12 +6,17 @@ description: 'Enforce that `this` is used when only `this` type is returned.'
 >
 > See **https://typescript-eslint.io/rules/prefer-return-this-type** for documentation.
 
-[Method chaining](https://en.wikipedia.org/wiki/Method_chaining) is a common pattern in OOP languages and TypeScript provides a special [polymorphic this type](https://www.typescriptlang.org/docs/handbook/2/classes.html#this-types).
-If any type other than `this` is specified as the return type of these chaining methods, TypeScript will fail to cast it when invoking in subclass.
+[Method chaining](https://en.wikipedia.org/wiki/Method_chaining) is a common pattern in OOP languages and TypeScript provides a special [polymorphic `this` type](https://www.typescriptlang.org/docs/handbook/2/classes.html#this-types) to facilitate it.
+Class methods that explicitly declare a return type of the class name instead of `this` make it harder for extending classes to call that method: the returned object will be typed as the base class, not the derived class.
+
+This rule reports when a class method declares a return type of that class name instead of `this`.
 
 ```ts
 class Animal {
   eat(): Animal {
+    //   ~~~~~~
+    // Either removing this type annotation or replacing
+    // it with `this` would remove the type error below.
     console.log("I'm moving!");
     return this;
   }
@@ -25,33 +30,13 @@ class Cat extends Animal {
 }
 
 const cat = new Cat();
+cat.eat().meow();
+//        ~~~~
 // Error: Property 'meow' does not exist on type 'Animal'.
 // because `eat` returns `Animal` and not all animals meow.
-cat.eat().meow();
-
-// the error can be fixed by removing the return type of `eat` or use `this` as the return type.
-class Animal {
-  eat(): this {
-    console.log("I'm moving!");
-    return this;
-  }
-}
-
-class Cat extends Animal {
-  meow(): this {
-    console.log('Meow~');
-    return this;
-  }
-}
-
-const cat = new Cat();
-// no errors. Because `eat` returns `Cat` now
-cat.eat().meow();
 ```
 
-## Rule Details
-
-Examples of code for this rule:
+## Examples
 
 <!--tabs-->
 

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/prefer-string-starts-ends-with.md

@@ -7,20 +7,19 @@ description: 'Enforce using `String#startsWith` and `String#endsWith` over other
 > See **https://typescript-eslint.io/rules/prefer-string-starts-ends-with** for documentation.
 
 There are multiple ways to verify if a string starts or ends with a specific string, such as `foo.indexOf('bar') === 0`.
-Since ES2015 has added `String#startsWith` and `String#endsWith`, this rule reports other ways to be consistent.
+As of ES2015, the most common way in JavaScript is to use `String#startsWith` and `String#endsWith`.
+Keeping to those methods consistently helps with code readability.
 
-## Rule Details
+This rule reports when a string method can be replaced safely with `String#startsWith` or `String#endsWith`.
 
-This rule is aimed at enforcing a consistent way to check whether a string starts or ends with a specific string.
-
-Examples of code for this rule:
+## Examples
 
 <!--tabs-->
 
 ### ❌ Incorrect
 
 ```ts
-let foo: string;
+declare const foo: string;
 
 // starts with
 foo[0] === 'b';
@@ -44,7 +43,12 @@ foo.match(/bar$/) != null;
 ### ✅ Correct
 
 ```ts
+declare const foo: string;
+
+// starts with
 foo.startsWith('bar');
+
+// ends with
 foo.endsWith('bar');
 ```
 

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/prefer-ts-expect-error.md

@@ -6,21 +6,15 @@ description: 'Enforce using `@ts-expect-error` over `@ts-ignore`.'
 >
 > See **https://typescript-eslint.io/rules/prefer-ts-expect-error** for documentation.
 
-TypeScript allows you to suppress all errors on a line by placing a single-line comment or a comment block line starting with `@ts-ignore` immediately before the erroring line.
-While powerful, there is no way to know if a `@ts-ignore` is actually suppressing an error without manually investigating what happens when the `@ts-ignore` is removed.
+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.
 
 This means its easy for `@ts-ignore`s to be forgotten about, and remain in code even after the error they were suppressing is fixed.
 This is dangerous, as if a new error arises on that line it'll be suppressed by the forgotten about `@ts-ignore`, and so be missed.
 
-To address this, TS3.9 ships with a new single-line comment directive: `// @ts-expect-error`.
+## Examples
 
-This directive operates in the same manner as `@ts-ignore`, but will error if the line it's meant to be suppressing doesn't actually contain an error, making it a lot safer.
-
-## Rule Details
-
-This rule looks for usages of `@ts-ignore`, and flags them to be replaced with `@ts-expect-error`.
-
-Examples of code for this rule:
+This rule reports any usage of `@ts-ignore`, including a fixer to replace with `@ts-expect-error`.
 
 <!--tabs-->
 
@@ -68,7 +62,7 @@ const isOptionEnabled = (key: string): boolean => {
 
 ## When Not To Use It
 
-If you are **NOT** using TypeScript 3.9 (or greater), then you will not be able to use this rule, as the directive is not supported
+If you are compiling against multiple versions of TypeScript and using `@ts-ignore` to ignore version-specific type errors, this rule might get in your way.
 
 ## Further Reading
 

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/promise-function-async.md

@@ -15,7 +15,7 @@ In contrast, non-`async` `Promise` - returning functions are technically capable
 Code that handles the results of those functions will often need to handle both cases, which can get complex.
 This rule's practice removes a requirement for creating code to handle both cases.
 
-## Rule Details
+## Examples
 
 Examples of code for this rule
 

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/quotes.md

@@ -6,7 +6,7 @@ description: 'Enforce the consistent use of either backticks, double, or single
 >
 > See **https://typescript-eslint.io/rules/quotes** for documentation.
 
-## Rule Details
+## Examples
 
 This rule extends the base [`eslint/quotes`](https://eslint.org/docs/rules/quotes) rule.
 It adds support for TypeScript features which allow quoted names, but not backtick quoted names.

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/require-array-sort-compare.md

@@ -6,30 +6,21 @@ description: 'Require `Array#sort` calls to always provide a `compareFunction`.'
 >
 > See **https://typescript-eslint.io/rules/require-array-sort-compare** for documentation.
 
-This rule prevents invoking the `Array#sort()` method without providing a `compare` argument.
-When called without a compare function, `Array#sort()` converts all non-undefined array elements into strings and then compares said strings based off their UTF-16 code units.
+When called without a compare function, `Array#sort()` converts all non-undefined array elements into strings and then compares said strings based off their UTF-16 code units [[ECMA specification](https://www.ecma-international.org/ecma-262/9.0/#sec-sortcompare)].
 
 The result is that elements are sorted alphabetically, regardless of their type.
-When sorting numbers, this results in the classic "10 before 2" order:
+For example, when sorting numbers, this results in a "10 before 2" order:
 
 ```ts
 [1, 2, 3, 10, 20, 30].sort(); //→ [1, 10, 2, 20, 3, 30]
 ```
 
-This also means that `Array#sort` does not always sort consistently, as elements may have custom `#toString` implementations that are not deterministic; this trap is noted in the language specification thusly:
+This rule reports on any call to the `Array#sort()` method that doesn't provide a `compare` argument.
 
-:::note
-Method calls performed by the `ToString` abstract operations in steps 5 and 7 have the potential to cause `SortCompare` to not behave as a consistent comparison function.
-
-https://www.ecma-international.org/ecma-262/9.0/#sec-sortcompare
-:::
-
-## Rule Details
+## Examples
 
 This rule aims to ensure all calls of the native `Array#sort` method provide a `compareFunction`, while ignoring calls to user-defined `sort` methods.
 
-Examples of code for this rule:
-
 <!--tabs-->
 
 ### ❌ Incorrect
@@ -84,4 +75,4 @@ const three = '3';
 
 ## When Not To Use It
 
-If you understand the language specification enough, you can turn this rule off safely.
+If you understand the language specification enough, and/or only ever sort arrays in a string-like manner, you can turn this rule off safely.

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/require-await.md

@@ -6,7 +6,7 @@ description: 'Disallow async functions which have no `await` expression.'
 >
 > See **https://typescript-eslint.io/rules/require-await** for documentation.
 
-## Rule Details
+## Examples
 
 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`.

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/restrict-plus-operands.md

@@ -1,14 +1,17 @@
 ---
-description: 'Require both operands of addition to have type `number` or `string`.'
+description: 'Require both operands of addition to be the same type and be `bigint`, `number`, or `string`.'
 ---
 
 > 🛑 This file is source code, not the primary documentation location! 🛑
 >
 > See **https://typescript-eslint.io/rules/restrict-plus-operands** for documentation.
 
-## Rule Details
+TypeScript allows `+` adding together two values of any type(s).
+However, adding values that are not the same type and/or are not the same primitive type is often a sign of programmer error.
 
-Examples of code for this rule:
+This rule reports when a `+` operation combines two values of different types, or a type that is not `bigint`, `number`, or `string`.
+
+## Examples
 
 <!--tabs-->
 
@@ -81,4 +84,15 @@ var fn = (a: any, b: bigint) => a + b;
 var fn = (a: any, b: number) => a + b;
 ```
 
-## How to Use
+## When Not To Use It
+
+If you don't mind `"[object Object]"` in your strings, then you will not need this rule.
+
+## Related To
+
+- [`no-base-to-string`](./no-base-to-string.md)
+- [`restrict-template-expressions`](./restrict-template-expressions.md)
+
+## Further Reading
+
+- [`Object.prototype.toString()` MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString)

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/restrict-template-expressions.md

@@ -6,9 +6,11 @@ description: 'Enforce template literal expressions to be of `string` type.'
 >
 > See **https://typescript-eslint.io/rules/restrict-template-expressions** for documentation.
 
-## Rule Details
+JavaScript will call `toString()` on an object when it is converted to a string, such as when `+` adding to a string or in `${}` template literals.
+The default Object `.toString()` returns `"[object Object]"`, which is often not what was intended.
+This rule reports on values used in a template literal string that aren't primitives and don't define a more useful `.toString()` method.
 
-Examples of code for this rule:
+## Examples
 
 <!--tabs-->
 
@@ -87,3 +89,8 @@ const msg1 = `arg = ${arg}`;
 const arg = /foo/;
 const msg1 = `arg = ${arg}`;
 ```
+
+## Related To
+
+- [`no-base-to-string`](./no-base-to-string.md)
+- [`restrict-plus-operands`](./restrict-plus-operands.md)

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/return-await.md

@@ -8,7 +8,7 @@ description: 'Enforce consistent returning of awaited values.'
 
 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).
 
-## Rule Details
+## Examples
 
 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.

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/semi.md

@@ -8,7 +8,7 @@ description: 'Require or disallow semicolons instead of ASI.'
 
 This rule enforces consistent use of semicolons after statements.
 
-## Rule Details
+## Examples
 
 This rule extends the base [`eslint/semi`](https://eslint.org/docs/rules/semi) rule.
 It adds support for TypeScript features that require semicolons.