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

allowAny​

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

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

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

allowedPromiseNames​

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.

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

class Bluebird {}

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

checkArrowFunctions​

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

checkFunctionDeclarations​

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

checkFunctionExpressions​

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

checkMethodDeclarations​

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

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

Resources​