feat(no-throw-statements)!: replace option allowInAsyncFunctions with allowToRejectPromises

Author: RebeccaStevens

docs/rules/no-throw-statements.md

@@ -58,15 +58,15 @@ This rule accepts an options object of the following type:
 
 ```ts
 type Options = {
-  allowInAsyncFunctions: boolean;
+  allowToRejectPromises: boolean;
 };
 ```
 
 ### Default Options
 
 ```ts
 const defaults = {
-  allowInAsyncFunctions: false,
+  allowToRejectPromises: false,
 };
 ```
 
@@ -76,19 +76,19 @@ const defaults = {
 
 ```ts
 const recommendedAndLiteOptions = {
-  allowInAsyncFunctions: true,
+  allowToRejectPromises: true,
 };
 ```
 
-### `allowInAsyncFunctions`
+### `allowToRejectPromises`
 
-If true, throw statements will be allowed within async functions.\
+If true, throw statements will be allowed when they are used to reject a promise, such when in an async function.\
 This essentially allows throw statements to be used as return statements for errors.
 
 #### ✅ Correct
 
 ```js
-/* eslint functional/no-throw-statements: ["error", { "allowInAsyncFunctions": true }] */
+/* eslint functional/no-throw-statements: ["error", { "allowToRejectPromises": true }] */
 
 async function divide(x, y) {
   const [xv, yv] = await Promise.all([x, y]);

docs/rules/prefer-immutable-types.md

@@ -426,7 +426,7 @@ acceptsCallback((options: CallbackOptions) => {});
 
 ```ts
 export interface CallbackOptions {
-  prop: string;
+  readonly prop: string;
 }
 type Callback = (options: CallbackOptions) => void;
 type AcceptsCallback = (callback: Callback) => void;

eslint.config.js

@@ -31,7 +31,12 @@ export default rsEslint(
       },
     },
     formatters: true,
-    functional: "lite",
+    functional: {
+      functionalEnforcement: "lite",
+      overrides: {
+        "functional/no-throw-statements": "off",
+      },
+    },
     jsonc: true,
     markdown: {
       enableTypeRequiredRules: true,
@@ -52,9 +57,6 @@ export default rsEslint(
     rules: {
       // Some types say they have nonnullable properties, but they don't always.
       "ts/no-unnecessary-condition": "off",
-
-      // Temp
-      "functional/no-throw-statements": "off",
     },
   },
   {

src/configs/recommended.ts

@@ -66,7 +66,7 @@ const overrides = {
   [noThrowStatements.fullName]: [
     "error",
     {
-      allowInAsyncFunctions: true,
+      allowToRejectPromises: true,
     },
   ],
   [noTryStatements.fullName]: "off",

src/rules/no-throw-statements.ts

@@ -8,7 +8,11 @@ import {
   type RuleResult,
   createRule,
 } from "#/utils/rule";
-import { isInFunctionBody } from "#/utils/tree";
+import {
+  getEnclosingFunction,
+  getEnclosingTryStatement,
+  isInPromiseHandlerFunction,
+} from "#/utils/tree";
 
 /**
  * The name of this rule.
@@ -25,7 +29,7 @@ export const fullName = `${ruleNameScope}/${name}`;
  */
 type Options = [
   {
-    allowInAsyncFunctions: boolean;
+    allowToRejectPromises: boolean;
   },
 ];
 
@@ -36,7 +40,7 @@ const schema: JSONSchema4[] = [
   {
     type: "object",
     properties: {
-      allowInAsyncFunctions: {
+      allowToRejectPromises: {
         type: "boolean",
       },
     },
@@ -49,7 +53,7 @@ const schema: JSONSchema4[] = [
  */
 const defaultOptions: Options = [
   {
-    allowInAsyncFunctions: false,
+    allowToRejectPromises: false,
   },
 ];
 
@@ -84,9 +88,29 @@ function checkThrowStatement(
   context: Readonly<RuleContext<keyof typeof errorMessages, Options>>,
   options: Readonly<Options>,
 ): RuleResult<keyof typeof errorMessages, Options> {
-  const [{ allowInAsyncFunctions }] = options;
+  const [{ allowToRejectPromises }] = options;
+
+  if (!allowToRejectPromises) {
+    return { context, descriptors: [{ node, messageId: "generic" }] };
+  }
+
+  if (isInPromiseHandlerFunction(node, context)) {
+    return { context, descriptors: [] };
+  }
+
+  const enclosingFunction = getEnclosingFunction(node);
+  if (enclosingFunction?.async !== true) {
+    return { context, descriptors: [{ node, messageId: "generic" }] };
+  }
 
-  if (!allowInAsyncFunctions || !isInFunctionBody(node, true)) {
+  const enclosingTryStatement = getEnclosingTryStatement(node);
+  if (
+    !(
+      enclosingTryStatement === null ||
+      getEnclosingFunction(enclosingTryStatement) !== enclosingFunction ||
+      enclosingTryStatement.handler === null
+    )
+  ) {
     return { context, descriptors: [{ node, messageId: "generic" }] };
   }
 

src/utils/tree.ts

@@ -4,7 +4,7 @@ import { type RuleContext } from "@typescript-eslint/utils/ts-eslint";
 
 import typescript from "#/conditional-imports/typescript";
 
-import { type BaseOptions } from "./rule";
+import { type BaseOptions, getTypeOfNode } from "./rule";
 import {
   isBlockStatement,
   isCallExpression,
@@ -18,6 +18,7 @@ import {
   isMethodDefinition,
   isObjectExpression,
   isProgram,
+  isPromiseType,
   isProperty,
   isTSInterfaceBody,
   isTSInterfaceHeritage,
@@ -117,6 +118,30 @@ export function isInReadonly(node: TSESTree.Node): boolean {
   return getReadonly(node) !== null;
 }
 
+/**
+ * Test if the given node is in a handler function callback of a promise.
+ */
+export function isInPromiseHandlerFunction<
+  Context extends RuleContext<string, BaseOptions>,
+>(node: TSESTree.Node, context: Context): boolean {
+  const functionNode = getAncestorOfType(
+    (n, c): n is TSESTree.FunctionLike => isFunctionLike(n) && n.body === c,
+    node,
+  );
+
+  if (
+    functionNode === null ||
+    !isCallExpression(functionNode.parent) ||
+    !isMemberExpression(functionNode.parent.callee) ||
+    !isIdentifier(functionNode.parent.callee.property)
+  ) {
+    return false;
+  }
+
+  const objectType = getTypeOfNode(functionNode.parent.callee.object, context);
+  return isPromiseType(objectType);
+}
+
 /**
  * Test if the given node is shallowly inside a `Readonly<{...}>`.
  */