Asynchronous JavaScript and APIs

🎯Learning Objectives

Level 17 handled a local form synchronously. A real page may need to wait for a response while the learner keeps using it. This lesson introduces promises, async/await, HTTP responses, JSON parsing, cancellation and result ownership.

Our task is a workshop-catalog loader with clear idle, loading, success, empty, error and canceled outcomes. You will distinguish a network failure from an HTTP error, validate parsed data before rendering and prevent an older response from replacing a newer request’s result.

⏱️Asynchronous Work and the Event Loop

JavaScript code in a browser context generally runs each job to completion before another job runs on that same thread. Browser facilities can handle waiting work such as timers and network operations, then arrange for callbacks or promise reactions to run later.

Asynchronous does not mean every line runs simultaneously or that heavy JavaScript computation automatically moves to another thread. A long synchronous loop can still block interaction and rendering. Awaiting a promise yields control from the async function while it is suspended; it does not freeze the whole browser.

Promise reactions run as microtasks. A zero-delay timer queues later work; it does not guarantee that its callback runs immediately or at an exact wall-clock time.

console.log("A");
setTimeout(() => console.log("B"), 0);
Promise.resolve().then(() => console.log("C"));
console.log("D");
// In this simple example: A, D, C, B

The ordinary logs run first. The promise reaction is processed before the later timer task in this example. Do not generalize this small trace into a promise about the timing of every network response.

🔔Callbacks — A Starting Point

A callback is a function supplied to another operation. Event listeners from the previous lesson are callbacks. A timer callback receives control after the timer becomes eligible and the event loop can run it.

Not every callback is asynchronous: Array.map calls its callback synchronously. Judge the operation’s contract rather than assuming that passing a function always schedules it for later.

Several nested dependent callbacks can make success and failure paths difficult to follow. Promises provide a composable representation of an eventual outcome.

setTimeout(() => {
  console.log("Timer callback ran");
}, 500);

const doubled = [1, 2].map(value => value * 2);
// map finishes synchronously here: [2, 4]

The 500ms value is a scheduling delay, not an exact observed duration. A busy page or background-tab policy can delay when the callback actually runs.

📦Promises — Pending, Fulfilled or Rejected

A promise represents an eventual result. It begins pending and can settle as fulfilled with a value or rejected with a reason. Once settled, its outcome does not switch from fulfillment to rejection or vice versa.

Calling resolve can adopt another promise’s outcome; resolution and immediate fulfillment are therefore not always the same moment. For beginner examples, focus on the observable eventual fulfillment or rejection.

The Promise constructor’s executor runs synchronously. Use the constructor when adapting a callback operation, rather than wrapping an already promise-based fetch call in an unnecessary new Promise.

function wait(milliseconds) {
  return new Promise(resolve => {
    setTimeout(resolve, milliseconds);
  });
}
wait(500).then(() => console.log("Wait completed"));

The executor schedules a timer immediately; the returned promise remains pending until that timer callback resolves it. The local lab adapts timers into a cancelable simulated response.

🔗then, catch and Returning the Next Step

Then returns a new promise. Its callback can return an ordinary value, return another promise, or throw an error. Returning the next asynchronous step makes the chain wait for it and carries failures along the chain.

Catch handles a rejection from the chain before it. Returning a fallback value from catch can turn the later chain into a fulfilled result. Throwing again preserves a failure path for later handling.

A missing return can let a chain proceed before an inner operation finishes. Keep the relationship between stages explicit rather than nesting an unreturned promise and expecting the outer chain to wait.

fetch("/api/workshops")
  .then(response => {
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return response.json();
  })
  .then(data => console.log(data))
  .catch(error => console.error(error.message));

The /api/workshops path is a hypothetical endpoint used in teaching examples; a project must provide that endpoint before using this code. The lab uses local predefined responses for predictable practice.

🧵async and await — Read the Sequence Clearly

An async function returns a promise. Returning a normal value fulfills its returned promise with that value; an uncaught error rejects it. Await suspends the function until the awaited value’s promise behavior settles and then supplies the fulfilled value or throws the rejection reason.

Await makes dependent steps readable without making them synchronous browser operations. Code outside the suspended function can continue to run. An async function can still execute substantial synchronous work before or between awaits.

A try/catch around an awaited operation can handle its rejection. Calling a promise-returning operation without awaiting or returning it can leave a failure outside that intended path.

async function loadCatalog() {
  const response = await fetch("/api/workshops");
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const data = await response.json();
  return data;
}

Fetch supplies a response object and json supplies parsed body data in two asynchronous stages. A response variable is not already the catalog array.

🛠️try, catch and finally — Outcome and Cleanup

Use try for the intended operation, catch for the failure path and finally for cleanup that should run after either outcome. Finally is suitable for clearing a timer or releasing a request’s resources.

A finally block can still alter control flow if it returns or throws, potentially overriding an earlier result. Keep cleanup free of an unnecessary returned value or new error.

Cleanup must also respect result ownership. An older request’s finally block should not turn off the newer request’s loading state merely because the older operation has ended.

setLoading(true);
try {
  const data = await loadCatalog();
  showCatalog(data);
} catch (error) {
  showError(error.message);
} finally {
  setLoading(false);
}

This simple example assumes one active request. The later ownership example adds an ID guard before changing the UI in finally. Handle expected cancellation separately from a request error that the learner should retry.

🌐HTTP and an API Response Contract

An API exposes an agreed interaction: endpoint, method, headers, request data and response format. A client should know which fields and types the response is expected to contain. HTTP status and JSON structure answer different questions.

A 200-range status commonly represents HTTP success. A 404 response means the requested resource was not found; a 500 response indicates a server-side error class. The appropriate interface response depends on the API’s documented contract.

An empty JSON array can be a successful result with no workshops. A malformed body or unacceptable record shape is a different outcome. A 204 response has no content, so do not blindly demand a JSON body for every successful status.

📨Fetch — Check the Response Before Parsing

Fetch returns a promise for a Response. HTTP error statuses such as 404 do not normally reject that promise by themselves. Check response.ok or the expected status, then choose how to handle the response.

A network or browser access failure can reject fetch without a usable response. An application can also fail later during body reading, parsing or validation. Keep these stages distinct while debugging.

Response.ok is true for statuses 200 through 299. A body-reading method such as json is asynchronous and normally consumes the body stream. Do not assume you can read the same body repeatedly without cloning or another deliberate strategy.

const response = await fetch("/api/workshops", {
  headers: { Accept: "application/json" }
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}
const data = await response.json();

This request header communicates a preferred response representation; it does not force the server to return valid JSON or the expected fields. The next step still needs validation.

✅JSON Parsing Is Not Schema Validation

Json parses a response body into a JavaScript value. Valid JSON can represent a string, number, null, object or array. Parsing successfully does not prove that a value is the catalog you expected.

Our catalog contract is a dense array with at most 20 records. Each record has a unique non-empty string ID of at most 40 characters, a non-empty title of at most 80 characters, and integer capacity/reserved values from 0–1000 with reserved not exceeding capacity.

IDs and titles are trimmed before uniqueness and rendering checks. Reject the whole payload if the contract fails. Avoid displaying an invalid availability count or silently turning an absent capacity into zero. Derive remaining only from accepted numeric fields.

if (!Array.isArray(data)) {
  throw new Error("Expected a workshop array");
}
for (const workshop of data) {
  if (!Number.isInteger(workshop.capacity) ||
      !Number.isInteger(workshop.reserved) ||
      workshop.reserved > workshop.capacity) {
    throw new Error("Invalid workshop record");
  }
}

This abbreviated snippet illustrates the idea. The lab’s validator also checks lengths, lower/upper bounds, uniqueness and sparse slots before rendering its predefined payload.

💬UI States — Loading Is Part of the Task

A useful loader begins idle, shows loading while work is pending, and ends with success, empty, error or canceled. Clear stale results when starting a new request, or deliberately label them as old if the product chooses to retain them.

Use a concise status and an appropriate busy state for the result region. An empty result should explain that no workshops were returned; it should not look like an unfinished loading screen. Keep a retry action available after a recoverable failure.

The lab keeps Load enabled so you can start overlapping requests deliberately. Cancel applies to the newest pending request. Its request log explains earlier completions that were ignored.

✋AbortController and Timeouts

AbortController provides a signal that compatible operations can observe. Pass its signal to fetch, then call abort when the result is no longer needed. The operation can reject with an AbortError; cancellation is different from reporting a server failure.

Aborting does not guarantee that a server never received or processed a request. For a real write operation, retry and cancellation policies need the server’s documented behavior. A read-only catalog has different consequences from creating a payment or reservation.

A timeout can be implemented by aborting after a chosen deadline and clearing the timer in finally. Record whether the deadline or the learner initiated cancellation if those outcomes need different messages.

const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 5000);
try {
  const response = await fetch("/api/workshops", {
    signal: controller.signal
  });
  // Check status, parse and validate here.
} finally {
  clearTimeout(timer);
}

The lab uses an AbortController with a local timer-backed response. Its Cancel control demonstrates signal-based rejection without making a network request.

🧭Overlapping Requests — Newest Result Owns the UI

A slow request can finish after a later, faster request. Without an ownership rule, the older result can overwrite the learner’s more recent choice. Speed alone is not a reliable ordering policy.

Give each request an increasing ID. Before writing success, empty, error or cleanup state, verify that it still owns the current UI. Canceling old work can save resources, but ownership checks remain valuable when an operation cannot be canceled or is already completing.

The lab intentionally allows older requests to continue when a new one starts. Their completions are logged as ignored, while only the newest request can change the current result. Reset and page exit abort pending work and invalidate its ownership.

const requestId = ++latestRequestId;
try {
  const data = await loadCatalog();
  if (requestId !== latestRequestId) return;
  showCatalog(data);
} finally {
  if (requestId === latestRequestId) setLoading(false);
}

Guard failures and finally as well as success. An obsolete request should not replace a newer error message or turn off its busy state.

🤝Sequential Work, Promise.all and allSettled

Await dependent steps in sequence when the second needs the first’s result. Start independent operations before awaiting the group if they can run concurrently. Promise.all accepts an iterable of values/promises and fulfills with results in input order, not completion order.

Promise.all rejects when an input rejects; that does not automatically cancel other already-started operations. Promise.allSettled waits for every input to settle and reports each outcome. Choose the behavior that fits the task.

Avoid a forEach(async ...) loop when the caller expects a completed batch before continuing. Use a suitable for...of loop for sequential work or map to create promises followed by an explicit group await.

const catalogPromise = loadCatalog();
const noticePromise = loadNotices();
const [catalog, notices] = await Promise.all([
  catalogPromise, noticePromise
]);

These helper names illustrate two independent API tasks. Their endpoints and failure policies must be implemented by the application. A group await changes coordination, not the server’s capacity or authorization rules.

🔐CORS, Credentials and Safe Rendering

Cross-origin browser requests are governed by access rules such as CORS. The server supplies the appropriate response headers; client JavaScript cannot simply grant itself permission. A no-cors request can yield an opaque response that the script cannot read as ordinary JSON, so it is not a repair for an API that needs readable data.

Credentials handling depends on the request options, origins and server policy. Keep private API keys and server secrets out of downloadable frontend files. A browser-visible key is not made private by placing it in an external JavaScript file.

Treat response text as data when rendering labels. Create elements and use textContent rather than inserting server-provided strings as raw HTML. Keep failures understandable without exposing internal server traces to a learner.

const title = document.createElement("h4");
title.textContent = acceptedWorkshop.title;
card.append(title);

The local lab renders only accepted records with textContent and uses predefined response scenarios. It does not contact external endpoints or store catalog data between visits.

🧪Premium Interactive — Async Catalog Loader

This is a local response simulation. It uses real promises, timers, AbortController and Response.json with predefined bodies; it does not call a live API. Choose a scenario and delay, then Load. Inspect the state, accepted cards, payload and request log.

Try success, an empty catalog, HTTP 404, network failure, malformed JSON and invalid record shape. Cancel while the newest request is loading. Reset cancels pending work and returns to idle. The timer delay is a teaching setting, not an exact timing guarantee.

For a race, start slow success at 1500ms, then switch to fast empty at 500ms and Load again. The newest empty result should remain after the earlier success completes. The log identifies the obsolete result as ignored. You can also start a fast earlier request and a slow newer one to check that old cleanup does not clear the newer loading state.

No accepted payload yet.

[]

🛠️Debugging — Locate the Failed Stage

If a 404 still reaches a success callback, inspect response.ok rather than assuming fetch rejects every unsuccessful HTTP status. If JSON parsing fails, inspect the body and representation; the server may have returned an HTML error page. If an older result replaces a newer query, check its request ID before rendering.

If loading disappears while the latest request is pending, inspect an older finally block. If cancellation leaves an unhandled rejection, make sure the canceled operation still has a rejection handler. If a CORS failure appears, inspect the server’s access policy rather than attempting to read an opaque no-cors response.

Use the deterministic lab cases to isolate one stage. A malformed body should fail parsing; an over-reserved record should fail validation. Neither should leave accepted cards visible under the new error state.

💬Interview Questions — Flip to Explain

❓MCQ Practice — Predict the Async Outcome

💻Extra Practice — Reproduce Specific Async Outcomes

📌Quick Revision

📖Glossary — Flip to Learn

🏆Final Challenge — A Loader with Owned Outcomes

Write an asynchronous catalog loader around an implemented endpoint or the lesson’s local response adapter. Show idle/loading/success/empty/error/canceled clearly. Check the HTTP contract, await body parsing and validate accepted records before rendering them as text.

Use an AbortController for compatible cancellation and increasing request IDs to protect every UI write. Keep older completion and cleanup from replacing the newest result. Reset or page cleanup should cancel pending work and invalidate it without leaving an unhandled rejection.

Test all six response scenarios, cancellation, reset while pending and both request-order races. Record which stage fails and whether the newest busy state remains correct. Use a timer-controlled test for logic, then inspect real browser timing, controls and accessibility feedback.

Success criterion: explain the promise path, distinguish transport/HTTP/parse/schema outcomes and demonstrate stable result ownership. Level 19 will introduce browser storage and other web APIs.