diff --git a/.cspell.json b/.cspell.json index 4ffaadbefaf..4a2e442eb9d 100644 --- a/.cspell.json +++ b/.cspell.json @@ -72,6 +72,7 @@ "declarators", "destructure", "destructured", + "destructures", "discoverability", "dprint", "errored", diff --git a/packages/eslint-plugin/docs/rules/explicit-member-accessibility.md b/packages/eslint-plugin/docs/rules/explicit-member-accessibility.md index 83b183800d8..0e375c96937 100644 --- a/packages/eslint-plugin/docs/rules/explicit-member-accessibility.md +++ b/packages/eslint-plugin/docs/rules/explicit-member-accessibility.md @@ -164,7 +164,7 @@ class Animal { } ``` -### Overrides +### `overrides` There are three ways in which an override can be used. @@ -312,7 +312,7 @@ class Animal { } ``` -### Except specific methods +### `ignoredMethodNames` If you want to ignore some specific methods, you can do it by specifying method names. Note that this option does not care for the context, and will ignore every method with these names, which could lead to it missing some cases. You should use this sparingly. e.g. `[ { ignoredMethodNames: ['specificMethod', 'whateverMethod'] } ]` diff --git a/packages/eslint-plugin/docs/rules/no-empty-interface.md b/packages/eslint-plugin/docs/rules/no-empty-interface.md index 64bf24ffe1f..f665acd4ae9 100644 --- a/packages/eslint-plugin/docs/rules/no-empty-interface.md +++ b/packages/eslint-plugin/docs/rules/no-empty-interface.md @@ -50,20 +50,9 @@ interface Baz extends Foo, Bar {} ## Options -This rule accepts a single object option with the following default configuration: - -```json -{ - "@typescript-eslint/no-empty-interface": [ - "error", - { - "allowSingleExtends": false - } - ] -} -``` +### `allowSingleExtends` -- `allowSingleExtends: true` will silence warnings about extending a single interface without adding additional members +`allowSingleExtends: true` will silence warnings about extending a single interface without adding additional members ## When Not To Use It diff --git a/packages/eslint-plugin/docs/rules/no-explicit-any.md b/packages/eslint-plugin/docs/rules/no-explicit-any.md index 5e251fb7a03..d81ea673b93 100644 --- a/packages/eslint-plugin/docs/rules/no-explicit-any.md +++ b/packages/eslint-plugin/docs/rules/no-explicit-any.md @@ -94,6 +94,13 @@ function greet(param: Array): Array {} ## Options +### `fixToUnknown` + +By default, this rule will not provide automatic ESLint _fixes_: only opt-in _suggestions_. +Switching types to `unknown` is safer but is likely to cause additional type errors. + +Enabling `{ "fixToUnknown": true }` gives the rule an auto-fixer to replace `: any` with `: unknown`. + ### `ignoreRestArgs` A boolean to specify if arrays from the rest operator are considered okay. `false` by default. diff --git a/packages/eslint-plugin/docs/rules/no-meaningless-void-operator.md b/packages/eslint-plugin/docs/rules/no-meaningless-void-operator.md index 5c149ef653a..e57606d5ec9 100644 --- a/packages/eslint-plugin/docs/rules/no-meaningless-void-operator.md +++ b/packages/eslint-plugin/docs/rules/no-meaningless-void-operator.md @@ -44,6 +44,8 @@ void bar(); // discarding a number ## Options +### `checkNever` + `checkNever: true` will suggest removing `void` when the argument has type `never`. ## When Not To Use It diff --git a/packages/eslint-plugin/docs/rules/no-misused-promises.md b/packages/eslint-plugin/docs/rules/no-misused-promises.md index 738b6f6f9af..fc4ba7e460e 100644 --- a/packages/eslint-plugin/docs/rules/no-misused-promises.md +++ b/packages/eslint-plugin/docs/rules/no-misused-promises.md @@ -17,7 +17,7 @@ See [`no-floating-promises`](./no-floating-promises.md) for detecting unhandled ## Options -### `"checksConditionals"` +### `checksConditionals` If you don't want to check conditionals, you can configure the rule with `"checksConditionals": false`: @@ -73,7 +73,7 @@ while (await promise) { -### `"checksVoidReturn"` +### `checksVoidReturn` Likewise, if you don't want to check functions that return promises where a void return is expected, your configuration will look like this: @@ -182,7 +182,7 @@ eventEmitter.on('some-event', () => { -### `"checksSpreads"` +### `checksSpreads` If you don't want to check object spreads, you can add this configuration: diff --git a/packages/eslint-plugin/docs/rules/no-this-alias.md b/packages/eslint-plugin/docs/rules/no-this-alias.md index e9be8a524e6..6014e56c323 100644 --- a/packages/eslint-plugin/docs/rules/no-this-alias.md +++ b/packages/eslint-plugin/docs/rules/no-this-alias.md @@ -33,6 +33,75 @@ 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: + + + +#### ❌ 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: + + + +#### ❌ 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 your project is structured in a way that it needs to assign `this` to variables, this rule is likely not for you. diff --git a/packages/eslint-plugin/docs/rules/parameter-properties.md b/packages/eslint-plugin/docs/rules/parameter-properties.md index 830e2a5250b..87a467344a0 100644 --- a/packages/eslint-plugin/docs/rules/parameter-properties.md +++ b/packages/eslint-plugin/docs/rules/parameter-properties.md @@ -19,7 +19,7 @@ It may take an options object containing either or both of: - `"allow"`: allowing certain kinds of properties to be ignored - `"prefer"`: either `"class-property"` _(default)_ or `"parameter-property"` -### `"allow"` +### `allow` If you would like to ignore certain kinds of properties then you may pass an object containing `"allow"` as an array of any of the following options: @@ -45,7 +45,7 @@ For example, to ignore `public` properties: } ``` -### `"prefer"` +### `prefer` By default, the rule prefers class property (`"class-property"`). You can switch it to instead preferring parameter property with (`"parameter-property"`). diff --git a/packages/eslint-plugin/docs/rules/prefer-literal-enum-member.md b/packages/eslint-plugin/docs/rules/prefer-literal-enum-member.md index 3684b84d544..de1ca2942b2 100644 --- a/packages/eslint-plugin/docs/rules/prefer-literal-enum-member.md +++ b/packages/eslint-plugin/docs/rules/prefer-literal-enum-member.md @@ -61,7 +61,9 @@ enum Valid { ## Options -- `allowBitwiseExpressions` set to `true` will allow you to use bitwise expressions in enum initializer (Default: `false`). +### `allowBitwiseExpressions` + +When set to `true` will allow you to use bitwise expressions in enum initializer (default: `false`). Examples of code for the `{ "allowBitwiseExpressions": true }` option: diff --git a/packages/eslint-plugin/docs/rules/prefer-nullish-coalescing.md b/packages/eslint-plugin/docs/rules/prefer-nullish-coalescing.md index 9377117fba4..0db387ab9a2 100644 --- a/packages/eslint-plugin/docs/rules/prefer-nullish-coalescing.md +++ b/packages/eslint-plugin/docs/rules/prefer-nullish-coalescing.md @@ -167,6 +167,16 @@ foo ?? 'a string'; Also, if you would like to ignore all primitives types, you can set `ignorePrimitives: true`. It is equivalent to `ignorePrimitives: { string: true, number: true, bigint: true, boolean: true }`. +### `allowRuleToRunWithoutStrictNullChecksIKnowWhatIAmDoing` + +If this is set to `false`, then the rule will error on every file whose `tsconfig.json` does _not_ have the `strictNullChecks` compiler option (or `strict`) set to `true`. + +Without `strictNullChecks`, TypeScript essentially erases `undefined` and `null` from the types. This means when this rule inspects the types from a variable, **it will not be able to tell that the variable might be `null` or `undefined`**, which essentially makes this rule useless. + +You should be using `strictNullChecks` to ensure complete type-safety in your codebase. + +If for some reason you cannot turn on `strictNullChecks`, but still want to use this rule - you can use this option to allow it - but know that the behavior of this rule is _undefined_ with the compiler option turned off. We will not accept bug reports if you are using this option. + ## When Not To Use It If you are not using TypeScript 3.7 (or greater), then you will not be able to use this rule, as the operator is not supported. diff --git a/packages/eslint-plugin/docs/rules/promise-function-async.md b/packages/eslint-plugin/docs/rules/promise-function-async.md index a11dfdea3ce..c85c00af40f 100644 --- a/packages/eslint-plugin/docs/rules/promise-function-async.md +++ b/packages/eslint-plugin/docs/rules/promise-function-async.md @@ -58,6 +58,74 @@ async function functionReturnsUnionWithPromiseImplicitly(p: boolean) { } ``` +## Options + +### `allowAny` + +Whether to ignore functions that return `any` and `unknown`. +If you want additional safety, consider turning this option off, as it makes the rule less able to catch incorrect Promise behaviors. + +Examples of code with `{ "allowAny": false }`: + + + +#### ❌ Incorrect + +```ts option='{ "allowAny": false }' +const returnsAny = () => ({}) as any; +``` + +#### ✅ Correct + +```ts option='{ "allowAny": false }' +const returnsAny = async () => ({}) as any; +``` + +### `allowedPromiseNames` + +For projects that use constructs other than the global built-in `Promise` for asynchronous code. +This option allows specifying string names of classes or interfaces that cause a function to be checked as well. + +Examples of code with `{ "allowedPromiseNames": ["Bluebird"] }`: + + + +#### ❌ Incorrect + +```ts option='{ "allowedPromiseNames": ["Bluebird"] }' +import { Bluebird } from 'bluebird'; + +const returnsBluebird = () => new Bluebird(() => {}); +``` + +#### ✅ Correct + +```ts option='{ "allowedPromiseNames": ["Bluebird"] }' +import { Bluebird } from 'bluebird'; + +const returnsBluebird = async () => new Bluebird(() => {}); +``` + +### `checkArrowFunctions` + +Whether to check arrow functions. +`true` by default, but can be set to `false` to ignore them. + +### `checkFunctionDeclarations` + +Whether to check standalone function declarations. +`true` by default, but can be set to `false` to ignore them. + +### `checkFunctionExpressions` + +Whether to check inline function expressions. +`true` by default, but can be set to `false` to ignore them. + +### `checkMethodDeclarations` + +Whether to check methods on classes and object literals +`true` by default, but can be set to `false` to ignore them. + ## When Not To Use It This rule can be difficult to enable on projects that use APIs which require functions to always be `async`. diff --git a/packages/eslint-plugin/docs/rules/sort-type-constituents.md b/packages/eslint-plugin/docs/rules/sort-type-constituents.md index c767bff5edd..10fe95e2bbe 100644 --- a/packages/eslint-plugin/docs/rules/sort-type-constituents.md +++ b/packages/eslint-plugin/docs/rules/sort-type-constituents.md @@ -82,6 +82,46 @@ type T4 = ## Options +### `checkIntersections` + +Whether to check intersection types (`&`). + +Examples of code with `{ "checkIntersections": true }` (the default): + + + +#### ❌ Incorrect + +```ts option='{ "checkIntersections": true }' +type ExampleIntersection = B & A; +``` + +#### ✅ Correct + +```ts option='{ "checkIntersections": true }' +type ExampleIntersection = A & B; +``` + +### `checkUnions` + +Whether to check union types (`|`). + +Examples of code with `{ "checkUnions": true }` (the default): + + + +#### ❌ Incorrect + +```ts option='{ "checkUnions": true }' +type ExampleUnion = B | A; +``` + +#### ✅ Correct + +```ts option='{ "checkUnions": true }' +type ExampleUnion = A | B; +``` + ### `groupOrder` Each constituent of the type is placed into a group, and then the rule sorts alphabetically within each group. @@ -100,6 +140,22 @@ The ordering of groups is determined by this option. - `union` - Union types (`A | B`) - `nullish` - `null` and `undefined` +For example, configuring the rule with `{ "groupOrder": ["literal", "nullish" ]}`: + + + +#### ❌ Incorrect + +```ts option='{ "groupOrder": ["literal", "nullish" ]}' +type ExampleGroup = null | 123; +``` + +#### ✅ Correct + +```ts option='{ "groupOrder": ["literal", "nullish" ]}' +type ExampleGroup = 123 | null; +``` + ## When Not To Use It This rule is purely a stylistic rule for maintaining consistency in your project. diff --git a/packages/eslint-plugin/docs/rules/triple-slash-reference.md b/packages/eslint-plugin/docs/rules/triple-slash-reference.md index 40509d8fe23..364d4f6063f 100644 --- a/packages/eslint-plugin/docs/rules/triple-slash-reference.md +++ b/packages/eslint-plugin/docs/rules/triple-slash-reference.md @@ -8,46 +8,94 @@ description: 'Disallow certain triple slash directives in favor of ES6-style imp TypeScript's `///` triple-slash references are a way to indicate that types from another module are available in a file. Use of triple-slash reference type directives is generally discouraged in favor of ECMAScript Module `import`s. -This rule reports on the use of `/// `, `/// `, or `/// ` directives. +This rule reports on the use of `/// `, `/// `, or `/// ` directives. ## Options -With `{ "path": "never", "types": "never", "lib": "never" }` options set, the following will all be **incorrect** usage: +Any number of the three kinds of references can be specified as an option. +Specifying `'always'` disables this lint rule for that kind of reference. -```ts option='{ "path": "never", "types": "never", "lib": "never" }' showPlaygroundButton -/// -/// -/// +### `lib` + +When set to `'never'`, bans `/// ` and enforces using an `import` instead: + + + +#### ❌ Incorrect + +```ts option='{ "lib": "never" }' +/// + +globalThis.value; +``` + +#### ✅ Correct + +```ts option='{ "lib": "never" }' +import { value } from 'code'; +``` + +### `path` + +When set to `'never'`, bans `/// ` and enforces using an `import` instead: + + + +#### ❌ Incorrect + +```ts option='{ "path": "never" }' +/// + +globalThis.value; ``` -Examples of **incorrect** code for the `{ "types": "prefer-import" }` option. Note that these are only errors when **both** styles are used for the **same** module: +#### ✅ Correct -```ts option='{ "types": "prefer-import" }' showPlaygroundButton -/// -import * as foo from 'foo'; +```ts option='{ "path": "never" }' +import { value } from 'code'; ``` -```ts option='{ "types": "prefer-import" }' showPlaygroundButton -/// -import foo = require('foo'); +### `types` + +When set to `'never'`, bans `/// ` and enforces using an `import` instead: + + + +#### ❌ Incorrect + +```ts option='{ "types": "never" }' +/// + +globalThis.value; ``` -With `{ "path": "always", "types": "always", "lib": "always" }` options set, the following will all be **correct** usage: +#### ✅ Correct -```ts option='{ "path": "always", "types": "always", "lib": "always" }' showPlaygroundButton -/// -/// -/// +```ts option='{ "types": "never" }' +import { value } from 'code'; ``` -Examples of **correct** code for the `{ "types": "prefer-import" }` option: + -```ts option='{ "types": "prefer-import" }' showPlaygroundButton -import * as foo from 'foo'; +The `types` option may alternately be given a `"prefer-import"` value. +Doing so indicates the rule should only report if there is already an `import` from the same location: + + + +#### ❌ Incorrect + +```ts option='{ "types": "prefer-import" }' +/// + +import { valueA } from 'code'; + +globalThis.valueB; ``` -```ts option='{ "types": "prefer-import" }' showPlaygroundButton -import foo = require('foo'); +#### ✅ Correct + +```ts option='{ "types": "prefer-import" }' +import { valueA, valueB } from 'code'; ``` ## When Not To Use It diff --git a/packages/eslint-plugin/tests/docs.test.ts b/packages/eslint-plugin/tests/docs.test.ts index 936467e17c2..b10ce6d7824 100644 --- a/packages/eslint-plugin/tests/docs.test.ts +++ b/packages/eslint-plugin/tests/docs.test.ts @@ -55,6 +55,9 @@ describe('Validating rule docs', () => { 'no-duplicate-imports.md', 'no-parameter-properties.md', ]); + + const rulesWithComplexOptions = new Set(['array-type', 'member-ordering']); + it('All rules must have a corresponding rule doc', () => { const files = fs .readdirSync(docsRoot) @@ -108,17 +111,19 @@ describe('Validating rule docs', () => { ); }); + const headings = tokens.filter(tokenIsHeading); + const requiredHeadings = ['When Not To Use It']; + const importantHeadings = new Set([ ...requiredHeadings, 'How to Use', 'Options', 'Related To', + 'When Not To Use It', ]); test('important headings must be h2s', () => { - const headings = tokens.filter(tokenIsHeading); - for (const heading of headings) { if (importantHeadings.has(heading.raw.replace(/#/g, '').trim())) { expect(heading.depth).toBe(2); @@ -146,6 +151,35 @@ describe('Validating rule docs', () => { } }); } + + const { schema } = rule.meta; + if ( + !rulesWithComplexOptions.has(ruleName) && + Array.isArray(schema) && + !rule.meta.docs?.extendsBaseRule && + rule.meta.type !== 'layout' + ) { + test('each rule option should be mentioned in a heading', () => { + const headingTextAfterOptions = headings + .slice(headings.findIndex(header => header.text === 'Options')) + .map(header => header.text) + .join('\n'); + + for (const schemaItem of schema) { + if (schemaItem.type === 'object') { + for (const property of Object.keys( + schemaItem.properties as object, + )) { + if (!headingTextAfterOptions.includes(`\`${property}\``)) { + throw new Error( + `At least one header should include \`${property}\`.`, + ); + } + } + } + } + }); + } }); } });