@typescript-eslint/eslint-plugin 8.0.0-alpha.8 → 8.0.0

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

@@ -17,6 +17,7 @@ Valid ways of handling a Promise-valued statement include:
 
 - `await`ing it
 - `return`ing it
+- `void`ing it
 - Calling its `.then()` with two arguments
 - Calling its `.catch()` with one argument
 
@@ -63,6 +64,9 @@ await promise;
 async function returnsPromise() {
   return 'value';
 }
+
+void returnsPromise();
+
 returnsPromise().then(
   () => {},
   () => {},
@@ -80,9 +84,54 @@ await Promise.all([1, 2, 3].map(async x => x + 1));
 
 ## Options
 
+### `checkThenables`
+
+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`
 
-This allows you to stop the rule reporting promises consumed with void operator.
+This option, which is `true` by default, allows you to stop the rule reporting promises consumed with void operator.
 This can be a good way to explicitly mark a promise as intentionally not awaited.
 
 Examples of **correct** code for this rule with `{ ignoreVoid: true }`:
@@ -100,7 +149,7 @@ With this option set to `true`, and if you are using `no-void`, you should turn
 
 ### `ignoreIIFE`
 
-This allows you to skip checking of async IIFEs (Immediately Invoked function Expressions).
+This allows you to skip checking of async IIFEs (Immediately Invoked Function Expressions).
 
 Examples of **correct** code for this rule with `{ ignoreIIFE: true }`:
 
@@ -115,6 +164,101 @@ await (async function () {
 })();
 ```
 
+### `allowForKnownSafePromises`
+
+This option allows marking specific types as "safe" to be floating. 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 an array of type specifiers to consider safe.
+Each item in the array must have one of the following forms:
+
+- A type defined in a file (`{ from: "file", name: "Foo", path: "src/foo-file.ts" }` with `path` being an optional path relative to the project root directory)
+- A type from the default library (`{ from: "lib", name: "PromiseLike" }`)
+- A type from a package (`{ from: "package", name: "Foo", package: "foo-lib" }`, this also works for types defined in a typings package).
+
+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`
+
+This option allows marking specific functions as "safe" to be called to create floating Promises.
+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 same array format as [`allowForKnownSafePromises`](#allowForKnownSafePromises).
+
+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.

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

@@ -127,19 +127,18 @@ Examples of code for this rule with `checksVoidReturn: true`:
 
 ```ts option='{ "checksVoidReturn": true }'
 [1, 2, 3].forEach(async value => {
-  await doSomething(value);
+  await fetch(`/${value}`);
 });
 
-new Promise(async (resolve, reject) => {
-  await doSomething();
+new Promise<void>(async (resolve, reject) => {
+  await fetch('/');
   resolve();
 });
 
-const eventEmitter = new EventEmitter();
-eventEmitter.on('some-event', async () => {
-  synchronousCall();
-  await doSomething();
-  otherSynchronousCall();
+document.addEventListener('click', async () => {
+  console.log('synchronous call');
+  await fetch('/');
+  console.log('synchronous call');
 });
 ```
 
@@ -169,8 +168,7 @@ new Promise((resolve, reject) => {
 });
 
 // Name the async wrapper to call it later
-const eventEmitter = new EventEmitter();
-eventEmitter.on('some-event', () => {
+document.addEventListener('click', () => {
   const handler = async () => {
     await doSomething();
     otherSynchronousCall();
@@ -210,30 +208,30 @@ Examples of code for this rule with `checksSpreads: true`:
 <TabItem value="❌ Incorrect">
 
 ```ts option='{ "checksSpreads": true }'
-const getData = () => someAsyncOperation({ myArg: 'foo' });
+const getData = () => fetch('/');
 
-return { foo: 42, ...getData() };
+console.log({ foo: 42, ...getData() });
 
-const getData2 = async () => {
-  await someAsyncOperation({ myArg: 'foo' });
+const awaitData = async () => {
+  await fetch('/');
 };
 
-return { foo: 42, ...getData2() };
+console.log({ foo: 42, ...awaitData() });
 ```
 
 </TabItem>
 <TabItem value="✅ Correct">
 
 ```ts option='{ "checksSpreads": true }'
-const getData = () => someAsyncOperation({ myArg: 'foo' });
+const getData = () => fetch('/');
 
-return { foo: 42, ...(await getData()) };
+console.log({ foo: 42, ...(await getData()) });
 
-const getData2 = async () => {
-  await someAsyncOperation({ myArg: 'foo' });
+const awaitData = async () => {
+  await fetch('/');
 };
 
-return { foo: 42, ...(await getData2()) };
+console.log({ foo: 42, ...(await awaitData()) });
 ```
 
 </TabItem>

package/docs/rules/no-redundant-type-constituents.mdx

@@ -96,3 +96,7 @@ If you strongly feel a preference for these unnecessary type constituents, this
 - [Intersection Types](https://www.typescriptlang.org/docs/handbook/2/objects.html#intersection-types)
 - [Bottom Types](https://en.wikipedia.org/wiki/Bottom_type)
 - [Top Types](https://en.wikipedia.org/wiki/Top_type)
+
+## Related To
+
+- [no-duplicate-type-constituents](./no-duplicate-type-constituents.mdx)

package/docs/rules/no-require-imports.mdx

@@ -38,7 +38,7 @@ import * as lib3 from 'lib3';
 
 ### `allow`
 
-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.
+An 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$']}`:
 
@@ -59,6 +59,33 @@ console.log(require('../package.json').version);
 </TabItem>
 </Tabs>
 
+### `allowAsImport`
+
+When set to `true`, the `import x = require(...)` declaration won't be reported.
+This is useful if you use certain module options that require strict CommonJS interop semantics.
+
+With `{allowAsImport: true}`:
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts option='{ "allowAsImport": true }'
+var foo = require('foo');
+const foo = require('foo');
+let foo = require('foo');
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts option='{ "allowAsImport": true }'
+import foo = require('foo');
+import foo from 'foo';
+```
+
+</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.

package/docs/rules/no-restricted-types.mdx

@@ -0,0 +1,71 @@
+---
+description: 'Disallow certain types.'
+---
+
+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-restricted-types** for documentation.
+
+It can sometimes be useful to ban specific types from being used in type annotations.
+For example, a project might be migrating from using one type to another, and want to ban references to the old type.
+
+This rule can be configured to ban a list of specific types and can suggest alternatives.
+Note that it does not ban the corresponding runtime objects from being used.
+
+## Options
+
+### `types`
+
+An object whose keys are the types you want to ban, and the values are error messages.
+
+The type can either be a type name literal (`OldType`) or a a type name with generic parameter instantiation(s) (`OldType<MyArgument>`).
+
+The values can be:
+
+- A string, which is the error message to be reported; or
+- `false` to specifically un-ban this type (useful when you are using `extendDefaults`); or
+- An object with the following properties:
+  - `message: string`: the message to display when the type is matched.
+  - `fixWith?: string`: a string to replace the banned type with when the fixer is run. If this is omitted, no fix will be done.
+  - `suggest?: string[]`: a list of suggested replacements for the banned type.
+
+Example configuration:
+
+```jsonc
+{
+  "@typescript-eslint/no-restricted-types": [
+    "error",
+    {
+      "types": {
+        // add a custom message to help explain why not to use it
+        "OldType": "Don't use OldType because it is unsafe",
+
+        // add a custom message, and tell the plugin how to fix it
+        "OldAPI": {
+          "message": "Use NewAPI instead",
+          "fixWith": "NewAPI",
+        },
+
+        // add a custom message, and tell the plugin how to suggest a fix
+        "SoonToBeOldAPI": {
+          "message": "Use NewAPI instead",
+          "suggest": ["NewAPIOne", "NewAPITwo"],
+        },
+      },
+    },
+  ],
+}
+```
+
+## When Not To Use It
+
+If you have no need to ban specific types from being used in type annotations, you don't need this rule.
+
+## Related To
+
+- [`no-empty-object-type`](./no-empty-object-type.mdx)
+- [`no-unsafe-function-type`](./no-unsafe-function-type.mdx)
+- [`no-wrapper-object-types`](./no-wrapper-object-types.mdx)

package/docs/rules/no-type-alias.mdx

@@ -19,7 +19,7 @@ TypeScript type aliases are a commonly necessary language feature; banning it al
 :::note
 
 If you want to ban certain classifications of type aliases, consider using [`no-restricted-syntax`](https://eslint.org/docs/latest/rules/no-restricted-syntax).
-See [Troubleshooting & FAQs](/troubleshooting#how-can-i-ban-specific-language-feature).
+See [Troubleshooting & FAQs](/troubleshooting/faqs/general#how-can-i-ban-specific-language-feature).
 
 :::
 

package/docs/rules/no-unnecessary-parameter-property-assignment.mdx

@@ -0,0 +1,42 @@
+---
+description: 'Disallow unnecessary assignment of constructor property parameter.'
+---
+
+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-unnecessary-parameter-property-assignment** for documentation.
+
+[TypeScript's parameter properties](https://www.typescriptlang.org/docs/handbook/2/classes.html#parameter-properties) allow creating and initializing a member in one place.
+Therefore, in most cases, it is not necessary to assign parameter properties of the same name to members within a constructor.
+
+## Examples
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+class Foo {
+  constructor(public bar: string) {
+    this.bar = bar;
+  }
+}
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+class Foo {
+  constructor(public bar: string) {}
+}
+```
+
+</TabItem>
+</Tabs>
+
+## When Not To Use It
+
+If you don't use parameter properties, you can ignore this rule.

package/docs/rules/no-unnecessary-template-expression.mdx

@@ -0,0 +1,85 @@
+---
+description: 'Disallow unnecessary template 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-unnecessary-template-expression** for documentation.
+
+This rule reports template literals that contain substitution expressions (also variously referred to as embedded expressions or string interpolations) that are unnecessary and can be simplified.
+
+:::info[Migration from `no-useless-template-literals`]
+
+This rule was formerly known as [`no-useless-template-literals`](./no-useless-template-literals.mdx).
+The new name is a drop-in replacement with identical functionality.
+
+:::
+
+## Examples
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+// Static values can be incorporated into the surrounding template.
+
+const ab1 = `${'a'}${'b'}`;
+const ab2 = `a${'b'}`;
+
+const stringWithNumber = `${'1 + 1 = '}${2}`;
+
+const stringWithBoolean = `${'true is '}${true}`;
+
+// Some simple expressions that are already strings
+// can be rewritten without a template at all.
+
+const text = 'a';
+const wrappedText = `${text}`;
+
+declare const intersectionWithString: string & { _brand: 'test-brand' };
+const wrappedIntersection = `${intersectionWithString}`;
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+// Static values can be incorporated into the surrounding template.
+
+const ab1 = `ab`;
+const ab2 = `ab`;
+
+const stringWithNumber = `1 + 1 = 2`;
+
+const stringWithBoolean = `true is true`;
+
+// Some simple expressions that are already strings
+// can be rewritten without a template at all.
+
+const text = 'a';
+const wrappedText = text;
+
+declare const intersectionWithString: string & { _brand: 'test-brand' };
+const wrappedIntersection = intersectionWithString;
+```
+
+</TabItem>
+</Tabs>
+
+:::info
+This rule does not aim to flag template literals without substitution expressions that could have been written as an ordinary string.
+That is to say, this rule will not help you turn `` `this` `` into `"this"`.
+If you are looking for such a rule, you can configure the [`@stylistic/ts/quotes`](https://eslint.style/rules/ts/quotes) rule to do this.
+:::
+
+## When Not To Use It
+
+When you want to allow string expressions inside template literals.
+
+## Related To
+
+- [`restrict-template-expressions`](./restrict-template-expressions.mdx)
+- [`@stylistic/ts/quotes`](https://eslint.style/rules/ts/quotes)

package/docs/rules/no-unnecessary-type-parameters.mdx

@@ -0,0 +1,114 @@
+---
+description: 'Disallow type parameters that only appear once.'
+---
+
+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-unnecessary-type-parameters** for documentation.
+
+This rule forbids type parameters that only appear once in a function, method, or class definition.
+
+Type parameters relate two types.
+If a type parameter only appears once, then it is not relating anything.
+It can usually be replaced with explicit types such as `unknown`.
+
+At best unnecessary type parameters make code harder to read.
+At worst they can be used to disguise unsafe type assertions.
+
+:::warning
+This rule was recently added, and has a surprising amount of hidden complexity compared to most of our rules. If you encounter unexpected behavior with it, please check closely the [Limitations](#limitations) section below and our [issue tracker](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+no-unnecessary-type-parameters).
+If you don't see your case covered, please [reach out to us](https://typescript-eslint.io/contributing/issues)!
+:::
+
+## Examples
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+function second<A, B>(a: A, b: B): B {
+  return b;
+}
+
+function parseJSON<T>(input: string): T {
+  return JSON.parse(input);
+}
+
+function printProperty<T, K extends keyof T>(obj: T, key: K) {
+  console.log(obj[key]);
+}
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+function second<B>(a: unknown, b: B): B {
+  return b;
+}
+
+function parseJSON(input: string): unknown {
+  return JSON.parse(input);
+}
+
+function printProperty<T>(obj: T, key: keyof T) {
+  console.log(obj[key]);
+}
+
+// T appears twice: in the type of arg and as the return type
+function identity<T>(arg: T): T {
+  return arg;
+}
+
+// T appears twice: "keyof T" and in the inferred return type (T[K]).
+// K appears twice: "key: K" and in the inferred return type (T[K]).
+function getProperty<T, K extends keyof T>(obj: T, key: K) {
+  return obj[key];
+}
+```
+
+</TabItem>
+</Tabs>
+
+## Limitations
+
+Note that this rule allows any type parameter that is used multiple times, even if those uses are via a type argument.
+For example, the following `T` is used multiple times by virtue of being in an `Array`, even though its name only appears once after declaration:
+
+```ts
+declare function createStateHistory<T>(): T[];
+```
+
+This is because the type parameter `T` relates multiple methods in the `T[]` together, making it used more than once.
+
+Therefore, this rule won't report on type parameters used as a type argument.
+That includes type arguments given to global types such as `Array` (including the `T[]` shorthand and in tuples), `Map`, and `Set`.
+
+## When Not To Use It
+
+This rule will report on functions that use type parameters solely to test types, for example:
+
+```ts
+function assertType<T>(arg: T) {}
+
+assertType<number>(123);
+assertType<number>('abc');
+//                 ~~~~~
+// Argument of type 'string' is not assignable to parameter of type 'number'.
+```
+
+If you're using this pattern then you'll want to disable this rule on files that test types.
+
+## Further Reading
+
+- TypeScript handbook: [Type Parameters Should Appear Twice](https://microsoft.github.io/TypeScript-New-Handbook/everything/#type-parameters-should-appear-twice)
+- Effective TypeScript: [The Golden Rule of Generics](https://effectivetypescript.com/2020/08/12/generics-golden-rule/)
+
+## Related To
+
+- eslint-plugin-etc's [`no-misused-generics`](https://github.com/cartant/eslint-plugin-etc/blob/main/docs/rules/no-misused-generics.md)
+- wotan's [`no-misused-generics`](https://github.com/fimbullinter/wotan/blob/master/packages/mimir/docs/no-misused-generics.md)
+- DefinitelyTyped-tools' [`no-unnecessary-generics`](https://github.com/microsoft/DefinitelyTyped-tools/blob/main/packages/eslint-plugin/docs/rules/no-unnecessary-generics.md)