Suggest an edit

Improve this article

Refine the answer for “What await does”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

**`await` is an operator that suspends the execution of an `async` function until a promise is fulfilled or rejected.** After that, `await` either returns the promise result or throws an error, just like a plain `throw`.

## Theory

### TL;DR
- `await` waits for a promise to settle inside an `async` function.
- If the promise fulfills, `await` returns its value.
- If the promise rejects, `await` throws, and `try...catch` catches it.
- It works only inside `async` functions or as top-level await in modules.
- It does not block the thread: other code keeps running while the function is paused.
- It also works with plain values: they are wrapped in `Promise.resolve(value)`.

### Quick example
```javascript
let result = await promise; // only inside an async function or top-level await

async function example() {
  console.log('Before await');
  const value = await Promise.resolve('Done');
  console.log('After await:', value);
}

example();
```

### Syntax and what await returns
```javascript
let result = await promise;
```

It works **only inside `async` functions** (or in top-level await in modules).

**Example 1, waiting for a promise**

```javascript
async function example() {
  console.log('Before await');
  const result = await Promise.resolve('Done');
  console.log('After await:', result);
}

example();
```

Output:

```text
Before await
After await: Done
```

`await` waits for the promise to settle and returns `'Done'`.

**Example 6, with non promise values.** If you pass a plain value, it is immediately **wrapped in `Promise.resolve()`**:

```javascript
async function demo() {
  const result = await 42;
  console.log(result);
}
demo(); // 42
```

This exists for uniformity: `await` always behaves as if a promise stood in front of it.

**Example 7, nested await**

```javascript
async function inner() {
  return 'Inside';
}

async function outer() {
  const res = await inner();
  console.log('Result:', res);
}

outer();
```

Output:

```text
Result: Inside
```

Since `inner()` returns a promise, `await` simply waits for it to settle.

### A rejection turns into an exception
**Example 2, an error through `await`**

```javascript
async function fail() {
  try {
    const res = await Promise.reject('Failure!');
  } catch (err) {
    console.error('Caught:', err);
  }
}

fail();
```

Output:

```text
Caught: Failure!
```

If a promise is rejected, `await` **throws an exception**, which is why errors are conveniently caught with `try...catch`.

### Sequential or parallel
**Example 3, sequential execution**

```javascript
async function steps() {
  console.log('1');
  await new Promise(res => setTimeout(res, 1000));
  console.log('2');
  await new Promise(res => setTimeout(res, 1000));
  console.log('3');
}

steps();
```

Output:

```text
1
(after 1 second)
2
(after 1 second)
3
```

Each `await` waits for the previous promise, so the code runs sequentially.

**Example 4, parallel execution (no immediate `await`)**

```javascript
async function parallel() {
  const a = fetch('/api/user');
  const b = fetch('/api/posts');

// both run at the same time
  const [user, posts] = await Promise.all([a, b]);
  console.log('Both requests finished');
}
```

If you put `await` in front of each request, they run **one after another** instead of in parallel.

### How await works inside the Event Loop
When the engine meets `await promise`, it:

1. suspends execution of the current `async` function;
2. registers the continuation (the rest of the function body) as a **microtask**;
3. frees the main thread, so other code can run;
4. when the promise settles, the microtask runs the rest of the function.

That is why `await` does not "block" JS, it only postpones the continuation of the function until the promise is ready.

**Example 5, a "pause" without blocking**

```javascript
async function wait() {
  console.log('Start');
  await new Promise(res => setTimeout(res, 2000));
  console.log('End');
}

wait();
console.log('This code runs while the waiting is going on!');
```

Output:

```text
Start
This code runs while the waiting is going on!
(after 2 seconds)
End
```

`await` does not block the thread, only the function itself.

### Summary
> Think of `await` as a pause at a traffic light:
>
> - the light is red (`Promise pending`), you wait;
> - green (`fulfilled`), you drive on;
> - a crash (`rejected`), an error is thrown and you move to `catch`.

| Feature | Description |
| --- | --- |
| **What it does** | suspends the `async` function until the promise settles |
| **Returns** | the `resolve` value, or throws on `reject` |
| **Where it can be used** | only inside `async` functions (or top-level await in modules) |
| **Does not block** | the rest of the program keeps running |
| **Works with** | promises and plain values (`Promise.resolve(value)`) |

### Common mistakes
- **Believing `await` blocks the page.** It pauses only its own function, not the thread: timers, event handlers and the rest of the code keep running.
- **`await` inside a loop for independent requests.** Every iteration waits for the previous one; independent operations belong in `Promise.all`.
- **Not wrapping `await` in `try...catch`.** A rejected promise throws, and without handling it becomes an unhandled rejection.
- **`await` outside an `async` function** in a classic script: that is a SyntaxError. Top-level await is available only in modules.
- **Putting `await` in front of every `fetch`** when the requests are independent: you are deliberately making the code slower.

Markdown · drag & drop images · ⌘B / ⌘I shortcuts844 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.