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

package/docs/rules/no-extra-non-null-assertion.mdx

@@ -1,60 +0,0 @@
----
-description: 'Disallow extra non-null assertions.'
----
-
-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-extra-non-null-assertion** for documentation.
-
-The `!` non-null assertion operator in TypeScript is used to assert that a value's type does not include `null` or `undefined`.
-Using the operator any more than once on a single value does nothing.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-const foo: { bar: number } | null = null;
-const bar = foo!!!.bar;
-```
-
-```ts
-function foo(bar: number | undefined) {
-  const bar: number = bar!!!;
-}
-```
-
-```ts
-function foo(bar?: { n: number }) {
-  return bar!?.n;
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-const foo: { bar: number } | null = null;
-const bar = foo!.bar;
-```
-
-```ts
-function foo(bar: number | undefined) {
-  const bar: number = bar!;
-}
-```
-
-```ts
-function foo(bar?: { n: number }) {
-  return bar?.n;
-}
-```
-
-</TabItem>
-</Tabs>
-
-{/* Intentionally Omitted: When Not To Use It */}

package/docs/rules/no-extra-parens.md

@@ -1,15 +0,0 @@
----
-displayed_sidebar: rulesSidebar
----
-
-:::danger Deprecated
-
-This rule has been moved to the [ESLint stylistic plugin](https://eslint.style).
-See [#8072](https://github.com/typescript-eslint/typescript-eslint/issues/8072) and [#8074](https://github.com/typescript-eslint/typescript-eslint/issues/8074) for more information.
-
-:::
-
-<!-- This doc file has been left on purpose to help direct people to the stylistic plugin.
-
-Note that there is no actual way to get to this page in the normal navigation,
-so end-users will only be able to get to this page from the search bar. -->

package/docs/rules/no-extra-semi.md

@@ -1,15 +0,0 @@
----
-displayed_sidebar: rulesSidebar
----
-
-:::danger Deprecated
-
-This rule has been moved to the [ESLint stylistic plugin](https://eslint.style).
-See [#8072](https://github.com/typescript-eslint/typescript-eslint/issues/8072) and [#8074](https://github.com/typescript-eslint/typescript-eslint/issues/8074) for more information.
-
-:::
-
-<!-- This doc file has been left on purpose to help direct people to the stylistic plugin.
-
-Note that there is no actual way to get to this page in the normal navigation,
-so end-users will only be able to get to this page from the search bar. -->

package/docs/rules/no-extraneous-class.mdx

@@ -1,329 +0,0 @@
----
-description: 'Disallow classes used as namespaces.'
----
-
-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-extraneous-class** for documentation.
-
-This rule reports when a class has no non-static members, such as for a class used exclusively as a static namespace.
-
-Users who come from a [OOP](https://en.wikipedia.org/wiki/Object-oriented_programming) paradigm may wrap their utility functions in an extra class, instead of putting them at the top level of an ECMAScript module.
-Doing so is generally unnecessary in JavaScript and TypeScript projects.
-
-- Wrapper classes add extra cognitive complexity to code without adding any structural improvements
-  - Whatever would be put on them, such as utility functions, are already organized by virtue of being in a module.
-  - As an alternative, you can `import * as ...` the module to get all of them in a single object.
-- IDEs can't provide as good suggestions for static class or namespace imported properties when you start typing property names
-- It's more difficult to statically analyze code for unused variables, etc. when they're all on the class (see: [Finding dead code (and dead types) in TypeScript](https://effectivetypescript.com/2020/10/20/tsprune)).
-
-This rule also reports classes that have only a constructor and no fields.
-Those classes can generally be replaced with a standalone function.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-class StaticConstants {
-  static readonly version = 42;
-
-  static isProduction() {
-    return process.env.NODE_ENV === 'production';
-  }
-}
-
-class HelloWorldLogger {
-  constructor() {
-    console.log('Hello, world!');
-  }
-}
-
-abstract class Foo {}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-export const version = 42;
-
-export function isProduction() {
-  return process.env.NODE_ENV === 'production';
-}
-
-function logHelloWorld() {
-  console.log('Hello, world!');
-}
-
-abstract class Foo {
-  abstract prop: string;
-}
-```
-
-</TabItem>
-</Tabs>
-
-## Alternatives
-
-### Individual Exports (Recommended)
-
-Instead of using a static utility class we recommend you individually export the utilities from your module.
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-export class Utilities {
-  static util1() {
-    return Utilities.util3();
-  }
-
-  static util2() {
-    /* ... */
-  }
-
-  static util3() {
-    /* ... */
-  }
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-export function util1() {
-  return util3();
-}
-
-export function util2() {
-  /* ... */
-}
-
-export function util3() {
-  /* ... */
-}
-```
-
-</TabItem>
-</Tabs>
-
-### Namespace Imports (Not Recommended)
-
-If you strongly prefer to have all constructs from a module available as properties of a single object, you can `import * as` the module.
-This is known as a "namespace import".
-Namespace imports are sometimes preferable because they keep all properties nested and don't need to be changed as you start or stop using various properties from the module.
-
-However, namespace imports are impacted by these downsides:
-
-- They also don't play as well with tree shaking in modern bundlers
-- They require a name prefix before each property's usage
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-// utilities.ts
-export class Utilities {
-  static sayHello() {
-    console.log('Hello, world!');
-  }
-}
-
-// consumers.ts
-import { Utilities } from './utilities';
-
-Utilities.sayHello();
-```
-
-</TabItem>
-<TabItem value="⚠️ Namespace Imports">
-
-```ts
-// utilities.ts
-export function sayHello() {
-  console.log('Hello, world!');
-}
-
-// consumers.ts
-import * as utilities from './utilities';
-
-utilities.sayHello();
-```
-
-</TabItem>
-<TabItem value="✅ Standalone Imports">
-
-```ts
-// utilities.ts
-export function sayHello() {
-  console.log('Hello, world!');
-}
-
-// consumers.ts
-import { sayHello } from './utilities';
-
-sayHello();
-```
-
-</TabItem>
-</Tabs>
-
-### Notes on Mutating Variables
-
-One case you need to be careful of is exporting mutable variables.
-While class properties can be mutated externally, exported variables are always constant.
-This means that importers can only ever read the first value they are assigned and cannot write to the variables.
-
-Needing to write to an exported variable is very rare and is generally considered a code smell.
-If you do need it you can accomplish it using getter and setter functions:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-export class Utilities {
-  static mutableCount = 1;
-
-  static incrementCount() {
-    Utilities.mutableCount += 1;
-  }
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-let mutableCount = 1;
-
-export function getMutableCount() {
-  return mutableField;
-}
-
-export function incrementCount() {
-  mutableField += 1;
-}
-```
-
-</TabItem>
-</Tabs>
-
-## Options
-
-This rule normally bans classes that are empty (have no constructor or fields).
-The rule's options each add an exemption for a specific type of class.
-
-### `allowConstructorOnly`
-
-{/* insert option description */}
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "allowConstructorOnly": true }'
-class NoFields {}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "allowConstructorOnly": true }'
-class NoFields {
-  constructor() {
-    console.log('Hello, world!');
-  }
-}
-```
-
-</TabItem>
-</Tabs>
-
-### `allowEmpty`
-
-{/* insert option description */}
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "allowEmpty": true }'
-class NoFields {
-  constructor() {
-    console.log('Hello, world!');
-  }
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "allowEmpty": true }'
-class NoFields {}
-```
-
-</TabItem>
-</Tabs>
-
-### `allowStaticOnly`
-
-{/* insert option description */}
-
-:::caution
-We strongly recommend against the `allowStaticOnly` exemption.
-It works against this rule's primary purpose of discouraging classes used only for static members.
-:::
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "allowStaticOnly": true }'
-class EmptyClass {}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "allowStaticOnly": true }'
-class NotEmptyClass {
-  static version = 42;
-}
-```
-
-</TabItem>
-</Tabs>
-
-### `allowWithDecorator`
-
-{/* insert option description */}
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "allowWithDecorator": true }'
-class Constants {
-  static readonly version = 42;
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "allowWithDecorator": true }'
-@logOnRead()
-class Constants {
-  static readonly version = 42;
-}
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-If your project was set up before modern class and namespace practices, and you don't have the time to switch over, you might not be practically able 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.

package/docs/rules/no-floating-promises.mdx

@@ -1,282 +0,0 @@
----
-description: 'Require Promise-like statements to be handled appropriately.'
----
-
-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-floating-promises** for documentation.
-
-A "floating" Promise is one that is created without any code set up to handle any errors it might throw.
-Floating Promises can cause several issues, such as improperly sequenced operations, ignored Promise rejections, and more.
-
-This rule will report Promise-valued statements that are not treated in one of the following ways:
-
-- Calling its `.then()` with two arguments
-- Calling its `.catch()` with one argument
-- `await`ing it
-- `return`ing it
-- [`void`ing it](#ignorevoid)
-
-This rule also reports when an Array containing Promises is created and not properly handled. The main way to resolve this is by using one of the Promise concurrency methods to create a single Promise, then handling that according to the procedure above. These methods include:
-
-- `Promise.all()`
-- `Promise.allSettled()`
-- `Promise.any()`
-- `Promise.race()`
-
-:::tip
-`no-floating-promises` only detects apparently unhandled Promise _statements_.
-See [`no-misused-promises`](./no-misused-promises.mdx) for detecting code that provides Promises to _logical_ locations such as if statements.
-
-See [_Using promises (error handling) on MDN_](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises#error_handling) for a detailed writeup on Promise error-handling.
-:::
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-const promise = new Promise((resolve, reject) => resolve('value'));
-promise;
-
-async function returnsPromise() {
-  return 'value';
-}
-returnsPromise().then(() => {});
-
-Promise.reject('value').catch();
-
-Promise.reject('value').finally();
-
-[1, 2, 3].map(async x => x + 1);
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-const promise = new Promise((resolve, reject) => resolve('value'));
-await promise;
-
-async function returnsPromise() {
-  return 'value';
-}
-
-void returnsPromise();
-
-returnsPromise().then(
-  () => {},
-  () => {},
-);
-
-Promise.reject('value').catch(() => {});
-
-await Promise.reject('value').finally(() => {});
-
-await Promise.all([1, 2, 3].map(async x => x + 1));
-```
-
-</TabItem>
-</Tabs>
-
-## Options
-
-### `checkThenables`
-
-{/* insert option description */}
-
-A ["Thenable"](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#thenables) value is an object which has a `then` method, such as a `Promise`.
-Other Thenables include TypeScript's built-in `PromiseLike` interface and any custom object that happens to have a `.then()`.
-
-The `checkThenables` option triggers `no-floating-promises` to also consider all values that satisfy the Thenable shape (a `.then()` method that takes two callback parameters), not just Promises.
-This can be useful if your code works with older `Promise` polyfills instead of the native `Promise` class.
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{"checkThenables": true}'
-declare function createPromiseLike(): PromiseLike<string>;
-
-createPromiseLike();
-
-interface MyThenable {
-  then(onFulfilled: () => void, onRejected: () => void): MyThenable;
-}
-
-declare function createMyThenable(): MyThenable;
-
-createMyThenable();
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{"checkThenables": true}'
-declare function createPromiseLike(): PromiseLike<string>;
-
-await createPromiseLike();
-
-interface MyThenable {
-  then(onFulfilled: () => void, onRejected: () => void): MyThenable;
-}
-
-declare function createMyThenable(): MyThenable;
-
-await createMyThenable();
-```
-
-</TabItem>
-</Tabs>
-
-### `ignoreVoid`
-
-{/* insert option description */}
-
-Placing the [`void` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/void) in front of a Promise can be a convenient way to explicitly mark that Promise as intentionally not awaited.
-
-:::warning
-Voiding a Promise doesn't handle it or change the runtime behavior.
-The outcome is just ignored, like disabling the rule with an [ESLint disable comment](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1).
-Such Promise rejections will still be unhandled.
-:::
-
-Examples of **correct** code for this rule with `{ ignoreVoid: true }`:
-
-```ts option='{ "ignoreVoid": true }' showPlaygroundButton
-async function returnsPromise() {
-  return 'value';
-}
-void returnsPromise();
-
-void Promise.reject('value');
-```
-
-When this option is set to `true`, if you are using `no-void`, you should turn on the [`allowAsStatement`](https://eslint.org/docs/rules/no-void#allowasstatement) option.
-
-### `ignoreIIFE`
-
-{/* insert option description */}
-
-Examples of **correct** code for this rule with `{ ignoreIIFE: true }`:
-
-{/* prettier-ignore */}
-```ts option='{ "ignoreIIFE": true }' showPlaygroundButton
-await (async function () {
-  await res(1);
-})();
-
-(async function () {
-  await res(1);
-})();
-```
-
-### `allowForKnownSafePromises`
-
-{/* insert option description */}
-
-For example, you may need to do this in the case of libraries whose APIs return Promises whose rejections are safely handled by the library.
-
-This option takes the shared [`TypeOrValueSpecifier` format](/packages/type-utils/type-or-value-specifier).
-
-Examples of code for this rule with:
-
-```json
-{
-  "allowForKnownSafePromises": [
-    { "from": "file", "name": "SafePromise" },
-    { "from": "lib", "name": "PromiseLike" },
-    { "from": "package", "name": "Bar", "package": "bar-lib" }
-  ]
-}
-```
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{"allowForKnownSafePromises":[{"from":"file","name":"SafePromise"},{"from":"lib","name":"PromiseLike"},{"from":"package","name":"Bar","package":"bar-lib"}]}'
-let promise: Promise<number> = Promise.resolve(2);
-promise;
-
-function returnsPromise(): Promise<number> {
-  return Promise.resolve(42);
-}
-
-returnsPromise();
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{"allowForKnownSafePromises":[{"from":"file","name":"SafePromise"},{"from":"lib","name":"PromiseLike"},{"from":"package","name":"Bar","package":"bar-lib"}]}'
-// promises can be marked as safe by using branded types
-type SafePromise = Promise<number> & { __linterBrands?: string };
-
-let promise: SafePromise = Promise.resolve(2);
-promise;
-
-function returnsSafePromise(): SafePromise {
-  return Promise.resolve(42);
-}
-
-returnsSafePromise();
-```
-
-</TabItem>
-</Tabs>
-
-### `allowForKnownSafeCalls`
-
-{/* insert option description */}
-
-For example, you may need to do this in the case of libraries whose APIs may be called without handling the resultant Promises.
-
-This option takes the shared [`TypeOrValueSpecifier` format](/packages/type-utils/type-or-value-specifier).
-
-Examples of code for this rule with:
-
-```json
-{
-  "allowForKnownSafeCalls": [
-    { "from": "file", "name": "safe", "path": "input.ts" }
-  ]
-}
-```
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{"allowForKnownSafeCalls":[{"from":"file","name":"safe","path":"input.ts"}]}'
-declare function unsafe(...args: unknown[]): Promise<void>;
-
-unsafe('...', () => {});
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{"allowForKnownSafeCalls":[{"from":"file","name":"safe","path":"input.ts"}]}' skipValidation
-declare function safe(...args: unknown[]): Promise<void>;
-
-safe('...', () => {});
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-This rule can be difficult to enable on large existing projects that set up many floating Promises.
-Alternately, if you're not worried about crashes from floating or misused Promises -such as if you have global unhandled Promise handlers registered- then in some cases it may be safe to not use this rule.
-You might consider using `void`s and/or [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-misused-promises`](./no-misused-promises.mdx)
-
-## Further Reading
-
-- ["Using Promises" MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises). Note especially the sections on [Promise rejection events](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises#promise_rejection_events) and [Composition](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises#composition).