Function Overloads and Async Functions

Two more function topics come up constantly in real TypeScript code: overloads, for functions whose return type depends on how they're called, and async functions, which return typed promises. Getting async types and error handling right is essential for any app that talks to an API.

Function overloads

function parse(value: string): number;                 // overload signatures
function parse(value: string[]): number[];
function parse(value: string | string[]): number | number[] {   // the implementation
  return Array.isArray(value) ? value.map(Number) : Number(value);
}

const one = parse("42");              // type: number
const many = parse(["1", "2", "3"]);  // type: number[]
console.log(one + 1, many.map((n) => n * 10));

43 [ 10, 20, 30 ]

Callers see only the overload signatures, so each call gets a precise return type. The implementation signature must be compatible with all of them and isn't callable directly.

Async functions

interface Course {
  id: number;
  title: string;
  lessons: number;
}

const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));

async function fetchCourse(id: number): Promise<Course> {     // async always returns a Promise
  await sleep(20);                                              // pretend network delay
  if (id <= 0) throw new Error(`Course ${id} not found`);
  return { id, title: id === 1 ? "TypeScript" : "C++ with STL", lessons: id === 1 ? 20 : 33 };
}

const course = await fetchCourse(1);                          // top-level await (ES module)
console.log(`${course.title}: ${course.lessons} lessons`);

const [ts, cpp] = await Promise.all([fetchCourse(1), fetchCourse(2)]);   // typed tuple of results
console.log(ts.title, "+", cpp.title, "=", ts.lessons + cpp.lessons, "lessons");

TypeScript: 20 lessons
TypeScript + C++ with STL = 53 lessons

An async function's return type is always Promise<T>, and await unwraps it to T. Promise.all with an array of different promises returns a tuple with each result's own type.

Errors are unknown

async function load(id: number): Promise<string> {
  if (id === 404) throw new Error("Not Found");
  if (id === 500) throw "server exploded";          // anything can be thrown in JavaScript
  return `course ${id}`;
}

for (const id of [7, 404, 500]) {
  try {
    console.log(await load(id));
  } catch (err) {                                    // err: unknown under strict mode
    if (err instanceof Error) console.log("Error:", err.message);
    else console.log("Unexpected:", String(err));
  }
}

course 7
Error: Not Found
Unexpected: server exploded

Typing a fetch helper

interface User { id: number; name: string }

async function getJson<T>(url: string, isValid: (data: unknown) => data is T): Promise<T> {
  const res = await fetch(url);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const data: unknown = await res.json();
  if (!isValid(data)) throw new Error("Unexpected response shape");
  return data;                                    // now safely typed as T
}

const isUser = (d: unknown): d is User =>
  typeof d === "object" && d !== null && "id" in d && "name" in d &&
  typeof d.id === "number" && typeof d.name === "string";

// const user = await getJson("/api/users/1", isUser);   // user: User

A generic helper plus a type guard (data is T) is how professional code bridges untyped network data and typed application code. Chapter 5 covers type guards in depth.

Practice

Summary