typescript-eslint · phaux · Aug 2, 2024 · Aug 2, 2024 · Aug 2, 2024 · Aug 2, 2024
diff --git a/packages/eslint-plugin/docs/rules/no-misused-promises.mdx b/packages/eslint-plugin/docs/rules/no-misused-promises.mdx
@@ -311,4 +311,5 @@ You might consider using [ESLint disable comments](https://eslint.org/docs/lates
 
 ## Related To
 
-- [`no-floating-promises`](./no-floating-promises.mdx)
+- [`strict-void-return`](./strict-void-return.mdx) - A superset of this rule's `checksVoidReturn` option which also checks for non-Promise values.
+- [`no-floating-promises`](./no-floating-promises.mdx) - Warns about unhandled promises in _statement_ positions.
diff --git a/packages/eslint-plugin/docs/rules/strict-void-return.mdx b/packages/eslint-plugin/docs/rules/strict-void-return.mdx
@@ -0,0 +1,321 @@
+---
+description: 'Disallow passing a value-returning function in a position accepting a void function.'
+---
+
+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/strict-void-return** for documentation.
+
+## Rule Details
+
+TypeScript considers functions returning a value to be assignable to a function returning void.
+Using this feature of TypeScript can lead to bugs or confusing code.
+
+## Examples
+
+### Return type unsafety
+
+Passing a value-returning function in a place expecting a void function can be unsound.
+TypeScript generally treats the `void` type as though it has the same runtime behavior as `undefined`,
+so this pattern will cause a mismatch between the runtime behavior and the types.
+
+```ts
+// TypeScript errors on overtly wrong ways of populating the `void` type...
+function returnsVoid(): void {
+  return 1234; // TS Error:  Type 'number' is not assignable to type 'void'.
+}
+
+// ...but allows more subtle ones
+const returnsVoid: () => void = () => 1234;
+
+// Likewise, TypeScript errors on overtly wrong usages of `void` as a runtime value...
+declare const v: void;
+if (v) {
+  // TS Error: An expression of type 'void' cannot be tested for truthiness.
+  // ... do something
+}
+
+// ...but silently treats `void` as `undefined` in more subtle scenarios
+declare const voidOrString: void | string;
+if (voidOrString) {
+  // voidOrString is narrowed to string in this branch, so this is allowed.
+  console.log(voidOrString.toUpperCase());
+}
+```
+
+Between these two behaviors, examples like the following will throw at runtime, despite not reporting a type error:
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+const getNothing: () => void = () => 2137;
+const getString: () => string = () => 'Hello';
+const maybeString = Math.random() > 0.1 ? getNothing() : getString();
+if (maybeString) console.log(maybeString.toUpperCase()); // ❌ Crash if getNothing was called
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+const getNothing: () => void = () => {};
+const getString: () => string = () => 'Hello';
+const maybeString = Math.random() > 0.1 ? getNothing() : getString();
+if (maybeString) console.log(maybeString.toUpperCase()); // ✅ No crash
+```
+
+</TabItem>
+</Tabs>
+
+### Unhandled returned promises
+
+If a callback is meant to return void, values returned from functions are likely ignored.
+Ignoring a returned Promise means any Promise rejection will be silently ignored
+or crash the process depending on runtime.
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+declare function takesCallback(cb: () => void): void;
+
+takesCallback(async () => {
+  const response = await fetch('https://api.example.com/');
+  const data = await response.json();
+  console.log(data);
+});
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+declare function takesCallback(cb: () => void): void;
+
+takesCallback(() => {
+  (async () => {
+    const response = await fetch('https://api.example.com/');
+    const data = await response.json();
+    console.log(data);
+  })().catch(console.error);
+});
+```
+
+</TabItem>
+</Tabs>
+
+:::info
+If you only care about promises,
+you can use the [`no-misused-promises`](no-misused-promises.mdx) rule instead.
+:::
+
+:::tip
+Use [`no-floating-promises`](no-floating-promises.mdx)
+to also enforce error handling of non-awaited promises in statement positions.
+:::
+
+### Ignored returned generators
+
+If a generator is returned from a void function it won't even be started.
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+declare function takesCallback(cb: () => void): void;
+
+takesCallback(function* () {
+  console.log('Hello');
+  yield;
+  console.log('World');
+});
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+declare function takesCallback(cb: () => void): void;
+
+takesCallback(() => {
+  function* gen() {
+    console.log('Hello');
+    yield;
+    console.log('World');
+  }
+  for (const _ of gen());
+});
+```
+
+</TabItem>
+</Tabs>
+
+### Accidental dead code
+
+Returning a value from a void function often is an indication of incorrect assumptions about APIs.
+Those incorrect assumptions can often lead to unnecessary code.
+
+The following `forEach` loop is a common mistake: its author likely either meant to add `console.log` or meant to use `.map` instead.
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+['Kazik', 'Zenek'].forEach(name => `Hello, ${name}!`);
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+['Kazik', 'Zenek'].forEach(name => console.log(`Hello, ${name}!`));
+```
+
+</TabItem>
+</Tabs>
+
+### Void context from extended classes
+
+This rule enforces class methods which override a void method to also be void.
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+class Foo {
+  cb() {
+    console.log('foo');
+  }
+}
+
+class Bar extends Foo {
+  cb() {
+    super.cb();
+    return 'bar';
+  }
+}
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+class Foo {
+  cb() {
+    console.log('foo');
+  }
+}
+
+class Bar extends Foo {
+  cb() {
+    super.cb();
+    console.log('bar');
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+### Void context from implemented interfaces
+
+This rule enforces class methods which implement a void method to also be void.
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+interface Foo {
+  cb(): void;
+}
+
+class Bar implements Foo {
+  cb() {
+    return 'cb';
+  }
+}
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+interface Foo {
+  cb(): void;
+}
+
+class Bar implements Foo {
+  cb() {
+    console.log('cb');
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+## Options
+
+### `allowReturnAny`
+
+{/* insert option description */}
+
+Additional incorrect code when the option is **disabled**:
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts option='{ "allowReturnAny": false }'
+declare function fn(cb: () => void): void;
+
+fn(() => JSON.parse('{}'));
+
+fn(() => {
+  return someUntypedApi();
+});
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts option='{ "allowReturnAny": false }'
+declare function fn(cb: () => void): void;
+
+fn(() => void JSON.parse('{}'));
+
+fn(() => {
+  someUntypedApi();
+});
+```
+
+</TabItem>
+</Tabs>
+
+## When Not To Use It
+
+Some projects are architected so that values returned from synchronous void functions are generally safe.
+If you only want to check for misused voids with asynchronous functions then you can use [`no-misused-promises`](./no-misused-promises.mdx) instead.
+
+In browser context, an unhandled promise will be reported as an error in the console.
+It's generally a good idea to also show some kind of indicator on the page that something went wrong,
+but if you are just prototyping or don't care about that, the default behavior might be acceptable.
+In such case, instead of handling the promises and `console.error`ing them anyways, you can just disable this rule.
+
+Similarly, the default behavior of crashing the process on unhandled promise rejection
+might be acceptable when developing, for example, a CLI tool.
+If your promise handlers simply call `process.exit(1)` on rejection,
+you may prefer to avoid this rule and rely on the default behavior.
+
+## Related To
+
+- [`no-misused-promises`](./no-misused-promises.mdx) - A subset of this rule which only cares about promises.
+- [`no-floating-promises`](./no-floating-promises.mdx) - Warns about unhandled promises in _statement_ positions.
+- [`no-confusing-void-expression`](./no-confusing-void-expression.mdx) - Disallows returning _void_ values.
+
+## Further Reading
+
+- [TypeScript FAQ - Void function assignability](https://github.com/Microsoft/TypeScript/wiki/FAQ#why-are-functions-returning-non-void-assignable-to-function-returning-void)
diff --git a/packages/eslint-plugin/src/configs/eslintrc/all.ts b/packages/eslint-plugin/src/configs/eslintrc/all.ts
@@ -154,6 +154,7 @@ export = {
     'no-return-await': 'off',
     '@typescript-eslint/return-await': 'error',
     '@typescript-eslint/strict-boolean-expressions': 'error',
+    '@typescript-eslint/strict-void-return': 'error',
     '@typescript-eslint/switch-exhaustiveness-check': 'error',
     '@typescript-eslint/triple-slash-reference': 'error',
     '@typescript-eslint/unbound-method': 'error',

diff --git a/packages/eslint-plugin/src/configs/eslintrc/disable-type-checked.ts b/packages/eslint-plugin/src/configs/eslintrc/disable-type-checked.ts
@@ -66,6 +66,7 @@ export = {
     '@typescript-eslint/restrict-template-expressions': 'off',
     '@typescript-eslint/return-await': 'off',
     '@typescript-eslint/strict-boolean-expressions': 'off',
+    '@typescript-eslint/strict-void-return': 'off',
     '@typescript-eslint/switch-exhaustiveness-check': 'off',
     '@typescript-eslint/unbound-method': 'off',
     '@typescript-eslint/use-unknown-in-catch-callback-variable': 'off',

diff --git a/packages/eslint-plugin/src/configs/flat/all.ts b/packages/eslint-plugin/src/configs/flat/all.ts
@@ -168,6 +168,7 @@ export default (
       'no-return-await': 'off',
       '@typescript-eslint/return-await': 'error',
       '@typescript-eslint/strict-boolean-expressions': 'error',
+      '@typescript-eslint/strict-void-return': 'error',
       '@typescript-eslint/switch-exhaustiveness-check': 'error',
       '@typescript-eslint/triple-slash-reference': 'error',
       '@typescript-eslint/unbound-method': 'error',

diff --git a/packages/eslint-plugin/src/configs/flat/disable-type-checked.ts b/packages/eslint-plugin/src/configs/flat/disable-type-checked.ts
@@ -73,6 +73,7 @@ export default (
     '@typescript-eslint/restrict-template-expressions': 'off',
     '@typescript-eslint/return-await': 'off',
     '@typescript-eslint/strict-boolean-expressions': 'off',
+    '@typescript-eslint/strict-void-return': 'off',
     '@typescript-eslint/switch-exhaustiveness-check': 'off',
     '@typescript-eslint/unbound-method': 'off',
     '@typescript-eslint/use-unknown-in-catch-callback-variable': 'off',

diff --git a/packages/eslint-plugin/src/rules/index.ts b/packages/eslint-plugin/src/rules/index.ts
@@ -125,6 +125,7 @@ import restrictTemplateExpressions from './restrict-template-expressions';
 import returnAwait from './return-await';
 import sortTypeConstituents from './sort-type-constituents';
 import strictBooleanExpressions from './strict-boolean-expressions';
+import strictVoidReturn from './strict-void-return';
 import switchExhaustivenessCheck from './switch-exhaustiveness-check';
 import tripleSlashReference from './triple-slash-reference';
 import typedef from './typedef';
@@ -259,6 +260,7 @@ const rules = {
   'return-await': returnAwait,
   'sort-type-constituents': sortTypeConstituents,
   'strict-boolean-expressions': strictBooleanExpressions,
+  'strict-void-return': strictVoidReturn,
   'switch-exhaustiveness-check': switchExhaustivenessCheck,
   'triple-slash-reference': tripleSlashReference,
   typedef,