An
async function
declaration creates an
AsyncFunction
object. Each time when an async function is called, it returns a new
Promise
which will be resolved with the value returned by the async function, or rejected with an exception uncaught within the async function.
Async functions can contain zero or more
await
expressions. Await expressions make promise-returning functions behave as though they're synchronous by suspending execution until the returned promise is fulfilled or rejected. The resolved value of the promise is treated as the return value of the await expression. Use of
async
and
await
enables the use of ordinary
try
/
catch
blocks around asynchronous code.
Note:
The
await
keyword is only valid inside async functions within regular JavaScript code. If you use it outside of an async function's body, you will get a
SyntaxError
.
await
can be used on its own with
JavaScript modules.
Note:
The purpose of
async
/
await
is to simplify the syntax
necessary to consume promise-based APIs. The behavior
of
async
/
await
is similar to combining
generators
and
promises.
Async functions always return a promise. If the return value of an async function is
not explicitly a promise, it will be implicitly wrapped in a promise.
For example, consider the following code:
async
function
foo
(
)
{
return
1
;
}
It is similar to:
function
foo
(
)
{
return
Promise
.
resolve
(
1
)
;
}
Note:
Even though the return value of an async function behaves as if it's wrapped in a
Promise.resolve
, they are not equivalent.
An async function will return a different
reference
, whereas
Promise.resolve
returns the same reference if the given value is a promise.
It can be a problem when you want to check the equality of a promise and a return value of an async function.
const
p
=
new
Promise
(
(
res
,
rej
)
=>
{
res
(
1
)
;
}
)
;
async
function
asyncReturn
(
)
{
return
p
;
}
function
basicReturn
(
)
{
return
Promise
.
resolve
(
p
)
;
}
console
.
log
(
p
===
basicReturn
(
)
)
;
console
.
log
(
p
===
asyncReturn
(
)
)
;
The body of an async function can be thought of as being split by zero or more await
expressions. Top-level code, up to and including the first await expression (if there is
one), is run synchronously. In this way, an async function without an await expression
will run synchronously. If there is an await expression inside the function body,
however, the async function will always complete asynchronously.
For example:
async
function
foo
(
)
{
await
1
;
}
It is also equivalent to:
function
foo
(
)
{
return
Promise
.
resolve
(
1
)
.
then
(
(
)
=>
undefined
)
;
}
Code after each await expression can be thought of as existing in a
.then
callback. In this way a promise chain is progressively constructed with each reentrant
step through the function. The return value forms the final link in the chain.
In the following example, we successively await two promises. Progress moves through
function
foo
in three stages.
-
The first line of the body of function
foo
is executed synchronously,
with the await expression configured with the pending promise. Progress through
foo
is then suspended and control is yielded back to the function that
called
foo
.
-
Some time later, when the first promise has either been fulfilled or rejected,
control moves back into
foo
. The result of the first promise fulfillment
(if it was not rejected) is returned from the await expression. Here
1
is
assigned to
result1
. Progress continues, and the second await expression
is evaluated. Again, progress through
foo
is suspended and control is
yielded.
-
Some time later, when the second promise has either been fulfilled or rejected,
control re-enters
foo
. The result of the second promise resolution is
returned from the second await expression. Here
2
is assigned to
result2
. Control moves to the return expression (if any). The default
return value of
undefined
is returned as the resolution value of the
current promise.
async
function
foo
(
)
{
const
result1
=
await
new
Promise
(
(
resolve
)
=>
setTimeout
(
(
)
=>
resolve
(
"1"
)
)
,
)
;
const
result2
=
await
new
Promise
(
(
resolve
)
=>
setTimeout
(
(
)
=>
resolve
(
"2"
)
)
,
)
;
}
foo
(
)
;
Note how the promise chain is not built-up in one go. Instead, the promise chain is
constructed in stages as control is successively yielded from and returned to the async
function. As a result, we must be mindful of error handling behavior when dealing with
concurrent asynchronous operations.
For example, in the following code an unhandled promise rejection error will be thrown,
even if a
.catch
handler has been configured further along the promise
chain. This is because
p2
will not be "wired into" the promise chain until
control returns from
p1
.
async
function
foo
(
)
{
const
p1
=
new
Promise
(
(
resolve
)
=>
setTimeout
(
(
)
=>
resolve
(
"1"
)
,
1000
)
)
;
const
p2
=
new
Promise
(
(
_
,
reject
)
=>
setTimeout
(
(
)
=>
reject
(
"2"
)
,
500
)
)
;
const
results
=
[
await
p1
,
await
p2
]
;
}
foo
(
)
.
catch
(
(
)
=>
{
}
)
;
async function
declarations behave similar to
function
declarations ? they are
hoisted
to the top of their scope and can be called anywhere in their scope, and they can be redeclared only in certain contexts.