xo 0.49.0 → 0.52.0

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/no-extraneous-class.md

@@ -1,15 +1,26 @@
-# `no-extraneous-class`
+---
+description: 'Disallow classes used as namespaces.'
+---
 
-Forbids the use of classes as namespaces.
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-extraneous-class** for documentation.
 
-This rule warns when a class is accidentally used as a namespace.
+This rule warns when a class has no non-static members, such as for a class used exclusively as a static namespace.
 
 ## Rule Details
 
-From TSLint’s docs:
+Users who come from a [OOP](https://en.wikipedia.org/wiki/Object-oriented_programming) paradigm may wrap their utility functions in an extra class, instead of putting them at the top level of an ECMAScript module.
+Doing so is generally unnecessary in JavaScript and TypeScript projects.
 
-> Users who come from a Java-style OO language may wrap their utility functions in an extra class,
-> instead of putting them at the top level.
+- Wrapper classes add extra cognitive complexity to code without adding any structural improvements
+  - Whatever would be put on them, such as utility functions, are already organized by virtue of being in a module.
+  - As an alternative, you can always `import * as ...` the module to get all of them in a single object.
+- IDEs can't provide as good suggestions for static class or namespace imported properties when you start typing property names
+- It's more difficult to statically analyze code for unused variables, etc. when they're all on the class (see: [Finding dead code (and dead types) in TypeScript](https://effectivetypescript.com/2020/10/20/tsprune)).
+
+This rule also flags classes that have only a constructor and no fields.
+Those classes can generally be replaced with a standalone function.
 
 Examples of code for this rule:
 
@@ -18,18 +29,16 @@ Examples of code for this rule:
 ### ❌ Incorrect
 
 ```ts
-class EmptyClass {}
+class StaticConstants {
+  static readonly version = 42;
 
-class ConstructorOnly {
-  constructor() {
-    foo();
+  static isProduction() {
+    return process.env.NODE_ENV === 'production';
   }
 }
 
-// Use an object instead:
-class StaticOnly {
-  static version = 42;
-  static hello() {
+class HelloWorldLogger {
+  constructor() {
     console.log('Hello, world!');
   }
 }
@@ -38,57 +47,250 @@ class StaticOnly {
 ### ✅ Correct
 
 ```ts
-class EmptyClass extends SuperClass {}
+export const version = 42;
+
+export function isProduction() {
+  return process.env.NODE_ENV === 'production';
+}
+
+function logHelloWorld() {
+  console.log('Hello, world!');
+}
+```
+
+## Alternatives
+
+### Individual Exports (Recommended)
+
+Instead of using a static utility class we recommend you individually export the utilities from your module.
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+export class Utilities {
+  static util1() {
+    return Utilities.util3();
+  }
 
-class ParameterProperties {
-  constructor(public name: string) {}
+  static util2() {
+    /* ... */
+  }
+
+  static util3() {
+    /* ... */
+  }
 }
+```
+
+#### ✅ Correct
+
+```ts
+export function util1() {
+  return util3();
+}
+
+export function util2() {
+  /* ... */
+}
+
+export function util3() {
+  /* ... */
+}
+```
+
+### Namespace Imports (Not Recommended)
+
+If you strongly prefer to have all constructs from a module available as properties of a single object, you can `import * as` the module.
+This is known as a "namespace import".
+Namespace imports are sometimes preferable because they keep all properties nested and don't need to be changed as you start or stop using various properties from the module.
 
-const StaticOnly = {
-  version: 42,
-  hello() {
+However, namespace imports are impacted by these downsides:
+
+- They also don't play as well with tree shaking in modern bundlers
+- They require a name prefix before each property's usage
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+// utilities.ts
+export class Utilities {
+  static sayHello() {
     console.log('Hello, world!');
-  },
-};
+  }
+}
+
+// consumers.ts
+import { Utilities } from './utilities';
+
+Utilities.sayHello();
+```
+
+#### ⚠️ Namespace Imports
+
+```ts
+// utilities.ts
+export function sayHello() {
+  console.log('Hello, world!');
+}
+
+// consumers.ts
+import * as utilities from './utilities';
+
+utilities.sayHello();
+```
+
+#### ✅ Standalone Imports
+
+```ts
+// utilities.ts
+export function sayHello() {
+  console.log('Hello, world!');
+}
+
+// consumers.ts
+import { sayHello } from './utilities';
+
+sayHello();
+```
+
+### Notes on Mutating Variables
+
+One case you need to be careful of is exporting mutable variables.
+While class properties can be mutated externally, exported variables are always constant.
+This means that importers can only ever read the first value they are assigned and cannot write to the variables.
+
+Needing to write to an exported variable is very rare and is generally considered a code smell.
+If you do need it you can accomplish it using getter and setter functions:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+export class Utilities {
+  static mutableCount = 1;
+
+  static incrementCount() {
+    Utilities.mutableCount += 1;
+  }
+}
+```
+
+#### ✅ Correct
+
+```ts
+let mutableCount = 1;
+
+export function getMutableCount() {
+  return mutableField;
+}
+
+export function incrementCount() {
+  mutableField += 1;
+}
 ```
 
 ## Options
 
-This rule accepts a single object option.
+This rule normally bans classes that are empty (have no constructor or fields).
+The rule's options each add an exemption for a specific type of class.
+
+### `allowConstructorOnly`
+
+`allowConstructorOnly` adds an exemption for classes that have only a constructor and no fields.
+
+<!--tabs-->
+
+#### ❌ Incorrect
 
 ```ts
-type Options = {
-  // allow extraneous classes if they only contain a constructor
-  allowConstructorOnly?: boolean;
-  // allow extraneous classes if they have no body (i.e. are empty)
-  allowEmpty?: boolean;
-  // allow extraneous classes if they only contain static members
-  allowStaticOnly?: boolean;
-  // allow extraneous classes if they have a decorator
-  allowWithDecorator?: boolean;
-};
+class NoFields {}
+```
 
-const defaultOptions: Options = {
-  allowConstructorOnly: false,
-  allowEmpty: false,
-  allowStaticOnly: false,
-  allowWithDecorator: false,
-};
+#### ✅ Correct
+
+```ts
+class NoFields {
+  constructor() {
+    console.log('Hello, world!');
+  }
+}
 ```
 
-## When Not To Use It
+### `allowEmpty`
 
-You can disable this rule if you don’t have anyone who would make these kinds of mistakes on your
-team or if you use classes as namespaces.
+The `allowEmpty` option adds an exemption for classes that are entirely empty.
 
-## Related To
+<!--tabs-->
 
-[`no-unnecessary-class`](https://palantir.github.io/tslint/rules/no-unnecessary-class/) from TSLint
+#### ❌ Incorrect
 
-## Attributes
+```ts
+class NoFields {
+  constructor() {
+    console.log('Hello, world!');
+  }
+}
+```
+
+#### ✅ Correct
+
+```ts
+class NoFields {}
+```
+
+### `allowStaticOnly`
+
+The `allowStaticOnly` option adds an exemption for classes that only contain static members.
+
+:::caution
+We strongly recommend against the `allowStaticOnly` exemption.
+It works against this rule's primary purpose of discouraging classes used only for static members.
+:::
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+class EmptyClass {}
+```
+
+#### ✅ Correct
+
+```ts
+class NotEmptyClass {
+  static version = 42;
+}
+```
+
+### `allowWithDecorator`
+
+The `allowWithDecorator` option adds an exemption for classes that contain a member decorated with a `@` decorator.
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+class Constants {
+  static readonly version = 42;
+}
+```
+
+#### ✅ Correct
+
+```ts
+class Constants {
+  @logOnRead()
+  static readonly version = 42;
+}
+```
+
+## When Not To Use It
 
-- Configs:
-  - [ ] ✅ Recommended
-  - [x] 🔒 Strict
-- [ ] 🔧 Fixable
-- [ ] 💭 Requires type information
+You can disable this rule if you are unable -or unwilling- to switch off using classes as namespaces.

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/no-floating-promises.md

@@ -1,6 +1,10 @@
-# `no-floating-promises`
+---
+description: 'Require Promise-like statements to be handled appropriately.'
+---
 
-Requires Promise-like statements to be handled appropriately.
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-floating-promises** for documentation.
 
 A "floating" Promise is one that is created without any code set up to handle any errors it might throw.
 
@@ -61,22 +65,6 @@ Promise.reject('value').finally(() => {});
 
 ## Options
 
-The rule accepts an options object with the following properties:
-
-```ts
-type Options = {
-  // if true, checking void expressions will be skipped
-  ignoreVoid?: boolean;
-  // if true, checking for async iife will be skipped
-  ignoreIIFE?: boolean;
-};
-
-const defaults = {
-  ignoreVoid: true,
-  ignoreIIFE: false,
-};
-```
-
 ### `ignoreVoid`
 
 This allows you to stop the rule reporting promises consumed with void operator.
@@ -118,12 +106,3 @@ If you do not use Promise-like values in your codebase, or want to allow them to
 ## Related To
 
 - [`no-misused-promises`](./no-misused-promises.md)
-- TSLint: ['no-floating-promises'](https://palantir.github.io/tslint/rules/no-floating-promises/)
-
-## Attributes
-
-- Configs:
-  - [x] ✅ Recommended
-  - [x] 🔒 Strict
-- [ ] 🔧 Fixable
-- [x] 💭 Requires type information

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/no-for-in-array.md

@@ -1,13 +1,15 @@
-# `no-for-in-array`
+---
+description: 'Disallow iterating over an array with a for-in loop.'
+---
 
-Disallow iterating over an array with a for-in loop.
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-for-in-array** for documentation.
 
 This rule prohibits iterating over an array with a for-in loop.
 
 ## Rule Details
 
-Rationale from TSLint:
-
 A for-in loop (`for (var k in o)`) iterates over the properties of an Object.
 While it is legal to use for-in loops with array types, it is not common.
 for-in will iterate over the indices of the array as strings, omitting any "holes" in
@@ -41,31 +43,6 @@ for (const x in { a: 3, b: 4, c: 5 }) {
 }
 ```
 
-## Options
-
-```jsonc
-// .eslintrc.json
-{
-  "rules": {
-    "@typescript-eslint/no-for-in-array": "error"
-  }
-}
-```
-
-This rule is not configurable.
-
 ## When Not To Use It
 
 If you want to iterate through a loop using the indices in an array as strings, you can turn off this rule.
-
-## Related To
-
-- TSLint: ['no-for-in-array'](https://palantir.github.io/tslint/rules/no-for-in-array/)
-
-## Attributes
-
-- Configs:
-  - [x] ✅ Recommended
-  - [x] 🔒 Strict
-- [ ] 🔧 Fixable
-- [x] 💭 Requires type information

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/no-implicit-any-catch.md

@@ -1,6 +1,15 @@
-# `no-implicit-any-catch`
+---
+description: 'Disallow usage of the implicit `any` type in catch clauses.'
+---
 
-Disallow usage of the implicit `any` type in catch clauses.
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-implicit-any-catch** for documentation.
+
+:::danger Deprecated
+
+This rule has been deprecated as TypeScript versions >=4 includes a `useUnknownInCatchVariables` compiler option with the same check.
+:::
 
 TypeScript 4.0 added support for adding an explicit `any` or `unknown` type annotation on a catch clause variable.
 
@@ -8,6 +17,8 @@ By default, TypeScript will type a catch clause variable as `any`, so explicitly
 
 The `noImplicitAny` flag in TypeScript does not cover this for backwards compatibility reasons, however you can use `useUnknownInCatchVariables` (part of `strict`) instead of this rule.
 
+## DEPRECATED
+
 ## Rule Details
 
 This rule requires an explicit type to be declared on a catch clause variable.
@@ -43,26 +54,10 @@ try {
 
 ## Options
 
-The rule accepts an options object with the following properties:
-
-```ts
-type Options = {
-  // if false, disallow specifying `: any` as the error type as well. See also `no-explicit-any`
-  allowExplicitAny: boolean;
-};
-
-const defaults = {
-  allowExplicitAny: false,
-};
-```
-
 ### `allowExplicitAny`
 
 The follow is is **_not_** considered a warning with `{ allowExplicitAny: true }`
 
-<!-- TODO: prettier currently removes the type annotations, re-enable this once prettier is updated -->
-<!-- prettier-ignore-start -->
-
 ```ts
 try {
   // ...
@@ -71,8 +66,6 @@ try {
 }
 ```
 
-<!-- prettier-ignore-end -->
-
 ## When Not To Use It
 
 If you are not using TypeScript 4.0 (or greater), then you will not be able to use this rule, annotations on catch clauses is not supported.
@@ -80,11 +73,3 @@ If you are not using TypeScript 4.0 (or greater), then you will not be able to u
 ## Further Reading
 
 - [TypeScript 4.0 Release Notes](https://devblogs.microsoft.com/typescript/announcing-typescript-4-0/#unknown-on-catch)
-
-## Attributes
-
-- Configs:
-  - [ ] ✅ Recommended
-  - [ ] 🔒 Strict
-- [x] 🔧 Fixable
-- [ ] 💭 Requires type information

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/no-implied-eval.md

@@ -1,6 +1,10 @@
-# `no-implied-eval`
+---
+description: 'Disallow the use of `eval()`-like methods.'
+---
 
-Disallow the use of `eval()`-like methods.
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-implied-eval** for documentation.
 
 It's considered a good practice to avoid using `eval()`. There are security and performance implications involved with doing so, which is why many linters recommend disallowing `eval()`. However, there are some other ways to pass a string and have it interpreted as JavaScript code that have similar concerns.
 
@@ -94,30 +98,6 @@ class Foo {
 setTimeout(Foo.fn, 100);
 ```
 
-## How to Use
-
-```jsonc
-{
-  // note you must disable the base rule as it can report incorrect errors
-  "no-implied-eval": "off",
-  "@typescript-eslint/no-implied-eval": ["error"]
-}
-```
-
 ## When Not To Use It
 
 If you want to allow `new Function()` or `setTimeout()`, `setInterval()`, `setImmediate()` and `execScript()` with string arguments, then you can safely disable this rule.
-
-<sup>
-
-Taken with ❤️ [from ESLint core](https://github.com/eslint/eslint/blob/main/docs/rules/no-implied-eval.md)
-
-</sup>
-
-## Attributes
-
-- Configs:
-  - [x] ✅ Recommended
-  - [x] 🔒 Strict
-- [ ] 🔧 Fixable
-- [x] 💭 Requires type information

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/no-inferrable-types.md

@@ -1,6 +1,10 @@
-# `no-inferrable-types`
+---
+description: 'Disallow explicit type declarations for variables or parameters initialized to a number, string, or boolean.'
+---
 
-Disallows explicit type declarations for variables or parameters initialized to a number, string, or boolean.
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-inferrable-types** for documentation.
 
 Explicit types where they can be easily inferred may add unnecessary verbosity.
 
@@ -9,33 +13,11 @@ Explicit types where they can be easily inferred may add unnecessary verbosity.
 This rule disallows explicit type declarations on parameters, variables
 and properties where the type can be easily inferred from its value.
 
-## Options
-
-This rule accepts the following options:
-
-```ts
-interface Options {
-  ignoreParameters?: boolean;
-  ignoreProperties?: boolean;
-}
-```
-
-### Default
-
-The default options are:
-
-```json
-{
-  "ignoreParameters": false,
-  "ignoreProperties": false
-}
-```
-
-With these options, the following patterns are:
+Examples of code with the default options:
 
 <!--tabs-->
 
-#### ❌ Incorrect
+### ❌ Incorrect
 
 ```ts
 const a: bigint = 10n;
@@ -76,7 +58,7 @@ class Foo {
 function fn(a: number = 5, b: boolean = true) {}
 ```
 
-#### ✅ Correct
+### ✅ Correct
 
 ```ts
 const a = 10n;
@@ -121,6 +103,8 @@ function fn(a: number, b: boolean, c: string) {}
 
 <!--/tabs-->
 
+## Options
+
 ### `ignoreParameters`
 
 When set to true, the following pattern is considered valid:
@@ -148,15 +132,3 @@ If you do not want to enforce inferred types.
 ## Further Reading
 
 TypeScript [Inference](https://www.typescriptlang.org/docs/handbook/type-inference.html)
-
-## Related To
-
-TSLint: [no-inferrable-types](https://palantir.github.io/tslint/rules/no-inferrable-types/)
-
-## Attributes
-
-- Configs:
-  - [x] ✅ Recommended
-  - [x] 🔒 Strict
-- [x] 🔧 Fixable
-- [ ] 💭 Requires type information

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/no-invalid-this.md

@@ -1,40 +1,12 @@
-# `no-invalid-this`
+---
+description: 'Disallow `this` keywords outside of classes or class-like objects.'
+---
 
-Disallow `this` keywords outside of classes or class-like objects.
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-invalid-this** for documentation.
 
 ## Rule Details
 
 This rule extends the base [`eslint/no-invalid-this`](https://eslint.org/docs/rules/no-invalid-this) rule.
 It adds support for TypeScript's `this` parameters.
-
-## How to Use
-
-```jsonc
-{
-  // note you must disable the base rule as it can report incorrect errors
-  "no-invalid-this": "off",
-  "@typescript-eslint/no-invalid-this": ["error"]
-}
-```
-
-## Options
-
-See [`eslint/no-invalid-this` options](https://eslint.org/docs/rules/no-invalid-this#options).
-
-## When Not To Use It
-
-When you are indifferent as to how your variables are initialized.
-
-<sup>
-
-Taken with ❤️ [from ESLint core](https://github.com/eslint/eslint/blob/main/docs/rules/no-invalid-this.md)
-
-</sup>
-
-## Attributes
-
-- Configs:
-  - [ ] ✅ Recommended
-  - [ ] 🔒 Strict
-- [ ] 🔧 Fixable
-- [ ] 💭 Requires type information