Detects missing await on async function calls
STOP: Are you a Flow or a Typescript user? Prefer these:
You'll first need to install ESLint:
$ npm i eslint --save-dev
Next, install eslint-plugin-no-floating-promise
:
$ npm install eslint-plugin-no-floating-promise --save-dev
Note: If you installed ESLint globally (using the -g
flag) then you must also install eslint-plugin-no-floating-promise
globally.
Add no-floating-promise
to the plugins section of your .eslintrc
configuration file. You can omit the eslint-plugin-
prefix:
{
"plugins": [
"no-floating-promise"
]
}
Then configure the rules you want to use under the rules section.
{
"rules": {
"no-floating-promise/no-floating-promise": 2
}
}
If you're using flat config (eslint.config.js
), which is default configuration format for eslint since v.9.0.0
:
const noFloatingPromise = require("eslint-plugin-no-floating-promise");
module.exports = [
{
plugins: {
"no-floating-promise": noFloatingPromise,
},
rules: {
"no-floating-promise/no-floating-promise": 2
}
}
];
The --fix
option on the command line automatically fixes problems reported by this rule.
Promises that are never awaited can cause unexpected behavior because they may be scheduled to execute at an unexpected time.
It's easy to accidentally make this mistake. For example, suppose we have the code
function writeToDb() {
// synchronously write to DB
}
writeToDb();
but the code gets refactored so that writing to the database is asynchronous.
async function writeToDb() {
// asynchronously write to DB
}
writeToDb(); // <- note we have no await here but probably the user intended to await on this!
This rule will fire for any call to an async
function that both
- not used (not assigned to a variable, not the return type of a function, etc.)
- not awaited on
Examples of incorrect code for this rule:
/*eslint no-floating-promise: "error"*/
async function foo() {}
foo();
(async () => 5)();
// note: function is not async but a Promise return type is specified
function foo(): Promise<void> { return Promise.resolve(); };
foo();
Examples of correct code for this rule:
/*eslint no-floating-promise: "error"*/
async function foo() {}
await foo();
await (async () => 5)();
// note: function is not async but a Promise return type is specified
function foo(): Promise<void> { return Promise.resolve(); };
await foo();
// note: promise is not awaited, but it is chained with a 'then'
async function foo() {}
foo().then(() => {});
You may catch additional errors by combining this rule with no-unused-expression
.
For example the following will not be considered an error by this plugin, but no-unused-expression
will complain that fooResult
is never used.
async function foo() {}
const fooResult = foo();
If you often make use of asynchronous functions were you explicitly do not want to await on them.
It's possible for a function to return a promise and not be async (as seen in test cases for this rule). My rule can leverage type annotations to detect these cases but if no type annotation is present, then no error is reported. We could modify this rule to traverse into the AST to see if the return is a promise or not but this sounds more expensive and would still not catch all cases so I didn't include this logic.
Additionally, TypeAnnotations are only generated for explicit Flow types so this rule can't take advantage of Flow inference. You could argue this rule would be more effective if implemented directly in Flow but this rule can still catch cases for vanilla Javascript so it didn't feel right to make Flow a dependency for this kind of linting.
Currently using then
or catch
silences this rule
async function foo() {}
foo().then(() => {});
You could argue this is desired since it avoids false-positive where developers explicitly do not want to await. I'm open to feedback about whether or not people want this behavior.
Right now my rule reports an error in the following case
async function foo() {}
function bar() {
foo();
}
However, adding an await
here is not possible because bar
is not an async function. In fact, my auto-fix rule would add an await
in front of foo
which would result in a compiler error.
However, likely this actually is an error and the user actually should make bar
an async function. However, I am open to disabling this rule in this context if that's what people want.
- It cannot make use of Flow inference (you need to explicitly specify types)
- It does not work across file boundaries (if import a function from a different file, you don't have any information)
- It doesn't work on member function calls (
foo.bar()
will not detect an error even ifbar
is an async function)