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.
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 Playgroundconst 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 PlaygroundOptionsβ
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,
},
];
allowAny
β
Whether to ignore functions that return any
and 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 }
:
- β Incorrect
- β Correct
const returnsAny = () => ({}) as any;
Open in Playgroundconst returnsAny = async () => ({}) as any;
Open in PlaygroundallowedPromiseNames
β
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"] }
:
- β Incorrect
- β Correct
class Bluebird {}
const returnsBluebird = () => new Bluebird(() => {});
Open in Playgroundclass Bluebird {}
const returnsBluebird = async () => new Bluebird(() => {});
Open in PlaygroundcheckArrowFunctions
β
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 Performance Troubleshooting if you experience performance degredations after enabling type checked rules.