typescript-eslint · arkapratimc · Feb 17, 2024 · Feb 18, 2024 · Feb 19, 2024 · Feb 19, 2024
diff --git a/packages/eslint-plugin/docs/rules/no-floating-promises.mdx b/packages/eslint-plugin/docs/rules/no-floating-promises.mdx
@@ -115,6 +115,51 @@ 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.
+
+Each item must be one of:
+
+- 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"}]}'
+type UnsafePromise = Promise<number> & { __linterBrands?: string };
+let promise: UnsafePromise = Promise.resolve(2);
+promise;
+promise.finally();
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts option='{"allowForKnownSafePromises":[{"from":"file","name":"SafePromise"},{"from":"lib","name":"PromiseLike"},{"from":"package","name":"Bar","package":"bar-lib"}]}'
+type SafePromise = Promise<number> & { __linterBrands?: string }; // promises can be marked as safe by using branded types
+let promise: SafePromise = Promise.resolve(2);
+promise;
+promise.finally();
+```
+
+</TabItem>
+</Tabs>
+
 ## When Not To Use It
 
 This rule can be difficult to enable on large existing projects that set up many floating Promises.

diff --git a/packages/eslint-plugin/src/rules/no-floating-promises.ts b/packages/eslint-plugin/src/rules/no-floating-promises.ts
@@ -1,19 +1,28 @@
-import type { TSESLint, TSESTree } from '@typescript-eslint/utils';
+import type {
+  ParserServicesWithTypeInformation,
+  TSESLint,
+  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';
 
+import type { TypeOrValueSpecifier } from '../util';
 import {
   createRule,
   getOperatorPrecedence,
   getParserServices,
   OperatorPrecedence,
+  readonlynessOptionsDefaults,
+  readonlynessOptionsSchema,
+  typeMatchesSpecifier,
 } from '../util';
 
 type Options = [
   {
     ignoreVoid?: boolean;
     ignoreIIFE?: boolean;
+    allowForKnownSafePromises?: TypeOrValueSpecifier[];
   },
 ];
 
@@ -79,6 +88,7 @@ export default createRule<Options, MessageId>({
               'Whether to ignore async IIFEs (Immediately Invoked Function Expressions).',
             type: 'boolean',
           },
+          allowForKnownSafePromises: readonlynessOptionsSchema.properties.allow,
         },
         additionalProperties: false,
       },
@@ -89,12 +99,16 @@ export default createRule<Options, MessageId>({
     {
       ignoreVoid: true,
       ignoreIIFE: false,
+      allowForKnownSafePromises: readonlynessOptionsDefaults.allow,
     },
   ],
 
   create(context, [options]) {
     const services = getParserServices(context);
     const checker = services.program.getTypeChecker();
+    // TODO: #5439
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const allowForKnownSafePromises = options.allowForKnownSafePromises!;
 
     return {
       ExpressionStatement(node): void {
@@ -253,7 +267,9 @@ export default createRule<Options, MessageId>({
       // Check the type. At this point it can't be unhandled if it isn't a promise
       // or array thereof.
 
-      if (isPromiseArray(checker, tsNode)) {
+      if (
+        isPromiseArray(services, allowForKnownSafePromises, checker, tsNode)
+      ) {
         return { isUnhandled: true, promiseArray: true };
       }
 
@@ -262,6 +278,28 @@ export default createRule<Options, MessageId>({
       }
 
       if (node.type === AST_NODE_TYPES.CallExpression) {
+        const member =
+          node.callee.type === AST_NODE_TYPES.MemberExpression
+            ? node.callee.object
+            : node;
+        const calledByThenOrCatch =
+          (node.callee.type === AST_NODE_TYPES.MemberExpression &&
+            node.callee.property.type === AST_NODE_TYPES.Identifier &&
+            node.callee.property.name === 'catch') ||
+          (node.callee.type === AST_NODE_TYPES.MemberExpression &&
+            node.callee.property.type === AST_NODE_TYPES.Identifier &&
+            node.callee.property.name === 'then');
+        if (
+          !calledByThenOrCatch &&
+          doesTypeMatchSpecifier(
+            services,
+            allowForKnownSafePromises,
+            services.getTypeAtLocation(member),
+          )
+        ) {
+          return { isUnhandled: false };
+        }
+
         // If the outer expression is a call, a `.catch()` or `.then()` with
         // rejection handler handles the promise.
 
@@ -291,6 +329,15 @@ export default createRule<Options, MessageId>({
         // All other cases are unhandled.
         return { isUnhandled: true };
       } else if (node.type === AST_NODE_TYPES.TaggedTemplateExpression) {
+        if (
+          doesTypeMatchSpecifier(
+            services,
+            allowForKnownSafePromises,
+            services.getTypeAtLocation(node),
+          )
+        ) {
+          return { isUnhandled: false };
+        }
         return { isUnhandled: true };
       } else if (node.type === AST_NODE_TYPES.ConditionalExpression) {
         // We must be getting the promise-like value from one of the branches of the
@@ -305,6 +352,15 @@ export default createRule<Options, MessageId>({
         node.type === AST_NODE_TYPES.Identifier ||
         node.type === AST_NODE_TYPES.NewExpression
       ) {
+        if (
+          doesTypeMatchSpecifier(
+            services,
+            allowForKnownSafePromises,
+            services.getTypeAtLocation(node),
+          )
+        ) {
+          return { isUnhandled: false };
+        }
         // If it is just a property access chain or a `new` call (e.g. `foo.bar` or
         // `new Promise()`), the promise is not handled because it doesn't have the
         // necessary then/catch call at the end of the chain.
@@ -325,20 +381,46 @@ export default createRule<Options, MessageId>({
   },
 });
 
-function isPromiseArray(checker: ts.TypeChecker, node: ts.Node): boolean {
+function doesTypeMatchSpecifier(
+  services: ParserServicesWithTypeInformation,
+  options: TypeOrValueSpecifier[],
+  type: ts.Type,
+): boolean {
+  return options.some(specifier =>
+    typeMatchesSpecifier(type, specifier, services.program),
+  );
+}
+
+function isPromiseArray(
+  services: ParserServicesWithTypeInformation,
+  options: TypeOrValueSpecifier[],
+  checker: ts.TypeChecker,
+  node: ts.Node,
+): boolean {
   const type = checker.getTypeAtLocation(node);
   for (const ty of tsutils
     .unionTypeParts(type)
     .map(t => checker.getApparentType(t))) {
     if (checker.isArrayType(ty)) {
       const arrayType = checker.getTypeArguments(ty)[0];
+      if (
+        options.length > 0 &&
+        tsutils
+          .unionTypeParts(arrayType)
+          .some(type => doesTypeMatchSpecifier(services, options, type))
+      ) {
+        return false;
+      }
       if (isPromiseLike(checker, node, arrayType)) {
         return true;
       }
     }
 
     if (checker.isTupleType(ty)) {
       for (const tupleElementType of checker.getTypeArguments(ty)) {
+        if (doesTypeMatchSpecifier(services, options, tupleElementType)) {
+          return false;
+        }
         if (isPromiseLike(checker, node, tupleElementType)) {
           return true;
         }

diff --git a/packages/eslint-plugin/tests/docs-eslint-output-snapshots/no-floating-promises.shot b/packages/eslint-plugin/tests/docs-eslint-output-snapshots/no-floating-promises.shot