← Back to rules

typescript/no-floating-promises Correctness

✅ This rule is turned on by default when type-aware linting is enabled.

💭 This rule requires type information.

💡 A suggestion is available for this rule.

功能说明

此规则禁止 TypeScript 代码中的"浮动"Promise，即创建后没有任何代码处理其解析或拒绝的 Promise。

此规则将报告未以下列方式之一处理的 Promise 值语句：

• 使用两个参数调用其 .then()
• 使用一个参数调用其 .catch()
• await 它
• return 它
• void 它

此规则还报告在创建包含 Promise 的数组时未正确处理的情况。解决此问题的主要方法是使用 Promise 并发方法之一创建单个 Promise，然后根据上述过程处理该 Promise。这些方法包括：

• Promise.all()
• Promise.allSettled()
• Promise.any()
• Promise.race()

为什么这样做是不好的？

浮动 Promise 可能导致多个问题，例如操作顺序不当、忽略 Promise 拒绝等。

示例

此规则的错误代码示例：

const promise = new Promise((resolve, reject) => resolve("value"));
promise;

async function returnsPromise() {
  return "value";
}
returnsPromise().then(() => {});

Promise.reject("value").catch();

Promise.reject("value").finally();

[1, 2, 3].map(async (x) => x + 1);

此规则的正确代码示例：

const promise = new Promise((resolve, reject) => resolve("value"));
await promise;

async function returnsPromise() {
  return "value";
}

void returnsPromise();

returnsPromise().then(
  () => {},
  () => {},
);

Promise.reject("value").catch(() => {});

await Promise.reject("value").finally(() => {});

await Promise.all([1, 2, 3].map(async (x) => x + 1));

配置

此规则接受一个配置对象，具有以下属性：

allowForKnownSafeCalls

类型：array

默认值：[]

允许特定调用被忽略，指定为类型或值说明符。

allowForKnownSafeCalls[n]

类型：object | string

用于匹配特定声明的类型或值说明符

支持四种类型的说明符：

1. 字符串说明符（已弃用）：按名称进行通用匹配

"Promise"

2. 文件说明符：匹配本地文件中声明的类型/值

{ "from": "file", "name": "MyType" }
{ "from": "file", "name": ["Type1", "Type2"] }
{ "from": "file", "name": "MyType", "path": "./types.ts" }

3. 库说明符：匹配 TypeScript 内置库类型

{ "from": "lib", "name": "Promise" }
{ "from": "lib", "name": ["Promise", "PromiseLike"] }

4. 包说明符：匹配来自 npm 包的类型/值

{ "from": "package", "name": "Observable", "package": "rxjs" }
{ "from": "package", "name": ["Observable", "Subject"], "package": "rxjs" }

allowForKnownSafeCalls[n].from

类型："file"

allowForKnownSafeCalls[n].name

类型：array | string

名称说明符，可以是单个字符串或字符串数组

allowForKnownSafeCalls[n].name[n]

类型：string

allowForKnownSafeCalls[n].path

类型：string

可选文件路径，用于指定类型或值必须声明的位置。如果省略，将匹配所有文件。

allowForKnownSafePromises

类型：array

默认值：[]

允许特定 Promise 类型被忽略，指定为类型或值说明符。

allowForKnownSafePromises[n]

类型：object | string

用于匹配特定声明的类型或值说明符

支持四种类型的说明符：

1. 字符串说明符（已弃用）：按名称进行通用匹配

"Promise"

2. 文件说明符：匹配本地文件中声明的类型/值

{ "from": "file", "name": "MyType" }
{ "from": "file", "name": ["Type1", "Type2"] }
{ "from": "file", "name": "MyType", "path": "./types.ts" }

3. 库说明符：匹配 TypeScript 内置库类型

{ "from": "lib", "name": "Promise" }
{ "from": "lib", "name": ["Promise", "PromiseLike"] }

4. 包说明符：匹配来自 npm 包的类型/值

{ "from": "package", "name": "Observable", "package": "rxjs" }
{ "from": "package", "name": ["Observable", "Subject"], "package": "rxjs" }

allowForKnownSafePromises[n].from

类型："file"

allowForKnownSafePromises[n].name

类型：array | string

名称说明符，可以是单个字符串或字符串数组

allowForKnownSafePromises[n].name[n]

类型：string

allowForKnownSafePromises[n].path

类型：string

可选文件路径，用于指定类型或值必须声明的位置。如果省略，将匹配所有文件。

checkThenables

类型：boolean

默认值：false

检查不一定是 Promise 的 thenable 对象。

ignoreIIFE

类型：boolean

默认值：false

忽略立即调用的函数表达式（IIFE）。

ignoreVoid

类型：boolean

默认值：true

忽略作为 void 表达式的 Promise。

如何使用

To enable this rule using the config file or in the CLI, you can use:

Config (.oxlintrc.json)

{
  "options": {
    "typeAware": true
  },
  "rules": {
    "typescript/no-floating-promises": "error"
  }
}

Config (oxlint.config.ts)

import { defineConfig } from "oxlint";

export default defineConfig({
  options: { typeAware: true },
  rules: {
    "typescript/no-floating-promises": "error",
  },
});

CLI

oxlint --type-aware --deny typescript/no-floating-promises

版本

此规则在 v1.11.0 中添加。

参考

• Rule Source
• Rule Source (tsgolint)