Typing API Data

The boundary problem

Everything so far checks code you wrote. But data crossing into your program — a web API response sent by another server (lesson 2-3), a file, user input — is typed by nobody. JSON.parse returns any by design, and lesson 2-3 warned you where any leads.

The professional pattern has three steps:

1. Declare an interface for the shape you expect
2. Hold the parsed value as unknown, not any
3. Write a checking function that proves the shape at runtime, then use the data fully typed

Step 3 uses a type predicate, a return type of the form value is ApiUser. It tells the compiler: when this function returns true, treat the argument as that type from here on. It is narrowing (Unit 4) that you define yourself.

as: the assertion inside the checker

One new keyword appears in the checking function below: value as { id?: unknown }. The as keyword is a type assertion — it tells the compiler "treat this value as this type", with no runtime check and no conversion. The compiler simply believes you. That makes as dangerous as a general tool: assert the wrong type and you have re-created the any problem with extra steps, a claim the running program can still violate.

The legitimate, narrow use is exactly what the checker does. After proving value is a non-null object, it asserts a shape whose properties are all typed unknown — so nothing becomes trusted, and each property must still pass its own typeof test before use. The assertion claims no more than "an object whose properties I am about to check". That is the rule for as in general: use it only when you know something the compiler cannot, and keep the claim as weak as possible.