diff --git a/packages/eslint-plugin/docs/rules/ban-ts-ignore.md b/packages/eslint-plugin/docs/rules/ban-ts-ignore.md index 8f69c864669..936d7936afc 100644 --- a/packages/eslint-plugin/docs/rules/ban-ts-ignore.md +++ b/packages/eslint-plugin/docs/rules/ban-ts-ignore.md @@ -4,6 +4,11 @@ This rule has been deprecated in favor of [`ban-ts-comment`](./ban-ts-comment.md Suppressing TypeScript Compiler Errors can be hard to discover. +## DEPRECATED + +This rule has been deprecated in favour of the [`ban-ts-comment`](./ban-ts-comment.md) rule. +It will be removed in a future version of this plugin. + ## Rule Details Does not allow the use of `// @ts-ignore` comments. diff --git a/packages/eslint-plugin/docs/rules/brace-style.md b/packages/eslint-plugin/docs/rules/brace-style.md index c8268dea44e..06dfa1619fb 100644 --- a/packages/eslint-plugin/docs/rules/brace-style.md +++ b/packages/eslint-plugin/docs/rules/brace-style.md @@ -3,11 +3,11 @@ ## Rule Details This rule extends the base [`eslint/brace-style`](https://eslint.org/docs/rules/brace-style) rule. -It supports all options and features of the base rule. +It adds support for `enum`, `interface`, `namespace` and `module` declarations. ## How to use -```cjson +```jsonc { // note you must disable the base rule as it can report incorrect errors "brace-style": "off", diff --git a/packages/eslint-plugin/docs/rules/camelcase.md b/packages/eslint-plugin/docs/rules/camelcase.md index f0b49d0420f..89cd63aa929 100644 --- a/packages/eslint-plugin/docs/rules/camelcase.md +++ b/packages/eslint-plugin/docs/rules/camelcase.md @@ -1,135 +1,43 @@ # Enforce camelCase naming convention (`camelcase`) -When it comes to naming variables, style guides generally fall into one of two -camps: camelCase (`variableName`) and underscores (`variable_name`). This rule -focuses on using the camelCase approach. If your style guide calls for -camelCasing your variable names, then this rule is for you! +## DEPRECATED -## Rule Details +This rule has been deprecated in favour of the [`naming-convention`](./naming-convention.md) rule. +It will be removed in a future version of this plugin. -This rule looks for any underscores (`_`) located within the source code. -It ignores leading and trailing underscores and only checks those in the middle -of a variable name. If ESLint decides that the variable is a constant -(all uppercase), then no warning will be thrown. Otherwise, a warning will be -thrown. This rule only flags definitions and assignments but not function calls. -In case of ES6 `import` statements, this rule only targets the name of the -variable that will be imported into the local module scope. +## Rule Details -**_This rule was taken from the ESLint core rule `camelcase`._** -**_Available options and test cases may vary depending on the version of ESLint installed in the system._** +This rule extends the base [`eslint/camelcase`](https://eslint.org/docs/rules/camelcase) rule. +It adds support for numerous TypeScript features. -## Options +## How to use -```cjson +```jsonc { - // note you must disable the base rule as it can report incorrect errors - "camelcase": "off", - "@typescript-eslint/camelcase": ["error", { "properties": "always" }] + // note you must disable the base rule as it can report incorrect errors + "camelcase": "off", + "@typescript-eslint/camelcase": ["error"] } ``` -This rule has an object option: - -- `"properties": "never"` (default) does not check property names -- `"properties": "always"` enforces camelCase style for property names -- `"genericType": "never"` (default) does not check generic identifiers -- `"genericType": "always"` enforces camelCase style for generic identifiers -- `"ignoreDestructuring": false` (default) enforces camelCase style for destructured identifiers -- `"ignoreDestructuring": true` does not check destructured identifiers -- `allow` (`string[]`) list of properties to accept. Accept regex. - -### properties: "always" - -Examples of **incorrect** code for this rule with the default `{ "properties": "always" }` option: - -```js -/*eslint @typescript-eslint/camelcase: "error"*/ - -import { no_camelcased } from 'external-module'; - -var my_favorite_color = '#112C85'; - -function do_something() { - // ... -} - -obj.do_something = function() { - // ... -}; +## Options -function foo({ no_camelcased }) { - // ... -} +See [`eslint/camelcase` options](https://eslint.org/docs/rules/camelcase#options). +This rule adds the following options: -function foo({ isCamelcased: no_camelcased }) { - // ... +```ts +interface Options extends BaseCamelcaseOptions { + genericType?: 'always' | 'never'; } -function foo({ no_camelcased = 'default value' }) { - // ... -} - -var obj = { - my_pref: 1, +const defaultOptions: Options = { + ...baseCamelcaseDefaultOptions, + genericType: 'never', }; - -var { category_id = 1 } = query; - -var { foo: no_camelcased } = bar; - -var { foo: bar_baz = 1 } = quz; -``` - -Examples of **correct** code for this rule with the default `{ "properties": "always" }` option: - -```js -/*eslint @typescript-eslint/camelcase: "error"*/ - -import { no_camelcased as camelCased } from 'external-module'; - -var myFavoriteColor = '#112C85'; -var _myFavoriteColor = '#112C85'; -var myFavoriteColor_ = '#112C85'; -var MY_FAVORITE_COLOR = '#112C85'; -var foo = bar.baz_boom; -var foo = { qux: bar.baz_boom }; - -obj.do_something(); -do_something(); -new do_something(); - -var { category_id: category } = query; - -function foo({ isCamelCased }) { - // ... -} - -function foo({ isCamelCased: isAlsoCamelCased }) { - // ... -} - -function foo({ isCamelCased = 'default value' }) { - // ... -} - -var { categoryId = 1 } = query; - -var { foo: isCamelCased } = bar; - -var { foo: isCamelCased = 1 } = quz; ``` -### `properties: "never"` - -Examples of **correct** code for this rule with the `{ "properties": "never" }` option: - -```js -/*eslint @typescript-eslint/camelcase: ["error", {properties: "never"}]*/ - -var obj = { - my_pref: 1, -}; -``` +- `"genericType": "never"` (default) does not check generic identifiers +- `"genericType": "always"` enforces camelCase style for generic identifiers ### `genericType: "always"` @@ -225,74 +133,4 @@ class Foo { } ``` -### `ignoreDestructuring: false` - -Examples of **incorrect** code for this rule with the default `{ "ignoreDestructuring": false }` option: - -```js -/*eslint @typescript-eslint/camelcase: "error"*/ - -var { category_id } = query; - -var { category_id = 1 } = query; - -var { category_id: category_id } = query; - -var { category_id: category_alias } = query; - -var { category_id: categoryId, ...other_props } = query; -``` - -### `ignoreDestructuring: true` - -Examples of **incorrect** code for this rule with the `{ "ignoreDestructuring": true }` option: - -```js -/*eslint @typescript-eslint/camelcase: ["error", {ignoreDestructuring: true}]*/ - -var { category_id: category_alias } = query; - -var { category_id, ...other_props } = query; -``` - -Examples of **correct** code for this rule with the `{ "ignoreDestructuring": true }` option: - -```js -/*eslint @typescript-eslint/camelcase: ["error", {ignoreDestructuring: true}]*/ - -var { category_id } = query; - -var { category_id = 1 } = query; - -var { category_id: category_id } = query; -``` - -## allow - -Examples of **correct** code for this rule with the `allow` option: - -```js -/*eslint @typescript-eslint/camelcase: ["error", {allow: ["UNSAFE_componentWillMount"]}]*/ - -function UNSAFE_componentWillMount() { - // ... -} -``` - -```js -/*eslint @typescript-eslint/camelcase: ["error", {allow: ["^UNSAFE_"]}]*/ - -function UNSAFE_componentWillMount() { - // ... -} - -function UNSAFE_componentWillMount() { - // ... -} -``` - -## When Not To Use It - -If you have established coding standards using a different naming convention (separating words with underscores), turn this rule off. - Taken with ❤️ [from ESLint core](https://github.com/eslint/eslint/blob/master/docs/rules/camelcase.md) diff --git a/packages/eslint-plugin/docs/rules/class-name-casing.md b/packages/eslint-plugin/docs/rules/class-name-casing.md index 38c30609747..ae5d5da7a2e 100644 --- a/packages/eslint-plugin/docs/rules/class-name-casing.md +++ b/packages/eslint-plugin/docs/rules/class-name-casing.md @@ -2,6 +2,11 @@ This rule enforces PascalCase names for classes and interfaces. +## DEPRECATED + +This rule has been deprecated in favour of the [`naming-convention`](./naming-convention.md) rule. +It will be removed in a future version of this plugin. + ## Rule Details This rule aims to make it easy to differentiate classes from regular variables at a glance. diff --git a/packages/eslint-plugin/docs/rules/comma-spacing.md b/packages/eslint-plugin/docs/rules/comma-spacing.md index 145e3607726..0920180416a 100644 --- a/packages/eslint-plugin/docs/rules/comma-spacing.md +++ b/packages/eslint-plugin/docs/rules/comma-spacing.md @@ -7,7 +7,7 @@ It adds support for trailing comma in a types parameters list. ## How to use -```cjson +```jsonc { // note you must disable the base rule as it can report incorrect errors "comma-spacing": "off", diff --git a/packages/eslint-plugin/docs/rules/default-param-last.md b/packages/eslint-plugin/docs/rules/default-param-last.md index f3eb9f27b9a..c9c51df40a3 100644 --- a/packages/eslint-plugin/docs/rules/default-param-last.md +++ b/packages/eslint-plugin/docs/rules/default-param-last.md @@ -2,7 +2,8 @@ ## Rule Details -This rule enforces default or optional parameters to be the last of parameters. +This rule extends the base [`eslint/default-param-last`](https://eslint.org/docs/rules/default-param-last) rule. +It adds support for optional parameters. Examples of **incorrect** code for this rule: @@ -38,4 +39,18 @@ class Foo { } ``` +## How to use + +```jsonc +{ + // note you must disable the base rule as it can report incorrect errors + "default-param-last": "off", + "@typescript-eslint/default-param-last": ["error"] +} +``` + +## Options + +See [`eslint/default-param-last` options](https://eslint.org/docs/rules/default-param-last#options). + Taken with ❤️ [from ESLint core](https://github.com/eslint/eslint/blob/master/docs/rules/default-param-last.md) diff --git a/packages/eslint-plugin/docs/rules/func-call-spacing.md b/packages/eslint-plugin/docs/rules/func-call-spacing.md index aa1d3fde96a..8aa9e7e0cbf 100644 --- a/packages/eslint-plugin/docs/rules/func-call-spacing.md +++ b/packages/eslint-plugin/docs/rules/func-call-spacing.md @@ -1,17 +1,13 @@ # Require or disallow spacing between function identifiers and their invocations (`func-call-spacing`) -When calling a function, developers may insert optional whitespace between the function’s name and the parentheses that invoke it. -This rule requires or disallows spaces between the function name and the opening parenthesis that calls it. - ## Rule Details This rule extends the base [`eslint/func-call-spacing`](https://eslint.org/docs/rules/func-call-spacing) rule. -It supports all options and features of the base rule. -This version adds support for generic type parameters on function calls. +It adds support for generic type parameters on function calls. ## How to use -```cjson +```jsonc { // note you must disable the base rule as it can report incorrect errors "func-call-spacing": "off", diff --git a/packages/eslint-plugin/docs/rules/generic-type-naming.md b/packages/eslint-plugin/docs/rules/generic-type-naming.md index 185b3811d9a..dc964273535 100644 --- a/packages/eslint-plugin/docs/rules/generic-type-naming.md +++ b/packages/eslint-plugin/docs/rules/generic-type-naming.md @@ -3,6 +3,11 @@ It can be helpful to enforce a consistent naming style for generic type variables used within a type. For example, prefixing them with `T` and ensuring a somewhat descriptive name, or enforcing Hungarian notation. +## DEPRECATED + +This rule has been deprecated in favour of the [`naming-convention`](./naming-convention.md) rule. +It will be removed in a future version of this plugin. + ## Rule Details This rule allows you to enforce conventions over type variables. By default, it does nothing. @@ -13,7 +18,7 @@ The rule takes a single string option, which is a regular expression that type v Examples of **correct** code with a configuration of `'^T[A-Z][a-zA-Z]+$'`: -```typescript +```ts type ReadOnly = { readonly [TKey in keyof TType]: TType[TKey]; }; @@ -25,7 +30,7 @@ interface SimpleMap { Examples of **incorrect** code with a configuration of `'^T[A-Z][a-zA-Z]+$'`: -```typescript +```ts type ReadOnly = { readonly [Key in keyof T]: T[Key] }; interface SimpleMap { diff --git a/packages/eslint-plugin/docs/rules/indent.md b/packages/eslint-plugin/docs/rules/indent.md index 4636cfeaeb5..023c774657a 100644 --- a/packages/eslint-plugin/docs/rules/indent.md +++ b/packages/eslint-plugin/docs/rules/indent.md @@ -1,713 +1,24 @@ # Enforce consistent indentation (`indent`) -There are several common guidelines which require specific indentation of nested blocks and statements, like: - -```js -function hello(indentSize, type) { - if (indentSize === 4 && type !== 'tab') { - console.log('Each next indentation will increase on 4 spaces'); - } -} -``` - -These are the most common scenarios recommended in different style guides: - -- Two spaces, not longer and no tabs: Google, npm, NodeJS, Idiomatic, Felix -- Tabs: jQuery -- Four spaces: Crockford +## PLEASE READ THIS ISSUE BEFORE USING THIS RULE [#1824](https://github.com/typescript-eslint/typescript-eslint/issues/1824) ## Rule Details -This rule enforces a consistent indentation style. The default style is `4 spaces`. - -## Options - -This rule has a mixed option: +This rule extends the base [`eslint/indent`](https://eslint.org/docs/rules/indent) rule. +It adds support for TypeScript nodes. -For example, for 2-space indentation: +## How to use -```cjson +```jsonc { - // note you must disable the base rule as it can report incorrect errors - "indent": "off", - "@typescript-eslint/indent": ["error", 2] + // note you must disable the base rule as it can report incorrect errors + "indent": "off", + "@typescript-eslint/indent": ["error"] } ``` -Or for tabbed indentation: - -```cjson -{ - // note you must disable the base rule as it can report incorrect errors - "indent": "off", - "@typescript-eslint/indent": ["error", "tab"] -} -``` - -Examples of **incorrect** code for this rule with the default options: - - -```js -/*eslint @typescript-eslint/indent: "error"*/ - -if (a) { - b=c; - function foo(d) { - e=f; - } -} -``` - -Examples of **correct** code for this rule with the default options: - - -```js -/*eslint @typescript-eslint/indent: "error"*/ - -if (a) { - b=c; - function foo(d) { - e=f; - } -} -``` - -This rule has an object option: - -- `"SwitchCase"` (default: 0) enforces indentation level for `case` clauses in `switch` statements -- `"VariableDeclarator"` (default: 1) enforces indentation level for `var` declarators; can also take an object to define separate rules for `var`, `let` and `const` declarations. -- `"outerIIFEBody"` (default: 1) enforces indentation level for file-level IIFEs. -- `"MemberExpression"` (default: 1) enforces indentation level for multi-line property chains. This can also be set to `"off"` to disable checking for `MemberExpression` indentation. -- `"FunctionDeclaration"` takes an object to define rules for function declarations. - - `parameters` (default: 1) enforces indentation level for parameters in a function declaration. This can either be a number indicating indentation level, or the string `"first"` indicating that all parameters of the declaration must be aligned with the first parameter. This can also be set to `"off"` to disable checking for `FunctionDeclaration` parameters. - - `body` (default: 1) enforces indentation level for the body of a function declaration. -- `"FunctionExpression"` takes an object to define rules for function expressions. - - `parameters` (default: 1) enforces indentation level for parameters in a function expression. This can either be a number indicating indentation level, or the string `"first"` indicating that all parameters of the expression must be aligned with the first parameter. This can also be set to `"off"` to disable checking for `FunctionExpression` parameters. - - `body` (default: 1) enforces indentation level for the body of a function expression. -- `"CallExpression"` takes an object to define rules for function call expressions. - - `arguments` (default: 1) enforces indentation level for arguments in a call expression. This can either be a number indicating indentation level, or the string `"first"` indicating that all arguments of the expression must be aligned with the first argument. This can also be set to `"off"` to disable checking for `CallExpression` arguments. -- `"ArrayExpression"` (default: 1) enforces indentation level for elements in arrays. It can also be set to the string `"first"`, indicating that all the elements in the array should be aligned with the first element. This can also be set to `"off"` to disable checking for array elements. -- `"ObjectExpression"` (default: 1) enforces indentation level for properties in objects. It can be set to the string `"first"`, indicating that all properties in the object should be aligned with the first property. This can also be set to `"off"` to disable checking for object properties. -- `"ImportDeclaration"` (default: 1) enforces indentation level for import statements. It can be set to the string `"first"`, indicating that all imported members from a module should be aligned with the first member in the list. This can also be set to `"off"` to disable checking for imported module members. -- `"flatTernaryExpressions": true` (`false` by default) requires no indentation for ternary expressions which are nested in other ternary expressions. -- `"ignoredNodes"` accepts an array of [selectors](https://eslint.org/docs/developer-guide/selectors). If an AST node is matched by any of the selectors, the indentation of tokens which are direct children of that node will be ignored. This can be used as an escape hatch to relax the rule if you disagree with the indentation that it enforces for a particular syntactic pattern. -- `"ignoreComments"` (default: false) can be used when comments do not need to be aligned with nodes on the previous or next line. - -Level of indentation denotes the multiple of the indent specified. Example: - -- Indent of 4 spaces with `VariableDeclarator` set to `2` will indent the multi-line variable declarations with 8 spaces. -- Indent of 2 spaces with `VariableDeclarator` set to `2` will indent the multi-line variable declarations with 4 spaces. -- Indent of 2 spaces with `VariableDeclarator` set to `{"var": 2, "let": 2, "const": 3}` will indent the multi-line variable declarations with 4 spaces for `var` and `let`, 6 spaces for `const` statements. -- Indent of tab with `VariableDeclarator` set to `2` will indent the multi-line variable declarations with 2 tabs. -- Indent of 2 spaces with `SwitchCase` set to `0` will not indent `case` clauses with respect to `switch` statements. -- Indent of 2 spaces with `SwitchCase` set to `1` will indent `case` clauses with 2 spaces with respect to `switch` statements. -- Indent of 2 spaces with `SwitchCase` set to `2` will indent `case` clauses with 4 spaces with respect to `switch` statements. -- Indent of tab with `SwitchCase` set to `2` will indent `case` clauses with 2 tabs with respect to `switch` statements. -- Indent of 2 spaces with `MemberExpression` set to `0` will indent the multi-line property chains with 0 spaces. -- Indent of 2 spaces with `MemberExpression` set to `1` will indent the multi-line property chains with 2 spaces. -- Indent of 2 spaces with `MemberExpression` set to `2` will indent the multi-line property chains with 4 spaces. -- Indent of 4 spaces with `MemberExpression` set to `0` will indent the multi-line property chains with 0 spaces. -- Indent of 4 spaces with `MemberExpression` set to `1` will indent the multi-line property chains with 4 spaces. -- Indent of 4 spaces with `MemberExpression` set to `2` will indent the multi-line property chains with 8 spaces. - -### tab - -Examples of **incorrect** code for this rule with the `"tab"` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", "tab"]*/ - -if (a) { - b=c; -function foo(d) { - e=f; - } -} -``` - -Examples of **correct** code for this rule with the `"tab"` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", "tab"]*/ - -if (a) { -/*tab*/b=c; -/*tab*/function foo(d) { -/*tab*//*tab*/e=f; -/*tab*/} -} -``` - -### `SwitchCase` - -Examples of **incorrect** code for this rule with the `2, { "SwitchCase": 1 }` options: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, { "SwitchCase": 1 }]*/ - -switch(a){ -case "a": - break; -case "b": - break; -} -``` - -Examples of **correct** code for this rule with the `2, { "SwitchCase": 1 }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, { "SwitchCase": 1 }]*/ - -switch(a){ - case "a": - break; - case "b": - break; -} -``` - -### `VariableDeclarator` - -Examples of **incorrect** code for this rule with the `2, { "VariableDeclarator": 1 }` options: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, { "VariableDeclarator": 1 }]*/ -/*eslint-env es6*/ - -var a, - b, - c; -let a, - b, - c; -const a = 1, - b = 2, - c = 3; -``` - -Examples of **correct** code for this rule with the `2, { "VariableDeclarator": 1 }` options: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, { "VariableDeclarator": 1 }]*/ -/*eslint-env es6*/ - -var a, - b, - c; -let a, - b, - c; -const a = 1, - b = 2, - c = 3; -``` - -Examples of **correct** code for this rule with the `2, { "VariableDeclarator": 2 }` options: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, { "VariableDeclarator": 2 }]*/ -/*eslint-env es6*/ - -var a, - b, - c; -let a, - b, - c; -const a = 1, - b = 2, - c = 3; -``` - -Examples of **correct** code for this rule with the `2, { "VariableDeclarator": { "var": 2, "let": 2, "const": 3 } }` options: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, { "VariableDeclarator": { "var": 2, "let": 2, "const": 3 } }]*/ -/*eslint-env es6*/ - -var a, - b, - c; -let a, - b, - c; -const a = 1, - b = 2, - c = 3; -``` - -### `outerIIFEBody` - -Examples of **incorrect** code for this rule with the options `2, { "outerIIFEBody": 0 }`: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, { "outerIIFEBody": 0 }]*/ - -(function() { - - function foo(x) { - return x + 1; - } - -})(); - - -if(y) { -console.log('foo'); -} -``` - -Examples of **correct** code for this rule with the options `2, {"outerIIFEBody": 0}`: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, { "outerIIFEBody": 0 }]*/ - -(function() { - -function foo(x) { - return x + 1; -} - -})(); - - -if(y) { - console.log('foo'); -} -``` - -### `MemberExpression` - -Examples of **incorrect** code for this rule with the `2, { "MemberExpression": 1 }` options: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, { "MemberExpression": 1 }]*/ - -foo -.bar -.baz() -``` - -Examples of **correct** code for this rule with the `2, { "MemberExpression": 1 }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, { "MemberExpression": 1 }]*/ - -foo - .bar - .baz(); -``` - -### `FunctionDeclaration` - -Examples of **incorrect** code for this rule with the `2, { "FunctionDeclaration": {"body": 1, "parameters": 2} }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, { "FunctionDeclaration": {"body": 1, "parameters": 2} }]*/ - -function foo(bar, - baz, - qux) { - qux(); -} -``` - -Examples of **correct** code for this rule with the `2, { "FunctionDeclaration": {"body": 1, "parameters": 2} }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, { "FunctionDeclaration": {"body": 1, "parameters": 2} }]*/ - -function foo(bar, - baz, - qux) { - qux(); -} -``` - -Examples of **incorrect** code for this rule with the `2, { "FunctionDeclaration": {"parameters": "first"} }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, {"FunctionDeclaration": {"parameters": "first"}}]*/ - -function foo(bar, baz, - qux, boop) { - qux(); -} -``` - -Examples of **correct** code for this rule with the `2, { "FunctionDeclaration": {"parameters": "first"} }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, {"FunctionDeclaration": {"parameters": "first"}}]*/ - -function foo(bar, baz, - qux, boop) { - qux(); -} -``` - -### `FunctionExpression` - -Examples of **incorrect** code for this rule with the `2, { "FunctionExpression": {"body": 1, "parameters": 2} }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, { "FunctionExpression": {"body": 1, "parameters": 2} }]*/ - -var foo = function(bar, - baz, - qux) { - qux(); -} -``` - -Examples of **correct** code for this rule with the `2, { "FunctionExpression": {"body": 1, "parameters": 2} }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, { "FunctionExpression": {"body": 1, "parameters": 2} }]*/ - -var foo = function(bar, - baz, - qux) { - qux(); -} -``` - -Examples of **incorrect** code for this rule with the `2, { "FunctionExpression": {"parameters": "first"} }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, {"FunctionExpression": {"parameters": "first"}}]*/ - -var foo = function(bar, baz, - qux, boop) { - qux(); -} -``` - -Examples of **correct** code for this rule with the `2, { "FunctionExpression": {"parameters": "first"} }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, {"FunctionExpression": {"parameters": "first"}}]*/ - -var foo = function(bar, baz, - qux, boop) { - qux(); -} -``` - -### `CallExpression` - -Examples of **incorrect** code for this rule with the `2, { "CallExpression": {"arguments": 1} }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, { "CallExpression": {"arguments": 1} }]*/ - -foo(bar, - baz, - qux -); -``` - -Examples of **correct** code for this rule with the `2, { "CallExpression": {"arguments": 1} }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, { "CallExpression": {"arguments": 1} }]*/ - -foo(bar, - baz, - qux -); -``` - -Examples of **incorrect** code for this rule with the `2, { "CallExpression": {"arguments": "first"} }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, {"CallExpression": {"arguments": "first"}}]*/ - -foo(bar, baz, - baz, boop, beep); -``` - -Examples of **correct** code for this rule with the `2, { "CallExpression": {"arguments": "first"} }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, {"CallExpression": {"arguments": "first"}}]*/ - -foo(bar, baz, - baz, boop, beep); -``` - -### `ArrayExpression` - -Examples of **incorrect** code for this rule with the `2, { "ArrayExpression": 1 }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, { "ArrayExpression": 1 }]*/ - -var foo = [ - bar, -baz, - qux -]; -``` - -Examples of **correct** code for this rule with the `2, { "ArrayExpression": 1 }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, { "ArrayExpression": 1 }]*/ - -var foo = [ - bar, - baz, - qux -]; -``` - -Examples of **incorrect** code for this rule with the `2, { "ArrayExpression": "first" }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, {"ArrayExpression": "first"}]*/ - -var foo = [bar, - baz, - qux -]; -``` - -Examples of **correct** code for this rule with the `2, { "ArrayExpression": "first" }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, {"ArrayExpression": "first"}]*/ - -var foo = [bar, - baz, - qux -]; -``` - -### `ObjectExpression` - -Examples of **incorrect** code for this rule with the `2, { "ObjectExpression": 1 }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, { "ObjectExpression": 1 }]*/ - -var foo = { - bar: 1, -baz: 2, - qux: 3 -}; -``` - -Examples of **correct** code for this rule with the `2, { "ObjectExpression": 1 }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, { "ObjectExpression": 1 }]*/ - -var foo = { - bar: 1, - baz: 2, - qux: 3 -}; -``` - -Examples of **incorrect** code for this rule with the `2, { "ObjectExpression": "first" }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, {"ObjectExpression": "first"}]*/ - -var foo = { bar: 1, - baz: 2 }; -``` - -Examples of **correct** code for this rule with the `2, { "ObjectExpression": "first" }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 2, {"ObjectExpression": "first"}]*/ - -var foo = { bar: 1, - baz: 2 }; -``` - -### `ImportDeclaration` - -Examples of **correct** code for this rule with the `4, { "ImportDeclaration": 1 }` option (the default): - - -```js -/*eslint @typescript-eslint/indent: ["error", 4, { ImportDeclaration: 1 }]*/ - -import { foo, - bar, - baz, -} from 'qux'; - -import { - foo, - bar, - baz, -} from 'qux'; -``` - -Examples of **incorrect** code for this rule with the `4, { ImportDeclaration: "first" }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 4, { ImportDeclaration: "first" }]*/ - -import { foo, - bar, - baz, -} from 'qux'; -``` - -Examples of **correct** code for this rule with the `4, { ImportDeclaration: "first" }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 4, { ImportDeclaration: "first" }]*/ - -import { foo, - bar, - baz, -} from 'qux'; -``` - -### `flatTernaryExpressions` - -Examples of **incorrect** code for this rule with the default `4, { "flatTernaryExpressions": false }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 4, { "flatTernaryExpressions": false }]*/ - -var a = - foo ? bar : - baz ? qux : - boop; -``` - -Examples of **correct** code for this rule with the default `4, { "flatTernaryExpressions": false }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 4, { "flatTernaryExpressions": false }]*/ - -var a = - foo ? bar : - baz ? qux : - boop; -``` - -Examples of **incorrect** code for this rule with the `4, { "flatTernaryExpressions": true }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 4, { "flatTernaryExpressions": true }]*/ - -var a = - foo ? bar : - baz ? qux : - boop; -``` - -Examples of **correct** code for this rule with the `4, { "flatTernaryExpressions": true }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 4, { "flatTernaryExpressions": true }]*/ - -var a = - foo ? bar : - baz ? qux : - boop; -``` - -### `ignoredNodes` - -The following configuration ignores the indentation of `ConditionalExpression` ("ternary expression") nodes: - -Examples of **correct** code for this rule with the `4, { "ignoredNodes": ["ConditionalExpression"] }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 4, { "ignoredNodes": ["ConditionalExpression"] }]*/ - -var a = foo - ? bar - : baz; - -var a = foo - ? bar -: baz; -``` - -The following configuration ignores indentation in the body of IIFEs. - -Examples of **correct** code for this rule with the `4, { "ignoredNodes": ["CallExpression > FunctionExpression.callee > BlockStatement.body"] }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 4, { "ignoredNodes": ["CallExpression > FunctionExpression.callee > BlockStatement.body"] }]*/ - -(function() { - -foo(); -bar(); - -}) -``` - -### `ignoreComments` - -Examples of additional **correct** code for this rule with the `4, { "ignoreComments": true }` option: - - -```js -/*eslint @typescript-eslint/indent: ["error", 4, { "ignoreComments": true }] */ - -if (foo) { - doSomething(); - -// comment intentionally de-indented - doSomethingElse(); -} -``` - -## Compatibility +## Options -- **JSHint**: `indent` -- **JSCS**: [`validateIndentation`](https://jscs-dev.github.io/rule/validateIndentation) +See [`eslint/indent` options](https://eslint.org/docs/rules/indent#options). Taken with ❤️ [from ESLint core](https://github.com/eslint/eslint/blob/master/docs/rules/indent.md) diff --git a/packages/eslint-plugin/docs/rules/interface-name-prefix.md b/packages/eslint-plugin/docs/rules/interface-name-prefix.md index f6439b490fd..6322c9c79d6 100644 --- a/packages/eslint-plugin/docs/rules/interface-name-prefix.md +++ b/packages/eslint-plugin/docs/rules/interface-name-prefix.md @@ -5,6 +5,11 @@ The unprefixed name is then available for a class that provides a standard imple Alternatively, the contributor guidelines for the TypeScript repo suggest [never prefixing](https://github.com/Microsoft/TypeScript/wiki/Coding-guidelines#names) interfaces with `I`. +## DEPRECATED + +This rule has been deprecated in favour of the [`naming-convention`](./naming-convention.md) rule. +It will be removed in a future version of this plugin. + ## Rule Details This rule enforces whether or not the `I` prefix is required for interface names. diff --git a/packages/eslint-plugin/docs/rules/member-naming.md b/packages/eslint-plugin/docs/rules/member-naming.md index e12f4f239b5..0dd8a5a2f29 100644 --- a/packages/eslint-plugin/docs/rules/member-naming.md +++ b/packages/eslint-plugin/docs/rules/member-naming.md @@ -2,6 +2,11 @@ It can be helpful to enforce naming conventions for `private` (and sometimes `protected`) members of an object. For example, prefixing private properties with a `_` allows them to be easily discerned when being inspected by tools that do not have knowledge of TypeScript (such as most debuggers). +## DEPRECATED + +This rule has been deprecated in favour of the [`naming-convention`](./naming-convention.md) rule. +It will be removed in a future version of this plugin. + ## Rule Details This rule allows you to enforce conventions for class property and method names by their visibility. By default, it enforces nothing. diff --git a/packages/eslint-plugin/docs/rules/member-ordering.md b/packages/eslint-plugin/docs/rules/member-ordering.md index cccf2bbbe0a..9a2a4cdee8f 100644 --- a/packages/eslint-plugin/docs/rules/member-ordering.md +++ b/packages/eslint-plugin/docs/rules/member-ordering.md @@ -53,37 +53,37 @@ Note: There is a deprecated syntax to specify the member types as an array. There are multiple ways to specify the member types. The most explicit and granular form is the following: -```json5 +```jsonc [ // Index signature - 'signature', + "signature", // Fields - 'public-static-field', - 'protected-static-field', - 'private-static-field', - 'public-instance-field', - 'protected-instance-field', - 'private-instance-field', - 'public-abstract-field', - 'protected-abstract-field', - 'private-abstract-field', + "public-static-field", + "protected-static-field", + "private-static-field", + "public-instance-field", + "protected-instance-field", + "private-instance-field", + "public-abstract-field", + "protected-abstract-field", + "private-abstract-field", // Constructors - 'public-constructor', - 'protected-constructor', - 'private-constructor', + "public-constructor", + "protected-constructor", + "private-constructor", // Methods - 'public-static-method', - 'protected-static-method', - 'private-static-method', - 'public-instance-method', - 'protected-instance-method', - 'private-instance-method', - 'public-abstract-method', - 'protected-abstract-method', - 'private-abstract-method', + "public-static-method", + "protected-static-method", + "private-static-method", + "public-instance-method", + "protected-instance-method", + "private-instance-method", + "public-abstract-method", + "protected-abstract-method", + "private-abstract-method" ] ``` @@ -93,23 +93,23 @@ Note: If you only specify some of the possible types, the non-specified ones can It is also possible to group member types by their accessibility (`static`, `instance`, `abstract`), ignoring their scope. -```json5 +```jsonc [ // Index signature // No accessibility for index signature. See above. // Fields - 'public-field', // = ['public-static-field', 'public-instance-field']) - 'protected-field', // = ['protected-static-field', 'protected-instance-field']) - 'private-field', // = ['private-static-field', 'private-instance-field']) + "public-field", // = ["public-static-field", "public-instance-field"]) + "protected-field", // = ["protected-static-field", "protected-instance-field"]) + "private-field", // = ["private-static-field", "private-instance-field"]) // Constructors // Only the accessibility of constructors is configurable. See below. // Methods - 'public-method', // = ['public-static-method', 'public-instance-method']) - 'protected-method', // = ['protected-static-method', 'protected-instance-method']) - 'private-method', // = ['private-static-method', 'private-instance-method']) + "public-method", // = ["public-static-method", "public-instance-method"]) + "protected-method", // = ["protected-static-method", "protected-instance-method"]) + "private-method" // = ["private-static-method", "private-instance-method"]) ] ``` @@ -117,23 +117,23 @@ It is also possible to group member types by their accessibility (`static`, `ins Another option is to group the member types by their scope (`public`, `protected`, `private`), ignoring their accessibility. -```json5 +```jsonc [ // Index signature // No scope for index signature. See above. // Fields - 'static-field', // = ['public-static-field', 'protected-static-field', 'private-static-field']) - 'instance-field', // = ['public-instance-field', 'protected-instance-field', 'private-instance-field']) - 'abstract-field', // = ['public-abstract-field', 'protected-abstract-field', 'private-abstract-field']) + "static-field", // = ["public-static-field", "protected-static-field", "private-static-field"]) + "instance-field", // = ["public-instance-field", "protected-instance-field", "private-instance-field"]) + "abstract-field", // = ["public-abstract-field", "protected-abstract-field", "private-abstract-field"]) // Constructors - 'constructor', // = ['public-constructor', 'protected-constructor', 'private-constructor']) + "constructor", // = ["public-constructor", "protected-constructor", "private-constructor"]) // Methods - 'static-method', // = ['public-static-method', 'protected-static-method', 'private-static-method']) - 'instance-method', // = ['public-instance-method', 'protected-instance-method', 'private-instance-method']) - 'abstract-method', // = ['public-abstract-method', 'protected-abstract-method', 'private-abstract-method']) + "static-method", // = ["public-static-method", "protected-static-method", "private-static-method"]) + "instance-method", // = ["public-instance-method", "protected-instance-method", "private-instance-method"]) + "abstract-method" // = ["public-abstract-method", "protected-abstract-method", "private-abstract-method"]) ] ``` @@ -141,21 +141,21 @@ Another option is to group the member types by their scope (`public`, `protected The third grouping option is to ignore both scope and accessibility. -```json5 +```jsonc [ // Index signature // No grouping for index signature. See above. // Fields - 'field', // = ['public-static-field', 'protected-static-field', 'private-static-field', 'public-instance-field', 'protected-instance-field', 'private-instance-field', - // 'public-abstract-field', 'protected-abstract-field', private-abstract-field']) + "field", // = ["public-static-field", "protected-static-field", "private-static-field", "public-instance-field", "protected-instance-field", "private-instance-field", + // "public-abstract-field", "protected-abstract-field", private-abstract-field"]) // Constructors // Only the accessibility of constructors is configurable. See above. // Methods - 'method', // = ['public-static-method', 'protected-static-method', 'private-static-method', 'public-instance-method', 'protected-instance-method', 'private-instance-method', - // 'public-abstract-method', 'protected-abstract-method', 'private-abstract-method']) + "method" // = ["public-static-method", "protected-static-method", "private-static-method", "public-instance-method", "protected-instance-method", "private-instance-method", + // "public-abstract-method", "protected-abstract-method", "private-abstract-method"]) ] ``` @@ -163,65 +163,65 @@ The third grouping option is to ignore both scope and accessibility. The default configuration looks as follows: -```json5 +```jsonc { - default: [ + "default": [ // Index signature - 'signature', + "signature", // Fields - 'public-static-field', - 'protected-static-field', - 'private-static-field', + "public-static-field", + "protected-static-field", + "private-static-field", - 'public-instance-field', - 'protected-instance-field', - 'private-instance-field', + "public-instance-field", + "protected-instance-field", + "private-instance-field", - 'public-abstract-field', - 'protected-abstract-field', - 'private-abstract-field', + "public-abstract-field", + "protected-abstract-field", + "private-abstract-field", - 'public-field', - 'protected-field', - 'private-field', + "public-field", + "protected-field", + "private-field", - 'static-field', - 'instance-field', - 'abstract-field', + "static-field", + "instance-field", + "abstract-field", - 'field', + "field", // Constructors - 'public-constructor', - 'protected-constructor', - 'private-constructor', + "public-constructor", + "protected-constructor", + "private-constructor", - 'constructor', + "constructor", // Methods - 'public-static-method', - 'protected-static-method', - 'private-static-method', + "public-static-method", + "protected-static-method", + "private-static-method", - 'public-instance-method', - 'protected-instance-method', - 'private-instance-method', + "public-instance-method", + "protected-instance-method", + "private-instance-method", - 'public-abstract-method', - 'protected-abstract-method', - 'private-abstract-method', + "public-abstract-method", + "protected-abstract-method", + "private-abstract-method", - 'public-method', - 'protected-method', - 'private-method', + "public-method", + "protected-method", + "private-method", - 'static-method', - 'instance-method', - 'abstract-method', + "static-method", + "instance-method", + "abstract-method", - 'method', - ], + "method" + ] } ``` @@ -749,7 +749,7 @@ type Foo = { It is possible to sort all members within a group alphabetically. -#### Configuration: `{ default: { memberTypes: , order: 'alphabetically' } }` +#### Configuration: `{ default: { memberTypes: , order: "alphabetically" } }` This will apply the default order (see above) and enforce an alphabetic order within each group. @@ -795,7 +795,7 @@ interface Foo { It is also possible to sort all members and ignore the member groups completely. -#### Configuration: `{ default: { memberTypes: 'never', order: 'alphabetically' } }` +#### Configuration: `{ default: { memberTypes: "never", order: "alphabetically" } }` ##### Incorrect example diff --git a/packages/eslint-plugin/docs/rules/no-array-constructor.md b/packages/eslint-plugin/docs/rules/no-array-constructor.md index 3ab59cbc6ff..fb9a68e7429 100644 --- a/packages/eslint-plugin/docs/rules/no-array-constructor.md +++ b/packages/eslint-plugin/docs/rules/no-array-constructor.md @@ -1,10 +1,9 @@ # Disallow generic `Array` constructors (`no-array-constructor`) -Use of the `Array` constructor to construct a new array is generally discouraged in favor of array literal notation because of the single-argument pitfall and because the `Array` global may be redefined. Two exceptions are when the Array constructor is used to intentionally create sparse arrays of a specified size by giving the constructor a single numeric argument, or when using TypeScript type parameters to specify the type of the items of the array (`new Array()`). - ## Rule Details -This rule disallows `Array` constructors. +This rule extends the base [`eslint/no-array-constructor`](https://eslint.org/docs/rules/no-array-constructor) rule. +It adds support for the generically typed `Array` constructor (`new Array()`). Examples of **incorrect** code for this rule: @@ -27,8 +26,18 @@ Array(500); new Array(someOtherArray.length); ``` -## When Not To Use It +## How to use + +```jsonc +{ + // note you must disable the base rule as it can report incorrect errors + "no-array-constructor": "off", + "@typescript-eslint/no-array-constructor": ["error"] +} +``` + +## Options -This rule enforces a nearly universal stylistic concern. That being said, this rule may be disabled if the constructor style is preferred. +See [`eslint/no-array-constructor` options](https://eslint.org/docs/rules/no-array-constructor#options). -Taken with ❤️ [from ESLint core](https://github.com/eslint/eslint/blob/7685fed33b15763ee3cf7dbe1facfc5ba85173f3/docs/rules/no-array-constructor.md) +Taken with ❤️ [from ESLint core](https://github.com/eslint/eslint/blob/master/docs/rules/no-array-constructor.md) diff --git a/packages/eslint-plugin/docs/rules/no-dupe-class-members.md b/packages/eslint-plugin/docs/rules/no-dupe-class-members.md index d0b3b57d988..ddfc1b9f1bd 100644 --- a/packages/eslint-plugin/docs/rules/no-dupe-class-members.md +++ b/packages/eslint-plugin/docs/rules/no-dupe-class-members.md @@ -7,7 +7,7 @@ It adds support for TypeScript's method overload definitions. ## How to use -```cjson +```jsonc { // note you must disable the base rule as it can report incorrect errors "no-dupe-class-members": "off", @@ -15,4 +15,8 @@ It adds support for TypeScript's method overload definitions. } ``` +## Options + +See [`eslint/no-dupe-class-members` options](https://eslint.org/docs/rules/no-dupe-class-members#options). + Taken with ❤️ [from ESLint core](https://github.com/eslint/eslint/blob/master/docs/rules/no-dupe-class-members.md) diff --git a/packages/eslint-plugin/docs/rules/no-empty-function.md b/packages/eslint-plugin/docs/rules/no-empty-function.md index 17628cb93c8..df6a3f82583 100644 --- a/packages/eslint-plugin/docs/rules/no-empty-function.md +++ b/packages/eslint-plugin/docs/rules/no-empty-function.md @@ -1,80 +1,24 @@ # Disallow empty functions (`no-empty-function`) -Empty functions can reduce readability because readers need to guess whether it’s intentional or not. So writing a clear comment for empty functions is a good practice. - ## Rule Details -The `@typescript-eslint/no-empty-function` rule extends the `no-empty-function` rule from ESLint core, and adds support for handling TypeScript specific code that would otherwise trigger the rule. +This rule extends the base [`eslint/no-empty-function`](https://eslint.org/docs/rules/no-empty-function) rule. +It adds support for handling TypeScript specific code that would otherwise trigger the rule. One example of valid TypeScript specific code that would otherwise trigger the `no-empty-function` rule is the use of [parameter properties](https://www.typescriptlang.org/docs/handbook/classes.html#parameter-properties) in constructor functions: -```typescript -class Person { - constructor(private firstName: string, private surname: string) {} -} -``` - -The above code is functionally equivalent to: +## How to use -```typescript -class Person { - private firstName: string; - private surname: string; - - constructor(firstName: string, surname: string) { - this.firstName = firstName; - this.surname = surname; - } -} -``` - -Parameter properties enable both the _declaration_ and _initialization_ of member properties in a single location, avoiding the boilerplate & duplication that is common when initializing member properties from parameter values in a constructor function. - -In these cases, although the constructor has an empty function body, it is technically valid and should not trigger an error. - -See the [ESLint documentation](https://eslint.org/docs/rules/no-empty-function) for more details on the `no-empty-function` rule. - -## Rule Changes - -```cjson +```jsonc { - // note you must disable the base rule as it can report incorrect errors - "no-empty-function": "off", - "@typescript-eslint/no-empty-function": "error" + // note you must disable the base rule as it can report incorrect errors + "no-empty-function": "off", + "@typescript-eslint/no-empty-function": ["error"] } ``` ## Options -This rule has an object option: - -- `allow` (`string[]`) - - `"protected-constructors"` - Protected class constructors. - - `"private-constructors"` - Private class constructors. - - [See the other options allowed](https://github.com/eslint/eslint/blob/master/docs/rules/no-empty-function.md#options) - -#### allow: protected-constructors - -Examples of **correct** code for the `{ "allow": ["protected-constructors"] }` option: - -```ts -/*eslint @typescript-eslint/no-empty-function: ["error", { "allow": ["protected-constructors"] }]*/ - -class Foo { - protected constructor() {} -} -``` - -#### allow: private-constructors - -Examples of **correct** code for the `{ "allow": ["private-constructors"] }` option: - -```ts -/*eslint @typescript-eslint/no-empty-function: ["error", { "allow": ["private-constructors"] }]*/ - -class Foo { - private constructor() {} -} -``` +See [`eslint/no-empty-function` options](https://eslint.org/docs/rules/no-empty-function#options). Taken with ❤️ [from ESLint core](https://github.com/eslint/eslint/blob/master/docs/rules/no-empty-function.md) diff --git a/packages/eslint-plugin/docs/rules/no-extra-parens.md b/packages/eslint-plugin/docs/rules/no-extra-parens.md index bcb21dec28d..8173b2ef1ad 100644 --- a/packages/eslint-plugin/docs/rules/no-extra-parens.md +++ b/packages/eslint-plugin/docs/rules/no-extra-parens.md @@ -1,22 +1,22 @@ # Disallow unnecessary parentheses (`no-extra-parens`) -This rule restricts the use of parentheses to only where they are necessary. - ## Rule Details This rule extends the base [`eslint/no-extra-parens`](https://eslint.org/docs/rules/no-extra-parens) rule. -It supports all options and features of the base rule plus TS type assertions. +It adds support for TypeScript type assertions. ## How to use -```cjson +```jsonc { - // note you must disable the base rule as it can report incorrect errors - "no-extra-parens": "off", - "@typescript-eslint/no-extra-parens": ["error"] + // note you must disable the base rule as it can report incorrect errors + "no-extra-parens": "off", + "@typescript-eslint/no-extra-parens": ["error"] } ``` ## Options See [`eslint/no-extra-parens` options](https://eslint.org/docs/rules/no-extra-parens#options). + +Taken with ❤️ [from ESLint core](https://github.com/eslint/eslint/blob/master/docs/rules/no-extra-parens.md) diff --git a/packages/eslint-plugin/docs/rules/no-extra-semi.md b/packages/eslint-plugin/docs/rules/no-extra-semi.md index bed5e29d657..f6865bd8b54 100644 --- a/packages/eslint-plugin/docs/rules/no-extra-semi.md +++ b/packages/eslint-plugin/docs/rules/no-extra-semi.md @@ -3,10 +3,11 @@ ## Rule Details This rule extends the base [`eslint/no-extra-semi`](https://eslint.org/docs/rules/no-extra-semi) rule. +It adds support for class properties. ## How to use -```cjson +```jsonc { // note you must disable the base rule as it can report incorrect errors "no-extra-semi": "off", @@ -14,4 +15,8 @@ This rule extends the base [`eslint/no-extra-semi`](https://eslint.org/docs/rule } ``` +## Options + +See [`eslint/no-extra-semi` options](https://eslint.org/docs/rules/no-extra-semi#options). + Taken with ❤️ [from ESLint core](https://github.com/eslint/eslint/blob/master/docs/rules/no-extra-semi.md) diff --git a/packages/eslint-plugin/docs/rules/no-magic-numbers.md b/packages/eslint-plugin/docs/rules/no-magic-numbers.md index 377e9272360..f41204c132b 100644 --- a/packages/eslint-plugin/docs/rules/no-magic-numbers.md +++ b/packages/eslint-plugin/docs/rules/no-magic-numbers.md @@ -1,25 +1,72 @@ # Disallow magic numbers (`no-magic-numbers`) -'Magic numbers' are numbers that occur multiple times in code without an explicit meaning. -They should preferably be replaced by named constants. - ## Rule Details -The `@typescript-eslint/no-magic-numbers` rule extends the `no-magic-numbers` rule from ESLint core, and adds support for handling TypeScript specific code that would otherwise trigger the rule. +This rule extends the base [`eslint/no-magic-numbers`](https://eslint.org/docs/rules/no-magic-numbers) rule. +It adds support for: -See the [ESLint documentation](https://eslint.org/docs/rules/no-magic-numbers) for more details on the `no-magic-numbers` rule. +- numeric literal types (`type T = 1`), +- `enum` members (`enum Foo { bar = 1 }`), +- `readonly` class properties (`class Foo { readonly bar = 1 }`). -## Rule Changes +## How to use -```cjson +```jsonc { - // note you must disable the base rule as it can report incorrect errors - "no-magic-numbers": "off", - "@typescript-eslint/no-magic-numbers": ["error", { "ignoreNumericLiteralTypes": true }] + // note you must disable the base rule as it can report incorrect errors + "no-magic-numbers": "off", + "@typescript-eslint/no-magic-numbers": [ + "error", + { + /* options */ + } + ] +} +``` + +## Options + +See [`eslint/no-magic-numbers` options](https://eslint.org/docs/rules/no-magic-numbers#options). +This rule adds the following options: + +```ts +interface Options extends BaseNoMagicNumbersOptions { + ignoreEnums?: boolean; + ignoreNumericLiteralTypes?: boolean; + ignoreReadonlyClassProperties?: boolean; +} + +const defaultOptions: Options = { + ...baseNoMagicNumbersDefaultOptions, + ignoreEnums: false, + ignoreNumericLiteralTypes: false, + ignoreReadonlyClassProperties: false, +}; +``` + +### `ignoreEnums` + +A boolean to specify if enums used in TypeScript are considered okay. `false` by default. + +Examples of **incorrect** code for the `{ "ignoreEnums": false }` option: + +```ts +/*eslint @typescript-eslint/no-magic-numbers: ["error", { "ignoreEnums": false }]*/ + +enum foo = { + SECOND = 1000, } ``` -In addition to the options supported by the `no-magic-numbers` rule in ESLint core, the rule adds the following options: +Examples of **correct** code for the `{ "ignoreEnums": true }` option: + +```ts +/*eslint @typescript-eslint/no-magic-numbers: ["error", { "ignoreEnums": true }]*/ + +enum foo = { + SECOND = 1000, +} +``` ### `ignoreNumericLiteralTypes` @@ -69,28 +116,4 @@ class Foo { } ``` -### `ignoreEnums` - -A boolean to specify if enums used in TypeScript are considered okay. `false` by default. - -Examples of **incorrect** code for the `{ "ignoreEnums": false }` option: - -```ts -/*eslint @typescript-eslint/no-magic-numbers: ["error", { "ignoreEnums": false }]*/ - -enum foo = { - SECOND = 1000, -} -``` - -Examples of **correct** code for the `{ "ignoreEnums": true }` option: - -```ts -/*eslint @typescript-eslint/no-magic-numbers: ["error", { "ignoreEnums": true }]*/ - -enum foo = { - SECOND = 1000, -} -``` - Taken with ❤️ [from ESLint core](https://github.com/eslint/eslint/blob/master/docs/rules/no-magic-numbers.md) diff --git a/packages/eslint-plugin/docs/rules/no-this-alias.md b/packages/eslint-plugin/docs/rules/no-this-alias.md index 7f5ee719fa0..b5d2afb542c 100644 --- a/packages/eslint-plugin/docs/rules/no-this-alias.md +++ b/packages/eslint-plugin/docs/rules/no-this-alias.md @@ -39,15 +39,15 @@ Examples of **correct** code for this rule: You can pass an object option: -```json5 +```jsonc { - '@typescript-eslint/no-this-alias': [ - 'error', + "@typescript-eslint/no-this-alias": [ + "error", { - allowDestructuring: true, // Allow `const { props, state } = this`; false by default - allowedNames: ['self'], // Allow `const self = this`; `[]` by default - }, - ], + "allowDestructuring": true, // Allow `const { props, state } = this`; false by default + "allowedNames": ["self"] // Allow `const self = this`; `[]` by default + } + ] } ``` diff --git a/packages/eslint-plugin/docs/rules/no-untyped-public-signature.md b/packages/eslint-plugin/docs/rules/no-untyped-public-signature.md index 87a17895c38..ffcd083b57d 100644 --- a/packages/eslint-plugin/docs/rules/no-untyped-public-signature.md +++ b/packages/eslint-plugin/docs/rules/no-untyped-public-signature.md @@ -2,6 +2,11 @@ public methods are meant to be used by code outside of your class. By typing both the parameters and the return type of public methods they will be more readable and easy to use. +## DEPRECATED + +This rule has been deprecated in favour of the [`explicit-module-boundary-types`](./explicit-module-boundary-types.md) rule. +It will be removed in a future version of this plugin. + ## Rule Details This rule aims to ensure that only typed public methods are declared in the code. @@ -46,9 +51,12 @@ This rule, in its default state, does not require any argument. You may pass method names you would like this rule to ignore, like so: -```cjson +```jsonc { - "@typescript-eslint/no-untyped-public-signature": ["error", { "ignoredMethods": ["ignoredMethodName"] }] + "@typescript-eslint/no-untyped-public-signature": [ + "error", + { "ignoredMethods": ["ignoredMethodName"] } + ] } ``` diff --git a/packages/eslint-plugin/docs/rules/no-unused-expressions.md b/packages/eslint-plugin/docs/rules/no-unused-expressions.md index 63674120fbc..cb61c2ed040 100644 --- a/packages/eslint-plugin/docs/rules/no-unused-expressions.md +++ b/packages/eslint-plugin/docs/rules/no-unused-expressions.md @@ -1,16 +1,13 @@ # Disallow unused expressions (`no-unused-expressions`) -This rule aims to eliminate unused expressions which have no effect on the state of the program. - ## Rule Details This rule extends the base [`eslint/no-unused-expressions`](https://eslint.org/docs/rules/no-unused-expressions) rule. -It supports all options and features of the base rule. -This version adds support for numerous typescript features. +It adds support for optional call expressions `x?.()`, and directive in module declarations. ## How to use -```cjson +```jsonc { // note you must disable the base rule as it can report incorrect errors "no-unused-expressions": "off", diff --git a/packages/eslint-plugin/docs/rules/no-unused-vars.md b/packages/eslint-plugin/docs/rules/no-unused-vars.md index a84b4362d61..44cfae690f8 100644 --- a/packages/eslint-plugin/docs/rules/no-unused-vars.md +++ b/packages/eslint-plugin/docs/rules/no-unused-vars.md @@ -1,305 +1,24 @@ # Disallow unused variables (`no-unused-vars`) -Variables that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring. Such variables take up space in the code and can lead to confusion by readers. +## PLEASE READ THIS ISSUE BEFORE USING THIS RULE [#1856](https://github.com/typescript-eslint/typescript-eslint/issues/1856) ## Rule Details -This rule is aimed at eliminating unused variables, functions, and parameters of functions. +This rule extends the base [`eslint/no-unused-vars`](https://eslint.org/docs/rules/no-unused-vars) rule. +It adds support for TypeScript features, such as types. -A variable is considered to be used if any of the following are true: +## How to use -- It represents a function that is called (`doSomething()`) -- It is read (`var y = x`) -- It is passed into a function as an argument (`doSomething(x)`) -- It is read inside of a function that is passed to another function (`doSomething(function() { foo(); })`) - -A variable is _not_ considered to be used if it is only ever assigned to (`var x = 5`) or declared. - -Examples of **incorrect** code for this rule: - -```js -/*eslint no-unused-vars: "error"*/ -/*global some_unused_var*/ - -// It checks variables you have defined as global -some_unused_var = 42; - -var x; - -// Write-only variables are not considered as used. -var y = 10; -y = 5; - -// A read for a modification of itself is not considered as used. -var z = 0; -z = z + 1; - -// By default, unused arguments cause warnings. -(function(foo) { - return 5; -})(); - -// Unused recursive functions also cause warnings. -function fact(n) { - if (n < 2) return 1; - return n * fact(n - 1); -} - -// When a function definition destructures an array, unused entries from the array also cause warnings. -function getY([x, y]) { - return y; -} -``` - -Examples of **correct** code for this rule: - -```js -/*eslint no-unused-vars: "error"*/ - -var x = 10; -alert(x); - -// foo is considered used here -myFunc( - function foo() { - // ... - }.bind(this), -); - -(function(foo) { - return foo; -})(); - -var myFunc; -myFunc = setTimeout(function() { - // myFunc is considered used - myFunc(); -}, 50); - -// Only the second argument from the destructured array is used. -function getY([, y]) { - return y; -} -``` - -### exported - -In environments outside of CommonJS or ECMAScript modules, you may use `var` to create a global variable that may be used by other scripts. You can use the `/* exported variableName */` comment block to indicate that this variable is being exported and therefore should not be considered unused. - -Note that `/* exported */` has no effect for any of the following: - -- when the environment is `node` or `commonjs` -- when `parserOptions.sourceType` is `module` -- when `ecmaFeatures.globalReturn` is `true` - -The line comment `// exported variableName` will not work as `exported` is not line-specific. - -Examples of **correct** code for `/* exported variableName */` operation: - -```js -/* exported global_var */ - -var global_var = 42; -``` - -## Options - -This rule takes one argument which can be a string or an object. The string settings are the same as those of the `vars` property (explained below). - -By default this rule is enabled with `all` option for variables and `after-used` for arguments. - -```CJSON +```jsonc { - "rules": { - // note you must disable the base rule as it can report incorrect errors - "no-unused-vars": "off", - "@typescript-eslint/no-unused-vars": ["error", { - "vars": "all", - "args": "after-used", - "ignoreRestSiblings": false - }] - } + // note you must disable the base rule as it can report incorrect errors + "no-unused-vars": "off", + "@typescript-eslint/no-unused-vars": ["error"] } ``` -### `vars` - -The `vars` option has two settings: - -- `all` checks all variables for usage, including those in the global scope. This is the default setting. -- `local` checks only that locally-declared variables are used but will allow global variables to be unused. - -#### `vars: local` - -Examples of **correct** code for the `{ "vars": "local" }` option: - -```js -/*eslint no-unused-vars: ["error", { "vars": "local" }]*/ -/*global some_unused_var */ - -some_unused_var = 42; -``` - -### `varsIgnorePattern` - -The `varsIgnorePattern` option specifies exceptions not to check for usage: variables whose names match a regexp pattern. For example, variables whose names contain `ignored` or `Ignored`. - -Examples of **correct** code for the `{ "varsIgnorePattern": "[iI]gnored" }` option: - -```js -/*eslint no-unused-vars: ["error", { "varsIgnorePattern": "[iI]gnored" }]*/ - -var firstVarIgnored = 1; -var secondVar = 2; -console.log(secondVar); -``` - -### `args` - -The `args` option has three settings: - -- `after-used` - unused positional arguments that occur before the last used argument will not be checked, but all named arguments and all positional arguments after the last used argument will be checked. -- `all` - all named arguments must be used. -- `none` - do not check arguments. - -#### `args: after-used` - -Examples of **incorrect** code for the default `{ "args": "after-used" }` option: - -```js -/*eslint no-unused-vars: ["error", { "args": "after-used" }]*/ - -// 2 errors, for the parameters after the last used parameter (bar) -// "baz" is defined but never used -// "qux" is defined but never used -(function(foo, bar, baz, qux) { - return bar; -})(); -``` - -Examples of **correct** code for the default `{ "args": "after-used" }` option: - -```js -/*eslint no-unused-vars: ["error", {"args": "after-used"}]*/ - -(function(foo, bar, baz, qux) { - return qux; -})(); -``` - -#### `args: all` - -Examples of **incorrect** code for the `{ "args": "all" }` option: - -```js -/*eslint no-unused-vars: ["error", { "args": "all" }]*/ - -// 2 errors -// "foo" is defined but never used -// "baz" is defined but never used -(function(foo, bar, baz) { - return bar; -})(); -``` - -#### `args: none` - -Examples of **correct** code for the `{ "args": "none" }` option: - -```js -/*eslint no-unused-vars: ["error", { "args": "none" }]*/ - -(function(foo, bar, baz) { - return bar; -})(); -``` - -### `ignoreRestSiblings` - -The `ignoreRestSiblings` option is a boolean (default: `false`). Using a [Rest Property](https://github.com/tc39/proposal-object-rest-spread) it is possible to "omit" properties from an object, but by default the sibling properties are marked as "unused". With this option enabled the rest property's siblings are ignored. - -Examples of **correct** code for the `{ "ignoreRestSiblings": true }` option: - -```js -/*eslint no-unused-vars: ["error", { "ignoreRestSiblings": true }]*/ -// 'type' is ignored because it has a rest property sibling. -var { type, ...coords } = data; -``` - -### `argsIgnorePattern` - -The `argsIgnorePattern` option specifies exceptions not to check for usage: arguments whose names match a regexp pattern. For example, variables whose names begin with an underscore. - -Examples of **correct** code for the `{ "argsIgnorePattern": "^_" }` option: - -```js -/*eslint no-unused-vars: ["error", { "argsIgnorePattern": "^_" }]*/ - -function foo(x, _y) { - return x + 1; -} -foo(); -``` - -### `caughtErrors` - -The `caughtErrors` option is used for `catch` block arguments validation. - -It has two settings: - -- `none` - do not check error objects. This is the default setting. -- `all` - all named arguments must be used. - -#### `caughtErrors: none` - -Not specifying this rule is equivalent of assigning it to `none`. - -Examples of **correct** code for the `{ "caughtErrors": "none" }` option: - -```js -/*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/ - -try { - //... -} catch (err) { - console.error('errors'); -} -``` - -#### `caughtErrors: all` - -Examples of **incorrect** code for the `{ "caughtErrors": "all" }` option: - -```js -/*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/ - -// 1 error -// "err" is defined but never used -try { - //... -} catch (err) { - console.error('errors'); -} -``` - -### `caughtErrorsIgnorePattern` - -The `caughtErrorsIgnorePattern` option specifies exceptions not to check for usage: catch arguments whose names match a regexp pattern. For example, variables whose names begin with a string 'ignore'. - -Examples of **correct** code for the `{ "caughtErrorsIgnorePattern": "^ignore" }` option: - -```js -/*eslint no-unused-vars: ["error", { "caughtErrorsIgnorePattern": "^ignore" }]*/ - -try { - //... -} catch (ignoreErr) { - console.error('errors'); -} -``` - -## When Not To Use It +## Options -If you don't want to be notified about unused variables or function arguments, you can safely turn this rule off. +See [`eslint/no-unused-vars` options](https://eslint.org/docs/rules/no-unused-vars#options). Taken with ❤️ [from ESLint core](https://github.com/eslint/eslint/blob/master/docs/rules/no-unused-vars.md) diff --git a/packages/eslint-plugin/docs/rules/no-use-before-define.md b/packages/eslint-plugin/docs/rules/no-use-before-define.md index e6acf604568..569b8130386 100644 --- a/packages/eslint-plugin/docs/rules/no-use-before-define.md +++ b/packages/eslint-plugin/docs/rules/no-use-before-define.md @@ -1,146 +1,46 @@ # Disallow the use of variables before they are defined (`no-use-before-define`) -In JavaScript, prior to ES6, variable and function declarations are hoisted to the top of a scope, so it's possible to use identifiers before their formal declarations in code. This can be confusing and some believe it is best to always declare variables and functions before using them. - -In ES6, block-level bindings (`let` and `const`) introduce a "temporal dead zone" where a `ReferenceError` will be thrown with any attempt to access the variable before its declaration. +## PLEASE READ THIS ISSUE BEFORE USING THIS RULE [#1856](https://github.com/typescript-eslint/typescript-eslint/issues/1856) ## Rule Details -This rule will warn when it encounters a reference to an identifier that has not yet been declared. - -Examples of **incorrect** code for this rule: - -```ts -/*eslint no-use-before-define: "error"*/ -/*eslint-env es6*/ - -alert(a); -var a = 10; - -f(); -function f() {} - -function g() { - return b; -} -var b = 1; - -// With blockBindings: true -{ - alert(c); - let c = 1; -} - -let myVar: StringOrNumber; -type StringOrNumber = string | number; -``` - -Examples of **correct** code for this rule: +This rule extends the base [`eslint/no-use-before-define`](https://eslint.org/docs/rules/no-use-before-define) rule. +It adds support for `type`, `interface` and `enum` declarations. -```ts -/*eslint no-use-before-define: "error"*/ -/*eslint-env es6*/ +## How to use -var a; -a = 10; -alert(a); - -function f() {} -f(1); - -var b = 1; -function g() { - return b; -} - -// With blockBindings: true +```jsonc { - let C; - c++; + // note you must disable the base rule as it can report incorrect errors + "no-use-before-define": "off", + "@typescript-eslint/no-use-before-define": ["error"] } - -type StringOrNumber = string | number; -let myVar: StringOrNumber; ``` ## Options -```json -{ - "no-use-before-define": ["error", { "functions": true, "classes": true }] -} -``` - -- `functions` (`boolean`) - - The flag which shows whether or not this rule checks function declarations. - If this is `true`, this rule warns every reference to a function before the function declaration. - Otherwise, ignores those references. - Function declarations are hoisted, so it's safe. - Default is `true`. -- `classes` (`boolean`) - - The flag which shows whether or not this rule checks class declarations of upper scopes. - If this is `true`, this rule warns every reference to a class before the class declaration. - Otherwise, ignores those references if the declaration is in upper function scopes. - Class declarations are not hoisted, so it might be danger. - Default is `true`. -- `enums` (`boolean`) - - The flag which shows whether or not this rule checks enum declarations of upper scopes. - If this is `true`, this rule warns every reference to a enum before the enum declaration. - Otherwise, ignores those references. - Default is `true`. -- `variables` (`boolean`) - - This flag determines whether or not the rule checks variable declarations in upper scopes. - If this is `true`, the rule warns every reference to a variable before the variable declaration. - Otherwise, the rule ignores a reference if the declaration is in an upper scope, while still reporting the reference if it's in the same scope as the declaration. - Default is `true`. -- `typedefs` (`boolean`, **added** in `@typescript-eslint/eslint-plugin`) - - The flag which shows whether or not this rule checks type declarations. - If this is `true`, this rule warns every reference to a type before the type declaration. - Otherwise, ignores those references. - Type declarations are hoisted, so it's safe. - Default is `true`. - -This rule accepts `"nofunc"` string as an option. -`"nofunc"` is the same as `{ "functions": false, "classes": true }`. - -### `functions` - -Examples of **correct** code for the `{ "functions": false }` option: - -```js -/*eslint no-use-before-define: ["error", { "functions": false }]*/ - -f(); -function f() {} -``` - -### `classes` +See [`eslint/no-use-before-define` options](https://eslint.org/docs/rules/no-use-before-define#options). +This rule adds the following options: -Examples of **incorrect** code for the `{ "classes": false }` option: - -```js -/*eslint no-use-before-define: ["error", { "classes": false }]*/ -/*eslint-env es6*/ - -new A(); -class A {} -``` - -Examples of **correct** code for the `{ "classes": false }` option: - -```js -/*eslint no-use-before-define: ["error", { "classes": false }]*/ -/*eslint-env es6*/ - -function foo() { - return new A(); +```ts +interface Options extends BaseNoMagicNumbersOptions { + enums?: boolean; + typedefs?: boolean; } -class A {} +const defaultOptions: Options = { + ...baseNoMagicNumbersDefaultOptions, + enums: true, + typedefs: true, +}; ``` ### `enums` +The flag which shows whether or not this rule checks enum declarations of upper scopes. +If this is `true`, this rule warns every reference to a enum before the enum declaration. +Otherwise, ignores those references. + Examples of **incorrect** code for the `{ "enums": true }` option: ```ts @@ -176,31 +76,13 @@ enum Foo { } ``` -### `variables` - -Examples of **incorrect** code for the `{ "variables": false }` option: - -```js -/*eslint no-use-before-define: ["error", { "variables": false }]*/ - -console.log(foo); -var foo = 1; -``` - -Examples of **correct** code for the `{ "variables": false }` option: - -```js -/*eslint no-use-before-define: ["error", { "variables": false }]*/ - -function baz() { - console.log(foo); -} - -var foo = 1; -``` - ### `typedefs` +The flag which shows whether or not this rule checks type declarations. +If this is `true`, this rule warns every reference to a type before the type declaration. +Otherwise, ignores those references. +Type declarations are hoisted, so it's safe. + Examples of **correct** code for the `{ "typedefs": false }` option: ```ts diff --git a/packages/eslint-plugin/docs/rules/no-useless-constructor.md b/packages/eslint-plugin/docs/rules/no-useless-constructor.md index 757ae5d4a12..524ad4b92d9 100644 --- a/packages/eslint-plugin/docs/rules/no-useless-constructor.md +++ b/packages/eslint-plugin/docs/rules/no-useless-constructor.md @@ -1,88 +1,26 @@ # Disallow unnecessary constructors (`no-useless-constructor`) -ES2015 provides a default class constructor if one is not specified. As such, it is unnecessary to provide an empty constructor or one that simply delegates into its parent class, as in the following examples: - -```js -class A { - constructor() {} -} - -class A extends B { - constructor(value) { - super(value); - } -} -``` - ## Rule Details -This rule flags class constructors that can be safely removed without changing how the class works. - -## Examples - -Examples of **incorrect** code for this rule: - -```js -/*eslint @typescript-eslint/no-useless-constructor: "error"*/ - -class A { - constructor() {} -} - -class A extends B { - constructor(...args) { - super(...args); - } -} -``` +This rule extends the base [`eslint/no-useless-constructor`](https://eslint.org/docs/rules/no-useless-constructor) rule. +It adds support for: -Examples of **correct** code for this rule: - -```js -/*eslint @typescript-eslint/no-useless-constructor: "error"*/ - -class A {} - -class A { - constructor() { - doSomething(); - } -} - -class A extends B { - constructor() { - super('foo'); - } -} - -class A extends B { - constructor() { - super(); - doSomething(); - } -} - -class A extends B { - constructor(protected name: string) {} -} - -class A extends B { - protected constructor() {} -} -``` +- constructors marked as `protected` / `private` (i.e. marking a constructor as non-public), +- `public` constructors when there is no superclass, +- constructors with only parameter properties. -## Rule Changes +## How to use -```cjson +```jsonc { - // note you must disable the base rule as it can report incorrect errors - "no-useless-constructor": "off", - "@typescript-eslint/no-useless-constructor": "error", + // note you must disable the base rule as it can report incorrect errors + "no-useless-constructor": "off", + "@typescript-eslint/no-useless-constructor": ["error"] } ``` -## When Not To Use It +## Options -If you don't want to be notified about unnecessary constructors, you can safely disable this rule. +See [`eslint/no-useless-constructor` options](https://eslint.org/docs/rules/no-useless-constructor#options). Taken with ❤️ [from ESLint core](https://github.com/eslint/eslint/blob/master/docs/rules/no-useless-constructor.md) diff --git a/packages/eslint-plugin/docs/rules/prefer-readonly.md b/packages/eslint-plugin/docs/rules/prefer-readonly.md index 6731a758580..9ce16a8c35f 100644 --- a/packages/eslint-plugin/docs/rules/prefer-readonly.md +++ b/packages/eslint-plugin/docs/rules/prefer-readonly.md @@ -52,9 +52,9 @@ This rule, in its default state, does not require any argument. You may pass `"onlyInlineLambdas": true` as a rule option within an object to restrict checking only to members immediately assigned a lambda value. -```cjson +```jsonc { - "@typescript-eslint/prefer-readonly": ["error", { "onlyInlineLambdas": true }] + "@typescript-eslint/prefer-readonly": ["error", { "onlyInlineLambdas": true }] } ``` diff --git a/packages/eslint-plugin/docs/rules/quotes.md b/packages/eslint-plugin/docs/rules/quotes.md index e9c37df36f7..6b63587f6b4 100644 --- a/packages/eslint-plugin/docs/rules/quotes.md +++ b/packages/eslint-plugin/docs/rules/quotes.md @@ -3,11 +3,11 @@ ## Rule Details This rule extends the base [`eslint/quotes`](https://eslint.org/docs/rules/quotes) rule. -It supports all options and features of the base rule. +It adds support for TypeScript features which allow quoted names, but not backtick quoted names. ## How to use -```cjson +```jsonc { // note you must disable the base rule as it can report incorrect errors "quotes": "off", diff --git a/packages/eslint-plugin/docs/rules/require-await.md b/packages/eslint-plugin/docs/rules/require-await.md index 23160dc7db5..2d8ad41fda9 100644 --- a/packages/eslint-plugin/docs/rules/require-await.md +++ b/packages/eslint-plugin/docs/rules/require-await.md @@ -1,49 +1,32 @@ # Disallow async functions which have no `await` expression (`require-await`) -Asynchronous functions that don’t use `await` might not need to be asynchronous functions and could be the unintentional result of refactoring. - ## Rule Details -The `@typescript-eslint/require-await` rule extends the `require-await` rule from ESLint core, and allows for cases where the additional typing information can prevent false positives that would otherwise trigger the rule. - -One example is when a function marked as `async` returns a value that is: +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`. -1. already a promise; or -2. the result of calling another `async` function +Examples of **correct** code for this rule: -```typescript -async function numberOne(): Promise { +```ts +async function returnsPromise1() { return Promise.resolve(1); } -async function getDataFromApi(endpoint: string): Promise { - return fetch(endpoint); -} -``` - -In the above examples, the core `require-await` triggers the following warnings: - -``` -async function 'numberOne' has no 'await' expression -async function 'getDataFromApi' has no 'await' expression +const returnsPromise2 = () => returnsPromise1(); ``` -One way to resolve these errors is to remove the `async` keyword. However doing so can cause a conflict with the [`@typescript-eslint/promise-function-async`](https://github.com/typescript-eslint/typescript-eslint/blob/master/packages/eslint-plugin/docs/rules/promise-function-async.md) rule (if enabled), which requires any function returning a promise to be marked as `async`. +## How to use -Another way to resolve these errors is to add an `await` keyword to the return statements. However doing so can cause a conflict with the [`no-return-await`](https://eslint.org/docs/rules/no-return-await) rule (if enabled), which warns against using `return await` since the return value of an `async` function is always wrapped in `Promise.resolve` anyway. - -With the additional typing information available in TypeScript code, this extension to the `require-await` rule is able to look at the _actual_ return types of an `async` function (before being implicitly wrapped in `Promise.resolve`), and avoid the need for an `await` expression when the return value is already a promise. - -See the [ESLint documentation](https://eslint.org/docs/rules/require-await) for more details on the `require-await` rule. - -## Rule Changes - -```cjson +```jsonc { - // note you must disable the base rule as it can report incorrect errors - "require-await": "off", - "@typescript-eslint/require-await": "error" + // note you must disable the base rule as it can report incorrect errors + "require-await": "off", + "@typescript-eslint/require-await": "error" } ``` +## Options + +See [`eslint/require-await` options](https://eslint.org/docs/rules/require-await#options). + Taken with ❤️ [from ESLint core](https://github.com/eslint/eslint/blob/master/docs/rules/require-await.md) diff --git a/packages/eslint-plugin/docs/rules/return-await.md b/packages/eslint-plugin/docs/rules/return-await.md index c00c2be5d02..1f0adc71ec1 100644 --- a/packages/eslint-plugin/docs/rules/return-await.md +++ b/packages/eslint-plugin/docs/rules/return-await.md @@ -4,95 +4,114 @@ Returning an awaited promise can make sense for better stack trace information a ## Rule Details -The `@typescript-eslint/return-await` rule specifies that awaiting a returned non-promise is never allowed. By default, the rule requires awaiting a returned promise in a `try-catch-finally` block and disallows returning an awaited promise in any other context. Optionally, the rule can require awaiting returned promises in all contexts, or disallow them in all contexts. +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. + +## How to use + +```jsonc +{ + // note you must disable the base rule as it can report incorrect errors + "no-return-await": "off", + "@typescript-eslint/return-await": "error" +} +``` ## Options -`in-try-catch` (default): `await`-ing a returned promise is required in `try-catch-finally` blocks and disallowed elsewhere. +```ts +type Options = 'in-try-catch' | 'always' | 'never'; + +const defaultOptions: Options = 'in-try-catch'; +``` -`always`: `await`-ing a returned promise is required everywhere. +### `in-try-catch` -`never`: `await`-ing a returned promise is disallowed everywhere. +Requires that a returned promise must be `await`ed in `try-catch-finally` blocks, and disallows it elsewhere. -```typescript -// valid in-try-catch -async function validInTryCatch1() { +Examples of **incorrect** code with `in-try-catch`: + +```ts +async function invalidInTryCatch1() { try { - return await Promise.resolve('try'); + return Promise.resolve('try'); } catch (e) {} } -async function validInTryCatch2() { - return Promise.resolve('try'); +async function invalidInTryCatch2() { + return await Promise.resolve('try'); } -async function validInTryCatch3() { - return 'value'; +async function invalidInTryCatch3() { + return await 'value'; } +``` -// valid always -async function validAlways1() { +Examples of **correct** code with `in-try-catch`: + +```ts +async function validInTryCatch1() { try { return await Promise.resolve('try'); } catch (e) {} } -async function validAlways2() { - return await Promise.resolve('try'); +async function validInTryCatch2() { + return Promise.resolve('try'); } -async function validAlways3() { +async function validInTryCatch3() { return 'value'; } +``` -// valid never -async function validNever1() { +### `always` + +Requires that all returned promises are `await`ed. + +Examples of **incorrect** code with `always`: + +```ts +async function invalidAlways1() { try { return Promise.resolve('try'); } catch (e) {} } -async function validNever2() { +async function invalidAlways2() { return Promise.resolve('try'); } -async function validNever3() { - return 'value'; +async function invalidAlways3() { + return await 'value'; } ``` -```typescript -// invalid in-try-catch -async function invalidInTryCatch1() { +Examples of **correct** code with `always`: + +```ts +async function validAlways1() { try { - return Promise.resolve('try'); + return await Promise.resolve('try'); } catch (e) {} } -async function invalidInTryCatch2() { +async function validAlways2() { return await Promise.resolve('try'); } -async function invalidInTryCatch3() { - return await 'value'; +async function validAlways3() { + return 'value'; } +``` -// invalid always -async function invalidAlways1() { - try { - return Promise.resolve('try'); - } catch (e) {} -} +### `never` -async function invalidAlways2() { - return Promise.resolve('try'); -} +Disallows all `await`ing any returned promises. -async function invalidAlways3() { - return await 'value'; -} +Examples of **incorrect** code with `never`: -// invalid never +```ts async function invalidNever1() { try { return await Promise.resolve('try'); @@ -108,16 +127,20 @@ async function invalidNever3() { } ``` -The rule also applies to `finally` blocks. So the following would be invalid with default options: +Examples of **correct** code with `never`: -```typescript -async function invalid() { +```ts +async function validNever1() { try { - return await Promise.resolve('try'); - } catch (e) { - return Promise.resolve('catch'); - } finally { - // cleanup - } + return Promise.resolve('try'); + } catch (e) {} +} + +async function validNever2() { + return Promise.resolve('try'); +} + +async function validNever3() { + return 'value'; } ``` diff --git a/packages/eslint-plugin/docs/rules/semi.md b/packages/eslint-plugin/docs/rules/semi.md index bbb3154fa1a..c233d354631 100644 --- a/packages/eslint-plugin/docs/rules/semi.md +++ b/packages/eslint-plugin/docs/rules/semi.md @@ -5,15 +5,13 @@ This rule enforces consistent use of semicolons after statements. ## Rule Details This rule extends the base [`eslint/semi`](https://eslint.org/docs/rules/semi) rule. -It supports all options and features of the base rule. -This version adds support for numerous typescript features. +It adds support for TypeScript features that require semicolons. -See also the [`@typescript-eslint/member-delimiter-style`](member-delimiter-style.md) rule, -which allows you to specify the delimiter for `type` and `interface` members. +See also the [`@typescript-eslint/member-delimiter-style`](member-delimiter-style.md) rule, which allows you to specify the delimiter for `type` and `interface` members. ## How to use -```cjson +```jsonc { // note you must disable the base rule as it can report incorrect errors "semi": "off", diff --git a/packages/eslint-plugin/docs/rules/space-before-function-paren.md b/packages/eslint-plugin/docs/rules/space-before-function-paren.md index bfbcb22d887..db2579e44d1 100644 --- a/packages/eslint-plugin/docs/rules/space-before-function-paren.md +++ b/packages/eslint-plugin/docs/rules/space-before-function-paren.md @@ -1,33 +1,13 @@ # Enforces consistent spacing before function parenthesis (`space-before-function-paren`) -When formatting a function, whitespace is allowed between the function name or `function` keyword and the opening parenthesis. Named functions also require a space between the `function` keyword and the function name, but anonymous functions require no whitespace. For example: - - -```ts -function withoutSpace(x) { - // ... -} - -function withSpace (x) { - // ... -} - -var anonymousWithoutSpace = function() {}; - -var anonymousWithSpace = function () {}; -``` - -Style guides may require a space after the `function` keyword for anonymous functions, while others specify no whitespace. Similarly, the space after a function name may or may not be required. - ## Rule Details This rule extends the base [`eslint/space-before-function-paren`](https://eslint.org/docs/rules/space-before-function-paren) rule. -It supports all options and features of the base rule. -This version adds support for generic type parameters on function calls. +It adds support for generic type parameters on function calls. ## How to use -```cjson +```jsonc { // note you must disable the base rule as it can report incorrect errors "space-before-function-paren": "off", diff --git a/packages/eslint-plugin/src/rules/ban-ts-ignore.ts b/packages/eslint-plugin/src/rules/ban-ts-ignore.ts index 7551df8d022..551bb0401a9 100644 --- a/packages/eslint-plugin/src/rules/ban-ts-ignore.ts +++ b/packages/eslint-plugin/src/rules/ban-ts-ignore.ts @@ -16,7 +16,7 @@ export default util.createRule({ 'Do not use "// @ts-ignore" comments because they suppress compilation errors.', }, deprecated: true, - replacedBy: ['@typescript-eslint/ban-ts-comment'], + replacedBy: ['ban-ts-comment'], }, defaultOptions: [], create(context) {