Async & Promises

console.log("1 sync");
 
setTimeout(() => console.log("6 task"), 0);
 
Promise.resolve()
  .then(() => console.log("3 micro"))
  .then(() => console.log("5 micro (chained)"));
 
queueMicrotask(() => console.log("4 micro"));
 
(async () => {
  console.log("2 sync (async fn body)");
  await null;
  console.log("4b micro (after await)");
})();
 
console.log("2b sync");

1 sync
2 sync (async fn body)
2b sync
3 micro
4 micro
4b micro (after await)
5 micro (chained)
6 task

const p = new Promise<number>((resolve, reject) => {
  const n = Math.random();
  if (n > 0.5) resolve(n);
  else reject(new Error("too small"));
  // a throw here also rejects
});
 
// Promise<number>, fulfilled
Promise.resolve(42);
Promise.reject(new Error("x"));  // Promise<never>, rejected
Promise.resolve(p) === p;        // true: same native promise
 
// ES2025: run sync-or-async fn, capture sync throws too
const safe = Promise.try(() => JSON.parse("{bad"));
safe.catch(() => {});

function nextMessage(ws: WebSocket): Promise<string> {
  const { promise, resolve, reject } =
    Promise.withResolvers<string>();
  ws.addEventListener(
    "message",
    (e) => resolve(String(e.data)),
    { once: true },
  );
  ws.addEventListener(
    "error",
    () => reject(new Error("ws")),
    { once: true },
  );
  return promise;
}

import { readFile } from "node:fs";
import { promisify } from "node:util";
 
type Cb<T> = (err: Error | null, value?: T) => void;
 
function toPromise<T>(fn: (cb: Cb<T>) => void): Promise<T> {
  return new Promise((resolve, reject) => {
    fn((err, value) =>
      err ? reject(err) : resolve(value as T),
    );
  });
}
 
const text = await toPromise<string>((cb) =>
  readFile("a.txt", "utf8", cb),
);
 
const readFileP = promisify(readFile);   // Node helper
const sleep = (ms: number) =>
  new Promise<void>((r) => setTimeout(r, ms));

declare function getUser(
  id: string,
): Promise<{ name: string }>;
 
getUser("u1")
  .then((u) => u.name)                 // Promise<string>
  .then((name) => name.toUpperCase())
  .catch((err: unknown) => "anonymous")  // recovers
  .finally(() => console.log("done"))
  .then((label) => console.log(label));

type User = { id: string; name: string };
declare function fetchUser(id: string): Promise<User>;
 
async function names(ids: string[]): Promise<string[]> {
  const out: string[] = [];
  for (const id of ids) {
    const u = await fetchUser(id);   // sequential on purpose
    out.push(u.name);
  }
  return out;
}
 
class Db {
  private constructor(readonly url: string) {}
  static async connect(url: string): Promise<Db> {
    await Promise.resolve();         // e.g. handshake
    return new Db(url);
  }
}
 
const db = await Db.connect("postgres://local"); // top level

class NotFoundError extends Error {
  override name = "NotFoundError";
}
 
async function load(id: string): Promise<string> {
  try {
    const res = await fetch(`/api/items/${id}`);
    if (res.status === 404) throw new NotFoundError(id);
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return await res.text();
  } catch (err) {                    // err: unknown (strict)
    if (err instanceof NotFoundError) return "";
    throw new Error(`load(${id}) failed`, { cause: err });
  } finally {
    console.log("load finished");    // runs on every path
  }
}

// browser: e is PromiseRejectionEvent
window.addEventListener("unhandledrejection", (e) => {
  console.error("unhandled", e.reason);
  e.preventDefault();                // suppress default log
});
 
// Node: log, then exit deliberately
process.on("unhandledRejection", (reason) => {
  console.error("unhandled", reason);
  process.exitCode = 1;
});

declare function getA(): Promise<number>;
declare function getB(): Promise<string>;
 
const [a, b] = await Promise.all([getA(), getB()]);
//     ^ number, string: tuples are preserved
 
const results = await Promise.allSettled([getA(), getA()]);
const ok = results
  .filter((r) => r.status === "fulfilled")
  .map((r) => r.value);   // number[] (TS 5.5+ inference)
 
const fastest = await Promise.any([
  fetch("https://a.example/data"),
  fetch("https://b.example/data"),
]);

declare function job(n: number): Promise<number>;
 
// sequential: total = sum of durations
for (const n of [1, 2, 3]) await job(n);
 
// parallel: total = slowest duration
const all = await Promise.all([1, 2, 3].map(job));
 
// start early, await late
const pa = job(1);
const pb = job(2);
const sum = (await pa) + (await pb);

async function mapPool<T, R>(
  items: readonly T[],
  limit: number,
  fn: (item: T, index: number) => Promise<R>,
): Promise<R[]> {
  const results = new Array<R>(items.length);
  let next = 0;
 
  async function worker(): Promise<void> {
    while (next < items.length) {
      const i = next++;              // safe: single thread
      results[i] = await fn(items[i] as T, i);
    }
  }
 
  const n = Math.max(1, Math.min(limit, items.length));
  await Promise.all(Array.from({ length: n }, worker));
  return results;
}
 
const pages = await mapPool(
  ["/a", "/b", "/c", "/d"],
  2,
  (url) => fetch(url).then((r) => r.text()),
);

function sleep(ms: number, signal?: AbortSignal) {
  return new Promise<void>((resolve, reject) => {
    signal?.throwIfAborted();
    const id = setTimeout(resolve, ms);
    signal?.addEventListener(
      "abort",
      () => {
        clearTimeout(id);
        reject(signal.reason);
      },
      { once: true },
    );
  });
}
 
type RetryOpts = {
  retries?: number;
  baseMs?: number;
  capMs?: number;
  signal?: AbortSignal;
  shouldRetry?: (err: unknown) => boolean;
};
 
async function retry<T>(
  fn: (attempt: number) => Promise<T>,
  opts: RetryOpts = {},
): Promise<T> {
  const { retries = 3, baseMs = 200, capMs = 5_000 } = opts;
  for (let attempt = 0; ; attempt++) {
    try {
      return await fn(attempt);
    } catch (err) {
      const give_up =
        attempt >= retries ||
        opts.signal?.aborted ||
        opts.shouldRetry?.(err) === false;
      if (give_up) throw err;
      const ceiling = Math.min(capMs, baseMs * 2 ** attempt);
      await sleep(Math.random() * ceiling, opts.signal);
    }
  }
}

function withTimeout<T>(
  p: Promise<T>,
  ms: number,
): Promise<T> {
  let id: ReturnType<typeof setTimeout> | undefined;
  const timeout = new Promise<never>((_, reject) => {
    id = setTimeout(
      () => reject(new Error(`Timed out after ${ms} ms`)),
      ms,
    );
  });
  return Promise.race([p, timeout]).finally(() =>
    clearTimeout(id),
  );
}

async function search(q: string, userSignal?: AbortSignal) {
  const signal = AbortSignal.any(
    [AbortSignal.timeout(5_000), userSignal].filter(
      (s): s is AbortSignal => s !== undefined,
    ),
  );
  try {
    const res = await fetch(`/search?q=${q}`, { signal });
    return (await res.json()) as unknown;
  } catch (err) {
    if (err instanceof DOMException) {
      if (err.name === "TimeoutError") return "timed out";
      if (err.name === "AbortError") return "canceled";
    }
    throw err;
  }
}
 
const ctrl = new AbortController();
const pending = search("ts", ctrl.signal);
ctrl.abort();                        // user navigated away

async function syncAll(
  ids: string[],
  { signal }: { signal?: AbortSignal } = {},
): Promise<void> {
  for (const id of ids) {
    signal?.throwIfAborted();        // stop between steps
    await fetch(`/sync/${id}`, { method: "POST", signal });
  }
}

type Page = { items: string[]; next: string | null };
 
async function* paginate(start: string) {
  let url: string | null = start;
  while (url) {
    const res: Response = await fetch(url);
    const page = (await res.json()) as Page;
    yield* page.items;
    url = page.next;
  }
}
 
for await (const item of paginate("/api/items")) {
  // calls return(): cleanup
  if (item === "stop") break;
}
 
// Baseline 2024: collect an async iterable
const everything = await Array.fromAsync(
  paginate("/api/items"),
);

async function getConfig() {
  return { port: 3000, debug: false };
}
type Config = Awaited<ReturnType<typeof getConfig>>;
//   ^ { port: number; debug: boolean }
 
type Task<T> = (signal: AbortSignal) => Promise<T>;
 
async function runAll<T>(tasks: Task<T>[]): Promise<T[]> {
  const ctrl = new AbortController();
  return Promise.all(tasks.map((t) => t(ctrl.signal)));
}
 
function summarize<T>(rs: PromiseSettledResult<T>[]) {
  return rs.map((r) =>
    r.status === "fulfilled" ? r.value : String(r.reason),
  );
}
 
// a void-returning callback type accepts async functions,
// and nobody awaits them: a floating promise
const onSave: () => void = async () => {
  await Promise.resolve();
};

declare function save(id: string): Promise<void>;
const ids = ["a", "b"];
 
ids.forEach(async (id) => {
  await save(id);                    // not awaited by anyone
});
// ...code here runs before any save finishes
 
for (const id of ids) await save(id);    // sequential
await Promise.all(ids.map((id) => save(id))); // parallel

declare function track(event: string): Promise<void>;
void track("page_view").catch(() => {});

declare function getUser(): Promise<{ id: string }>;
declare function getFeed(): Promise<string[]>;
 
// slow: getFeed waits for getUser for no reason
const u1 = await getUser();
const f1 = await getFeed();
 
// fast: independent work in parallel
const [u2, f2] = await Promise.all([getUser(), getFeed()]);

declare function risky(): Promise<string>;
 
async function bad(): Promise<string> {
  try {
    return risky();                  // rejection skips catch
  } catch {
    return "fallback";
  }
}
 
async function good(): Promise<string> {
  try {
    return await risky();            // rejection caught here
  } catch {
    return "fallback";
  }
}

function loadImage(src: string): Promise<HTMLImageElement> {
  return new Promise((resolve, reject) => {
    const img = new Image();
    img.onload = () => resolve(img);
    img.onerror = () =>
      reject(new Error(`Failed to load ${src}`));
    img.src = src;
  });
}
 
const sleep = (ms: number) =>
  new Promise<void>((resolve) => setTimeout(resolve, ms));
 
const logo = await loadImage("/logo.png");
await sleep(250);

function dedupe<A extends unknown[], R>(
  key: (...args: A) => string,
  fn: (...args: A) => Promise<R>,
): (...args: A) => Promise<R> {
  const inFlight = new Map<string, Promise<R>>();
  return (...args) => {
    const k = key(...args);
    const hit = inFlight.get(k);
    if (hit) return hit;
    const p = fn(...args).finally(() => inFlight.delete(k));
    inFlight.set(k, p);
    return p;
  };
}
 
const getUser = dedupe(
  (id: string) => id,
  async (id: string): Promise<unknown> =>
    (await fetch(`/api/users/${id}`)).json(),
);
// two components mount at once: one request
await Promise.all([getUser("u1"), getUser("u1")]);

function once<T>(init: () => Promise<T>): () => Promise<T> {
  let cached: Promise<T> | undefined;
  return () =>
    (cached ??= init().catch((err: unknown) => {
      cached = undefined; // let the next caller retry
      throw err;
    }));
}
 
declare function connect(url: string): Promise<{ ok: true }>;
const getDb = once(() => connect("postgres://db/app"));
 
// every caller shares the same connection promise
const [a, b] = await Promise.all([getDb(), getDb()]);
a === b; // true

function latestOnly<A extends unknown[], R>(
  fn: (signal: AbortSignal, ...args: A) => Promise<R>,
): (...args: A) => Promise<R> {
  let current: AbortController | undefined;
  return (...args) => {
    current?.abort(); // the previous call rejects AbortError
    current = new AbortController();
    return fn(current.signal, ...args);
  };
}
 
const search = latestOnly(async (signal, q: string) => {
  const url = `/api/search?q=${encodeURIComponent(q)}`;
  const res = await fetch(url, { signal });
  return res.json() as Promise<string[]>;
});
 
declare function render(hits: string[]): void;
const isAbort = (e: unknown) =>
  e instanceof DOMException && e.name === "AbortError";
search("typ").then(render, (e) => {
  if (!isAbort(e)) throw e;
});
search("typescript").then(render); // only this one renders

async function pollUntil<T>(
  fn: () => Promise<T>,
  done: (value: T) => boolean,
  { intervalMs = 1_000, signal }: {
    intervalMs?: number;
    signal?: AbortSignal;
  } = {},
): Promise<T> {
  for (;;) {
    signal?.throwIfAborted();
    const value = await fn();
    if (done(value)) return value;
    await new Promise((r) => setTimeout(r, intervalMs));
  }
}
 
type Job = { status: "queued" | "done" | "failed" };
const job = await pollUntil(
  async (): Promise<Job> => (await fetch("/jobs/42")).json(),
  (j) => j.status === "done" || j.status === "failed",
  { intervalMs: 2_000, signal: AbortSignal.timeout(60_000) },
);

class Mutex {
  #tail: Promise<void> = Promise.resolve();
  async run<T>(fn: () => Promise<T>): Promise<T> {
    const prev = this.#tail;
    const next = Promise.withResolvers<void>();
    this.#tail = next.promise; // the next caller waits on it
    await prev;
    try {
      return await fn();
    } finally {
      next.resolve();
    }
  }
}
 
declare function readBalance(): Promise<number>;
declare function writeBalance(n: number): Promise<void>;
const lock = new Mutex();
// read-modify-write without lost updates
const deposit = (amount: number) =>
  lock.run(async () => {
    await writeBalance((await readBalance()) + amount);
  });
await Promise.all([deposit(10), deposit(20)]);

type Task<T> = (signal: AbortSignal) => Promise<T>;
 
async function allOrCancel<T>(
  tasks: readonly Task<T>[],
  outer?: AbortSignal,
): Promise<T[]> {
  const ctrl = new AbortController();
  const signal = outer
    ? AbortSignal.any([outer, ctrl.signal])
    : ctrl.signal;
  try {
    return await Promise.all(tasks.map((t) => t(signal)));
  } catch (err) {
    ctrl.abort(err); // stop the siblings still running
    throw err;
  }
}
 
const pages = await allOrCancel(
  ["/a", "/b", "/c"].map((url) => async (signal) => {
    const res = await fetch(url, { signal });
    if (!res.ok) throw new Error(`${url}: ${res.status}`);
    return res.text();
  }),
);

type Report<T> = {
  ok: T[];
  failed: { index: number; reason: unknown }[];
};
async function settle<T>(
  work: readonly Promise<T>[],
): Promise<Report<T>> {
  const results = await Promise.allSettled(work);
  return {
    ok: results.flatMap((r) =>
      r.status === "fulfilled" ? [r.value] : [],
    ),
    failed: results.flatMap((r, index) =>
      r.status === "rejected"
        ? [{ index, reason: r.reason as unknown }]
        : [],
    ),
  };
}
declare function sendEmail(to: string): Promise<string>;
 
const to = ["a@x.dev", "b@x.dev", "c@x.dev"];
const { ok, failed } = await settle(to.map(sendEmail));
console.info(`${ok.length} sent, ${failed.length} failed`);
for (const f of failed) console.error(to[f.index], f.reason);