Fetch API

const res = await fetch("https://api.example.com/users/1");
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const user: unknown = await res.json();

const res = await fetch("/api/report");
const backup = res.clone();
try {
  const data: unknown = await res.json();
} catch {
  throw new Error(`Not JSON: ${await backup.text()}`);
}

const res = await fetch("/api/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Ada", role: "admin" }),
});

declare const file: File;
 
const form = new FormData();
form.append("title", "Q3 report");
form.append("file", file, "report.pdf");
await fetch("/api/upload", { method: "POST", body: form });

const params = new URLSearchParams({
  q: "fetch",
  page: "2",
});
 
// as a form body
await fetch("/login", { method: "POST", body: params });
 
// as a query string: URL handles the encoding
const url = new URL("/search", "https://example.com");
url.searchParams.set("q", "a&b c");
await fetch(url); // .../search?q=a%26b+c

declare const file: File;
 
await fetch(`/api/files/${encodeURIComponent(file.name)}`, {
  method: "PUT",
  body: file, // Content-Type from file.type
});

const enc = new TextEncoder();
const body = new ReadableStream<Uint8Array>({
  start(controller) {
    controller.enqueue(enc.encode("line 1\n"));
    controller.enqueue(enc.encode("line 2\n"));
    controller.close();
  },
});
 
// lib.dom's RequestInit doesn't declare duplex yet
const init: RequestInit & { duplex: "half" } = {
  method: "POST",
  body,
  duplex: "half",
};
await fetch("/api/ingest", init);

declare const token: string;
 
const h = new Headers({
  "Content-Type": "application/json",
});
h.append("Accept", "application/json");
h.set("Authorization", `Bearer ${token}`);
 
h.get("content-type");           // "application/json"
h.has("ACCEPT");                  // true: case-insensitive
for (const [name, value] of h) {}
// names come out lower-cased

export class HttpError extends Error {
  override name = "HttpError";
  readonly status: number;
  readonly body: string;
 
  constructor(res: Response, body: string) {
    super(`HTTP ${res.status} ${res.statusText} ${res.url}`);
    this.status = res.status;
    this.body = body;
  }
}
 
export async function ensureOk(res: Response) {
  if (!res.ok) throw new HttpError(res, await res.text());
  return res;
}

declare const url: string;
 
try {
  const res = await fetch(url, {
    signal: AbortSignal.timeout(5_000),
  });
  await ensureOk(res);
} catch (err) {
  if (!(err instanceof Error)) throw err;
  if (err.name === "TimeoutError") {
    // took longer than 5 s
  } else if (err.name === "AbortError") {
    // canceled by the user or by code
  } else if (err instanceof TypeError) {
    // network failure
  } else throw err;
}

function withTimeout(ms: number, signal?: AbortSignal) {
  const timeout = AbortSignal.timeout(ms);
  return signal
    ? AbortSignal.any([signal, timeout])
    : timeout;
}
 
const controller = new AbortController();
const res = await fetch("/api/search?q=ts", {
  signal: withTimeout(8_000, controller.signal),
});
controller.abort(); // e.g. on unmount or a newer keystroke

import { z } from "zod";
 
const User = z.object({
  id: z.number().int(),
  name: z.string(),
  email: z.email(),
  createdAt: z.iso.datetime().transform((s) => new Date(s)),
});
type User = z.output<typeof User>; // createdAt: Date

import { z } from "zod";
 
export async function fetchJson<S extends z.ZodType>(
  input: string | URL,
  schema: S,
  init?: RequestInit,
): Promise<z.output<S>> {
  const res = await fetch(input, init);
  if (!res.ok) {
    throw new HttpError(res, await res.text());
  }
  return schema.parse(await res.json());
}
 
const users = await fetchJson("/api/users", z.array(User));
//    ^? { id: number; name: string; ... }[]

const res = await fetch("/logs/today.txt");
if (!res.body) throw new Error("No body");
 
const reader = res.body
  .pipeThrough(new TextDecoderStream())
  .getReader();
for (;;) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(value); // a string chunk, not a line
}

async function download(
  url: string,
  onProgress: (fraction: number) => void,
): Promise<Blob> {
  const res = await fetch(url);
  if (!res.ok || !res.body) {
    throw new Error(`HTTP ${res.status}`);
  }
  const total =
    Number(res.headers.get("Content-Length")) || 0;
  const reader = res.body.getReader();
  const chunks: Uint8Array<ArrayBuffer>[] = [];
  let loaded = 0;
  for (;;) {
    const { done, value } = await reader.read();
    if (done) break;
    chunks.push(value);
    loaded += value.byteLength;
    if (total) onProgress(Math.min(loaded / total, 1));
  }
  const type = res.headers.get("Content-Type") ?? "";
  return new Blob(chunks, { type });
}

type Entry = { etag: string; data: unknown };
const cache = new Map<string, Entry>();
 
async function getCached(url: string): Promise<unknown> {
  const hit = cache.get(url);
  const headers: HeadersInit = hit
    ? { "If-None-Match": hit.etag }
    : {};
  const res = await fetch(url, { headers });
  if (res.status === 304 && hit) return hit.data;
  const data: unknown = await res.json();
  const etag = res.headers.get("ETag");
  if (etag) cache.set(url, { etag, data });
  return data;
}

// ❌ waterfall: two sequential round trips
const a = await fetch("/api/profile");
const b = await fetch("/api/settings");
 
// ✅ in parallel
const [profile, settings] = await Promise.all([
  fetch("/api/profile"),
  fetch("/api/settings"),
]);

<link rel="preconnect" href="https://api.example.com"
      crossorigin>
<link rel="dns-prefetch" href="https://cdn.example.com">

import { z } from "zod";
 
export type ApiError =
  | { kind: "network"; cause: unknown }
  | { kind: "timeout" }
  | { kind: "http"; status: number; body: string }
  | { kind: "parse"; error: z.ZodError };
 
export type Result<T> =
  | { ok: true; data: T }
  | { ok: false; error: ApiError };
 
type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 
type ClientOptions = {
  baseUrl: string;
  headers?: HeadersInit;
  timeoutMs?: number;
  retries?: number;
};
 
const RETRY_STATUS = new Set([408, 429, 500, 502, 503, 504]);
const IDEMPOTENT = new Set<Method>(["GET", "PUT", "DELETE"]);
const sleep = (ms: number) =>
  new Promise<void>((r) => setTimeout(r, ms));
const fail = (error: ApiError) =>
  ({ ok: false, error }) as const;
 
export function createClient(opts: ClientOptions) {
  const { timeoutMs = 10_000, retries = 2 } = opts;
 
  async function attempt<S extends z.ZodType>(
    method: Method,
    url: URL,
    schema: S,
    body: unknown,
  ): Promise<Result<z.output<S>>> {
    const headers = new Headers(opts.headers);
    headers.set("Accept", "application/json");
    if (body !== undefined) {
      headers.set("Content-Type", "application/json");
    }
    let res: Response;
    try {
      res = await fetch(url, {
        method,
        headers,
        body:
          body === undefined ? null : JSON.stringify(body),
        signal: AbortSignal.timeout(timeoutMs),
      });
    } catch (cause) {
      const timedOut =
        cause instanceof Error &&
        cause.name === "TimeoutError";
      const error: ApiError = timedOut
        ? { kind: "timeout" }
        : { kind: "network", cause };
      return fail(error);
    }
    if (!res.ok) {
      const { status } = res;
      const text = await res.text();
      return fail({ kind: "http", status, body: text });
    }
    const json: unknown =
      res.status === 204 ? null : await res.json();
    const parsed = schema.safeParse(json);
    return parsed.success
      ? { ok: true, data: parsed.data }
      : fail({ kind: "parse", error: parsed.error });
  }
 
  async function request<S extends z.ZodType>(
    method: Method,
    path: string,
    schema: S,
    body?: unknown,
  ): Promise<Result<z.output<S>>> {
    const url = new URL(path, opts.baseUrl);
    const tries = IDEMPOTENT.has(method) ? retries + 1 : 1;
    let result = await attempt(method, url, schema, body);
    for (let i = 1; i < tries && shouldRetry(result); i++) {
      // exponential backoff with jitter
      await sleep(2 ** i * 200 + Math.random() * 100);
      result = await attempt(method, url, schema, body);
    }
    return result;
  }
 
  return {
    get: <S extends z.ZodType>(path: string, schema: S) =>
      request("GET", path, schema),
    post: <S extends z.ZodType>(
      p: string,
      s: S,
      b: unknown,
    ) =>
      request("POST", p, s, b),
    request,
  };
}
 
function shouldRetry(r: Result<unknown>): boolean {
  if (r.ok) return false;
  const e = r.error;
  return (
    e.kind === "network" ||
    e.kind === "timeout" ||
    (e.kind === "http" && RETRY_STATUS.has(e.status))
  );
}

const api = createClient({
  baseUrl: "https://api.example.com",
});
 
const r = await api.get("/users/1", User);
if (r.ok) {
  console.log(r.data.name); // typed from the schema
} else {
  switch (r.error.kind) {
    case "http":    console.error(r.error.status); break;
    case "parse":
      console.error(r.error.error.issues);
      break;
    case "timeout":
    case "network": console.error("try again later"); break;
  }
}

const TIMEOUT_MS = 10_000;
 
async function getJson<T>(url: string): Promise<T> {
  const res = await fetch(url, {
    headers: { Accept: "application/json" },
    signal: AbortSignal.timeout(TIMEOUT_MS),
  });
  if (!res.ok) throw new Error(`GET ${url}: ${res.status}`);
  return (await res.json()) as T;
}
 
async function postJson<T>(
  url: string,
  body: unknown,
): Promise<T> {
  const res = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(TIMEOUT_MS),
  });
  if (!res.ok) throw new Error(`POST ${url}: ${res.status}`);
  return (await res.json()) as T;
}
 
type User = { id: string; name: string };
const user = await getJson<User>("/api/users/1");
const made = await postJson<User>("/api/users", {
  name: "Ada",
});

async function downloadFile(
  url: string,
  init?: RequestInit, // e.g. an Authorization header
): Promise<void> {
  const res = await fetch(url, init);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const cd = res.headers.get("Content-Disposition") ?? "";
  const name =
    /filename="?([^";]+)"?/i.exec(cd)?.[1] ?? "download";
  const href = URL.createObjectURL(await res.blob());
  const a = Object.assign(document.createElement("a"), {
    href,
    download: name,
  });
  a.click();
  setTimeout(() => URL.revokeObjectURL(href), 0);
}
 
await downloadFile("/api/reports/42.csv", {
  headers: { Authorization: "Bearer <token>" },
});

function upload(
  url: string,
  body: FormData | Blob,
  onProgress: (done: number) => void,
  signal?: AbortSignal,
): Promise<string> {
  return new Promise((resolve, reject) => {
    const xhr = new XMLHttpRequest();
    xhr.open("POST", url);
    xhr.upload.onprogress = (e) => {
      if (e.lengthComputable) onProgress(e.loaded / e.total);
    };
    xhr.onload = () =>
      xhr.status < 300
        ? resolve(xhr.responseText)
        : reject(new Error(`HTTP ${xhr.status}`));
    xhr.onerror = () => reject(new TypeError("Network"));
    xhr.onabort = () => reject(signal?.reason);
    signal?.addEventListener("abort", () => xhr.abort());
    xhr.send(body);
  });
}

function retryAfterMs(res: Response): number | undefined {
  const h = res.headers.get("Retry-After");
  if (!h) return undefined;
  const secs = Number(h); // "120" or an HTTP date
  if (Number.isFinite(secs)) return secs * 1_000;
  const at = Date.parse(h);
  return Number.isNaN(at) ? undefined : at - Date.now();
}
 
async function fetchPolitely(
  input: string | URL,
  init?: RequestInit,
  maxTries = 4,
): Promise<Response> {
  for (let attempt = 1; ; attempt++) {
    const res = await fetch(input, init);
    const busy = res.status === 429 || res.status === 503;
    if (!busy || attempt >= maxTries) return res;
    const wait = retryAfterMs(res) ?? 500 * 2 ** attempt;
    await res.body?.cancel(); // release the connection
    const ms = Math.min(Math.max(wait, 0), 60_000);
    await new Promise((r) => setTimeout(r, ms));
  }
}

type QueryValue =
  | string | number | boolean | null | undefined
  | readonly (string | number)[];
 
function withQuery(
  base: string | URL,
  query: Record<string, QueryValue>,
): URL {
  const url = new URL(base);
  for (const [key, value] of Object.entries(query)) {
    if (value == null) continue; // drop null/undefined
    const items = Array.isArray(value) ? value : [value];
    for (const item of items) {
      url.searchParams.append(key, String(item));
    }
  }
  return url;
}
 
withQuery("https://api.example.com/items", {
  q: "a&b",
  tag: ["ts", "bun"],
  page: 2,
  cursor: undefined,
}).href; // ...items?q=a%26b&tag=ts&tag=bun&page=2

declare function getToken(): string | undefined;
declare function refreshToken(): Promise<string>;
 
let refreshing: Promise<string> | undefined;
 
export async function authFetch(
  input: string | URL,
  init: RequestInit = {}, // body must be re-sendable
): Promise<Response> {
  const send = (tok: string | undefined) => {
    const headers = new Headers(init.headers);
    if (tok) headers.set("Authorization", `Bearer ${tok}`);
    return fetch(input, { ...init, headers });
  };
  const res = await send(getToken());
  if (res.status !== 401) return res;
  // many parallel 401s share a single refresh call
  refreshing ??= refreshToken().finally(() => {
    refreshing = undefined;
  });
  return send(await refreshing); // retry once
}

function track(
  event: string,
  data: Record<string, unknown> = {},
): void {
  const body = JSON.stringify({ event, ...data });
  void fetch("/api/events", {
    method: "POST",
    keepalive: true, // may outlive the page (64 KiB budget)
    headers: { "Content-Type": "application/json" },
    body,
  }).catch(() => {}); // analytics must never throw
}
 
// the last reliable moment on mobile is "hidden"
document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "hidden") {
    track("page_hidden", { path: location.pathname });
  }
});