Async & fetch.
Talk to servers. Render real data.

// What would happen if fetch were synchronous:
console.log("Start");
const data = fetch("/api/users"); // this would freeze the page for 500ms
console.log("End"); // only runs after the fetch finishes

// What actually happens with async:
console.log("Start"); // 1 — runs immediately
fetch("/api/users").then(data => {
    console.log("Got data"); // 3 — runs after response arrives
});
console.log("End"); // 2 — runs immediately, doesn't wait

// Output order:
// Start
// End
// Got data

// The fetch didn't block. Code kept running.
// When the response arrived, the .then callback fired.

// Same pattern with async/await:
async function loadUsers() {
    console.log("Start");
    const response = await fetch("/api/users"); // pauses THIS function only
    console.log("Got data");
    return response;
}
console.log("Start");
loadUsers(); // starts the async function
console.log("End"); // runs before the await resolves

// Output:
// Start
// End
// Got data

// A Promise is a placeholder for a value that arrives later
const promise = fetch("/api/users");
// promise is pending, then fulfilled or rejected

// .then() — attach a callback for success
promise.then(response => {
    console.log("Success:", response);
});

// .catch() — attach a callback for failure
promise.catch(error => {
    console.error("Failed:", error);
});

// .finally() — runs regardless of success or failure
promise.finally(() => {
    console.log("Done, either way");
});

// Chaining — .then() returns a new Promise
fetch("/api/users")
    .then(response => response.json()) // returns a Promise
    .then(data => console.log(data)) // receives the parsed data
    .catch(err => console.error(err));

// Promise.all() — run multiple in parallel, wait for all
const [users, posts, comments] = await Promise.all([
    fetch("/api/users").then(r => r.json()),
    fetch("/api/posts").then(r => r.json()),
    fetch("/api/comments").then(r => r.json()),
]);
// All three requests fire in parallel. Waits for the slowest one.

// Promise.race() — first one to finish wins
const fastest = await Promise.race([
    fetch("/api/primary"),
    fetch("/api/fallback"),
]);
// Whichever responds first is used. The other is ignored.

// Creating a Promise manually
function wait(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
}
await wait(1000); // waits 1 second
console.log("1 second later");

// Promise chain — works, but verbose
function loadUser() {
    return fetch("/api/user")
        .then(response => response.json())
        .then(data => {
            console.log(data);
            return data;
        })
        .catch(err => console.error(err));
}

// async/await — same thing, easier to read
async function loadUser() {
    try {
        const response = await fetch("/api/user");
        const data = await response.json();
        console.log(data);
        return data;
    } catch (err) {
        console.error(err);
    }
}

// The async keyword does two things:
// 1. Allows you to use await inside the function
// 2. Makes the function always return a Promise

// await pauses the function, not the program
async function example() {
    console.log("1");
    await wait(1000);
    console.log("2"); // runs after 1 second
}

// Sequential vs parallel — the performance difference
// SLOW — 3 seconds total, each await pauses
async function sequential() {
    const a = await fetch("/api/a"); // 1s
    const b = await fetch("/api/b"); // 1s
    const c = await fetch("/api/c"); // 1s
    return [a, b, c];
}

// FAST — 1 second total, all requests in flight
async function parallel() {
    const [a, b, c] = await Promise.all([
        fetch("/api/a"),
        fetch("/api/b"),
        fetch("/api/c"),
    ]);
    return [a, b, c];
}

// Await only works inside async functions
// function broken() { await fetch("/api"); } // SyntaxError
// Use an async wrapper, or top-level await in ES modules:
// const data = await fetch("/api"); // valid in a .mjs file

// Basic GET request — TWO awaits
async function getUsers() {
    const response = await fetch("/api/users"); // 1st await
    const data = await response.json(); // 2nd await
    console.log(data);
}

// POST request — send data to the server
async function createUser(user) {
    const response = await fetch("/api/users", {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
        },
        body: JSON.stringify(user),
    });
    const data = await response.json();
    return data;
}

// PUT/PATCH — update
await fetch("/api/users/1", {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ name: "New Name" }),
});

// DELETE
await fetch("/api/users/1", { method: "DELETE" });

// Custom headers (auth, API keys)
await fetch("/api/data", {
    headers: {
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
    },
});

// Query parameters — build URLs safely
const url = new URL("/api/search");
url.searchParams.set("q", "javascript");
url.searchParams.set("page", "1");
const response = await fetch(url);

// Response formats
const json = await response.json(); // parses JSON
const text = await response.text(); // raw string
const blob = await response.blob(); // for images, files
const buffer = await response.arrayBuffer(); // binary

// The pattern — try/catch around async operations
async function loadUser(id) {
    try {
        const response = await fetch("/api/users/" + id);

        // fetch does NOT throw on 404/500 — must check manually
        if (!response.ok) {
            throw new Error("HTTP " + response.status);
        }

        const data = await response.json();
        return data;
    } catch (err) {
        console.error("Failed to load user:", err.message);
        return null; // or re-throw, or return a default
    } finally {
        console.log("Done loading user");
    }
}

// Caller handles the result
const user = await loadUser(1);
if (user) {
    renderUser(user);
} else {
    showError("Could not load user");
}

// Promise chains — .catch() for the same purpose
fetch("/api/users/1")
    .then(r => {
        if (!r.ok) throw new Error("HTTP " + r.status);
        return r.json();
    })
    .then(data => console.log(data))
    .catch(err => console.error(err))
    .finally(() => console.log("Done"));

// Common error patterns
// 1. Network failure — no internet, DNS error
// fetch() rejects → caught by try/catch
// 2. HTTP error — 404, 500
// fetch() resolves, response.ok is false → you throw
// 3. JSON parse error — malformed JSON
// response.json() rejects → caught by try/catch
// 4. Timeout — response never arrives
// Use AbortController (see below)

// Timeout with AbortController
async function fetchWithTimeout(url, ms = 5000) {
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), ms);
    try {
        const response = await fetch(url, { signal: controller.signal });
        return await response.json();
    } finally {
        clearTimeout(timeout);
    }
}