JavaScript async/await: Write Async Code That Reads Top-Down

async/await Is Just Promises in Disguise

async/await isn't a new concurrency model. It's sugar on top of promises that lets you write code that looks sequential even though it's asynchronous. Same machinery, much friendlier shape.

Here's the same task written both ways:

Both functions return a promise. Both do exactly the same thing. The async version reads top-to-bottom with no .then chain — that's the whole appeal.

async Marks a Function as Returning a Promise

Put async in front of a function, an arrow function, or a method, and two things happen:

1. The function always returns a promise. Whatever you return becomes the resolved value.
2. You're allowed to use await inside it.

Notice result isn't the string — it's a promise that resolves to the string. Even though greet contains no await and no async work, the async keyword still wraps the return value in a promise. If the function throws, the promise rejects.

await Pauses Until a Promise Settles

Inside an async function, await somePromise pauses that function until the promise resolves, then hands you the resolved value. If the promise rejects, await throws.

Watch the output order. "started countdown" prints before "2" — because await only pauses the async function, not the rest of the program. The event loop keeps running; countdown just resumes later when each wait promise resolves.

You can await anything promise-like. await 42 is legal too — non-promises get wrapped in Promise.resolve(42) and resolved immediately.

Error Handling With try/catch

With plain promises you chain .catch(). With async/await, a rejected promise becomes a thrown exception you can catch the normal way:

One try/catch covers every await inside it. Network failures, JSON parse errors, and your own throw statements all land in the same catch. That's a real upgrade over nested .then/.catch chains.

One thing to watch: fetch only rejects on network errors, not HTTP 4xx/5xx. You check res.ok yourself and throw — a pattern you'll see constantly in real code.

Don't await in a Loop When You Don't Have To

This is the most common async/await pitfall. Sequential await inside a loop means each iteration waits for the previous one:

sequential takes ~900ms. parallel takes ~300ms. The rule of thumb: if tasks don't depend on each other's results, start them all, then await Promise.all. Only await one-by-one when the next call actually needs the previous result.

For collections, Promise.all(items.map(async (x) => ...)) is the idiom. A plain for...of with await inside runs serially — sometimes you want that (rate-limiting, ordering) but usually you don't.

Mixing async/await and Plain Promises

You don't have to pick a side. async functions return promises, and await works on any promise — so you can mix them freely:

The two styles are interchangeable. Use await when the code reads better top-down; use .then when you want a quick one-off or you're working outside an async context.

Top-Level await (in ES Modules)

Historically, you had to wrap await in an async function because await wasn't allowed at the top level of a script. That changed: inside an ES module (a .mjs file or a <script type="module">), you can now await directly at the top:

// in an ES module
const res = await fetch("https://jsonplaceholder.typicode.com/users/1");
const user = await res.json();
console.log(user.name);

Top-level await delays the module's completion until the awaited promise settles — any importer of that module waits too. Handy for config loading and dynamic imports, but use it sparingly: a slow top-level await blocks everyone who imports the module.

In CommonJS files or regular inline scripts, this still fails with a SyntaxError. The classic workaround is an immediately-invoked async function:

Things That Trip People Up

A quick tour of the usual gotchas:

• Forgetting async. Using await in a regular function is a syntax error. The fix is adding async — or calling the async helper with .then.
• Forgetting to await the result. const data = getJSON(url); gives you a promise, not the data. If you use it as if it were the value, you'll see [object Promise] show up in your output.
• Unhandled rejections. An async function you fire-and-forget (doWork();) will silently swallow errors unless you add .catch or await it inside a try/catch.
• forEach with async callbacks. array.forEach(async (x) => await something(x)) doesn't wait for anything — forEach ignores the returned promises. Use for...of with await, or Promise.all(array.map(...)).

Run it — "finished?" prints before any "done", because broken returns without waiting. fixed waits for everything, then prints "finished!" last.

When to Reach for async/await

Default to async/await for any code that does more than one asynchronous step in sequence, or that needs try/catch-style error handling. Stick with raw promises for trivial one-liners, for library code that returns a promise without needing to await anything itself, or when you genuinely need combinators like Promise.race or .finally() in a chain.

Used well, async/await makes async code read like a recipe: do this, then this, then this. The event loop still does its thing — you just get to stop thinking in callbacks.

Next: The fetch API

Most of the examples here used fetch as a stand-in for "some async thing." It's worth a proper look — how requests and responses work, handling JSON, setting headers, and why fetch doesn't reject on HTTP errors. That's the next page.