typescript-eslint · JoshuaKGoldberg · Jul 6, 2024 · Jun 4, 2024 · Jun 4, 2024 · Jun 4, 2024
diff --git a/packages/eslint-plugin/docs/rules/no-floating-promises.mdx b/packages/eslint-plugin/docs/rules/no-floating-promises.mdx
@@ -84,6 +84,55 @@ 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>
+
+:::info
+This option is enabled by default in v7 but will be turned off by default in v8.
+:::
+
 ### `ignoreVoid`

 This option, which is `true` by default, allows you to stop the rule reporting promises consumed with void operator.

diff --git a/packages/eslint-plugin/src/rules/no-floating-promises.ts b/packages/eslint-plugin/src/rules/no-floating-promises.ts
@@ -8,6 +8,7 @@ import {
  createRule,
  getOperatorPrecedence,
  getParserServices,
+  isBuiltinSymbolLike,
  OperatorPrecedence,
  readonlynessOptionsDefaults,
  readonlynessOptionsSchema,
@@ -16,9 +17,10 @@ import {

 type Options = [
  {
-    ignoreVoid?: boolean;
-    ignoreIIFE?: boolean;
    allowForKnownSafePromises?: TypeOrValueSpecifier[];
+    checkThenables?: boolean;
+    ignoreIIFE?: boolean;
+    ignoreVoid?: boolean;
  },
 ];

@@ -75,6 +77,12 @@ export default createRule<Options, MessageId>({
      {
        type: 'object',
        properties: {
+          allowForKnownSafePromises: readonlynessOptionsSchema.properties.allow,
+          checkThenables: {
+            description:
+              'Whether to check all "Thenable"s, not just the built-in Promise type.',
+            type: 'boolean',
+          },
          ignoreVoid: {
            description: 'Whether to ignore `void` expressions.',
            type: 'boolean',
@@ -84,7 +92,6 @@ export default createRule<Options, MessageId>({
              'Whether to ignore async IIFEs (Immediately Invoked Function Expressions).',
            type: 'boolean',
          },
-          allowForKnownSafePromises: readonlynessOptionsSchema.properties.allow,
        },
        additionalProperties: false,
      },
@@ -93,15 +100,18 @@ export default createRule<Options, MessageId>({
  },
  defaultOptions: [
    {
+      allowForKnownSafePromises: readonlynessOptionsDefaults.allow,
+      checkThenables: true,
      ignoreVoid: true,
      ignoreIIFE: false,
-      allowForKnownSafePromises: readonlynessOptionsDefaults.allow,
    },
  ],

  create(context, [options]) {
    const services = getParserServices(context);
    const checker = services.program.getTypeChecker();
+    const { checkThenables } = options;
+
    // TODO: #5439
    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
    const allowForKnownSafePromises = options.allowForKnownSafePromises!;
@@ -356,14 +366,10 @@ export default createRule<Options, MessageId>({
      return false;
    }

-    // Modified from tsutils.isThenable() to only consider thenables which can be
-    // rejected/caught via a second parameter. Original source (MIT licensed):
-    //
-    //   https://github.com/ajafff/tsutils/blob/49d0d31050b44b81e918eae4fbaf1dfe7b7286af/util/type.ts#L95-L125
    function isPromiseLike(node: ts.Node, type?: ts.Type): boolean {
      type ??= checker.getTypeAtLocation(node);

-      // Ignore anything specified by `allowForKnownSafePromises` option.
+      // The highest priority is to allow anything allowlisted
      if (
        allowForKnownSafePromises.some(allowedType =>
          typeMatchesSpecifier(type, allowedType, services.program),
@@ -372,7 +378,26 @@ export default createRule<Options, MessageId>({
        return false;
      }

-      for (const ty of tsutils.unionTypeParts(checker.getApparentType(type))) {
+      // Otherwise, we always consider the built-in Promise to be Promise-like...
+      const typeParts = tsutils.unionTypeParts(checker.getApparentType(type));
+      if (
+        typeParts.some(typePart =>
+          isBuiltinSymbolLike(services.program, typePart, 'Promise'),
+        )
+      ) {
+        return true;
+      }
+
+      // ...and only check all Thenables if explicitly told to
+      if (!checkThenables) {
+        return false;
+      }
+
+      // Modified from tsutils.isThenable() to only consider thenables which can be
+      // rejected/caught via a second parameter. Original source (MIT licensed):
+      //
+      //   https://github.com/ajafff/tsutils/blob/49d0d31050b44b81e918eae4fbaf1dfe7b7286af/util/type.ts#L95-L125
+      for (const ty of typeParts) {
        const then = ty.getProperty('then');
        if (then === undefined) {
          continue;

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
diff --git a/packages/eslint-plugin/tests/rules/no-floating-promises.test.ts b/packages/eslint-plugin/tests/rules/no-floating-promises.test.ts
@@ -733,6 +733,41 @@ promise().then(() => {});
        },
      ],
    },
+    {
+      code: `
+interface SafePromise<T> extends Promise<T> {
+  brand: 'safe';
+}
+
+declare const createSafePromise: () => SafePromise<string>;
+createSafePromise();
+      `,
+      options: [
+        {
+          allowForKnownSafePromises: [{ from: 'file', name: 'SafePromise' }],
+          checkThenables: true,
+        },
+      ],
+    },
+    {
+      code: `
+declare const createPromise: () => PromiseLike<number>;
+createPromise();
+      `,
+      options: [{ checkThenables: false }],
+    },
+    {
+      code: `
+interface MyThenable {
+  then(onFulfilled: () => void, onRejected: () => void): MyThenable;
+}
+
+declare function createMyThenable(): MyThenable;
+
+createMyThenable();
+      `,
+      options: [{ checkThenables: false }],
+    },
  ],

  invalid: [
@@ -2181,5 +2216,54 @@ myTag\`abc\`;
      options: [{ allowForKnownSafePromises: [{ from: 'file', name: 'Foo' }] }],
      errors: [{ line: 4, messageId: 'floatingVoid' }],
    },
+    {
+      code: `
+declare const createPromise: () => PromiseLike<number>;
+createPromise();
+      `,
+      errors: [{ line: 3, messageId: 'floatingVoid' }],
+      options: [{ checkThenables: true }],
+    },
+    {
+      code: `
+interface MyThenable {
+  then(onFulfilled: () => void, onRejected: () => void): MyThenable;
+}
+
+declare function createMyThenable(): MyThenable;
+
+createMyThenable();
+      `,
+      errors: [{ line: 8, messageId: 'floatingVoid' }],
+      options: [{ checkThenables: true }],
+    },
+    {
+      code: `
+declare const createPromise: () => Promise<number>;
+createPromise();
+      `,
+      errors: [{ line: 3, messageId: 'floatingVoid' }],
+      options: [{ checkThenables: false }],
+    },
+    {
+      code: `
+class MyPromise<T> extends Promise<T> {}
+declare const createMyPromise: () => MyPromise<number>;
+createMyPromise();
+      `,
+      errors: [{ line: 4, messageId: 'floatingVoid' }],
+      options: [{ checkThenables: false }],
+    },
+    {
+      code: `
+class MyPromise<T> extends Promise<T> {
+  additional: string;
+}
+declare const createMyPromise: () => MyPromise<number>;
+createMyPromise();
+      `,
+      errors: [{ line: 6, messageId: 'floatingVoid' }],
+      options: [{ checkThenables: false }],
+    },
  ],
 });
diff --git a/packages/eslint-plugin/tests/schema-snapshots/no-floating-promises.shot b/packages/eslint-plugin/tests/schema-snapshots/no-floating-promises.shot