Nov 4, 2024 · Sep 27, 2024 · Sep 27, 2024 · Sep 27, 2024 · Sep 27, 2024 · Sep 27, 2024
diff --git a/eslint.config.mjs b/eslint.config.mjs
    },
    linterOptions: { reportUnusedDisableDirectives: 'error' },
    rules: {
      // TODO: https://github.com/typescript-eslint/typescript-eslint/issues/8538
      '@typescript-eslint/no-confusing-void-expression': 'off',

      //
      // our plugin :D
      //

      '@typescript-eslint/no-confusing-void-expression': [
        'error',
        { ignoreVoidReturningFunctions: true },
      ],
      '@typescript-eslint/ban-ts-comment': [
        'error',
        {
diff --git a/packages/eslint-plugin/docs/rules/no-confusing-void-expression.mdx b/packages/eslint-plugin/docs/rules/no-confusing-void-expression.mdx
 console.log(void alert('Hello, world!'));
 ```

 ### `ignoreVoidReturningFunctions`

 Whether to ignore returns from functions with `void` return types when inside a function with a `void` return type.

 Some projects prefer allowing functions that explicitly return `void` to return `void` expressions. Doing so allows more writing more succinct functions.

 :::note
 This is technically risky as the `void`-returning function might actually be returning a value not seen by the type system.
 :::

 ```ts option='{ "ignoreVoidReturningFunctions": true }' showPlaygroundButton
 function foo(): void {
  return console.log();
 }

 function onError(callback: () => void): void {
  callback();
 }

 onError(() => console.log('oops'));
 ```

 ## When Not To Use It

 The return type of a function can be inspected by going to its definition or hovering over it in an IDE.
diff --git a/packages/eslint-plugin/src/rules/no-confusing-void-expression.ts b/packages/eslint-plugin/src/rules/no-confusing-void-expression.ts
  nullThrows,
  NullThrowsReasons,
 } from '../util';
 import { getParentFunctionNode } from '../util/getParentFunctionNode';

 export type Options = [
  {
    ignoreArrowShorthand?: boolean;
    ignoreVoidOperator?: boolean;
    ignoreVoidReturningFunctions?: boolean;
  },
 ];

            description:
              'Whether to ignore returns that start with the `void` operator.',
          },
          ignoreVoidReturningFunctions: {
            type: 'boolean',
            description:
              'Whether to ignore returns from functions with explicit `void` return types and functions with contextual `void` return types.',
          },
        },
      },
    ],
  },
  defaultOptions: [{ ignoreArrowShorthand: false, ignoreVoidOperator: false }],

  create(context, [options]) {
    const services = getParserServices(context);
    const checker = services.program.getTypeChecker();

    return {
      'AwaitExpression, CallExpression, TaggedTemplateExpression'(
        node:
          | TSESTree.AwaitExpression
          | TSESTree.CallExpression
          | TSESTree.TaggedTemplateExpression,
      ): void {
        const services = getParserServices(context);
        const type = getConstrainedTypeAtLocation(services, node);
        if (!tsutils.isTypeFlagSet(type, ts.TypeFlags.VoidLike)) {
          // not a void expression
        if (invalidAncestor.type === AST_NODE_TYPES.ArrowFunctionExpression) {
          // handle arrow function shorthand

          if (options.ignoreVoidReturningFunctions) {
            const returnsVoid = isVoidReturningFunctionNode(invalidAncestor);

            if (returnsVoid) {
              return;
            }
          }

          if (options.ignoreVoidOperator) {
            // handle wrapping with `void`
            return context.report({
        if (invalidAncestor.type === AST_NODE_TYPES.ReturnStatement) {
          // handle return statement

          if (options.ignoreVoidReturningFunctions) {
            const functionNode = getParentFunctionNode(invalidAncestor);

            if (functionNode) {
              const returnsVoid = isVoidReturningFunctionNode(functionNode);

              if (returnsVoid) {
                return;
              }
            }
          }

          if (options.ignoreVoidOperator) {
            // handle wrapping with `void`
            return context.report({
    function canFix(
      node: ReturnStatementWithArgument | TSESTree.ArrowFunctionExpression,
    ): boolean {
      const services = getParserServices(context);

      const targetNode =
        node.type === AST_NODE_TYPES.ReturnStatement
          ? node.argument
      const type = getConstrainedTypeAtLocation(services, targetNode);
      return tsutils.isTypeFlagSet(type, ts.TypeFlags.VoidLike);
    }

    function isFunctionReturnTypeIncludesVoid(functionType: ts.Type): boolean {
      const callSignatures = tsutils.getCallSignaturesOfType(functionType);

      return callSignatures.some(signature => {
        const returnType = signature.getReturnType();

        return tsutils
          .unionTypeParts(returnType)
          .some(tsutils.isIntrinsicVoidType);
      });
    }

    function isVoidReturningFunctionNode(
      functionNode:
        | TSESTree.ArrowFunctionExpression
        | TSESTree.FunctionDeclaration
        | TSESTree.FunctionExpression,
    ): boolean {
      // Game plan:
      //   - If the function node has a type annotation, check if it includes `void`.
      //     - If it does then the function is safe to return `void` expressions in.
      //   - Otherwise, check if the function is a function-expression or an arrow-function.
      //   -   If it is, get its contextual type and bail if we cannot.
      //   - Return based on whether the contextual type includes `void` or not

      const functionTSNode = services.esTreeNodeToTSNodeMap.get(functionNode);

      if (functionTSNode.type) {
        const returnType = checker.getTypeFromTypeNode(functionTSNode.type);

        return tsutils
          .unionTypeParts(returnType)
          .some(tsutils.isIntrinsicVoidType);
      }

      if (ts.isExpression(functionTSNode)) {
        const functionType = checker.getContextualType(functionTSNode);

        if (functionType) {
          return tsutils
            .unionTypeParts(functionType)
            .some(isFunctionReturnTypeIncludesVoid);
        }
      }

      return false;
    }
  },
 });
diff --git a/packages/eslint-plugin/src/rules/no-unsafe-return.ts b/packages/eslint-plugin/src/rules/no-unsafe-return.ts
 import type { TSESTree } from '@typescript-eslint/utils';

 import { AST_NODE_TYPES } from '@typescript-eslint/utils';
 import * as tsutils from 'ts-api-utils';
 import * as ts from 'typescript';

  isTypeUnknownType,
  isUnsafeAssignment,
 } from '../util';
 import { getParentFunctionNode } from '../util/getParentFunctionNode';

 export default createRule({
  name: 'no-unsafe-return',
      'noImplicitThis',
    );

    function getParentFunctionNode(
      node: TSESTree.Node,
    ):
      | TSESTree.ArrowFunctionExpression
      | TSESTree.FunctionDeclaration
      | TSESTree.FunctionExpression
      | null {
      let current = node.parent;
      while (current) {
        if (
          current.type === AST_NODE_TYPES.ArrowFunctionExpression ||
          current.type === AST_NODE_TYPES.FunctionDeclaration ||
          current.type === AST_NODE_TYPES.FunctionExpression
        ) {
          return current;
        }

        current = current.parent;
      }

      // this shouldn't happen in correct code, but someone may attempt to parse bad code
      // the parser won't error, so we shouldn't throw here
      /* istanbul ignore next */ return null;
    }

    function checkReturn(
      returnNode: TSESTree.Node,
      reportingNode: TSESTree.Node = returnNode,
diff --git a/packages/eslint-plugin/src/util/getParentFunctionNode.ts b/packages/eslint-plugin/src/util/getParentFunctionNode.ts
 import type { TSESTree } from '@typescript-eslint/utils';

 import { AST_NODE_TYPES } from '@typescript-eslint/utils';

 export function getParentFunctionNode(
  node: TSESTree.Node,
 ):
  | TSESTree.ArrowFunctionExpression
  | TSESTree.FunctionDeclaration
  | TSESTree.FunctionExpression
  | null {
  let current = node.parent;
  while (current) {
    if (
      current.type === AST_NODE_TYPES.ArrowFunctionExpression ||
      current.type === AST_NODE_TYPES.FunctionDeclaration ||
      current.type === AST_NODE_TYPES.FunctionExpression
    ) {
      return current;
    }

    current = current.parent;
  }

  // this shouldn't happen in correct code, but someone may attempt to parse bad code
  // the parser won't error, so we shouldn't throw here
  /* istanbul ignore next */ return null;
 }
diff --git a/packages/eslint-plugin/tests/docs-eslint-output-snapshots/no-confusing-void-expression.shot b/packages/eslint-plugin/tests/docs-eslint-output-snapshots/no-confusing-void-expression.shot
Original file line number	Diff line number	Diff line change
Expand Up		@@ -98,13 +98,14 @@ export default tseslint.config(
		},
		linterOptions: { reportUnusedDisableDirectives: 'error' },
		rules: {
		// TODO: https://github.com/typescript-eslint/typescript-eslint/issues/8538
		'@typescript-eslint/no-confusing-void-expression': 'off',

		//
		// our plugin :D
		//

		'@typescript-eslint/no-confusing-void-expression': [
		'error',
		{ ignoreVoidReturningFunctions: true },
		],
		'@typescript-eslint/ban-ts-comment': [
		'error',
		{
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -119,6 +119,28 @@ function doSomething() {
		console.log(void alert('Hello, world!'));
		```

		### `ignoreVoidReturningFunctions`

		Whether to ignore returns from functions with `void` return types when inside a function with a `void` return type.

		Some projects prefer allowing functions that explicitly return `void` to return `void` expressions. Doing so allows more writing more succinct functions.

		:::note
		This is technically risky as the `void`-returning function might actually be returning a value not seen by the type system.
		:::

		```ts option='{ "ignoreVoidReturningFunctions": true }' showPlaygroundButton
		function foo(): void {
		return console.log();
		}

		function onError(callback: () => void): void {
		callback();
		}

		onError(() => console.log('oops'));
		```

		## When Not To Use It

		The return type of a function can be inspected by going to its definition or hovering over it in an IDE.
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -16,11 +16,13 @@ import {
		nullThrows,
		NullThrowsReasons,
		} from '../util';
		import { getParentFunctionNode } from '../util/getParentFunctionNode';

		export type Options = [
		{
		ignoreArrowShorthand?: boolean;
		ignoreVoidOperator?: boolean;
		ignoreVoidReturningFunctions?: boolean;
		},
		];

Expand DownExpand Up		@@ -86,21 +88,28 @@ export default createRule<Options, MessageId>({
		description:
		'Whether to ignore returns that start with the `void` operator.',
		},
		ignoreVoidReturningFunctions: {
		type: 'boolean',
		description:
		'Whether to ignore returns from functions with explicit `void` return types and functions with contextual `void` return types.',
		},
		},
		},
		],
		},
		defaultOptions: [{ ignoreArrowShorthand: false, ignoreVoidOperator: false }],

		create(context, [options]) {
		const services = getParserServices(context);
		const checker = services.program.getTypeChecker();

		return {
		'AwaitExpression, CallExpression, TaggedTemplateExpression'(
		node:
		\| TSESTree.AwaitExpression
		\| TSESTree.CallExpression
		\| TSESTree.TaggedTemplateExpression,
		): void {
		const services = getParserServices(context);
		const type = getConstrainedTypeAtLocation(services, node);
		if (!tsutils.isTypeFlagSet(type, ts.TypeFlags.VoidLike)) {
		// not a void expression
Expand All		@@ -122,6 +131,14 @@ export default createRule<Options, MessageId>({
		if (invalidAncestor.type === AST_NODE_TYPES.ArrowFunctionExpression) {
		// handle arrow function shorthand

		if (options.ignoreVoidReturningFunctions) {
		const returnsVoid = isVoidReturningFunctionNode(invalidAncestor);

		if (returnsVoid) {
		return;
		}
		}

		if (options.ignoreVoidOperator) {
		// handle wrapping with `void`
		return context.report({
Expand DownExpand Up		@@ -177,6 +194,18 @@ export default createRule<Options, MessageId>({
		if (invalidAncestor.type === AST_NODE_TYPES.ReturnStatement) {
		// handle return statement

		if (options.ignoreVoidReturningFunctions) {
		const functionNode = getParentFunctionNode(invalidAncestor);

		if (functionNode) {
		const returnsVoid = isVoidReturningFunctionNode(functionNode);

		if (returnsVoid) {
		return;
		}
		}
		}

		if (options.ignoreVoidOperator) {
		// handle wrapping with `void`
		return context.report({
Expand DownExpand Up		@@ -380,8 +409,6 @@ export default createRule<Options, MessageId>({
		function canFix(
		node: ReturnStatementWithArgument \| TSESTree.ArrowFunctionExpression,
		): boolean {
		const services = getParserServices(context);

		const targetNode =
		node.type === AST_NODE_TYPES.ReturnStatement
		? node.argument
Expand All		@@ -390,5 +417,53 @@ export default createRule<Options, MessageId>({
		const type = getConstrainedTypeAtLocation(services, targetNode);
		return tsutils.isTypeFlagSet(type, ts.TypeFlags.VoidLike);
		}

		function isFunctionReturnTypeIncludesVoid(functionType: ts.Type): boolean {
		const callSignatures = tsutils.getCallSignaturesOfType(functionType);

		return callSignatures.some(signature => {
JoshuaKGoldberg marked this conversation as resolved. Show resolvedHide resolved
		const returnType = signature.getReturnType();

		return tsutils
		.unionTypeParts(returnType)
		.some(tsutils.isIntrinsicVoidType);
		});
		}

		function isVoidReturningFunctionNode(
		functionNode:
		\| TSESTree.ArrowFunctionExpression
		\| TSESTree.FunctionDeclaration
		\| TSESTree.FunctionExpression,
		): boolean {
		// Game plan:
		// - If the function node has a type annotation, check if it includes `void`.
		// - If it does then the function is safe to return `void` expressions in.
		// - Otherwise, check if the function is a function-expression or an arrow-function.
		// - If it is, get its contextual type and bail if we cannot.
		// - Return based on whether the contextual type includes `void` or not

		const functionTSNode = services.esTreeNodeToTSNodeMap.get(functionNode);

		if (functionTSNode.type) {
		const returnType = checker.getTypeFromTypeNode(functionTSNode.type);

		return tsutils
		.unionTypeParts(returnType)
		.some(tsutils.isIntrinsicVoidType);
JoshuaKGoldberg marked this conversation as resolved. Show resolvedHide resolved
		}

		if (ts.isExpression(functionTSNode)) {
		const functionType = checker.getContextualType(functionTSNode);

		if (functionType) {
		return tsutils
		.unionTypeParts(functionType)
		.some(isFunctionReturnTypeIncludesVoid);
		}
		}

		return false;
		}
		},
		});
Original file line number	Diff line number	Diff line change
		@@ -1,6 +1,5 @@
		import type { TSESTree } from '@typescript-eslint/utils';

		import { AST_NODE_TYPES } from '@typescript-eslint/utils';
		import * as tsutils from 'ts-api-utils';
		import * as ts from 'typescript';

Expand All		@@ -18,6 +17,7 @@ import {
		isTypeUnknownType,
		isUnsafeAssignment,
		} from '../util';
		import { getParentFunctionNode } from '../util/getParentFunctionNode';

		export default createRule({
		name: 'no-unsafe-return',
Expand DownExpand Up		@@ -49,31 +49,6 @@ export default createRule({
		'noImplicitThis',
		);

		function getParentFunctionNode(
		node: TSESTree.Node,
		):
		\| TSESTree.ArrowFunctionExpression
		\| TSESTree.FunctionDeclaration
		\| TSESTree.FunctionExpression
		\| null {
		let current = node.parent;
		while (current) {
		if (
		current.type === AST_NODE_TYPES.ArrowFunctionExpression \|\|
		current.type === AST_NODE_TYPES.FunctionDeclaration \|\|
		current.type === AST_NODE_TYPES.FunctionExpression
		) {
		return current;
		}

		current = current.parent;
		}

		// this shouldn't happen in correct code, but someone may attempt to parse bad code
		// the parser won't error, so we shouldn't throw here
		/* istanbul ignore next */ return null;
		}

		function checkReturn(
		returnNode: TSESTree.Node,
		reportingNode: TSESTree.Node = returnNode,
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,28 @@
		import type { TSESTree } from '@typescript-eslint/utils';

		import { AST_NODE_TYPES } from '@typescript-eslint/utils';

		export function getParentFunctionNode(
		node: TSESTree.Node,
		):
		\| TSESTree.ArrowFunctionExpression
		\| TSESTree.FunctionDeclaration
		\| TSESTree.FunctionExpression
		\| null {
		let current = node.parent;
		while (current) {
		if (
		current.type === AST_NODE_TYPES.ArrowFunctionExpression \|\|
		current.type === AST_NODE_TYPES.FunctionDeclaration \|\|
		current.type === AST_NODE_TYPES.FunctionExpression
		) {
		return current;
		}

		current = current.parent;
		}

		// this shouldn't happen in correct code, but someone may attempt to parse bad code
		// the parser won't error, so we shouldn't throw here
		/* istanbul ignore next */ return null;
		}