In Designing a Typed API Client, the client ended with return result as Routes[R]['output']. That cast was a promise about the server. This lesson is about keeping that promise honest.
Every program has a boundary: the places where data comes from somewhere the compiler cannot see. HTTP responses, JSON.parse, URL parameters, localStorage, form fields, messages from other windows, environment variables. Inside the boundary, types describe values your own code created. At the boundary, types are just hopes. The pattern for handling it has a well-known slogan: parse, don’t validate. Turn untyped data into typed data once, at the edge, and let the rest of the program trust the types.
JSON.parse returns any, and so does Response.json(). any is contagious: assign it to a variable typed Order and TypeScript believes you. The first step is to refuse that gift:
const raw: unknown = await res.json();\nraw.status;\n// Error: 'raw' is of type 'unknown'.unknown is the honest type for data you have not checked. You can pass it around, but you cannot use it until you narrow it. Narrowing is what a parser does.
A parser takes unknown and returns either a typed value or a description of what was wrong. With the Result type from the last lesson:
const STATUSES = ['processing', 'shipped', 'delivered', 'cancelled', 'returned'] as const;\ntype OrderStatus = (typeof STATUSES)[number];\ntype Order = { id: number; status: OrderStatus; totalCents: number; couponCode: string | null };\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction isOrderStatus(value: unknown): value is OrderStatus {\n return typeof value === 'string' && (STATUSES as readonly string[]).includes(value);\n}\n\nfunction parseOrder(input: unknown): Result<Order, string> {\n if (!isRecord(input)) return err('order: expected an object');\n const { id, status, totalCents, couponCode } = input;\n if (typeof id !== 'number' || !Number.isInteger(id)) return err('id: expected an integer');\n if (!isOrderStatus(status)) return err(`status: unknown value ${JSON.stringify(status)}`);\n if (typeof totalCents !== 'number') return err('totalCents: expected a number');\n if (couponCode !== null && typeof couponCode !== 'string') return err('couponCode: expected a string or null');\n return ok({ id, status, totalCents, couponCode });\n}Look at the final line: there is no cast. Each check narrowed one variable, and by the end TypeScript can verify that the object literal matches Order. If the type gains a field and the parser forgets it, the ok(…) line fails to compile. This is also where you would brand values, calling toOrderId(id) from Branded Types and Exhaustive Checks.
Back in the client, the fix for that final cast is a table of parsers, one per route, checked against the route map with a mapped type and satisfies:
const parsers = {\n 'GET /orders/:id': parseOrder,\n 'GET /orders': parseOrderPage,\n 'POST /orders/:id/cancel': parseCancelledOrder,\n} satisfies { [R in keyof Routes]: (input: unknown) => Result<Routes[R]['output'], string> };Forget a route and satisfies reports the missing key; return the wrong type from a parser and it reports that too. Inside call, the response now goes through parsers[route] before it is returned. TypeScript cannot connect the generic R to the matching row of the table, so one annotation remains there, but it now sits on data that has actually been checked: the client’s output types are earned instead of asserted.
isRecord and isOrderStatus are type predicates: functions whose return type is value is T. When one returns true, TypeScript narrows the argument at the call site. Since TypeScript 5.5, simple ones like (x) => x !== null are inferred, as you saw in section 1, but anything with real logic needs the annotation.
Sometimes you want to narrow and stop if the data is bad, without an if at every call site. An assertion function returns nothing and throws on failure, and its asserts return type narrows everything after the call:
function assertIsOrder(input: unknown): asserts input is Order {\n const parsed = parseOrder(input);\n if (!parsed.ok) throw new Error(`Invalid order: ${parsed.error}`);\n}\n\nconst raw: unknown = JSON.parse(cachedJson);\nassertIsOrder(raw);\nraw.status; // OrderStatusAssertion functions fit places where bad data is a bug rather than an expected case: test helpers, data your own server rendered into the page, invariants. For HTTP responses, prefer a parser that returns a Result, so a changed API produces a handled error rather than a crash. One quirk: an assertion function must be called through a name with an explicit type, so const assertIsOrder = (x: unknown): asserts x is Order => … needs a type annotation on the const itself, or TypeScript reports “Assertions require every name in the call target to be declared with an explicit type annotation”.
In the exercise you will write Cartwheel’s order parser, a predicate and an assertion function, and replace a cast that has been lying since day one. Next lesson builds typed event emitters and builders on top of everything in this section.
\n","toc":[{"id":"sec-1","text":"Start from unknown","level":2},{"id":"sec-2","text":"A parser, by hand","level":2},{"id":"sec-3","text":"Closing the gap in the API client","level":3},{"id":"sec-4","text":"Type predicates","level":2},{"id":"sec-5","text":"Assertion functions","level":2}],"takeaways":["JSON.parse, response.json() and localStorage give you any; annotate their results as unknown so the compiler forces a check.","A parser takes unknown and returns a typed value or an error, so the rest of the code only ever sees data that has been checked.","A type predicate (value is T) narrows at the call site, but TypeScript trusts its body, so a wrong predicate is an unchecked cast.","An assertion function (asserts value is T) narrows everything after the call and must throw when the check fails.","Schema libraries declare the check once and derive the type from it, which removes the risk of a parser and a type drifting apart."],"further":[{"title":"Using type predicates","url":"https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates"},{"title":"Assertion functions (TypeScript 3.7 release notes)","url":"https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html"},{"title":"JSON.parse() (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse"}],"quiz":[{"q":"const data = await res.json(); What is the type of data, and what should you do about it?
unknown; narrow it before use.","why":"Response.json() is declared to return Promise<any>, not unknown, so nothing forces you to narrow unless you annotate it."},{"text":"Order, inferred from the endpoint URL.","why":"TypeScript cannot know what a server returns; the URL is just a string to it."},{"text":"object; cast it with as Order.","why":"The type is any, and a cast skips the check that would catch a changed API."},{"text":"any; annotate it as unknown and run it through a parser.","why":"Correct. any switches checking off for every use; unknown forces each use to be proved first."}],"answer":3},{"q":"What is wrong with this predicate?
\nfunction isOrder(value: unknown): value is Order {\n return typeof value === 'object' && value !== null && 'id' in value;\n}id is enough to prove a value is an Order.","why":"A customer record also has id. The predicate claims far more than it checks."},{"text":"It claims the value is a full Order but only checks for id, and TypeScript trusts the claim without verifying it.","why":"Correct. A predicate’s body is not checked against its return type, so a weak check is an unchecked cast."},{"text":"Predicates cannot use the in operator.","why":"in is a normal narrowing check and works fine inside predicates."}],"answer":1},{"q":"How does an assertion function differ from a type predicate?
","options":[{"text":"An assertion function returnsboolean; a predicate returns void.","why":"It is the other way round. A predicate returns boolean; an assertion function returns nothing and throws on failure."},{"text":"An assertion function narrows the value for the rest of the scope after the call, and throws if the check fails.","why":"Correct. assertIsOrder(x); x.id works, because returning normally proves the assertion."},{"text":"Assertion functions only work on primitives.","why":"They work on any type, including objects and unions."}],"answer":1},{"q":"Where should a value from localStorage.getItem('cart') be parsed?
Replace the lying cast in parseOrder with a real parser, and give the helpers real types:
isRecord and isOrderStatus become type predicates.parseOrder(input: unknown) returns ok(order) only when id is an integer, status is a known status, totalCents is a whole number, and couponCode is a string or null. Otherwise it returns err(message), where the message starts with the name of the bad field (for example status: …). The returned order must contain only those four fields.assertIsOrder becomes an assertion function that narrows its argument to Order and throws an Error whose message contains Invalid order when parsing fails.No as casts in parseOrder.
value is Record<string, unknown> and value is OrderStatus.","In parseOrder, check isRecord(input) first, destructure the four fields, and check each with typeof or your predicate, returning err('field: …') on the first failure.","Build the result from the narrowed variables, ok({ id, status, totalCents, couponCode }), so TypeScript verifies it and extra fields are dropped. For the assertion, the return type is asserts input is Order."],"explanation":"The old input as Order let anything through, including a status the UI has no branch for. Now each field is narrowed by an ordinary check, and the final object literal is built from the narrowed variables, so the compiler verifies it matches Order without a cast, and unexpected fields such as cardNumber never get past the boundary. The two predicates are small enough to be obviously correct. assertIsOrder reuses the parser and turns a failure into a thrown error, and its asserts signature narrows the caller’s variable for the rest of the scope.
status","rejects-types":"Wrong field types, arrays and null are rejected with messages naming the field","only-known-fields":"Unexpected fields are not copied into the parsed order","asserts":"assertIsOrder throws ‘Invalid order…’ for bad data"}},"words":777,"readMinutes":4}