Skip to content

avoid-nested-futures

Group: Correctness
Path: lint/correctness/avoid-nested-futures
Default: Off, opt in
Origin: Falcon
Rule: 99 of 512

Avoid Future<Future<T>>, FutureOr<Future<T>>, and other directly nested future wrappers. Return Future<T> (or FutureOr<T>) instead.

Checks explicit type occurrences, including expanded typedefs, using SDK declaration identities and lexical type parameters. Collections of futures are not nested wrappers; inferred-only types are deliberately not reported.

Reference: https://dcm.dev/docs/rules/common/avoid-nested-futures/

Invalid

example.dartdart

import 'dart:async';
import 'dart:async' as async;

Future<Future<int>>? first;
FutureOr<Future<int>>? second;
FutureOr<FutureOr<int>>? third;
Future<FutureOr<String>>? fourth;
async.Future<async.Future<int>>? prefixed;
void consume(Future<Future<void>> value) {}

Remove the nested future wrapper; return a single `Future` or `FutureOr` instead.

3

4Future<Future<int>>? first;

∙

Remove the nested future wrapper; return a single `Future` or `FutureOr` instead.

4Future<Future<int>>? first;

5FutureOr<Future<int>>? second;

∙

Remove the nested future wrapper; return a single `Future` or `FutureOr` instead.

5FutureOr<Future<int>>? second;

6FutureOr<FutureOr<int>>? third;

∙

Remove the nested future wrapper; return a single `Future` or `FutureOr` instead.

6FutureOr<FutureOr<int>>? third;

7Future<FutureOr<String>>? fourth;

∙

Remove the nested future wrapper; return a single `Future` or `FutureOr` instead.

7Future<FutureOr<String>>? fourth;

8async.Future<async.Future<int>>? prefixed;

∙

Remove the nested future wrapper; return a single `Future` or `FutureOr` instead.

8async.Future<async.Future<int>>? prefixed;

9void consume(Future<Future<void>> value) {}

∙

Valid

example.dartdart

import 'dart:async';

Future<int>? one;
FutureOr<int>? maybe;
List<Future<int>>? many;
Future<List<int>>? collection;
Future<Stream<int>>? stream;
Future<int> Function()? callback;
Future? raw;

Configure avoid-nested-futures

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

falcon.jsonjson

{
  "linter": {
    "rules": {
      "correctness": {
        "avoid-nested-futures": "error"
      }
    }
  }
}

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

example.dartdart

// falcon-ignore lint/correctness/avoid-nested-futures: <reason>

avoid-nested-streams-and-futures
Avoid directly nesting SDK streams and futures: Stream<Future<T>> and Future<Stream<T>> complicate consumption.
avoid-read-inside-buildrecommendedprovider
Flags non-listening Provider reads directly inside Flutter widget builds.
avoid-recursive-calls
Reports direct self-calls in functions and methods, including guarded recursion.
avoid-recursive-widget-callsrecommendedflutter
Warns when a widget's build method constructs the same widget again.
avoid-ref-inside-state-disposeriverpod
Rejects Riverpod widget references used during State.dispose.
avoid-ref-read-inside-buildrecommendedriverpod
Flags one-time Riverpod reads of provider state during widget build.
avoid-ref-watch-outside-buildrecommendedriverpod
Flags Riverpod WidgetRef.watch subscriptions outside synchronous widget build bodies.
avoid-relative-lib-importsavoid_relative_lib_importsrecommended
Disallow relative imports that reach into a lib/ directory.