@typescript-eslint/eslint-plugin 8.33.1-alpha.5 → 8.33.1

package/docs/rules/consistent-type-imports.mdx

@@ -1,139 +0,0 @@
----
-description: 'Enforce consistent usage of type imports.'
----
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-> 🛑 This file is source code, not the primary documentation location! 🛑
->
-> See **https://typescript-eslint.io/rules/consistent-type-imports** for documentation.
-
-TypeScript allows specifying a `type` keyword on imports to indicate that the export exists only in the type system, not at runtime.
-This allows transpilers to drop imports without knowing the types of the dependencies.
-
-> See [Blog > Consistent Type Exports and Imports: Why and How](/blog/consistent-type-imports-and-exports-why-and-how) for more details.
-
-## Options
-
-### `prefer`
-
-{/* insert option description */}
-
-Valid values for `prefer` are:
-
-- `type-imports` will enforce that you always use `import type Foo from '...'` except referenced by metadata of decorators. It is the default.
-- `no-type-imports` will enforce that you always use `import Foo from '...'`.
-
-Examples of **correct** code with `{prefer: 'type-imports'}`, and **incorrect** code with `{prefer: 'no-type-imports'}`.
-
-```ts option='{ "prefer": "type-imports" }' showPlaygroundButton
-import type { Foo } from 'Foo';
-import type Bar from 'Bar';
-type T = Foo;
-const x: Bar = 1;
-```
-
-Examples of **incorrect** code with `{prefer: 'type-imports'}`, and **correct** code with `{prefer: 'no-type-imports'}`.
-
-```ts option='{ "prefer": "type-imports" }' showPlaygroundButton
-import { Foo } from 'Foo';
-import Bar from 'Bar';
-type T = Foo;
-const x: Bar = 1;
-```
-
-### `fixStyle`
-
-{/* insert option description */}
-
-Valid values for `fixStyle` are:
-
-- `separate-type-imports` will add the type keyword after the import keyword `import type { A } from '...'`. It is the default.
-- `inline-type-imports` will inline the type keyword `import { type A } from '...'` and is only available in TypeScript 4.5 and onwards. See [documentation here](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html#type-modifiers-on-import-names 'TypeScript 4.5 documentation on type modifiers and import names').
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-import { Foo } from 'Foo';
-import Bar from 'Bar';
-type T = Foo;
-const x: Bar = 1;
-```
-
-</TabItem>
-<TabItem value="✅ With `separate-type-imports`">
-
-```ts option='{ "fixStyle": "separate-type-imports" }'
-import type { Foo } from 'Foo';
-import type Bar from 'Bar';
-type T = Foo;
-const x: Bar = 1;
-```
-
-</TabItem>
-<TabItem value="✅ With `inline-type-imports`">
-
-```ts option='{ "fixStyle": "inline-type-imports" }'
-import { type Foo } from 'Foo';
-import type Bar from 'Bar';
-type T = Foo;
-const x: Bar = 1;
-```
-
-</TabItem>
-</Tabs>
-
-### `disallowTypeAnnotations`
-
-{/* insert option description */}
-
-Examples of **incorrect** code with `{disallowTypeAnnotations: true}`:
-
-```ts option='{ "disallowTypeAnnotations": true }' showPlaygroundButton
-type T = import('Foo').Foo;
-const x: import('Bar') = 1;
-```
-
-## Caveat: `@decorators` + `experimentalDecorators: true` + `emitDecoratorMetadata: true`
-
-:::note
-If you are using `experimentalDecorators: false` (eg [TypeScript v5.0's stable decorators](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-0.html#decorators)) then the rule will always report errors as expected.
-This caveat **only** applies to `experimentalDecorators: true`
-:::
-
-The rule will **_not_** report any errors in files _that contain decorators_ when **both** `experimentalDecorators` and `emitDecoratorMetadata` are turned on.
-
-> See [Blog > Changes to consistent-type-imports when used with legacy decorators and decorator metadata](/blog/changes-to-consistent-type-imports-with-decorators) for more details.
-
-If you are using [type-aware linting](/getting-started/typed-linting) then we will automatically infer your setup from your tsconfig and you should not need to configure anything.
-Otherwise you can explicitly tell our tooling to analyze your code as if the compiler option was turned on by setting both [`parserOptions.emitDecoratorMetadata = true`](/packages/parser/#emitdecoratormetadata) and [`parserOptions.experimentalDecorators = true`](/packages/parser/#experimentaldecorators).
-
-## Comparison with `importsNotUsedAsValues` / `verbatimModuleSyntax`
-
-[`verbatimModuleSyntax`](https://www.typescriptlang.org/tsconfig#verbatimModuleSyntax) was introduced in TypeScript v5.0 (as a replacement for `importsNotUsedAsValues`).
-This rule and `verbatimModuleSyntax` _mostly_ behave in the same way.
-There are a few behavior differences:
-| Situation | `consistent-type-imports` (ESLint) | `verbatimModuleSyntax` (TypeScript) |
-| -------------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------- |
-| Unused imports | Ignored (consider using [`@typescript-eslint/no-unused-vars`](/rules/no-unused-vars)) | Type error |
-| Usage with `emitDecoratorMetadata` & `experimentalDecorations` | Ignores files that contain decorators | Reports on files that contain decorators |
-| Failures detected | Does not fail `tsc` build; can be auto-fixed with `--fix` | Fails `tsc` build; cannot be auto-fixed on the command-line |
-| `import { type T } from 'T';` | TypeScript will emit nothing (it "elides" the import) | TypeScript emits `import {} from 'T'` |
-
-Because there are some differences, using both this rule and `verbatimModuleSyntax` at the same time can lead to conflicting errors.
-As such we recommend that you only ever use one _or_ the other -- never both.
-
-## When Not To Use It
-
-If you specifically want to use both import kinds for stylistic reasons, or don't wish to enforce one style over the other, you can avoid this rule.
-
-However, keep in mind that inconsistent style can harm readability in a project.
-We recommend picking a single option for this rule that works best for your project.
-
-## Related To
-
-- [`no-import-type-side-effects`](./no-import-type-side-effects.mdx)
-- [`import/consistent-type-specifier-style`](https://github.com/import-js/eslint-plugin-import/blob/main/docs/rules/consistent-type-specifier-style.md)
-- [`import/no-duplicates` with `{"prefer-inline": true}`](https://github.com/import-js/eslint-plugin-import/blob/main/docs/rules/no-duplicates.md#inline-type-imports)

package/docs/rules/default-param-last.mdx

@@ -1,59 +0,0 @@
----
-description: 'Enforce default parameters to be last.'
----
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-> 🛑 This file is source code, not the primary documentation location! 🛑
->
-> See **https://typescript-eslint.io/rules/default-param-last** for documentation.
-
-It adds support for optional parameters.
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-function f(a = 0, b: number) {}
-function f(a: number, b = 0, c: number) {}
-function f(a: number, b?: number, c: number) {}
-class Foo {
-  constructor(
-    public a = 10,
-    private b: number,
-  ) {}
-}
-class Foo {
-  constructor(
-    public a?: number,
-    private b: number,
-  ) {}
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-function f(a = 0) {}
-function f(a: number, b = 0) {}
-function f(a: number, b?: number) {}
-function f(a: number, b?: number, c = 0) {}
-function f(a: number, b = 0, c?: number) {}
-class Foo {
-  constructor(
-    public a,
-    private b = 0,
-  ) {}
-}
-class Foo {
-  constructor(
-    public a,
-    private b?: number,
-  ) {}
-}
-```
-
-</TabItem>
-</Tabs>

package/docs/rules/dot-notation.mdx

@@ -1,94 +0,0 @@
----
-description: 'Enforce dot notation whenever possible.'
----
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-> 🛑 This file is source code, not the primary documentation location! 🛑
->
-> See **https://typescript-eslint.io/rules/dot-notation** for documentation.
-
-It adds:
-
-- Support for optionally ignoring computed `private` and/or `protected` member access.
-- Compatibility with TypeScript's `noPropertyAccessFromIndexSignature` option.
-
-## Options
-
-This rule adds the following options:
-
-```ts
-interface Options extends BaseDotNotationOptions {
-  allowPrivateClassPropertyAccess?: boolean;
-  allowProtectedClassPropertyAccess?: boolean;
-  allowIndexSignaturePropertyAccess?: boolean;
-}
-
-const defaultOptions: Options = {
-  ...baseDotNotationDefaultOptions,
-  allowPrivateClassPropertyAccess: false,
-  allowProtectedClassPropertyAccess: false,
-  allowIndexSignaturePropertyAccess: false,
-};
-```
-
-If the TypeScript compiler option `noPropertyAccessFromIndexSignature` is set to `true`, then this rule always allows the use of square bracket notation to access properties of types that have a `string` index signature, even if `allowIndexSignaturePropertyAccess` is `false`.
-
-### `allowPrivateClassPropertyAccess`
-
-{/* insert option description */}
-
-This can be useful because TypeScript will report a type error on dot notation but not array notation.
-
-Example of a correct code when `allowPrivateClassPropertyAccess` is set to `true`:
-
-```ts option='{ "allowPrivateClassPropertyAccess": true }' showPlaygroundButton
-class X {
-  private priv_prop = 123;
-}
-
-const x = new X();
-x['priv_prop'] = 123;
-```
-
-### `allowProtectedClassPropertyAccess`
-
-{/* insert option description */}
-
-This can be useful because TypeScript will report a type error on dot notation but not array notation.
-
-Example of a correct code when `allowProtectedClassPropertyAccess` is set to `true`:
-
-```ts option='{ "allowProtectedClassPropertyAccess": true }' showPlaygroundButton
-class X {
-  protected protected_prop = 123;
-}
-
-const x = new X();
-x['protected_prop'] = 123;
-```
-
-### `allowIndexSignaturePropertyAccess`
-
-{/* insert option description */}
-
-Example of correct code when `allowIndexSignaturePropertyAccess` is set to `true`:
-
-```ts option='{ "allowIndexSignaturePropertyAccess": true }' showPlaygroundButton
-class X {
-  [key: string]: number;
-}
-
-const x = new X();
-x['hello'] = 123;
-```
-
-If the TypeScript compiler option `noPropertyAccessFromIndexSignature` is set to `true`, then the above code is always allowed, even if `allowIndexSignaturePropertyAccess` is `false`.
-
-## When Not To Use It
-
-If you specifically want to use both member access kinds for stylistic reasons, or don't wish to enforce one style over the other, you can avoid this rule.
-
-However, keep in mind that inconsistent style can harm readability in a project.
-We recommend picking a single option for this rule that works best for your project.

package/docs/rules/explicit-function-return-type.mdx

@@ -1,359 +0,0 @@
----
-description: 'Require explicit return types on functions and class methods.'
----
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-> 🛑 This file is source code, not the primary documentation location! 🛑
->
-> See **https://typescript-eslint.io/rules/explicit-function-return-type** for documentation.
-
-Functions in TypeScript often don't need to be given an explicit return type annotation.
-Leaving off the return type is less code to read or write and allows the compiler to infer it from the contents of the function.
-
-However, explicit return types do make it visually more clear what type is returned by a function.
-They can also speed up TypeScript type checking performance in large codebases with many large functions.
-
-This rule enforces that functions do have an explicit return type annotation.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-// Should indicate that no value is returned (void)
-function test() {
-  return;
-}
-
-// Should indicate that a number is returned
-var fn = function () {
-  return 1;
-};
-
-// Should indicate that a string is returned
-var arrowFn = () => 'test';
-
-class Test {
-  // Should indicate that no value is returned (void)
-  method() {
-    return;
-  }
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-// No return value should be expected (void)
-function test(): void {
-  return;
-}
-
-// A return value of type number
-var fn = function (): number {
-  return 1;
-};
-
-// A return value of type string
-var arrowFn = (): string => 'test';
-
-class Test {
-  // No return value should be expected (void)
-  method(): void {
-    return;
-  }
-}
-```
-
-</TabItem>
-</Tabs>
-
-## Options
-
-### Configuring in a mixed JS/TS codebase
-
-If you are working on a codebase within which you lint non-TypeScript code (i.e. `.js`/`.mjs`/`.cjs`/`.jsx`), you should ensure that you should use [ESLint `overrides`](https://eslint.org/docs/user-guide/configuring#disabling-rules-only-for-a-group-of-files) to only enable the rule on `.ts`/`.mts`/`.cts`/`.tsx` files. If you don't, then you will get unfixable lint errors reported within `.js`/`.mjs`/`.cjs`/`.jsx` files.
-
-```jsonc
-{
-  "rules": {
-    // disable the rule for all files
-    "@typescript-eslint/explicit-function-return-type": "off",
-  },
-  "overrides": [
-    {
-      // enable the rule specifically for TypeScript files
-      "files": ["*.ts", "*.mts", "*.cts", "*.tsx"],
-      "rules": {
-        "@typescript-eslint/explicit-function-return-type": "error",
-      },
-    },
-  ],
-}
-```
-
-### `allowExpressions`
-
-{/* insert option description */}
-
-Examples of code for this rule with `{ allowExpressions: true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "allowExpressions": true }'
-function test() {}
-
-const fn = () => {};
-
-export default () => {};
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "allowExpressions": true }'
-node.addEventListener('click', () => {});
-
-node.addEventListener('click', function () {});
-
-const foo = arr.map(i => i * i);
-```
-
-</TabItem>
-</Tabs>
-
-### `allowTypedFunctionExpressions`
-
-{/* insert option description */}
-
-Examples of code for this rule with `{ allowTypedFunctionExpressions: true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "allowTypedFunctionExpressions": true }'
-let arrowFn = () => 'test';
-
-let funcExpr = function () {
-  return 'test';
-};
-
-let objectProp = {
-  foo: () => 1,
-};
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "allowTypedFunctionExpressions": true }'
-type FuncType = () => string;
-
-let arrowFn: FuncType = () => 'test';
-
-let funcExpr: FuncType = function () {
-  return 'test';
-};
-
-let asTyped = (() => '') as () => string;
-
-interface ObjectType {
-  foo(): number;
-}
-let objectProp: ObjectType = {
-  foo: () => 1,
-};
-let objectPropAs = {
-  foo: () => 1,
-} as ObjectType;
-
-declare function functionWithArg(arg: () => number);
-functionWithArg(() => 1);
-
-declare function functionWithObjectArg(arg: { method: () => number });
-functionWithObjectArg({
-  method() {
-    return 1;
-  },
-});
-```
-
-</TabItem>
-</Tabs>
-
-### `allowHigherOrderFunctions`
-
-{/* insert option description */}
-
-Examples of code for this rule with `{ allowHigherOrderFunctions: true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "allowHigherOrderFunctions": true }'
-var arrowFn = () => () => {};
-
-function fn() {
-  return function () {};
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "allowHigherOrderFunctions": true }'
-var arrowFn = () => (): void => {};
-
-function fn() {
-  return function (): void {};
-}
-```
-
-</TabItem>
-</Tabs>
-
-### `allowDirectConstAssertionInArrowFunctions`
-
-{/* insert option description */}
-
-Examples of code for this rule with `{ allowDirectConstAssertionInArrowFunctions: true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "allowDirectConstAssertionInArrowFunctions": true }'
-const func = (value: number) => ({ type: 'X', value }) as any;
-const func = (value: number) => ({ type: 'X', value }) as Action;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "allowDirectConstAssertionInArrowFunctions": true }'
-const func = (value: number) => ({ foo: 'bar', value }) as const;
-const func = () => x as const;
-```
-
-</TabItem>
-</Tabs>
-
-### `allowConciseArrowFunctionExpressionsStartingWithVoid`
-
-{/* insert option description */}
-
-Examples of code for this rule with `{ allowConciseArrowFunctionExpressionsStartingWithVoid: true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "allowConciseArrowFunctionExpressionsStartingWithVoid": true }'
-var join = (a: string, b: string) => `${a}${b}`;
-
-const log = (message: string) => {
-  console.log(message);
-};
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "allowConciseArrowFunctionExpressionsStartingWithVoid": true }'
-var log = (message: string) => void console.log(message);
-```
-
-</TabItem>
-</Tabs>
-
-### `allowFunctionsWithoutTypeParameters`
-
-{/* insert option description */}
-
-Examples of code for this rule with `{ allowFunctionsWithoutTypeParameters: true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "allowFunctionsWithoutTypeParameters": true }'
-function foo<T>(t: T) {
-  return t;
-}
-
-const bar = <T>(t: T) => t;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "allowFunctionsWithoutTypeParameters": true }'
-function foo<T>(t: T): T {
-  return t;
-}
-
-const bar = <T>(t: T): T => t;
-
-function allowedFunction(x: string) {
-  return x;
-}
-
-const allowedArrow = (x: string) => x;
-```
-
-</TabItem>
-</Tabs>
-
-### `allowedNames`
-
-{/* insert option description */}
-
-You may pass function/method names you would like this rule to ignore, like so:
-
-```json
-{
-  "@typescript-eslint/explicit-function-return-type": [
-    "error",
-    {
-      "allowedNames": ["ignoredFunctionName", "ignoredMethodName"]
-    }
-  ]
-}
-```
-
-### `allowIIFEs`
-
-{/* insert option description */}
-
-Examples of code for this rule with `{ allowIIFEs: true }`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "allowIIFEs": true }'
-var func = () => 'foo';
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "allowIIFEs": true }'
-var foo = (() => 'foo')();
-
-var bar = (function () {
-  return 'bar';
-})();
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-If you don't find the added cost of explicitly writing function return types to be worth the visual clarity, or your project is not large enough for it to be a factor in type checking performance, then you will not need this rule.
-
-## Further Reading
-
-- TypeScript [Functions](https://www.typescriptlang.org/docs/handbook/functions.html#function-types)