Typing APIs: a fetch type is a promise, not a proof

fetch hands you any, and as makes it worse

response.json() returns Promise<any>. That any is honest: at compile time TypeScript genuinely does not know what JSON the server will send. The moment you write a type, you are asserting knowledge the compiler cannot verify:

const res = await fetch("/api/user/42");
const user = await res.json(); // ^? any

// "I promise this is a User" — but nothing checks it
const typed = (await res.json()) as User; // ^? User

as User is a one-way assertion. It silences any and produces a value the rest of your program treats as fully-typed — but it performs zero runtime work. If the server sends { id: 42, profil: null } (note the typo, or a renamed field, or a null where you expected an object), typed.profile.name compiles, ships, and throws at runtime. The cast was a lie the type system had no way to catch.

as Response and the boundary of trust

The data is untrusted, and so is its shape. Picture the round trip: your typed call leaves, JSON bytes come back, and there is a fork in the road. One branch casts — fast, free, and unsound. The other validates — a runtime check that actually inspects the bytes and only then lets a typed value through.

The boundary is the single most important concept in this unit: it is the line where compile-time guarantees stop. Everything left of it (your call sites, your render code) is proven by the type checker. Everything right of it (the actual response) is runtime data the checker never saw. A cast pretends the line isn’t there. Validation is the only thing that earns the type.

Model the response as a discriminated union, not a happy-path shape

Even before validation, you get further by typing reality. Real APIs return errors, not just successes. A field that is “always there” on the happy path is undefined in the error path. Model both:

type ApiOk<T> = { ok: true; data: T };
type ApiErr = { ok: false; error: { code: string; message: string } };
type ApiResult<T> = ApiOk<T> | ApiErr;

declare function getUser(id: number): Promise<ApiResult<User>>;

const r = await getUser(42);
if (r.ok) {
  r.data; // ^? User  — narrowed: data exists only on the ok branch
} else {
  r.error.message; // ^? string  — error exists only here
  // r.data;  // Error: Property 'data' does not exist on type 'ApiErr'
}

The ok: true | false discriminant (unit 02) forces every caller to handle the failure branch — the compiler refuses to let them reach r.data without first proving r.ok. This is strictly better than a User | undefined return that gets !-ed away. It does not validate the bytes, but it makes the contract honest in the type system.

Result<T, E> pushes errors into values

The same idea, generalised: instead of throwing across the boundary, return a Result and make the caller deal with both arms. Errors become ordinary values the type checker tracks:

type Result<T, E = Error> =
  | { kind: "ok"; value: T }
  | { kind: "err"; error: E };

function parseJson<T>(text: string): Result<T, SyntaxError> {
  try {
    return { kind: "ok", value: JSON.parse(text) as T };
  } catch (e) {
    return { kind: "err", error: e as SyntaxError };
  }
}
// Note: the `as T` inside is STILL a lie — JSON.parse returns any.
// Result models the throw/no-throw fork honestly, but it does not
// verify the success value's shape. That gap is what lesson 2 closes.

Result makes control flow type-safe. It does not make the payload type-safe — the as T is the same boundary lie wearing a nicer coat.

Sharing types across client and server

When you find yourself copying a server interface into a frontend file by hand, ask yourself: what happens when the server adds a field next week? The cleanest way to make the annotation less of a lie is to stop hand-writing it. If client and server share one source of truth, the type can’t silently drift from the bytes:

• Same monorepo / shared package — export the response type from one module both sides import. The next lesson’s zod schemas and lesson 3’s tRPC are two ways to do this; both derive the type from one definition.
• OpenAPI-generated types — when the server publishes an OpenAPI spec, a codegen step turns it into client types (see the APIs track on OpenAPI). The generated User is mechanically tied to the documented contract, so it drifts only when the spec drifts — and a spec diff is reviewable. It still does not validate at runtime; a server bug that violates its own spec sails through. Generation narrows the drift gap; it does not close the trust gap.