Typing async results and failures

Promise<T> describes the value a promise fulfils with. It says nothing about how it can fail: there is no second type parameter for the rejection, because any code along the way can throw anything. That is the same reason a caught error is unknown.

The types around promises worth knowing:

• An async function's return type is always Promise<...>; returning a T produces Promise<T>, and returning a Promise<T> does not nest.
• Awaited<T> is what await produces, unwrapping nested promises: Awaited<Promise<Promise<number>>> is number.
• PromiseSettledResult<T> is a discriminated union: { status: "fulfilled"; value: T } | { status: "rejected"; reason: any }.

allSettled, narrowed

Promise.all gives you every value or the first failure. Promise.allSettled waits for everything and reports each outcome. Each result is narrowed on status before you may read value or reason — and reason is typed any, so treat it as unknown:

1function charge(amount: number): Promise<string> {2  return new Promise((resolve, reject) =>3    setTimeout(() => {4      if (amount <= 0) reject(new Error(`invalid amount ${amount}`));5      else resolve(`charged ${amount}`);6    }, 10),7  );8}9 10export async function run(): Promise<string[]> {11  const results = await Promise.allSettled([charge(20), charge(-5), charge(8)]);12  // Each result is PromiseSettledResult<string>: narrow on status to read it.13  return results.map((r) =>14    r.status === "fulfilled"15      ? `ok: ${r.value}`16      : `failed: ${r.reason instanceof Error ? r.reason.message : String(r.reason)}`,17  );18}

The results come back in the order of the input array, whatever order the promises settled in.

return against return await

Inside a try, return somePromise hands the promise to the caller before it settles; the function leaves the try, so a later rejection is never seen by its catch. return await settles it inside the try:

1async function load(): Promise<string> {2  throw new Error("database down");3}4 5async function withoutAwait(): Promise<string> {6  try {7    return load();          // the promise leaves the try before it rejects8  } catch {9    return "fallback";10  }11}12 13async function withAwait(): Promise<string> {14  try {15    return await load();    // the rejection is thrown here, inside the try16  } catch {17    return "fallback";18  }19}20 21export async function run(): Promise<string[]> {22  const out: string[] = [];23  for (const f of [withoutAwait, withAwait]) {24    try {25      out.push(`${f.name}: ${await f()}`);26    } catch (e) {27      out.push(`${f.name}: rejected with ${(e as Error).message}`);28    }29  }30  return out;31}

Outside a try, the caller sees the same outcome either way; the difference is only which function the rejection passes through.

Expected failures as values

A rejection is invisible in the type. For failures the caller is expected to handle — not found, declined, suspended — returning a discriminated union puts them in the type, and the compiler then makes every caller look:

1type Result<T, E extends string> =2  | { ok: true; value: T }3  | { ok: false; error: E };4 5type LookupError = "not-found" | "suspended";6 7async function findUser(id: number): Promise<Result<string, LookupError>> {8  await new Promise((r) => setTimeout(r, 5));9  if (id === 1) return { ok: true, value: "Nino" };10  if (id === 2) return { ok: false, error: "suspended" };11  return { ok: false, error: "not-found" };12}13 14export async function run(): Promise<string[]> {15  const out: string[] = [];16  for (const id of [1, 2, 3]) {17    const r = await findUser(id);18    // The failure is part of the type, so the caller cannot forget it exists.19    out.push(r.ok ? `found ${r.value}` : `no user ${id}: ${r.error}`);20  }21  return out;22}

Keep throwing for the unexpected (a bug, a lost connection); return a result for outcomes that are part of the domain.

Common mistakes

• Assuming Promise<User> documents the failures. It does not; read the code, or use a result type.
• return promise inside try and expecting catch to handle it. As the example shows, the rejection goes to the caller instead.
• Reading r.value on an allSettled result without narrowing. A rejected entry has no value; check status first.
• Collecting results in a .then callback. Callbacks run in completion order, not input order; take the array that all or allSettled returns instead.

What interviewers ask

• Why is there no Promise<T, E>? Anything can throw inside the chain, and the type system does not track exceptions, so a rejection type could never be trusted; the reason is effectively unknown.
• When does return await matter? Inside (or ), where the rejection must happen while the function is still in the block.