== Why is this an issue?

Futures are objects that represent the eventual completion or failure of an asynchronous operation. They provide a way to handle asynchronous operations in a more organized and manageable manner. To use `await`, you need to ensure that you are calling a function or an expression that returns a future.

The reason `await` should only be used on a future is that it expects the operand to be a future object. When you use `await`, it waits for the future to be resolved or rejected and then returns the resolved value or throws the rejection reason, respectively. If the operand of `await` is not a future, awaiting it is redundant and might not have been the developer's intent.

If you try to use `await` on a non-future value, such as a regular object or a primitive type, it will not pause the execution of the function because there is no asynchronous behavior involved. Instead, `await` will convert the value to a resolved future, and will wait for it to complete.

[source,dart,diff-id=1,diff-type=noncompliant]
----
var x = 42;
await x; // Noncompliant: x is a number, not a promise
----

[source,dart,diff-id=1,diff-type=compliant]
----
var x = functionReturningFuture();
await x;
----

== Resources

=== Documentation

* Dart Docs - https://dart.dev/tools/linter-rules/await_only_futures[Dart Linter rule - await_only_futures]
* Dart Docs - https://dart.dev/libraries/async/async-await[Asynchronous programming: futures, async, await]

ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

=== Message

Uses 'await' on an instance of 'int', which is not a subtype of 'Future'.

=== Highlighting

The `await` keyword.

'''
== Comments And Links
(visible only on this page)

endif::env-github,rspecator-view[]
