== Why is this an issue?

Promises 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 promise.

The reason `await` should only be used on a promise is that it expects the operand to be a promise object. When you use `await`, it waits for the promise 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 promise, awaiting it is redundant and might not have been the developer's intent.

If you try to use `await` on a non-promise 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 promise, and waits for it.

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

You should only use `await` on promises because it is designed to handle asynchronous operations and works in conjunction with the Promise API to provide a clean and intuitive way to write asynchronous code in JavaScript.

[source,javascript,diff-id=1,diff-type=compliant]
----
const x = Promise.resolve(42);
await x;
----

When calling a function that returns a promise as the last expression, you might forget to return it, especially if you refactored your code from a single-expression arrow function.

[source,js,diff-id=2,diff-type=noncompliant]
----
function foo() {
  Promise.resolve(42);
}
async function bar() {
  await foo(); // Noncompliant
}
----

Make sure that you return the promise.

[source,js,diff-id=2,diff-type=compliant]
----
function foo() {
  return Promise.resolve(42);
}
async function bar() {
  await foo(); // Compliant
}
----

=== Exceptions

The rule does not raise issues if you are awaiting a function whose definition contains JSdoc with `@returns` or `@return` tags. This is due to JSdoc often mistakenly declaring a returning type without mentioning that it is resolved by a promise. For example:

[source,js]
----
async function foo () {
  await bar(); // Compliant
}

/**
 * @return {number}
 */
async function bar () {
  return 42;
}
----

== Resources
=== Documentation

* MDN web docs - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await[await]
* MDN web docs - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise[Promise]
* MDN web docs - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await#conversion_to_promise[Conversion to promise]

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

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

=== Message

Refactor this redundant 'await' on a non-promise.


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

=== on 26 Jul 2017, 18:02:55 Ann Campbell wrote:
\[~carlo.bottiglieri] this was a bit bare-bones. I've fluffed it up some. Please double-check me.

=== on 26 Jul 2017, 18:26:10 Carlo Bottiglieri wrote:
\[~ann.campbell.2] I made a small change, for the rest it's fine for me, but the rendering of the code highlight is mostly broken in my browser (I checked and the syntax looks correct)

=== on 26 Jul 2017, 19:29:11 Ann Campbell wrote:
Yes [~carlo.bottiglieri], Jira's handling of its own markdown is broken. It will come out fine when RuleAPI generates the description tho.

=== on 27 Jul 2017, 13:42:42 Freddy Mallet wrote:
\[~carlo.bottiglieri] and [~ann.campbell.2], let's go for the creation of the implementation tickets for JS and TS ?

=== on 9 Aug 2017, 18:09:57 Elena Vilchik wrote:
I removed from default profile. While we can add it back if make rule configurable (list of promise-like classes)

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