Feb 17, 2024 · Feb 18, 2024 · Feb 19, 2024 · Feb 19, 2024 · Feb 21, 2024 · Mar 19, 2024
diff --git a/packages/eslint-plugin/docs/rules/no-floating-promises.mdx b/packages/eslint-plugin/docs/rules/no-floating-promises.mdx
 })();
 ```

 ### `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
 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[];
  },
 ];

              'Whether to ignore async IIFEs (Immediately Invoked Function Expressions).',
            type: 'boolean',
          },
          allowForKnownSafePromises: readonlynessOptionsSchema.properties.allow,
        },
        additionalProperties: false,
      },
    {
      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 {
      // 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 };
      }

      }

      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.

        // 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
        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.
  },
 });

 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
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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:
kirkwaiblinger marked this conversation as resolved. Show resolvedHide resolved

		- 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.
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -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[];
		},
		];

Expand DownExpand Up		@@ -79,6 +88,7 @@ export default createRule<Options, MessageId>({
		'Whether to ignore async IIFEs (Immediately Invoked Function Expressions).',
		type: 'boolean',
		},
		allowForKnownSafePromises: readonlynessOptionsSchema.properties.allow,
		},
JoshuaKGoldberg marked this conversation as resolved. Show resolvedHide resolved
		additionalProperties: false,
		},
Expand All		@@ -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!;

arkapratimc marked this conversation as resolved. Show resolvedHide resolved
		return {
		ExpressionStatement(node): void {
Expand DownExpand Up		@@ -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 };
		}

Expand All		@@ -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.

Expand DownExpand Up		@@ -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
Expand All		@@ -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.
Expand All		@@ -325,20 +381,46 @@ export default createRule<Options, MessageId>({
		},
		});

		function isPromiseArray(checker: ts.TypeChecker, node: ts.Node): boolean {
		function doesTypeMatchSpecifier(
		services: ParserServicesWithTypeInformation,
kirkwaiblinger marked this conversation as resolved. Show resolvedHide resolved
		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;
		}
Expand Down