@typescript-eslint/promise-function-async

A function that returns a promise but isn't async can fail in two ways. It can return a rejected promise, or it can throw before it gets that far. The caller then needs both a try and a .catch(). An async function always returns a promise, so every failure is a rejection.

Without a return type annotation, a function is reported if any part of what it returns is a promise. With one, it's reported only if every part of the annotation is a promise.

--fix adds async.

Configure

Off by default. This rule needs types, so turning it on makes bun lint type check your code first.

[lint.rules]
"@typescript-eslint/promise-function-async" = "error" # or "warn"

Every option, set to its default:

[lint.rules]
"@typescript-eslint/promise-function-async" = ["error", {
  allowAny = true,
  allowedPromiseNames = [], # list of strings
  checkArrowFunctions = true,
  checkFunctionDeclarations = true,
  checkFunctionExpressions = true,
  checkMethodDeclarations = true,
}]

Examples

Reported:

function loadUser(id: string) {
  if (!id) throw new Error("missing id");
  return fetch(`/users/${id}`);
}

const cached = (hit?: string) => hit ?? Promise.resolve("miss");

Not reported:

async function loadUser(id: string) {
  if (!id) throw new Error("missing id");
  return fetch(`/users/${id}`);
}

const cached = (hit?: string): string | Promise<string> => hit ?? Promise.resolve("miss");

Options

Option	Default	What it does
allowAny	true	With false, also report functions that return any or unknown.
allowedPromiseNames	[]	Names of other classes or interfaces to treat as promises.
checkArrowFunctions	true	Check arrow functions.
checkFunctionDeclarations	true	Check function declarations.
checkFunctionExpressions	true	Check function expressions and object literal methods.
checkMethodDeclarations	true	Check class methods.

Reported with allowAny: false:

function parse(text: string): unknown {
  return JSON.parse(text);
}

Reported with allowedPromiseNames: ["Task"]:

class Task {}

function start() {
  return new Task();
}

Not reported with checkFunctionExpressions: false:

const api = {
  ping() {
    return fetch("/ping");
  },
};