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.

eslint.config.mjs
export default tseslint.config({
  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 consider any and unknown to be Promises. Default: true.

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​

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

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. 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​

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.

Resources​