falconGitHub

prefer-return-await

Path
lint/performance/prefer-return-await
Default
Off, opt in
Origin
Falcon
Rule
399 of 512

Await returned SDK Futures inside a try body protected by a catch clause.

Without awaiting, asynchronous failures bypass the local catch clauses. Function-body boundaries prevent an outer try from affecting nested closures.

Invalid

example.dartdart
import 'dart:async';
import 'dart:async' as async;

Future<int> fetch() async => 1;
Future<int> guarded() async {
  try {
    return fetch();
  } catch (_) { return 0; }
}
Future<int> typedCatch() async {
  try {
    return (fetch());
  } on Exception { return 0; }
}
Future<int> branch(bool condition) async {
  try {
    if (condition) {
      return fetch();
    }
    return 0;
  } catch (_) { return 0; }
}
Future<int> nestedTry() async {
  try {
    try { return fetch();  }
    finally { print('cleanup'); }
  } catch (_) { return 0; }
}
async.Future<int> prefixed(async.Future<int> value) async {
  try { return value;  }
  catch (_) { return 0; }
}
Returning this `Future` without awaiting lets asynchronous failures bypass the catch block. Return `await` on the `Future` instead.
6 try {
7 return fetch();
Returning this `Future` without awaiting lets asynchronous failures bypass the catch block. Return `await` on the `Future` instead.
11 try {
12 return (fetch());
Returning this `Future` without awaiting lets asynchronous failures bypass the catch block. Return `await` on the `Future` instead.
17 if (condition) {
18 return fetch();
Returning this `Future` without awaiting lets asynchronous failures bypass the catch block. Return `await` on the `Future` instead.
24 try {
25 try { return fetch(); }
Returning this `Future` without awaiting lets asynchronous failures bypass the catch block. Return `await` on the `Future` instead.
29async.Future<int> prefixed(async.Future<int> value) async {
30 try { return value; }

Valid

example.dartdart
import 'dart:async';
Future<int> fetch() async => 1;
Future<int> forwarding() => fetch();
Future<int> outside() async { return fetch(); }
Future<int> arrow() async => fetch();
Future<int> awaited() async {
  try { return await fetch(); } catch (_) { return 0; }
}
Future<int> scalar() async {
  try { return 1; } catch (_) { return 0; }
}
Future<int> finalizerOnly() async {
  try { return fetch(); } finally { print('done'); }
}
Future<int> finalizerReturn() async {
  try { return 1; } catch (_) { return 0; }
  finally { return fetch(); }
}
Future<int> catchReturn() async {
  try { return 1; } catch (_) { return fetch(); }
}
Future<int> nested() async {
  try {
    Future<int> inner() async { return fetch(); }
    return await inner();
  } catch (_) { return 0; }
}
Future<dynamic> unknown(dynamic value) async {
  try { return value; } catch (_) { return 0; }
}

Configure prefer-return-await

Set its severity in falcon.json. See the configuration guide.

falcon.jsonjson
{
  "linter": {
    "rules": {
      "performance": {
        "prefer-return-await": "error"
      }
    }
  }
}

Or silence one occurrence with a suppression comment; the reason is required.

example.dartdart
// falcon-ignore lint/performance/prefer-return-await: <reason>
  • prefer-single-setstateflutter

    Merge consecutive Flutter State.setState statements in the same block.

  • prefer-use-callbackflutter_hooks

    Prefer useCallback for synchronous memoized function literals.

  • prefer-use-memoflutter_hooks

    Prefer memoizing freshly allocated collection values used as hook keys.

  • prefer-using-list-viewflutter

    Suggests considering ListView for a SingleChildScrollView containing a plain Flutter Column with at least two unconditional children in a list literal.

  • sized-box-for-whitespacesized_box_for_whitespacerecommendedflutter

    Flags a Container used only to add fixed width/height whitespace.

  • unnecessary-to-list-in-spreadsunnecessary_to_list_in_spreadsrecommended

    Flags a .toList() call on the operand of a spread, e.g.

  • use-is-even-rather-than-modulouse_is_even_rather_than_modulo

    Prefers isEven/isOdd to comparing x % 2 with 0 or 1.

  • use-string-buffersuse_string_buffersrecommended

    Prefers a StringBuffer to growing a String with + inside a loop.