Skip to main content

return-await

Enforce consistent returning of awaited values.

🛠

Some problems reported by this rule are automatically fixable by the --fix ESLint command line option.

💡

Some problems reported by this rule are manually fixable by editor suggestions.

💭

This rule requires type information to run.

Returning an awaited promise can make sense for better stack trace information as well as for consistent error handling (returned promises will not be caught in an async function try/catch).

Examples

This rule builds on top of the eslint/no-return-await rule. It expands upon the base rule to add support for optionally requiring return await in certain cases.

How to Use

.eslintrc.cjs
module.exports = {
"rules": {
// Note: you must disable the base rule as it can report incorrect errors
"no-return-await": "off",
"@typescript-eslint/return-await": "warn"
}
};

Options

See eslint/no-return-await options.

type Options = 'in-try-catch' | 'always' | 'never';

const defaultOptions: Options = 'in-try-catch';

in-try-catch

Requires that a returned promise must be awaited in try-catch-finally blocks, and disallows it elsewhere. Specifically:

  • if you return a promise within a try, then it must be awaited.
  • if you return a promise within a catch, and there is no finally, then it must not be awaited.
  • if you return a promise within a catch, and there is a finally, then it must be awaited.
  • if you return a promise within a finally, then it must not be awaited.

Examples of code with in-try-catch:

async function invalidInTryCatch1() {
try {
return Promise.resolve('try');
} catch (e) {}
}

async function invalidInTryCatch2() {
try {
throw new Error('error');
} catch (e) {
return await Promise.resolve('catch');
}
}

async function invalidInTryCatch3() {
try {
throw new Error('error');
} catch (e) {
return Promise.resolve('catch');
} finally {
console.log('cleanup');
}
}

async function invalidInTryCatch4() {
try {
throw new Error('error');
} catch (e) {
throw new Error('error2');
} finally {
return await Promise.resolve('finally');
}
}

async function invalidInTryCatch5() {
return await Promise.resolve('try');
}

async function invalidInTryCatch6() {
return await 'value';
}

always

Requires that all returned promises are awaited.

Examples of code with always:

async function invalidAlways1() {
try {
return Promise.resolve('try');
} catch (e) {}
}

async function invalidAlways2() {
return Promise.resolve('try');
}

async function invalidAlways3() {
return await 'value';
}

never

Disallows all awaiting any returned promises.

Examples of code with never:

async function invalidNever1() {
try {
return await Promise.resolve('try');
} catch (e) {}
}

async function invalidNever2() {
return await Promise.resolve('try');
}

async function invalidNever3() {
return await 'value';
}

Taken with ❤️ from ESLint core

Resources