Skip to main content

promise-function-async

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

🔧

Some problems reported by this rule are automatically fixable by the --fix ESLint command line option.

💭

This rule requires type information to run.

Ensures that each function is only capable of:

  • returning a rejected promise, or
  • throwing an Error object.

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.

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.

.eslintrc.cjs
module.exports = {
  "rules": {
    "@typescript-eslint/promise-function-async": "error"
  }
};
Try this rule in the playground ↗

Examples​

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

Options​

This rule accepts the following options:

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

When Not To Use It​

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 Performance Troubleshooting if you experience performance degredations after enabling type checked rules.

Resources​