@typescript-eslint/eslint-plugin 7.0.0-alpha.0 → 7.0.1

package/docs/rules/no-require-imports.md

@@ -28,9 +28,32 @@ import { lib2 } from 'lib2';
 import * as lib3 from 'lib3';
 ```
 
+## Options
+
+### `allow`
+
+A array of strings. These strings will be compiled into regular expressions with the `u` flag and be used to test against the imported path. A common use case is to allow importing `package.json`. This is because `package.json` commonly lives outside of the TS root directory, so statically importing it would lead to root directory conflicts, especially with `resolveJsonModule` enabled. You can also use it to allow importing any JSON if your environment doesn't support JSON modules, or use it for other cases where `import` statements cannot work.
+
+With `{allow: ['/package\\.json$']}`:
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+console.log(require('../data.json').version);
+```
+
+### ✅ Correct
+
+```ts
+console.log(require('../package.json').version);
+```
+
 ## When Not To Use It
 
-If you don't care about using newer module syntax, then you will not need this rule.
+If your project frequently uses older CommonJS `require`s, then this rule might not be applicable to you.
+If only a subset of your project uses `require`s then 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
 

package/docs/rules/no-restricted-imports.md

@@ -6,9 +6,7 @@ description: 'Disallow specified modules when loaded by `import`.'
 >
 > See **https://typescript-eslint.io/rules/no-restricted-imports** for documentation.
 
-## Examples
-
-This rule extends the base [`eslint/no-restricted-imports`](https://eslint.org/docs/rules/no-restricted-imports) rule.
+This rule extends the base [`eslint/no-restricted-imports`](https://eslint.org/docs/rules/no-restricted-imports) rule. It adds support for the type import (`import type X from "..."`, `import { type X } from "..."`) and `import x = require("...")` syntaxes.
 
 ## Options
 
@@ -21,17 +19,27 @@ This rule adds the following options:
 You can specify this option for a specific path or pattern as follows:
 
 ```jsonc
-"@typescript-eslint/no-restricted-imports": ["error", {
-  "paths": [{
-    "name": "import-foo",
-    "message": "Please use import-bar instead.",
-    "allowTypeImports": true
-  }, {
-    "name": "import-baz",
-    "message": "Please use import-quux instead.",
-    "allowTypeImports": true
-  }]
-}]
+{
+  "rules": {
+    "@typescript-eslint/no-restricted-imports": [
+      "error",
+      {
+        "paths": [
+          {
+            "name": "import-foo",
+            "message": "Please use import-bar instead.",
+            "allowTypeImports": true,
+          },
+          {
+            "name": "import-baz",
+            "message": "Please use import-quux instead.",
+            "allowTypeImports": true,
+          },
+        ],
+      },
+    ],
+  },
+}
 ```
 
 When set to `true`, the rule will allow [Type-Only Imports](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html#type-only-imports-and-export).
@@ -42,7 +50,7 @@ Examples of code with the above config:
 
 #### ❌ Incorrect
 
-```ts
+```ts option='{"paths":[{"name":"import-foo","message":"Please use import-bar instead.","allowTypeImports":true},{"name":"import-baz","message":"Please use import-quux instead.","allowTypeImports":true}]}'
 import foo from 'import-foo';
 export { Foo } from 'import-foo';
 
@@ -52,7 +60,7 @@ export { Baz } from 'import-baz';
 
 #### ✅ Correct
 
-```ts
+```ts option='{"paths":[{"name":"import-foo","message":"Please use import-bar instead.","allowTypeImports":true},{"name":"import-baz","message":"Please use import-quux instead.","allowTypeImports":true}]}'
 import { foo } from 'other-module';
 
 import type foo from 'import-foo';

package/docs/rules/no-shadow.md

@@ -6,8 +6,6 @@ description: 'Disallow variable declarations from shadowing variables declared i
 >
 > See **https://typescript-eslint.io/rules/no-shadow** for documentation.
 
-## Examples
-
 This rule extends the base [`eslint/no-shadow`](https://eslint.org/docs/rules/no-shadow) rule.
 It adds support for TypeScript's `this` parameters and global augmentation, and adds options for TypeScript features.
 
@@ -30,25 +28,31 @@ const defaultOptions: Options = {
 
 ### `ignoreTypeValueShadow`
 
-When set to `true`, the rule will ignore the case when you name a type the same as a variable.
-
-TypeScript allows types and variables to shadow one-another. This is generally safe because you cannot use variables in type locations without a `typeof` operator, so there's little risk of confusion.
+When set to `true`, the rule will ignore the case when you name a type the same as a variable. This is generally safe because you cannot use variables in type locations without a `typeof` operator, so there's little risk of confusion.
 
 Examples of **correct** code with `{ ignoreTypeValueShadow: true }`:
 
-```ts
+```ts option='{ "ignoreTypeValueShadow": true }' showPlaygroundButton
 type Foo = number;
-const Foo = 1;
-
 interface Bar {
   prop: number;
 }
-const Bar = 'test';
+
+function f() {
+  const Foo = 1;
+  const Bar = 'test';
+}
 ```
 
+:::note
+
+_Shadowing_ specifically refers to two identical identifiers that are in different, nested scopes. This is different from _redeclaration_, which is when two identical identifiers are in the same scope. Redeclaration is covered by the [`no-redeclare`](./no-redeclare.md) rule instead.
+
+:::
+
 ### `ignoreFunctionTypeParameterNameValueShadow`
 
-When set to `true`, the rule will ignore the case when you name a function type argument the same as a variable.
+When set to `true`, the rule will ignore the case when you name a parameter in a function type the same as a variable.
 
 Each of a function type's arguments creates a value variable within the scope of the function type. This is done so that you can reference the type later using the `typeof` operator:
 
@@ -74,7 +78,7 @@ If you do not use the `typeof` operator in a function type return type position,
 
 Examples of **correct** code with `{ ignoreFunctionTypeParameterNameValueShadow: true }`:
 
-```ts
+```ts option='{ "ignoreFunctionTypeParameterNameValueShadow": true }' showPlaygroundButton
 const test = 1;
 type Func = (test: string) => typeof test;
 ```

package/docs/rules/no-this-alias.md

@@ -15,7 +15,7 @@ or not managing scope well.
 
 ### ❌ Incorrect
 
-```js
+```ts
 const self = this;
 
 setTimeout(function () {
@@ -25,7 +25,7 @@ setTimeout(function () {
 
 ### ✅ Correct
 
-```js
+```ts
 setTimeout(() => {
   this.doWork();
 });
@@ -33,6 +33,76 @@ setTimeout(() => {
 
 ## Options
 
+### `allowDestructuring`
+
+It can sometimes be useful to destructure properties from a class instance, such as retrieving multiple properties from the instance in one of its methods.
+`allowDestructuring` allows those destructures and is `true` by default.
+You can explicitly disallow them by setting `allowDestructuring` to `false`.
+
+Examples of code for the `{ "allowDestructuring": false }` option:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts option='{ "allowDestructuring": false }'
+class ComponentLike {
+  props: unknown;
+  state: unknown;
+
+  render() {
+    const { props, state } = this;
+
+    console.log(props);
+    console.log(state);
+  }
+}
+```
+
+#### ✅ Correct
+
+```ts option='{ "allowDestructuring": false }'
+class ComponentLike {
+  props: unknown;
+  state: unknown;
+
+  render() {
+    console.log(this.props);
+    console.log(this.state);
+  }
+}
+```
+
+### `allowedNames`
+
+`no-this-alias` can alternately be used to allow only a specific list of names as `this` aliases.
+We recommend against this except as a transitory step towards fixing all rule violations.
+
+Examples of code for the `{ "allowedNames": ["self"] }` option:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts option='{ "allowedNames": ["self"] }'
+class Example {
+  method() {
+    const that = this;
+  }
+}
+```
+
+#### ✅ Correct
+
+```ts option='{ "allowedNames": ["self"] }'
+class Example {
+  method() {
+    const self = this;
+  }
+}
+```
+
 ## When Not To Use It
 
-If you need to assign `this` to variables, you shouldn’t use this rule.
+If your project is structured in a way that it needs to assign `this` to variables, this rule is likely not for you.
+If only a subset of your project assigns `this` to variables then 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.

package/docs/rules/no-throw-literal.md

@@ -20,8 +20,6 @@ This rule is aimed at maintaining consistency when throwing exception by disallo
 ### ❌ Incorrect
 
 ```ts
-/*eslint @typescript-eslint/no-throw-literal: "error"*/
-
 throw 'error';
 
 throw 0;
@@ -53,19 +51,17 @@ throw foo.bar;
 ### ✅ Correct
 
 ```ts
-/*eslint @typescript-eslint/no-throw-literal: "error"*/
-
 throw new Error();
 
-throw new Error("error");
+throw new Error('error');
 
-const e = new Error("error");
+const e = new Error('error');
 throw e;
 
 try {
-    throw new Error("error");
+  throw new Error('error');
 } catch (e) {
-    throw e;
+  throw e;
 }
 
 const err = new Error();
@@ -77,13 +73,13 @@ function err() {
 throw err();
 
 const foo = {
-  bar: new Error();
-}
+  bar: new Error(),
+};
 throw foo.bar;
 
 class CustomError extends Error {
   // ...
-};
+}
 throw new CustomError();
 ```
 
@@ -109,3 +105,5 @@ const defaultOptions: Options = {
   allowThrowingUnknown: false,
 };
 ```
+
+<!-- Intentionally omitted: When Not To Use It -->

package/docs/rules/no-type-alias.md

@@ -27,15 +27,23 @@ In TypeScript, type aliases serve three purposes:
 ```ts
 // this...
 type Person = {
-    firstName: string,
-    lastName: string,
-    age: number
+  firstName: string;
+  lastName: string;
+  age: number;
 };
 
-function addPerson(person : Person) { ... }
+function addPerson(person: Person) {
+  // ...
+}
 
 // is easier to read than this...
-function addPerson(person : { firstName: string, lastName: string, age: number}) { ... }
+function addPerson(person: {
+  firstName: string;
+  lastName: string;
+  age: number;
+}) {
+  // ...
+}
 ```
 
 - Act sort of like an interface, providing a set of methods and properties that must exist
@@ -43,16 +51,18 @@ function addPerson(person : { firstName: string, lastName: string, age: number})
 
 ```ts
 type Person = {
-    firstName: string,
-    lastName: string,
-    age: number,
-    walk: () => void,
-    talk: () => void
+  firstName: string;
+  lastName: string;
+  age: number;
+  walk: () => void;
+  talk: () => void;
 };
 
 // you know person will have 3 properties and 2 methods,
 // because the structure has already been defined.
-var person : Person = { ... }
+var person: Person = {
+  // ...
+};
 
 // so we can be sure that this will work
 person.walk();
@@ -112,7 +122,7 @@ The setting accepts the following values:
 
 Examples of **correct** code for the `{ "allowAliases": "always" }` options:
 
-```ts
+```ts option='{ "allowAliases": "always" }' showPlaygroundButton
 // primitives
 type Foo = 'a';
 
@@ -139,7 +149,7 @@ type Foo = Bar & Baz;
 
 Examples of **incorrect** code for the `{ "allowAliases": "in-unions" }` option:
 
-```ts
+```ts option='{ "allowAliases": "in-unions" }' showPlaygroundButton
 // primitives
 type Foo = 'a';
 
@@ -160,7 +170,7 @@ type Foo = Bar & Baz;
 
 Examples of **correct** code for the `{ "allowAliases": "in-unions" }` option:
 
-```ts
+```ts option='{ "allowAliases": "in-unions" }' showPlaygroundButton
 // primitives
 type Foo = 'a' | 'b';
 
@@ -177,7 +187,7 @@ type Foo = Bar | Baz;
 
 Examples of **incorrect** code for the `{ "allowAliases": "in-intersections" }` option:
 
-```ts
+```ts option='{ "allowAliases": "in-intersections" }' showPlaygroundButton
 // primitives
 type Foo = 'a';
 
@@ -200,7 +210,7 @@ type Foo = Bar | Baz;
 
 Examples of **correct** code for the `{ "allowAliases": "in-intersections" }` option:
 
-```ts
+```ts option='{ "allowAliases": "in-intersections" }' showPlaygroundButton
 // primitives
 type Foo = string & string[];
 
@@ -215,7 +225,7 @@ type Foo = Bar & Baz;
 
 Examples of **incorrect** code for the `{ "allowAliases": "in-unions-and-intersections" }` option:
 
-```ts
+```ts option='{ "allowAliases": "in-unions-and-intersections" }' showPlaygroundButton
 // primitives
 type Foo = 'a';
 
@@ -232,7 +242,7 @@ type Foo = Bar;
 
 Examples of **correct** code for the `{ "allowAliases": "in-unions-and-intersections" }` option:
 
-```ts
+```ts option='{ "allowAliases": "in-unions-and-intersections" }' showPlaygroundButton
 // primitives
 type Foo = 'a' | 'b';
 
@@ -263,7 +273,7 @@ The setting accepts the following values:
 
 Examples of **correct** code for the `{ "allowCallbacks": "always" }` option:
 
-```ts
+```ts option='{ "allowCallbacks": "always" }' showPlaygroundButton
 type Foo = () => void;
 
 type Foo = (name: string) => string;
@@ -281,7 +291,7 @@ This applies to conditional types.
 
 Examples of **correct** code for the `{ "allowConditionalTypes": "always" }` option:
 
-```ts
+```ts option='{ "allowConditionalTypes": "always" }' showPlaygroundButton
 type Foo<T> = T extends number ? number : null;
 ```
 
@@ -295,7 +305,7 @@ The setting accepts the following values:
 
 Examples of **correct** code for the `{ "allowConstructors": "always" }` option:
 
-```ts
+```ts option='{ "allowConstructors": "always" }' showPlaygroundButton
 type Foo = new () => void;
 ```
 
@@ -312,7 +322,7 @@ The setting accepts the following options:
 
 Examples of **correct** code for the `{ "allowLiterals": "always" }` options:
 
-```ts
+```ts option='{ "allowLiterals": "always" }' showPlaygroundButton
 type Foo = {};
 
 type Foo = {
@@ -333,7 +343,7 @@ type Foo = { name: string } & { age: number };
 
 Examples of **incorrect** code for the `{ "allowLiterals": "in-unions" }` option:
 
-```ts
+```ts option='{ "allowLiterals": "in-unions" }' showPlaygroundButton
 type Foo = {};
 
 type Foo = {
@@ -352,13 +362,13 @@ type Foo = { name: string } & { age: number };
 
 Examples of **correct** code for the `{ "allowLiterals": "in-unions" }` option:
 
-```ts
+```ts option='{ "allowLiterals": "in-unions" }' showPlaygroundButton
 type Foo = { name: string } | { age: number };
 ```
 
 Examples of **incorrect** code for the `{ "allowLiterals": "in-intersections" }` option:
 
-```ts
+```ts option='{ "allowLiterals": "in-intersections" }' showPlaygroundButton
 type Foo = {};
 
 type Foo = {
@@ -377,13 +387,13 @@ type Foo = { name: string } | { age: number };
 
 Examples of **correct** code for the `{ "allowLiterals": "in-intersections" }` option:
 
-```ts
+```ts option='{ "allowLiterals": "in-intersections" }' showPlaygroundButton
 type Foo = { name: string } & { age: number };
 ```
 
 Examples of **incorrect** code for the `{ "allowLiterals": "in-unions-and-intersections" }` option:
 
-```ts
+```ts option='{ "allowLiterals": "in-unions-and-intersections" }' showPlaygroundButton
 type Foo = {};
 
 type Foo = {
@@ -400,7 +410,7 @@ type Foo = {
 
 Examples of **correct** code for the `{ "allowLiterals": "in-unions-and-intersections" }` option:
 
-```ts
+```ts option='{ "allowLiterals": "in-unions-and-intersections" }' showPlaygroundButton
 type Foo = { name: string } | { age: number };
 
 type Foo = { name: string } & { age: number };
@@ -419,7 +429,7 @@ The setting accepts the following values:
 
 Examples of **correct** code for the `{ "allowMappedTypes": "always" }` options:
 
-```ts
+```ts option='{ "allowMappedTypes": "always" }' showPlaygroundButton
 type Foo<T> = { readonly [P in keyof T]: T[P] };
 
 type Foo<T> = { [P in keyof T]?: T[P] };
@@ -439,7 +449,7 @@ type Foo<T, U> = { [P in keyof T]?: T[P] } & { [P in keyof U]?: U[P] };
 
 Examples of **incorrect** code for the `{ "allowMappedTypes": "in-unions" }` option:
 
-```ts
+```ts option='{ "allowMappedTypes": "in-unions" }' showPlaygroundButton
 type Foo<T> = { readonly [P in keyof T]: T[P] };
 
 type Foo<T> = { [P in keyof T]?: T[P] };
@@ -453,7 +463,7 @@ type Foo<T, U> = { [P in keyof T]?: T[P] } & { [P in keyof U]?: U[P] };
 
 Examples of **correct** code for the `{ "allowMappedTypes": "in-unions" }` option:
 
-```ts
+```ts option='{ "allowMappedTypes": "in-unions" }' showPlaygroundButton
 type Foo<T, U> =
   | { readonly [P in keyof T]: T[P] }
   | { readonly [P in keyof U]: U[P] };
@@ -463,7 +473,7 @@ type Foo<T, U> = { [P in keyof T]?: T[P] } | { [P in keyof U]?: U[P] };
 
 Examples of **incorrect** code for the `{ "allowMappedTypes": "in-intersections" }` option:
 
-```ts
+```ts option='{ "allowMappedTypes": "in-intersections" }' showPlaygroundButton
 type Foo<T> = { readonly [P in keyof T]: T[P] };
 
 type Foo<T> = { [P in keyof T]?: T[P] };
@@ -477,7 +487,7 @@ type Foo<T, U> = { [P in keyof T]?: T[P] } | { [P in keyof U]?: U[P] };
 
 Examples of **correct** code for the `{ "allowMappedTypes": "in-intersections" }` option:
 
-```ts
+```ts option='{ "allowMappedTypes": "in-intersections" }' showPlaygroundButton
 type Foo<T, U> = { readonly [P in keyof T]: T[P] } & {
   readonly [P in keyof U]: U[P];
 };
@@ -487,7 +497,7 @@ type Foo<T, U> = { [P in keyof T]?: T[P] } & { [P in keyof U]?: U[P] };
 
 Examples of **incorrect** code for the `{ "allowMappedTypes": "in-unions-and-intersections" }` option:
 
-```ts
+```ts option='{ "allowMappedTypes": "in-unions-and-intersections" }' showPlaygroundButton
 type Foo<T> = { readonly [P in keyof T]: T[P] };
 
 type Foo<T> = { [P in keyof T]?: T[P] };
@@ -495,7 +505,7 @@ type Foo<T> = { [P in keyof T]?: T[P] };
 
 Examples of **correct** code for the `{ "allowMappedTypes": "in-unions-and-intersections" }` option:
 
-```ts
+```ts option='{ "allowMappedTypes": "in-unions-and-intersections" }' showPlaygroundButton
 type Foo<T, U> =
   | { readonly [P in keyof T]: T[P] }
   | { readonly [P in keyof U]: U[P] };
@@ -522,7 +532,7 @@ The setting accepts the following options:
 
 Examples of **correct** code for the `{ "allowTupleTypes": "always" }` options:
 
-```ts
+```ts option='{ "allowTupleTypes": "always" }' showPlaygroundButton
 type Foo = [number];
 
 type Foo = [number] | [number, number];
@@ -534,7 +544,7 @@ type Foo = [number] | ([number, number] & [string, string]);
 
 Examples of **incorrect** code for the `{ "allowTupleTypes": "in-unions" }` option:
 
-```ts
+```ts option='{ "allowTupleTypes": "in-unions" }' showPlaygroundButton
 type Foo = [number];
 
 type Foo = [number] & [number, number];
@@ -544,7 +554,7 @@ type Foo = [string] & [number];
 
 Examples of **correct** code for the `{ "allowTupleTypes": "in-unions" }` option:
 
-```ts
+```ts option='{ "allowTupleTypes": "in-unions" }' showPlaygroundButton
 type Foo = [number] | [number, number];
 
 type Foo = [string] | [number];
@@ -552,7 +562,7 @@ type Foo = [string] | [number];
 
 Examples of **incorrect** code for the `{ "allowTupleTypes": "in-intersections" }` option:
 
-```ts
+```ts option='{ "allowTupleTypes": "in-intersections" }' showPlaygroundButton
 type Foo = [number];
 
 type Foo = [number] | [number, number];
@@ -562,7 +572,7 @@ type Foo = [string] | [number];
 
 Examples of **correct** code for the `{ "allowTupleTypes": "in-intersections" }` option:
 
-```ts
+```ts option='{ "allowTupleTypes": "in-intersections" }' showPlaygroundButton
 type Foo = [number] & [number, number];
 
 type Foo = [string] & [number];
@@ -570,15 +580,15 @@ type Foo = [string] & [number];
 
 Examples of **incorrect** code for the `{ "allowTupleTypes": "in-unions-and-intersections" }` option:
 
-```ts
+```ts option='{ "allowTupleTypes": "in-unions-and-intersections" }' showPlaygroundButton
 type Foo = [number];
 
 type Foo = [string];
 ```
 
-Examples of **correct** code for the `{ "allowLiterals": "in-unions-and-intersections" }` option:
+Examples of **correct** code for the `{ "allowTupleTypes": "in-unions-and-intersections" }` option:
 
-```ts
+```ts option='{ "allowTupleTypes": "in-unions-and-intersections" }' showPlaygroundButton
 type Foo = [number] & [number, number];
 
 type Foo = [string] | [number];
@@ -594,7 +604,7 @@ The setting accepts the following options:
 
 Examples of **correct** code for the `{ "allowGenerics": "always" }` options:
 
-```ts
+```ts option='{ "allowGenerics": "always" }' showPlaygroundButton
 type Foo = Bar<string>;
 
 type Foo = Record<string, number>;
@@ -606,10 +616,7 @@ type Foo = Partial<Bar>;
 type Foo = Omit<Bar, 'a' | 'b'>;
 ```
 
-## When Not To Use It
-
-When you can't express some shape with an interface or you need to use a union, tuple type,
-callback, etc. that would cause the code to be unreadable or impractical.
+<!-- Intentionally Omitted: When Not To Use It -->
 
 ## Further Reading