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

package/docs/rules/no-unsafe-type-assertion.mdx

@@ -1,63 +0,0 @@
----
-description: 'Disallow type assertions that narrow a type.'
----
-
-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/no-unsafe-type-assertion** for documentation.
-
-Type assertions are a way to tell TypeScript what the type of a value is. This can be useful but also unsafe if you use type assertions to narrow down a type.
-
-This rule forbids using type assertions to narrow a type, as this bypasses TypeScript's type-checking. Type assertions that broaden a type are safe because TypeScript essentially knows _less_ about a type.
-
-Instead of using type assertions to narrow a type, it's better to rely on type guards, which help avoid potential runtime errors caused by unsafe type assertions.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-function f() {
-  return Math.random() < 0.5 ? 42 : 'oops';
-}
-
-const z = f() as number;
-
-const items = [1, '2', 3, '4'];
-
-const number = items[0] as number;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-function f() {
-  return Math.random() < 0.5 ? 42 : 'oops';
-}
-
-const z = f() as number | string | boolean;
-
-const items = [1, '2', 3, '4'];
-
-const number = items[0] as number | string | undefined;
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-If your codebase has many unsafe type assertions, then it may be difficult to enable this rule.
-It may be easier to skip the `no-unsafe-*` rules pending increasing type safety in unsafe areas of your project.
-You might consider using [ESLint disable comments](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1) for those specific situations instead of completely disabling this rule.
-
-If your project frequently stubs objects in test files, the rule may trigger a lot of reports. Consider disabling the rule for such files to reduce frequent warnings.
-
-## Further Reading
-
-- More on TypeScript's [type assertions](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#type-assertions)

package/docs/rules/no-unsafe-unary-minus.mdx

@@ -1,60 +0,0 @@
----
-description: 'Require unary negation to take a number.'
----
-
-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/no-unsafe-unary-minus** for documentation.
-
-TypeScript does not prevent you from putting a minus sign before things other than numbers:
-
-```ts
-const s = 'hello';
-const x = -s; // x is NaN
-```
-
-This rule restricts the unary `-` operator to `number | bigint`.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-declare const a: string;
--a;
-
-declare const b: {};
--b;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
--42;
--42n;
-
-declare const a: number;
--a;
-
-declare const b: number;
--b;
-
-declare const c: number | bigint;
--c;
-
-declare const d: any;
--d;
-
-declare const e: 1 | 2;
--e;
-```
-
-</TabItem>
-</Tabs>
-
-{/* Intentionally Omitted: When Not To Use It */}

package/docs/rules/no-unused-expressions.mdx

@@ -1,52 +0,0 @@
----
-description: 'Disallow unused expressions.'
----
-
-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/no-unused-expressions** for documentation.
-
-It supports TypeScript-specific expressions:
-
-- Marks directives in modules declarations (`"use strict"`, etc.) as not unused
-- Marks the following expressions as unused if their wrapped value expressions are unused:
-  - Assertion expressions: `x as number;`, `x!;`, `<number>x;`
-  - Instantiation expressions: `Set<number>;`
-
-Although the type expressions never have runtime side effects (that is, `x!;` is the same as `x;`), they can be used to assert types for testing purposes.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-Set<number>;
-1 as number;
-window!;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-function getSet() {
-  return Set;
-}
-
-// Funtion calls are allowed, so type expressions that wrap function calls are allowed
-getSet()<number>;
-getSet() as Set<unknown>;
-getSet()!;
-
-// Namespaces can have directives
-namespace A {
-  'use strict';
-}
-```
-
-</TabItem>
-</Tabs>

package/docs/rules/no-unused-vars.mdx

@@ -1,136 +0,0 @@
----
-description: 'Disallow unused variables.'
----
-
-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/no-unused-vars** for documentation.
-
-It adds support for TypeScript features, such as types.
-
-## Options
-
-## FAQs
-
-### What benefits does this rule have over TypeScript?
-
-TypeScript provides [`noUnusedLocals`](https://www.typescriptlang.org/tsconfig#noUnusedLocals) and [`noUnusedParameters`](https://www.typescriptlang.org/tsconfig#noUnusedParameters) compiler options that can report errors on unused local variables or parameters, respectively.
-Those compiler options can be convenient to use if you don't want to set up ESLint and typescript-eslint.
-However:
-
-- These lint rules are more configurable than TypeScript's compiler options.
-  - For example, the [`varsIgnorePattern` option](https://eslint.org/docs/latest/rules/no-unused-vars#varsignorepattern) can customize what names are always allowed to be exempted. TypeScript hardcodes its exemptions to names starting with `_`.
-    If you would like to emulate the TypeScript style of exempting names starting with `_`, you can use this configuration (this includes errors as well):
-    ```json
-    {
-      "rules": {
-        "@typescript-eslint/no-unused-vars": [
-          "error",
-          {
-            "args": "all",
-            "argsIgnorePattern": "^_",
-            "caughtErrors": "all",
-            "caughtErrorsIgnorePattern": "^_",
-            "destructuredArrayIgnorePattern": "^_",
-            "varsIgnorePattern": "^_",
-            "ignoreRestSiblings": true
-          }
-        ]
-      }
-    }
-    ```
-- [ESLint can be configured](https://eslint.org/docs/latest/use/configure/rules) within lines, files, and folders. TypeScript compiler options are linked to their TSConfig file.
-- Many projects configure TypeScript's reported errors to block builds more aggressively than ESLint complaints. Blocking builds on unused variables can be inconvenient.
-
-We generally recommend using `@typescript-eslint/no-unused-vars` to flag unused locals and parameters instead of TypeScript.
-
-:::tip
-Editors such as VS Code will still generally "grey out" unused variables even if `noUnusedLocals` and `noUnusedParameters` are not enabled in a project.
-:::
-
-Also see similar rules provided by ESLint:
-
-- [`no-unused-private-class-members`](https://eslint.org/docs/latest/rules/no-unused-private-class-members)
-- [`no-unused-labels`](https://eslint.org/docs/latest/rules/no-unused-labels)
-
-### Why does this rule report variables used only for types?
-
-This rule does not count type-only uses when determining whether a variable is used.
-Declaring variables only to use them for types adds code and runtime complexity.
-The variables are never actually used at runtime.
-They can be misleading to readers of the code.
-
-<Tabs>
-
-<TabItem value="typeof Variables">
-
-For example, if a variable is only used for `typeof`, this rule will report:
-
-```ts
-const box = {
-  //  ~~~
-  //  'box' is assigned a value but only used as a type.
-  value: 123,
-};
-
-export type Box = typeof box;
-```
-
-Instead, it's often cleaner and less code to write out the types directly:
-
-```ts
-export interface Box {
-  value: number;
-}
-```
-
-</TabItem>
-
-<TabItem value="Zod Schemas">
-
-For example, if a Zod schema variable is only used for `typeof`, this rule will report:
-
-```ts
-import { z } from 'zod';
-
-const schema = z.object({
-  //  ~~~~~~
-  //  'schema' is assigned a value but only used as a type.
-  value: z.number(),
-});
-
-export type Box = z.infer<typeof schema>;
-```
-
-Instead, it's often cleaner and less code to write out the types directly:
-
-```ts
-export interface Box {
-  value: number;
-}
-```
-
-</TabItem>
-
-</Tabs>
-
-If you find yourself writing runtime values only for types, consider refactoring your code to declare types directly.
-
-### Why are variables reported as unused despite being referenced by @link in JSDoc?
-
-JSDoc references are not supported by typescript-eslint.
-You can use a rule such as [`jsdoc/no-undefined-types`](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-undefined-types.md) to resolve variables as used in JSDoc comments.
-
-```ts
-import type { Box } from './Box';
-//            ~~~
-//            'Box' is defined but never used.
-
-/**
- * @see {@link Box}
- */
-export function getBox() {}
-```

package/docs/rules/no-use-before-define.mdx

@@ -1,98 +0,0 @@
----
-description: 'Disallow the use of variables before they are defined.'
----
-
-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/no-use-before-define** for documentation.
-
-It adds support for `type`, `interface` and `enum` declarations.
-
-## Options
-
-This rule adds the following options:
-
-```ts
-interface Options extends BaseNoUseBeforeDefineOptions {
-  enums?: boolean;
-  typedefs?: boolean;
-  ignoreTypeReferences?: boolean;
-}
-
-const defaultOptions: Options = {
-  ...baseNoUseBeforeDefineDefaultOptions,
-  enums: true,
-  typedefs: true,
-  ignoreTypeReferences: true,
-};
-```
-
-### `enums`
-
-{/* insert option description */}
-
-If this is `true`, this rule warns every reference to a enum before the enum declaration.
-If this is `false`, this rule will ignore references to enums, when the reference is in a child scope.
-
-Examples of code for the `{ "enums": true }` option:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "enums": true }'
-const x = Foo.FOO;
-
-enum Foo {
-  FOO,
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "enums": false }'
-function foo() {
-  return Foo.FOO;
-}
-
-enum Foo {
-  FOO,
-}
-```
-
-</TabItem>
-</Tabs>
-
-### `typedefs`
-
-{/* insert option description */}
-
-If this is `true`, this rule warns every reference to a type before the type declaration.
-If this is `false`, this rule will ignore references to types.
-
-Examples of **correct** code for the `{ "typedefs": false }` option:
-
-```ts option='{ "typedefs": false }' showPlaygroundButton
-let myVar: StringOrNumber;
-type StringOrNumber = string | number;
-```
-
-### `ignoreTypeReferences`
-
-{/* insert option description */}
-
-If this is `true`, this rule ignores all type references.
-If this is `false`, this will check all type references.
-
-Examples of **correct** code for the `{ "ignoreTypeReferences": true }` option:
-
-```ts option='{ "ignoreTypeReferences": true }' showPlaygroundButton
-let var1: StringOrNumber;
-type StringOrNumber = string | number;
-
-let var2: Enum;
-enum Enum {}
-```

package/docs/rules/no-useless-constructor.mdx

@@ -1,21 +0,0 @@
----
-description: 'Disallow unnecessary constructors.'
----
-
-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/no-useless-constructor** for documentation.
-
-It adds support for:
-
-- 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.
-
-### Caveat
-
-This lint rule will report on constructors whose sole purpose is to change visibility of a parent constructor.
-See [discussion on this rule's lack of type information](https://github.com/typescript-eslint/typescript-eslint/issues/3820#issuecomment-917821240) for context.

package/docs/rules/no-useless-empty-export.mdx

@@ -1,53 +0,0 @@
----
-description: "Disallow empty exports that don't change anything in a module file."
----
-
-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/no-useless-empty-export** for documentation.
-
-An empty `export {}` statement is sometimes useful in TypeScript code to turn a file that would otherwise be a script file into a module file.
-Per the [TypeScript Handbook Modules page](https://www.typescriptlang.org/docs/handbook/modules.html):
-
-> In TypeScript, just as in ECMAScript 2015, any file containing a top-level import or export is considered a module.
-> Conversely, a file without any top-level import or export declarations is treated as a script whose contents are available in the global scope (and therefore to modules as well).
-
-However, an `export {}` statement does nothing if there are any other top-level import or export statements in a file.
-
-This rule reports an `export {}` that doesn't do anything in a file already using ES modules.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-export const value = 'Hello, world!';
-export {};
-```
-
-```ts
-import 'some-other-module';
-export {};
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-export const value = 'Hello, world!';
-```
-
-```ts
-import 'some-other-module';
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-If you don't mind an empty `export {}` at the bottom of files, you likely don't need this rule.

package/docs/rules/no-useless-template-literals.mdx

@@ -1,9 +0,0 @@
----
-displayed_sidebar: rulesSidebar
----
-
-:::danger Deprecated
-
-This rule has been renamed to [`no-unnecessary-template-expression`](./no-unnecessary-template-expression.mdx). See [#8544](https://github.com/typescript-eslint/typescript-eslint/issues/8544) for more information.
-
-:::

package/docs/rules/no-var-requires.mdx

@@ -1,77 +0,0 @@
----
-description: 'Disallow `require` statements except in import statements.'
----
-
-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/no-var-requires** for documentation.
-
-:::danger Deprecated
-
-This rule has been deprecated in favour of the [`@typescript-eslint/no-require-imports`](./no-require-imports.mdx) rule.
-
-:::
-
-In other words, the use of forms such as `var foo = require("foo")` are banned. Instead use ES6 style imports or `import foo = require("foo")` imports.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-var foo = require('foo');
-const foo = require('foo');
-let foo = require('foo');
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-import foo = require('foo');
-require('foo');
-import foo from 'foo';
-```
-
-</TabItem>
-</Tabs>
-
-## Options
-
-### `allow`
-
-{/* insert option description */}
-
-A array of strings. These strings will be compiled into regular expressions with the `u` flag and be used to test against the imported path. A common use case is to allow importing `package.json`. This is because `package.json` commonly lives outside of the TS root directory, so statically importing it would lead to root directory conflicts, especially with `resolveJsonModule` enabled. You can also use it to allow importing any JSON if your environment doesn't support JSON modules, or use it for other cases where `import` statements cannot work.
-
-With `{allow: ['/package\\.json$']}`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "allow": ["/package.json$"] }'
-const foo = require('../data.json');
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "allow": ["/package.json$"] }'
-const foo = require('../package.json');
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-If your project frequently uses older CommonJS `require`s, then this rule might not be applicable to you.
-If only a subset of your project uses `require`s then you might consider using [ESLint disable comments](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1) for those specific situations instead of completely disabling this rule.
-
-## Related To
-
-- [`no-require-imports`](./no-require-imports.mdx)

package/docs/rules/no-wrapper-object-types.mdx

@@ -1,75 +0,0 @@
----
-description: 'Disallow using confusing built-in primitive class wrappers.'
----
-
-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/no-wrapper-object-types** for documentation.
-
-TypeScript defines several confusing pairs of types that look very similar to each other, but actually mean different things: `boolean`/`Boolean`, `number`/`Number`, `string`/`String`, `bigint`/`BigInt`, `symbol`/`Symbol`, `object`/`Object`.
-In general, only the lowercase variant is appropriate to use.
-Therefore, this rule enforces that you only use the lowercase variant.
-
-JavaScript has [8 data types](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures) at runtime, and these are described in TypeScript by the lowercase types `undefined`, `null`, `boolean`, `number`, `string`, `bigint`, `symbol`, and `object`.
-
-As for the uppercase types, these are _structural types_ which describe JavaScript "wrapper" objects for each of the data types, such as [`Boolean`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) and [`Number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number).
-Additionally, due to the quirks of structural typing, the corresponding primitives are _also_ assignable to these uppercase types, since they have the same "shape".
-
-It is a universal best practice to work directly with the built-in primitives, like `0`, rather than objects that "look like" the corresponding primitive, like `new Number(0)`.
-
-- Primitives have the expected value semantics with `==` and `===` equality checks, whereas their object counterparts are compared by reference.
-  That is to say, `"str" === "str"` but `new String("str") !== new String("str")`.
-- Primitives have well-known behavior around truthiness/falsiness which is common to rely on, whereas all objects are truthy, regardless of the wrapped value (e.g. `new Boolean(false)` is truthy).
-- TypeScript only allows arithmetic operations (e.g. `x - y`) to be performed on numeric primitives, not objects.
-
-As a result, using the lowercase type names like `number` in TypeScript types instead of the uppercase names like `Number` is a better practice that describes code more accurately.
-
-Examples of code for this rule:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-let myBigInt: BigInt;
-let myBoolean: Boolean;
-let myNumber: Number;
-let myString: String;
-let mySymbol: Symbol;
-
-let myObject: Object = 'allowed by TypeScript';
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-let myBigint: bigint;
-let myBoolean: boolean;
-let myNumber: number;
-let myString: string;
-let mySymbol: symbol;
-
-let myObject: object = "Type 'string' is not assignable to type 'object'.";
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-If your project is a rare one that intentionally deals with the class equivalents of primitives, it might not be worthwhile to use this rule.
-You might consider using [ESLint disable comments](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1) for those specific situations instead of completely disabling this rule.
-
-## Further Reading
-
-- [MDN documentation on primitives](https://developer.mozilla.org/en-US/docs/Glossary/Primitive)
-- [MDN documentation on `string` primitives and `String` objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_primitives_and_string_objects)
-
-## Related To
-
-- [`no-empty-object-type`](./no-empty-object-type.mdx)
-- [`no-restricted-types`](./no-restricted-types.mdx)
-- [`no-unsafe-function-type`](./no-unsafe-function-type.mdx)