Skip to main content

promise-function-async

Require any function or method that returns a Promise to be marked async.

🔧

此规则报告的一些问题可通过 --fix ESLint 命令行选项自动修复。

💭

该规则需要 类型信息 才能运行。


确保每个功能只能：

英：Ensures that each function is only capable of:

  • 返回被拒绝的 promise，或者
  • 抛出一个 Error 对象。

相比之下，非 async、Promise 返回函数在技术上都可以实现。 处理这些函数结果的代码通常需要处理这两种情况，这可能会变得复杂。 此规则的实践消除了创建代码来处理这两种情况的要求。

英：In contrast, non-async, Promise-returning functions are technically capable of either. Code that handles the results of those functions will often need to handle both cases, which can get complex. This rule's practice removes a requirement for creating code to handle both cases.

当函数隐式返回 Promise 和非 Promise 类型的联合时，通常是一个错误—该规则标记了这些情况。 如果是故意的，请显式设置返回类型以允许规则通过。

.eslintrc.cjs
module.exports = {
  "rules": {
    "@typescript-eslint/promise-function-async": "error"
  }
};
在线运行试试这个规则 ↗

示例​

此规则的代码示例

英：Examples of code for this rule

const arrowFunctionReturnsPromise = () => Promise.resolve('value');

function functionReturnsPromise() {
  return Promise.resolve('value');
}

function functionReturnsUnionWithPromiseImplicitly(p: boolean) {
  return p ? 'value' : Promise.resolve('value');
}
Open in Playground

选项​

allowAny​

是否忽略返回 any 和 unknown 的函数。 如果你想要额外的安全性，请考虑关闭此选项，因为它会使规则更难捕获不正确的 Promise 行为。

英：Whether to ignore functions that return any and unknown. If you want additional safety, consider turning this option off, as it makes the rule less able to catch incorrect Promise behaviors.

{ "allowAny": false } 的代码示例：

英：Examples of code with { "allowAny": false }:

const returnsAny = () => ({}) as any;
Open in Playground

allowedPromiseNames​

对于使用全局内置 Promise 以外的构造来实现异步代码的项目。 此选项允许指定导致函数被检查的类或接口的字符串名称。

英：For projects that use constructs other than the global built-in Promise for asynchronous code. This option allows specifying string names of classes or interfaces that cause a function to be checked as well.

{ "allowedPromiseNames": ["Bluebird"] } 的代码示例：

英：Examples of code with { "allowedPromiseNames": ["Bluebird"] }:

import { Bluebird } from 'bluebird';

const returnsBluebird = () => new Bluebird(() => {});
Open in Playground

checkArrowFunctions​

是否检查箭头函数。 默认为 true，但可以设置为 false 以忽略它们。

英：Whether to check arrow functions. true by default, but can be set to false to ignore them.

checkFunctionDeclarations​

是否检查独立函数声明。 默认为 true，但可以设置为 false 以忽略它们。

英：Whether to check standalone function declarations. true by default, but can be set to false to ignore them.

checkFunctionExpressions​

是否检查内联函数表达式。 默认为 true，但可以设置为 false 以忽略它们。

英：Whether to check inline function expressions. true by default, but can be set to false to ignore them.

checkMethodDeclarations​

默认情况下是否检查类和对象字面量 true 上的方法，但可以设置为 false 以忽略它们。

英：Whether to check methods on classes and object literals true by default, but can be set to false to ignore them.

何时不使用它​

在使用要求函数始终为 async 的 API 的项目上启用此规则可能很困难。 你可以考虑使用 ESLint 禁用注释 以及针对这些特定情况归档依赖的问题，而不是完全禁用此规则。

英：This rule can be difficult to enable on projects that use APIs which require functions to always be async. You might consider using ESLint disable comments along with filing issues on your dependencies for those specific situations instead of completely disabling this rule.

选项​

该规则接受以下选项

type Options = [
  {
    /** Whether to consider `any` and `unknown` to be Promises. */
    allowAny?: boolean;
    /** Any extra names of classes or interfaces to be considered Promises. */
    allowedPromiseNames?: string[];
    checkArrowFunctions?: boolean;
    checkFunctionDeclarations?: boolean;
    checkFunctionExpressions?: boolean;
    checkMethodDeclarations?: boolean;
  },
];

const defaultOptions: Options = [
  {
    allowAny: true,
    allowedPromiseNames: [],
    checkArrowFunctions: true,
    checkFunctionDeclarations: true,
    checkFunctionExpressions: true,
    checkMethodDeclarations: true,
  },
];

资源​