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，或者

  ¥returning a rejected promise, or

• 抛出一个 Error 对象。

  ¥throwing an Error object.

相比之下，非 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 类型的联合时，通常是一个错误 - 此规则会标记这些情况。如果是故意的，请显式设置返回类型以允许规则通过。

¥When functions return unions of Promise and non-Promise types implicitly, it is usually a mistake—this rule flags those cases. If it is intentional, make the return type explicitly to allow the rule to pass.

Flat Config

eslint.config.mjs

export default tseslint.config({
  rules: {
    "@typescript-eslint/promise-function-async": "error"
  }
});

Legacy Config

.eslintrc.cjs

module.exports = {
  "rules": {
    "@typescript-eslint/promise-function-async": "error"
  }
};

在线运行试试这个规则 ↗

示例

¥Examples

此规则的代码示例

¥Examples of code for this rule

❌ Incorrect

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

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

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

Open in Playground

✅ Correct

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

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

// An explicit return type that is not Promise means this function cannot be made async, so it is ignored by the rule
function functionReturnsUnionWithPromiseExplicitly(
  p: boolean,
): string | Promise<string> {
  return p ? 'value' : Promise.resolve('value');
}

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

Open in Playground

选项

该规则接受以下选项:

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[];
    /** Whether to check arrow functions. */
    checkArrowFunctions?: boolean;
    /** Whether to check standalone function declarations. */
    checkFunctionDeclarations?: boolean;
    /** Whether to check inline function expressions */
    checkFunctionExpressions?: boolean;
    /** Whether to check methods on classes and object literals. */
    checkMethodDeclarations?: boolean;
  },
];

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

¥Options

allowAny

Whether to consider any and unknown to be Promises. Default: true.

如果你想要额外的安全性，请考虑关闭此选项，因为它会使规则更难捕获不正确的 Promise 行为。

¥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 }:

❌ Incorrect

const returnsAny = () => ({}) as any;

Open in Playground

✅ Correct

const returnsAny = async () => ({}) as any;

Open in Playground

allowedPromiseNames

Any extra names of classes or interfaces to be considered Promises. Default: [].

对于使用除全局内置 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"] }:

❌ Incorrect

class Bluebird {}

const returnsBluebird = () => new Bluebird(() => {});

Open in Playground

✅ Correct

class Bluebird {}

const returnsBluebird = async () => new Bluebird(() => {});

Open in Playground

checkArrowFunctions

Whether to check arrow functions. Default: true.

checkFunctionDeclarations

Whether to check standalone function declarations. Default: true.

checkFunctionExpressions

Whether to check inline function expressions Default: true.

checkMethodDeclarations

Whether to check methods on classes and object literals. Default: true.

何时不使用它

¥When Not To Use It

在使用要求函数始终为 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 checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting.

See Troubleshooting > Linting with Type Information > Performance if you experience performance degradations after enabling type checked rules.

'## 资源'

• 规则源码
• 测试源码