Asynchronous JavaScript

Synchronous code finishes the current statement before moving to the next. Your page’s JavaScript runs on one main thread, so two pieces of that code do not execute at the same instant. This is easy to follow until a statement starts work whose result will arrive later.

Start now, handle the result later

An asynchronous operation starts now and delivers its result afterward, through a callback or a promise. The browser or Node.js is the host environment. It manages the waiting while your program continues. Timers, user input, and image loading all use this kind of arrangement.

console.log("Opening");
setTimeout(() => console.log("Ready"), 700);
console.log("Waiting");

Read the call to setTimeout as “register this function.” It returns without waiting 700 ms. The current script therefore logs "Opening" and "Waiting" first. After about 700 ms, the callback can run and log "Ready". The exact delay also depends on when the main thread becomes free.

There are two different activities here: the environment tracks the timer, and JavaScript eventually calls the function that logs the result. The waiting overlaps other work; the callback still runs on the main thread.

Why a page freezes

A long synchronous loop keeps the thread occupied. While it runs, click handlers and timer callbacks cannot execute, and the page cannot update its display through that thread. Registering a zero-delay timer does not give it permission to interrupt the loop.

Suppose a timer becomes ready while a calculation is still running. The environment queues its callback. Finishing the calculation is what frees the thread; the timer’s deadline alone cannot do that. A callback that performs another long calculation can freeze the page too.

To reduce a calculation’s effect on responsiveness, divide it into smaller pieces that allow other tasks between them, or move suitable work to a web worker, a separate background thread provided by the browser. Simply putting a large loop inside an async function leaves that loop on the main thread.

Three ways to receive a result

A callback passes the next action as a function. A promise represents one eventual outcome and lets you attach success and failure handlers. An async function works with promises while await lets its own execution pause at a clear point.

These styles coexist. A timer still takes a callback even when the surrounding code uses promises. An async function can await a promise produced by a callback wrapper. Choose the style that makes the result’s path easy to follow.

When reading asynchronous code, first mark the statements that run during the current call. Next mark the functions registered for later. A line inside a registered callback does not run merely because execution has reached the line that creates that function.

The event loop coordinates work that is ready to run. To predict output, keep three things separate: the functions running now, callbacks waiting as tasks, and promise-related work waiting as microtasks.

Follow the stack and queues

The call stack holds active function calls. Calling a function pushes a frame onto it; returning removes that frame. The current function runs until it returns or calls another function.

A task can be a script, a timer callback, or a click handler. Tasks run one at a time. Browsers can have multiple task queues, so do not assume every source of work shares one universal first-in, first-out queue.

The microtask queue contains promise handlers from then, catch, and finally, continuations after await, and callbacks passed to queueMicrotask. At a microtask checkpoint after the current work, the queue drains before the next task. Microtasks added during that drain also run before the next task.

Trace one script

console.log("begin");
setTimeout(() => console.log("timer"), 0);
Promise.resolve().then(() => console.log("promise"));
console.log("finish");

1. The script logs "begin".
2. It registers a timer callback; it does not call it.
3. It queues the fulfilled promise’s handler as a microtask.
4. It logs "finish" and finishes the current work.
5. The microtask logs "promise".
6. The timer task logs "timer".

An already fulfilled promise still schedules its handler for later. A delay of 0 ms still schedules a timer task.

Include jobs added along the way

Promise.resolve()
  .then(() => console.log("first"))
  .then(() => console.log("third"));
queueMicrotask(() => console.log("second"));
console.log("now");

The script logs "now". The microtask queue initially holds the first promise handler, then the queueMicrotask callback. When the first handler logs "first" and returns, it makes the next promise handler ready. That new handler joins the end of the queue. The remaining output is "second", then "third".

Completion and responsiveness

Once a task or microtask begins, asynchronously queued work cannot interrupt it. This run-to-completion behavior lets you reason about a local change without a timer suddenly entering halfway through the function.

After microtasks finish, the browser can update the screen at a rendering opportunity. It does not have to repaint after every task. An endless stream of microtasks can prevent both later tasks and rendering: each new microtask keeps the current drain going. Deferring work to a microtask therefore does not guarantee that the page gets a chance to respond.

For a trace, write the immediate output first, drain microtasks in order, and only then move to ready timer tasks. Add newly scheduled work to the appropriate queue when the code actually schedules it.

Track a timer created by a microtask

setTimeout(() => console.log("outer timer"), 0);
Promise.resolve().then(() => {
  console.log("job one");
  setTimeout(() => console.log("inner timer"), 0);
}).then(() => console.log("job two"));
console.log("script");

The script registers the outer timer and the first promise handler, then logs "script". The first microtask logs "job one" and registers the inner timer. Returning from that handler queues "job two", which also runs before a timer task. The output ends with "outer timer", then "inner timer": both timers have the same delay, and the outer one was registered first.

Creating a timer during a microtask does not make its callback a microtask. Classify the work by the scheduling API that receives it, then add it to the appropriate queue.

Timers schedule callbacks for later. They measure a delay in milliseconds: 1000 ms is 1 s. The delay sets when a callback can become eligible to run; other work and browser limits can make it run later.

Schedule and cancel one call

function remind(topic) {
  console.log("Review " + topic);
}
const reminder = setTimeout(remind, 2000, "promises");
// To cancel before it runs:
clearTimeout(reminder);

Extra arguments after the delay are passed to the callback. A missing delay counts as 0. Save the returned timer handle if you may need to cancel it. Browsers return a numeric ID; Node.js returns a Timeout object. Both work with clearTimeout. Clearing a finished or nonexistent timer has no effect.

Pass a function: setTimeout(remind, 2000, "promises"). Writing setTimeout(remind("promises"), 2000) calls remind immediately and passes its return value to the timer. An arrow function is another way to delay a call with arguments: setTimeout(() => remind("promises"), 2000).

Repeat with an interval or another timeout

let ticks = 0;
const clock = setInterval(() => {
  ticks++;
  console.log("Tick " + ticks);
  if (ticks === 3) clearInterval(clock);
}, 1000);

The first tick is after about one second. The third callback stops future ticks. Keep the interval handle and use clearInterval when the repeating work should end.

A callback can instead schedule its own next timeout. When it calls setTimeout at the end of its synchronous work, the next delay starts after that work. This gives a pause between runs and allows a different delay each time. An interval keeps asking for runs on a fixed schedule; slow work can leave little pause. If a run starts asynchronous work, wait for that work too before scheduling the next run when overlap would be a problem.

Timing has limits

A busy thread delays ready callbacks. Browsers also throttle timers in background tabs, often to about one check per second or less. When the timer nesting level is greater than five, the HTML timer rule raises delays below 4 ms to 4 ms. Very large delays also need care: the usual signed 32-bit limit is 2147483647 ms, about 24.8 days; values beyond that can overflow and fire much sooner.

Capture the right loop value

for (let i = 1; i <= 3; i++) {
  setTimeout(() => console.log(i), 100);
}

Each let iteration has its own binding, so the output is "1", "2", "3". With var, all callbacks share the same variable. After the loop it is 4, so each logs "4".

Wait for a quiet period

Debouncing cancels a pending timeout each time a new event arrives. A new timeout then schedules the action after the latest event. With a 300 ms delay, typing every 100 ms keeps postponing the action; it runs about 300 ms after typing stops. Store the handle outside the handler so the next call can cancel the previous timer.

Build a debounce handler

let pendingSave;
function scheduleSave(text) {
  clearTimeout(pendingSave);
  pendingSave = setTimeout(() => {
    console.log("Saved: " + text);
  }, 300);
}
scheduleSave("n");
scheduleSave("no");
scheduleSave("note");

These calls happen in the same script. Each clears the earlier handle before replacing it, so only "Saved: note" is logged, after about 300 ms. The final callback captures that call’s text parameter. The handle lives outside the function so every call can cancel the previously scheduled timeout.

If the handle were declared afresh inside each call, the next call would not retain the previous timer’s handle. If a handler scheduled without clearing, it would deliver all three messages. Debouncing needs both the shared handle and the cancellation before replacement.

A callback is a function you pass to another function to be called by that function. The callback’s code describes what should happen with a result. Whether it runs during the current call or later depends on the API that receives it.

A callback can run synchronously

const doubled = [2, 5].map(n => n * 2);
console.log(doubled);

map calls its callback for each element before returning the new array. The result is [4, 10]. The arrow function is a callback, but this code does not schedule future work. You can use doubled on the next line because the array is already complete.

Deliver a delayed result

function prepareLabel(name, callback) {
  setTimeout(() => {
    callback("Label: " + name);
  }, 200);
}
prepareLabel("Mira", label => {
  console.log(label);
});
console.log("Label requested");

prepareLabel starts a timer and returns. The script logs "Label requested". After about 200 ms, the timer callback constructs the label and calls the supplied callback, which logs "Label: Mira". The operation chooses when to call; the caller chooses what to do with the result.

Put dependent work where the result exists

let label;
prepareLabel("Mira", value => {
  label = value;
});
console.log(label);

This logs undefined: the assignment has not happened yet. Move console.log(value) into the callback. Adding a longer unrelated timeout before reading label would only guess when the result will be available; using the result callback ties the work to actual completion.

A return inside a delayed callback also cannot return the value from the outer function. The outer call is already over. In the example, return "Label: Mira" inside the timer callback would return to the timer machinery, leaving the caller of prepareLabel without the delayed label.

Pass the next action without calling it

A named callback works too:

function showLabel(label) {
  console.log(label);
}
prepareLabel("Mira", showLabel);

showLabel is the function value. showLabel() would call it immediately with no label and pass its return value instead. Use an arrow wrapper when the later action needs a particular argument or several statements.

For two dependent asynchronous steps, start the second inside the first step’s callback. For example, after receiving a user, pass that user to an operation that prepares their settings. Starting both outside their callbacks would not establish that dependency.

The receiving function controls how often it calls the callback. Some callbacks, such as event handlers, are deliberately called many times. A one-result operation should call its result callback once. A promise gives such an operation a result that can settle only once.

An asynchronous operation can fail as well as succeed. A callback API needs a clear way to report each outcome and a clear place for the caller to handle it.

Check the error first

The error-first convention uses callback(err, result). A successful call passes null for the error. A failed call passes an Error object and does not supply a usable result.

function readLabel(id, callback) {
  setTimeout(() => {
    if (id <= 0) {
      callback(new Error("Invalid label id"));
      return;
    }
    callback(null, { id: id, text: "Draft" });
  }, 200);
}
readLabel(4, (err, label) => {
  if (err) {
    console.log(err.message);
    return;
  }
  console.log(label.text);
});

The producer stops after reporting an invalid ID, so it cannot also report success. The consumer stops after seeing an error, so it cannot try to read label.text from an absent result. With ID 4, the output is "Draft". With ID 0, it is "Invalid label id".

Both returns matter. Without the consumer’s return, a second error about an undefined value could hide the useful original message. Without the producer’s return, one operation could call the callback twice. For a one-result API, report exactly one outcome.

A surrounding try has already finished

try {
  setTimeout(() => {
    throw new Error("Late failure");
  }, 0);
} catch (err) {
  console.log("Handled");
}

The try schedules the timer and finishes. The callback throws in a later task, when that try is no longer active, so "Handled" is not logged. Catch a possible throw inside the callback, or pass a failure through the API’s error parameter. A later promise wrapper must turn that callback error into a rejection explicitly.

Keep dependent steps readable

Callback code becomes hard to follow when each next step appears inside the previous step’s callback. Reading a profile, then its projects, then a project’s tasks creates several levels of nesting. Each operation also needs its own error check. This pattern is often called callback hell or the pyramid of doom.

Named functions can give those steps meaningful names and reduce the visual nesting. Keep error reporting consistent across them: a later step is just as capable of failing as the first one. Promises and async functions offer a flatter way to express the same sequence while keeping failure propagation connected.

Not all callback APIs use an error parameter. Some browser objects have separate success and failure events. For an image, set onload and onerror handlers before assigning src so both outcomes have a handler when loading starts. Read the API’s contract before assuming a parameter named err exists.

A promise represents an eventual outcome. A function can return it immediately, letting the caller connect work to a result that does not exist yet.

States and settlement

A promise is pending until it is fulfilled with a value or rejected with a reason. Fulfilled and rejected promises are settled; their outcome cannot change.

“Resolved” is more precise than an everyday synonym for “successful.” A promise resolved with another pending promise follows that promise’s eventual outcome, including rejection. It can therefore be resolved while still pending.

Create a promise around an operation

function wait(ms) {
  return new Promise(resolve => {
    setTimeout(resolve, ms);
  });
}
wait(200).then(() => console.log("Pause finished"));

new Promise calls its executor immediately. That executor registers a timer. When the timer calls resolve, the promise fulfills with undefined, and the registered then handler runs later as a microtask. This helper gives a reusable pause without blocking the thread.

An executor can receive both resolve and reject:

function reserve(quantity) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (quantity <= 8) resolve(8 - quantity);
      else reject(new Error("Not enough stock"));
    }, 200);
  });
}
reserve(3).then(left => console.log(left));
reserve(9).catch(err => console.log(err.message));

For these positive quantities, the first call fulfills with 5 and the second rejects with "Not enough stock". The promise lets the caller receive either outcome through the same returned object.

Creation starts the executor

console.log("before");
const result = new Promise(resolve => {
  console.log("creating");
  resolve(12);
});
console.log("after");
result.then(value => console.log(value));

The output is "before", "creating", "after", "12". Attaching then does not start this executor. The constructor already ran it; then registers code to consume its outcome.

Only the first call to resolve or reject decides the promise’s fate. Later calls cannot replace it. This also applies when the first resolution adopts another promise whose result is still pending. Calling resolve does not stop the executor’s ordinary code, so use return when a branch should end.

Make every path finish correctly

A synchronous throw in the executor rejects the promise automatically. A throw in a later timer callback is outside that call and is not converted into a rejection. Use reject(new Error("...")) there; otherwise the error can be uncaught while the promise remains pending.

A branch that calls neither function can leave the caller waiting forever. Use Error objects for rejection reasons so handlers can read a message and debugging tools can show useful error information.

Promise.resolve(value) creates a fulfilled promise for a plain value or adopts another promise’s outcome. Promise.reject(error) creates a rejected promise. Attach rejection handling when using the latter.

Follow an adopted outcome

const inner = new Promise(resolve => {
  setTimeout(() => resolve("packed"), 250);
});
const outer = new Promise((resolve, reject) => {
  resolve(inner);
  reject(new Error("Too late to replace it"));
});
outer.then(value => console.log(value));

The inner executor starts its timer during construction. The outer executor then resolves with inner, locking outer to inner’s eventual outcome. The later reject call cannot replace that decision. Outer remains pending until inner fulfills, and its handler logs "packed" after about 250 ms.

If inner rejected instead, outer would follow that rejection. The first call to resolve selected which outcome to follow; it did not guarantee success. This distinction matters when a wrapper passes through another promise instead of supplying a finished plain value.

Promise handlers connect code to success, failure, or either outcome. Each handler registration also returns a new promise, allowing the next piece of code to follow what that handler produces.

Use the handler that fits the outcome

p.then(onFulfilled) receives a fulfilled value. p.catch(onRejected) receives a rejection reason; it is shorthand for p.then(undefined, onRejected). Handlers are functions and run as microtasks, even if p has already settled.

Promise.resolve("draft")
  .then(text => console.log(text));
console.log("registered");

The script logs "registered" before the handler logs "draft". An immediately available value does not make the handler synchronous.

Passing a function is essential. then(console.log("draft")) logs "draft" during registration and passes undefined as the handler. Use then(() => console.log("draft")) when the message should be logged later. then(console.log) passes the logging function itself, so it receives the value.

Clean up after success or failure

finally is useful for hiding a loading indicator or enabling a button after an operation settles. Its callback receives no value or error argument.

Promise.resolve(4)
  .finally(() => console.log("Cleanup"))
  .then(value => console.log(value));

The output is "Cleanup", then "4". Returning an ordinary value from the cleanup callback does not replace 4. A returned promise can delay the next step until cleanup finishes. If cleanup throws or returns a rejected promise, that failure becomes the new chain outcome.

A typical page flow sets a loading state before starting, handles a result in then, reports a failure in catch, and resets the loading state in finally. Put the result-dependent work in then or catch, where the needed argument exists.

Separate subscriptions from a chain

const p = Promise.resolve(4);
p.then(value => value * 2);
p.then(value => console.log(value));

These are two separate subscriptions to p. Both receive 4. The multiplication belongs to the new promise returned by the first then; it does not alter p or feed the second subscription.

Connect them to pass the transformed value:

p.then(value => value * 2)
  .then(value => console.log(value));

Now the final handler receives 8. The difference is which promise each handler is attached to.

The returned object is still a promise

In const next = p.then(value => value * 2), next is a new promise, not the number 8. The handler may run after the surrounding script ends, and it may itself return delayed work. Use another handler or await to obtain the value. Treating next as a number immediately loses this timing information.

A promise chain makes the output of one handler the input of the next. Each link must return the value or promise that later links need.

Pass values through the chain

Promise.resolve(3)
  .then(count => count * 4)
  .then(total => total + 2)
  .then(total => console.log(total));

The first handler receives 3 and returns 12. The second receives 12 and returns 14. The final handler logs "14". An arrow expression returns automatically; a function body with braces needs an explicit return to send a value onward.

Return a promise for a dependent step

function wait(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}
function makeCode() {
  return wait(100).then(() => "P4");
}
function makeLabel(code) {
  return wait(200).then(() => "Parcel " + code);
}
makeCode()
  .then(code => makeLabel(code))
  .then(label => console.log(label));

makeCode supplies "P4" after about 100 ms. The next handler returns the promise from makeLabel. The chain follows it, waits about another 200 ms, and passes "Parcel P4" to the final handler. The caller receives a label, not a promise nested inside the value.

Find a broken link

Compare that middle handler with this one:

.then(code => {
  makeLabel(code);
})

It starts makeLabel but returns nothing. Its new promise fulfills with undefined without waiting for the label. The next handler therefore receives undefined after the code step, while label preparation continues separately. Errors from that separate work also stop flowing through this outer chain.

Repair it with return makeLabel(code); inside the braces, or remove the braces to return the expression. The same rule applies when a handler starts a pause: .then(() => wait(200)) waits; .then(() => { wait(200); }) does not.

Flatten nesting and keep needed values

Putting another then deep inside the first handler can recreate callback-style nesting. Return the inner promise and put the next handler at the outer level. This preserves one path for timing, values, and errors.

Each handler has its own local scope. If a later step needs both the code and the label, return an object holding them:

makeCode()
  .then(code => makeLabel(code).then(label => ({ code, label })))
  .then(pair => console.log(pair.code + ": " + pair.label));

This small inner handler builds the combined value and is returned, so it stays connected. An async function can also keep both results in ordinary local variables.

A rejection skips later fulfillment handlers until a rejection handler is reached. A final catch can handle failures from every connected step above it. Dependent work belongs in this sequence; independent work can start together with Promise.all.

An async function always returns a promise. Inside it, await pauses that function until a value is available, letting dependent steps read from top to bottom.

Return a value through a promise

async function getCount() {
  return 6;
}
getCount().then(count => console.log(count));

Calling getCount() gives a promise fulfilled with 6. The handler logs "6". If the function throws, its returned promise rejects. Returning another promise makes the async function follow that promise’s eventual outcome.

You can declare an async function with async function name(), an async arrow such as const name = async () => {}, or an async object method. The promise-returning behavior is the same.

Pause at await

function wait(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}
async function showSteps() {
  console.log("Step one");
  await wait(300);
  console.log("Step two");
}
showSteps();
console.log("Caller continues");

The output starts with "Step one", then "Caller continues". About 300 ms later, it logs "Step two". Calling the function runs its body synchronously up to the first await. The pause returns control to the caller. Once the promise fulfills, the rest of showSteps resumes through the microtask queue.

Await pauses its function, not the whole thread. Other ready tasks can run during the wait. A large synchronous calculation before or after the await can still block the thread while that calculation runs.

Read a value or receive an error

A fulfilled promise supplies its value: const count = await getCount(); sets count to 6. A rejected promise throws its reason at the await line. Surround the awaited operation with try and catch when this function should handle that failure.

await also accepts plain values. In const count = await 6;, the result is still 6, but the function’s continuation is deferred. It does not become synchronous just because no waiting operation was needed.

Check where await belongs

Use await inside the async function whose body contains it. It is also allowed at the top level of a JavaScript module. A normal function body cannot contain await; an outer async function does not make a nested normal callback async.

A caller still receives a promise. To use the final value, await it from another async function or attach then. For example, const total = getCount(); stores a promise; it does not store 6.

An event handler can itself be async. The handler can await a preparation step before updating a page. Give that action its own error handling because event dispatch does not wait for the handler’s returned promise. At the top of a program, a call such as showSteps().catch(console.error) gives an unanticipated failure a handler.

A promise chain can become an async function without changing its dependencies. Each result gets a local variable, and each awaited step begins only after the earlier result it needs is ready.

Replace handlers with awaited assignments

function wait(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}
function getUser(id) {
  return wait(100).then(() => ({ id, name: "Nia" }));
}
function getOrders(user) {
  return wait(200).then(() => [user.name + "-1", user.name + "-2"]);
}
async function showOrders(id) {
  const user = await getUser(id);
  const orders = await getOrders(user);
  console.log(user.name + ": " + orders.length + " orders");
}
showOrders(8).catch(console.error);

The first await supplies a user. Only then can getOrders(user) start. After about 300 ms in total, the function logs "Nia: 2 orders". Both user and orders are in scope for that final line. In a chain, each handler’s parameter would belong to a separate local scope.

The corresponding chain would return getOrders(user) from the first handler. Rewriting it with await makes that wait explicit while keeping the order intact. A final chain catch becomes a try/catch around the awaited steps; finally becomes a cleanup block.

Convert a callback API into a promise API

Adding async to a wrapper does not make a callback API’s delayed value become its return value. Connect the callback to promise settlement:

function readTag(id, callback) {
  setTimeout(() => {
    if (id <= 0) callback(new Error("Invalid tag"));
    else callback(null, "Tag " + id);
  }, 100);
}
function readTagAsync(id) {
  return new Promise((resolve, reject) => {
    readTag(id, (err, tag) => {
      if (err) {
        reject(err);
        return;
      }
      resolve(tag);
    });
  });
}

Inside an async function, const tag = await readTagAsync(8); gives "Tag 8". Calling it with 0 instead throws "Invalid tag" at the await. Success resolves the wrapper; failure rejects it. The adapter changes how the outcome is delivered, not what the underlying operation does.

This conversion is called promisifying. For ordinary one-result error-first APIs, Node.js also provides util.promisify, and many built-in modules already have promise-based variants such as fs/promises.

Keep one clear path

Timers become pauses through a promise-returning wait helper. An async loop can log a step, await the pause, and then begin the next iteration. With callbacks, the next step would have to be scheduled inside the previous callback.

Promises, chains, and async functions work together: an async function can await a chain, and a caller can attach then to an async function’s returned promise. Within a function, use the form that makes dependencies and error handling easy to follow. An extra Promise constructor is useful for adapting a callback, but existing promise-returning operations can be awaited directly.

Async code can look synchronous while still passing promises between functions. Many bugs come from reading the eventual value too early or assuming a helper waits for callbacks that it ignores.

Await the value before using it

async function getQuantity() {
  return 18;
}
async function total() {
  const quantity = await getQuantity();
  console.log(quantity * 3);
}
total().catch(console.error);

This logs "54". Without await, quantity would hold a promise. Multiplying that promise by 3 produces NaN, not a delayed calculation that automatically updates itself.

A condition has the same trap. An async check returning false still returns a promise object, and objects are truthy. Use if (await allowed()) inside an async function when the branch depends on the eventual boolean. Testing if (allowed()) tests the object itself.

forEach does not collect callback promises

function wait(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}
async function labelAll(ids) {
  ids.forEach(async id => {
    await wait(100);
    console.log("Label " + id);
  });
  console.log("Labels finished");
}
labelAll([4, 9]).catch(console.error);

"Labels finished" appears before the labels. forEach calls both callbacks, ignores their returned promises, and finishes its own synchronous iteration. Even await ids.forEach(...) would await undefined, not the callback work. A failure inside those ignored promises is also outside the promise returned by labelAll.

For ordered processing, write an ordinary loop:

for (const id of ids) {
  await labelOne(id);
}
console.log("Labels finished");

Here labelOne is a promise-returning operation. Each item starts after the previous one finishes. For independent items, use await Promise.all(ids.map(id => labelOne(id))); before the final log. map collects the returned promises, and Promise.all gives the caller one promise for their completion.

Separate independence from syntax

Awaiting each operation immediately makes their waits sequential. For independent waits of 1000, 2000, and 1500 ms, that takes about 4500 ms. Starting all three and combining them takes about 2000 ms. A step that needs an earlier result still has to wait for it.

Keep failures connected

A nested function needs its own async keyword to use await, but that keyword alone does not make its caller await the result. Check both ends: does the callback return a promise, and does the caller use it?

For work deliberately started without awaiting completion, attach a rejection handler such as backgroundTask().catch(console.error). Also check returns in async wrappers: async function prepare() { await wait(100); } fulfills with undefined. Waiting for a step and returning its result are separate decisions.

Return results from the repaired group

function wait(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}
async function prepareItem(id) {
  await wait(50);
  return "Item " + id;
}
async function prepareAll(ids) {
  return await Promise.all(ids.map(id => prepareItem(id)));
}
prepareAll([6, 2]).then(items => console.log(items.join(", ")));

Each map callback returns a promise, and map keeps those promises in an array. All waits for both and supplies ["Item 6", "Item 2"]. PrepareAll returns that array through its own promise, so the caller logs "Item 6, Item 2" after the group finishes.

Removing prepareAll’s return would still wait for the group, but the caller would receive undefined. Replacing map with forEach would lose the array of promises. Check collection, waiting, and returning separately when repairing a multi-item action.

A promise rejection follows the connected chain until a rejection handler deals with it. Understanding what that handler returns tells you whether the chain has recovered or is still failing.

Trace a rejection past success handlers

Promise.resolve(8)
  .then(value => {
    throw new Error("Count rejected");
  })
  .then(value => console.log("Unused: " + value))
  .catch(err => {
    console.log(err.message);
    return 2;
  })
  .then(value => console.log("Using " + value));

The throw rejects the new promise returned by the first then. The next fulfillment handler is skipped, so "Unused" is never logged. The catch logs "Count rejected" and returns 2. That return fulfills the next link, so the last handler logs "Using 2".

An explicitly rejected promise and a throw inside a handler enter the same rejection path. This is why one final catch can handle failures from several earlier connected steps.

Choose recovery or propagation

A rejection handler that returns a value recovers with that value. Returning nothing also recovers, but with undefined. Logging a failure is therefore not the same as keeping the chain rejected:

Promise.reject(new Error("Label missing"))
  .catch(err => console.log(err.message))
  .then(value => console.log(value));

The final handler receives undefined. If later code requires a real label, that silent recovery is probably wrong. Return a usable fallback, or throw the error again.

function reportAndRethrow(err) {
  console.error(err);
  throw err;
}

Using this function in catch logs the error and leaves the next promise rejected with the same reason. A caller further down the chain can decide what to do.

Put the handler after the work it protects

A catch handles failures above it. If it recovers, later steps run normally, and their new failures need a later handler. A handler in the middle cannot catch errors that have not happened yet.

There is also an important difference between .then(success, failure) and .then(success).catch(failure). The two handlers in one then respond to the outcome of the incoming promise. Its failure handler does not catch an error thrown by its own success handler. That error belongs to the new promise the call returns, so a downstream catch is needed.

Preserve useful errors

Reject with Error objects so handlers can read err.message and err.name. Throwing or rejecting a string is allowed, but code expecting an Error’s fields will not receive them. Keep the original error when propagating a failure unless added context helps the caller understand which operation failed.

try, catch, and finally let an async function handle failures at the point where it awaits them. Use this structure to keep result handling, recovery, and cleanup together.

An error transfers control

An Error object describes a failure. new Error("Label missing") has the message "Label missing" and the name "Error"; debugging tools can also show its stack. Built-in failures have types such as TypeError.

throw stops normal execution at that point and transfers control to the nearest applicable catch. Code after the handling can still run when the function catches its own error. Throw Error objects so later handlers receive useful fields.

Await inside the protected block

async function run() {
  console.log("Working");
  try {
    await Promise.reject(new Error("Device busy"));
    console.log("Complete");
  } catch (err) {
    console.log("Failed: " + err.message);
  } finally {
    console.log("Controls enabled");
  }
}
run().catch(console.error);

The rejected promise throws at the await line. The rest of try is skipped. The output is "Working", "Failed: Device busy", then "Controls enabled". A successful operation would reach "Complete" and still run the same cleanup.

Use finally for a spinner, button state, or other resource that must be reset after either outcome. It runs even when try or catch has a return statement. Keep cleanup from throwing unless that new failure is deliberately meant to replace the earlier outcome. A return in finally can override an earlier return or throw, so avoid using it for ordinary cleanup.

Returning a promise is different from awaiting it here

async function readSetting() {
  try {
    return await Promise.reject(new Error("Missing setting"));
  } catch {
    return "light";
  }
}
readSetting().then(value => console.log(value));

This logs "light". The function waits inside try, so rejection reaches the local catch. Removing await returns the rejected promise immediately; the function adopts its rejection, but the local catch does not handle that later outcome. A caller would need to catch it.

Give each failure an appropriate boundary

One try can cover a group of awaits when the whole action should stop if any step fails. Give an optional step a smaller boundary when it can recover independently. For example, const settings = await loadSettings().catch(() => ({ theme: "light" })); uses a default object and continues.

A variable declared inside try is block-scoped. If code after the block needs it, declare let result; before try, or finish the result-dependent work inside try. Do not move a value outside its scope merely to keep a final log in a preferred position.

When the current function cannot recover, allow rejection to reach the caller. Catching it only to hide it prevents that caller from making a useful decision.

An action needs an error boundary: a place that receives its final failure and chooses a response. Without that boundary, a promise can reject while nobody is handling its outcome.

Handle the final path

An unhandled rejection is a rejection that still lacks a handler when the host checks. Handling can use catch, the rejection argument of then, or try/catch around await. A browser reports the problem and can fire unhandledrejection. Node.js stops by default for unhandled rejections under its normal policy, so leaving one loose can end a program.

An action such as main() or an async click handler should handle its final promise. Lower-level functions can pass failures upward, but the path must end somewhere that decides what to do. A global rejection listener can help log missed failures; it cannot choose the best recovery for each action.

An empty catch swallows the failure. Log technical details with console.error(err) and show a clear message if the user’s action failed. A message such as "The label could not be saved. Try again in a moment." gives the user an action without exposing a stack trace.

Add context without losing the cause

async function prepareLabel() {
  try {
    return await Promise.reject(new Error("Device offline"));
  } catch (err) {
    throw new Error("Could not prepare label", { cause: err });
  }
}
prepareLabel().catch(err => {
  console.log(err.message);
  console.log(err.cause.message);
});

This logs "Could not prepare label" and "Device offline". The outer message identifies the failed action. The cause property preserves the lower-level error for diagnosis. The Error cause option is part of ECMAScript 2022.

Retry a fresh operation, with a limit

function wait(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}
async function withRetry(task, attempts) {
  for (let attempt = 1; attempt <= attempts; attempt++) {
    try {
      return await task();
    } catch (err) {
      if (attempt === attempts) throw err;
      await wait(200);
    }
  }
}

Call this with a function that starts a new attempt and a positive whole-number limit. If task fails twice and succeeds on its third call, a limit of four stops on the third call and returns its value. If all four attempts fail, the fourth error is rethrown. The delay occurs only between attempts.

return await keeps a rejection inside this try, where catch can retry it. Passing one already rejected promise instead of a task function would not restart the work.

Retry when a failure can be temporary. Use a fallback when the feature can work with default data. Stop and inform the user when the action cannot succeed. If a lower-level function cannot make that choice, preserve the error and let the caller decide.

Independent asynchronous operations can wait at the same time. The choice to start them together comes from their data needs, not from adding the word async.

Start independent operations before waiting for all

function wait(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}
function makePart(name, ms) {
  return wait(ms).then(() => name);
}
async function assemble() {
  const parts = await Promise.all([
    makePart("cover", 1000),
    makePart("pages", 2000),
    makePart("label", 1500)
  ]);
  console.log(parts.join(", "));
}
assemble().catch(console.error);

The three calls start before Promise.all waits. About 2000 ms later, the array contains ["cover", "pages", "label"]. Waiting for each call before starting the next would take about 4500 ms instead. Timer delays are approximate, so real elapsed times can be longer.

Here parallel means overlapping waits. The promise handlers still run one at a time on the main thread. Calling three heavy synchronous functions inside the array would run those calculations one after another; Promise.all would not move them to separate threads.

Results keep their input positions

The label finishes before the pages, but remains third in the array. Promise.all keeps input order, not completion order. Destructuring can name those positions:

const [cover, pages] = await Promise.all([
  makePart("cover", 1000),
  makePart("pages", 2000)
]);

Use that code inside an async function. For a collection, ids.map(id => loadItem(id)) starts one promise-returning operation per ID and gives Promise.all the promise array. Do not await each item inside a loop if all are independent and should overlap.

Failure ends the combined wait

Promise.all rejects as soon as an input rejects. If one part fails after about 300 ms, a catch can receive that reason then; it need not wait for the longest successful part.

The other operations keep running. Their side effects can still happen, but the combined promise will not later fulfill with their values. This fail-fast rule is useful when the next step requires every result.

Respect dependencies and attach handlers promptly

If one operation needs a user produced by another, obtain the user first. The later calls can be combined only if they are independent of one another once that user exists.

Starting two promises and awaiting them separately does overlap their waits, but the second can reject before the code reaches its await. If it still has no handler when the host checks, an unhandled rejection can be reported. Combining the promises promptly with Promise.all attaches handling to both inputs and gives the caller one failure path.

Plain values are allowed among the inputs and keep their positions. Promise.all([]) is already fulfilled with an empty array. A handler attached to it still runs asynchronously.

The right promise combinator depends on what counts as a useful result. Decide whether you need all successes, all outcomes, the first settlement, or the first success.

Keep partial results with allSettled

Promise.allSettled waits for every input and returns outcome records in input order. A success becomes { status: "fulfilled", value }; a failure becomes { status: "rejected", reason }. A rejected input does not reject the combined promise.

Promise.allSettled([
  Promise.resolve("Map ready"),
  Promise.reject(new Error("Chart unavailable"))
]).then(results => {
  for (const result of results) {
    if (result.status === "fulfilled") console.log(result.value);
    else console.log(result.reason.message);
  }
});

This logs "Map ready" and "Chart unavailable". It suits independent panels where one working panel remains useful even if another fails. Read value only on a fulfilled record and reason on a rejected record.

Let the first settlement decide with race

Promise.race follows the first input that settles, whether it fulfills or rejects. A failure after 100 ms beats a success after 200 ms. This is useful for a time limit:

function wait(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}
function timeout(ms) {
  return new Promise((_, reject) => {
    setTimeout(() => reject(new Error("Time limit reached")), ms);
  });
}
Promise.race([
  wait(600).then(() => "Prepared"),
  timeout(250)
]).then(console.log).catch(err => console.log(err.message));

The timeout rejects first, so the output is "Time limit reached". The 600 ms operation keeps running. A race settles the caller’s combined promise; it does not cancel its losing operations.

Wait for the first success with any

Promise.any ignores failed inputs while a success is still possible. If one operation fails after 100 ms and another fulfills after 200 ms, it gives the latter value. A faster rejection does not win.

If every input rejects, any rejects with an AggregateError. Its errors array keeps the rejection reasons in input order. This allows a caller to inspect why each attempt failed, even when their failures arrived in a different order.

Compare the decision rules

• all: every value is required; reject on the first rejection.
• allSettled: every outcome is required; wait for all records.
• race: first settlement decides, including failure.
• any: first fulfillment decides; reject only if all reject.

With no inputs, all and allSettled fulfill with []. any rejects with AggregateError because no success is possible. race stays pending because nothing can settle it.

All four are supported in current browsers and Node.js. all and race entered ECMAScript in 2015, allSettled in 2020, and any in 2021.

Compare one pair of outcomes

Suppose both operations start now: the first input fails after about 100 ms, while the second fulfills with "usable" after about 300 ms. Applying each combinator to that same pair gives different results:

• All rejects near 100 ms with the first input’s error, because every input must succeed.
• AllSettled fulfills near 300 ms with a rejected record followed by a fulfilled record, preserving input positions.
• Race rejects near 100 ms because that is the first settlement.
• Any fulfills near 300 ms with "usable" because the earlier failure cannot supply a success.

All and race happen to reject together in this case, but they use different rules. If the fast first input succeeded and the second input failed later, race would keep its early success while all would reject on the later failure. Choose from the required outcome, not from the timing of one example.