Jun 8, 2024 · Jun 3, 2024 · Jun 3, 2024 · Jun 3, 2024 · Jun 4, 2024 · Jun 5, 2024
diff --git a/packages/eslint-plugin/docs/rules/no-floating-promises.mdx b/packages/eslint-plugin/docs/rules/no-floating-promises.mdx
 </TabItem>
 </Tabs>

 ### `allowForKnownSafeCalls`

 This option allows marking specific functions as "safe" to be called to create floating Promises.
 For example, you may need to do this in the case of libraries whose APIs may be called without handling the resultant Promises.

 This option takes the same array format as [`allowForKnownSafePromises`](#allowForKnownSafePromises).

 Examples of code for this rule with:

 ```json
 {
  "allowForKnownSafeCalls": [
    { "from": "file", "name": "safe", "path": "input.ts" }
  ]
 }
 ```

 <Tabs>
 <TabItem value="❌ Incorrect">

 ```ts option='{"allowForKnownSafeCalls":[{"from":"file","name":"safe","path":"input.ts"}]}'
 declare function unsafe(...args: unknown[]): Promise<void>;

 unsafe('...', () => {});
 ```

 </TabItem>
 <TabItem value="✅ Correct">

 ```ts option='{"allowForKnownSafeCalls":[{"from":"file","name":"safe","path":"input.ts"}]}' skipValidation
 declare function safe(...args: unknown[]): Promise<void>;

 safe('...', () => {});
 ```

 </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
    ignoreVoid?: boolean;
    ignoreIIFE?: boolean;
    allowForKnownSafePromises?: TypeOrValueSpecifier[];
    allowForKnownSafeCalls?: TypeOrValueSpecifier[];
  },
 ];

            type: 'boolean',
          },
          allowForKnownSafePromises: readonlynessOptionsSchema.properties.allow,
          allowForKnownSafeCalls: readonlynessOptionsSchema.properties.allow,
        },
        additionalProperties: false,
      },
      ignoreVoid: true,
      ignoreIIFE: false,
      allowForKnownSafePromises: readonlynessOptionsDefaults.allow,
      allowForKnownSafeCalls: 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
    /* eslint-disable @typescript-eslint/no-non-null-assertion */
    const allowForKnownSafePromises = options.allowForKnownSafePromises!;
    const allowForKnownSafeCalls = options.allowForKnownSafeCalls!;
    /* eslint-enable @typescript-eslint/no-non-null-assertion */

    return {
      ExpressionStatement(node): void {
          expression = expression.expression;
        }

        if (isKnownSafePromiseReturn(expression)) {
          return;
        }

        const { isUnhandled, nonFunctionHandler, promiseArray } =
          isUnhandledPromise(checker, expression);

      },
    };

    function isKnownSafePromiseReturn(node: TSESTree.Node): boolean {
      if (node.type !== AST_NODE_TYPES.CallExpression) {
        return false;
      }

      const type = services.getTypeAtLocation(node.callee);

      return allowForKnownSafeCalls.some(allowedType =>
        typeMatchesSpecifier(type, allowedType, services.program),
      );
    }

    function isHigherPrecedenceThanUnary(node: ts.Node): boolean {
      const operator = ts.isBinaryExpression(node)
        ? node.operatorToken.kind
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
        { allowForKnownSafePromises: [{ from: 'file', name: 'SafePromise' }] },
      ],
    },
    {
      code: `
        declare function it(...args: unknown[]): Promise<void>;

        it('...', () => {});
      `,
      options: [
        {
          allowForKnownSafeCalls: [
            {
              from: 'file',
              name: 'it',
              // https://github.com/typescript-eslint/typescript-eslint/pull/9234/files#r1626465054
              path: process.env.TYPESCRIPT_ESLINT_PROJECT_SERVICE
                ? 'file.ts'
                : 'tests/fixtures/file.ts',
            },
          ],
        },
      ],
    },
    {
      code: `
 declare const myTag: (strings: TemplateStringsArray) => Promise<void>;
      options: [{ allowForKnownSafePromises: [{ from: 'file', name: 'Foo' }] }],
      errors: [{ line: 4, messageId: 'floatingVoid' }],
    },
    {
      code: `
        declare function unsafe(...args: unknown[]): Promise<void>;

        unsafe('...', () => {});
      `,
      errors: [{ line: 4, messageId: 'floatingVoid' }],
      options: [
        {
          allowForKnownSafeCalls: [
            {
              from: 'file',
              name: 'it',
              // https://github.com/typescript-eslint/typescript-eslint/pull/9234/files#r1626465054
              path: process.env.TYPESCRIPT_ESLINT_PROJECT_SERVICE
                ? 'file.ts'
                : 'tests/fixtures/file.ts',
            },
          ],
        },
      ],
    },
    {
      code: `
        declare function it(...args: unknown[]): Promise<void>;

        it('...', () => {}).then(() => {});
      `,
      errors: [{ line: 4, messageId: 'floatingVoid' }],
      options: [
        {
          allowForKnownSafeCalls: [
            {
              from: 'file',
              name: 'it',
              // https://github.com/typescript-eslint/typescript-eslint/pull/9234/files#r1626465054
              path: process.env.TYPESCRIPT_ESLINT_PROJECT_SERVICE
                ? 'file.ts'
                : 'tests/fixtures/file.ts',
            },
          ],
        },
      ],
    },
    {
      code: `
        declare function it(...args: unknown[]): Promise<void>;

        it('...', () => {}).finally(() => {});
      `,
      errors: [{ line: 4, messageId: 'floatingVoid' }],
      options: [
        {
          allowForKnownSafeCalls: [
            {
              from: 'file',
              name: 'it',
              // https://github.com/typescript-eslint/typescript-eslint/pull/9234/files#r1626465054
              path: process.env.TYPESCRIPT_ESLINT_PROJECT_SERVICE
                ? 'file.ts'
                : 'tests/fixtures/file.ts',
            },
          ],
        },
      ],
    },
  ],
 });
diff --git a/packages/eslint-plugin/tests/schema-snapshots/no-floating-promises.shot b/packages/eslint-plugin/tests/schema-snapshots/no-floating-promises.shot
Original file line number	Diff line number	Diff line change
Expand Up		@@ -176,6 +176,44 @@ returnsSafePromise();
		</TabItem>
		</Tabs>

		### `allowForKnownSafeCalls`

		This option allows marking specific functions as "safe" to be called to create floating Promises.
		For example, you may need to do this in the case of libraries whose APIs may be called without handling the resultant Promises.

		This option takes the same array format as [`allowForKnownSafePromises`](#allowForKnownSafePromises).

		Examples of code for this rule with:

		```json
		{
		"allowForKnownSafeCalls": [
		{ "from": "file", "name": "safe", "path": "input.ts" }
		]
		}
		```

		<Tabs>
		<TabItem value="❌ Incorrect">

		```ts option='{"allowForKnownSafeCalls":[{"from":"file","name":"safe","path":"input.ts"}]}'
		declare function unsafe(...args: unknown[]): Promise<void>;

		unsafe('...', () => {});
		```

		</TabItem>
		<TabItem value="✅ Correct">

		```ts option='{"allowForKnownSafeCalls":[{"from":"file","name":"safe","path":"input.ts"}]}' skipValidation
		declare function safe(...args: unknown[]): Promise<void>;

		safe('...', () => {});
JoshuaKGoldberg marked this conversation as resolved. Show resolvedHide resolved
		```

		</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
Expand Up		@@ -19,6 +19,7 @@ type Options = [
		ignoreVoid?: boolean;
		ignoreIIFE?: boolean;
		allowForKnownSafePromises?: TypeOrValueSpecifier[];
		allowForKnownSafeCalls?: TypeOrValueSpecifier[];
		},
		];

Expand DownExpand Up		@@ -85,6 +86,7 @@ export default createRule<Options, MessageId>({
		type: 'boolean',
		},
		allowForKnownSafePromises: readonlynessOptionsSchema.properties.allow,
		allowForKnownSafeCalls: readonlynessOptionsSchema.properties.allow,
		},
		additionalProperties: false,
		},
Expand All		@@ -96,15 +98,18 @@ export default createRule<Options, MessageId>({
		ignoreVoid: true,
		ignoreIIFE: false,
		allowForKnownSafePromises: readonlynessOptionsDefaults.allow,
		allowForKnownSafeCalls: 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
		/* eslint-disable @typescript-eslint/no-non-null-assertion */
		const allowForKnownSafePromises = options.allowForKnownSafePromises!;
		const allowForKnownSafeCalls = options.allowForKnownSafeCalls!;
		/* eslint-enable @typescript-eslint/no-non-null-assertion */

		return {
		ExpressionStatement(node): void {
Expand All		@@ -118,6 +123,10 @@ export default createRule<Options, MessageId>({
		expression = expression.expression;
		}

		if (isKnownSafePromiseReturn(expression)) {
kirkwaiblinger marked this conversation as resolved. Show resolvedHide resolved
		return;
		}

		const { isUnhandled, nonFunctionHandler, promiseArray } =
		isUnhandledPromise(checker, expression);

Expand DownExpand Up		@@ -197,6 +206,18 @@ export default createRule<Options, MessageId>({
		},
		};

		function isKnownSafePromiseReturn(node: TSESTree.Node): boolean {
		if (node.type !== AST_NODE_TYPES.CallExpression) {
		return false;
		}

		const type = services.getTypeAtLocation(node.callee);

		return allowForKnownSafeCalls.some(allowedType =>
		typeMatchesSpecifier(type, allowedType, services.program),
		);
		}

		function isHigherPrecedenceThanUnary(node: ts.Node): boolean {
		const operator = ts.isBinaryExpression(node)
		? node.operatorToken.kind
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -698,6 +698,27 @@ myTag\`abc\`;
		{ allowForKnownSafePromises: [{ from: 'file', name: 'SafePromise' }] },
		],
		},
		{
		code: `
		declare function it(...args: unknown[]): Promise<void>;

		it('...', () => {});
		`,
		options: [
		{
		allowForKnownSafeCalls: [
		{
		from: 'file',
		name: 'it',
		// https://github.com/typescript-eslint/typescript-eslint/pull/9234/files#r1626465054
		path: process.env.TYPESCRIPT_ESLINT_PROJECT_SERVICE
		? 'file.ts'
		: 'tests/fixtures/file.ts',
		},
		],
		},
		],
		},
		{
		code: `
		declare const myTag: (strings: TemplateStringsArray) => Promise<void>;
Expand DownExpand Up		@@ -2181,5 +2202,71 @@ myTag\`abc\`;
		options: [{ allowForKnownSafePromises: [{ from: 'file', name: 'Foo' }] }],
		errors: [{ line: 4, messageId: 'floatingVoid' }],
		},
		{
		code: `
		declare function unsafe(...args: unknown[]): Promise<void>;

		unsafe('...', () => {});
		`,
		errors: [{ line: 4, messageId: 'floatingVoid' }],
		options: [
		{
		allowForKnownSafeCalls: [
		{
		from: 'file',
		name: 'it',
		// https://github.com/typescript-eslint/typescript-eslint/pull/9234/files#r1626465054
		path: process.env.TYPESCRIPT_ESLINT_PROJECT_SERVICE
		? 'file.ts'
		: 'tests/fixtures/file.ts',
		},
		],
		},
		],
		},
		{
		code: `
		declare function it(...args: unknown[]): Promise<void>;

		it('...', () => {}).then(() => {});
		`,
		errors: [{ line: 4, messageId: 'floatingVoid' }],
		options: [
		{
		allowForKnownSafeCalls: [
		{
		from: 'file',
		name: 'it',
		// https://github.com/typescript-eslint/typescript-eslint/pull/9234/files#r1626465054
		path: process.env.TYPESCRIPT_ESLINT_PROJECT_SERVICE
		? 'file.ts'
		: 'tests/fixtures/file.ts',
		},
		],
		},
		],
		},
		{
		code: `
		declare function it(...args: unknown[]): Promise<void>;

		it('...', () => {}).finally(() => {});
		`,
		errors: [{ line: 4, messageId: 'floatingVoid' }],
		options: [
		{
		allowForKnownSafeCalls: [
		{
		from: 'file',
		name: 'it',
		// https://github.com/typescript-eslint/typescript-eslint/pull/9234/files#r1626465054
		path: process.env.TYPESCRIPT_ESLINT_PROJECT_SERVICE
		? 'file.ts'
		: 'tests/fixtures/file.ts',
		},
		],
		},
		],
		},
		],
		});