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

❌ Incorrect
✅ Correct

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

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

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

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

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.

Examples​

Options​

When Not To Use It​

Resources​

Examples

Options

When Not To Use It

Resources