Typing fetch & JSON

A server reply has no type

A shop page loads a product from its server with fetch, then reads the reply's body as JSON with response.json() (the fetch & JSON lesson covers both). Here the server sends { "name": "Tea", "price": 3 }, and the code has a typo:

1async function showProduct() {2  const response = await fetch("product.json");3  const product = await response.json();4  //    ^?5  console.log(`${product.nmae} costs $${product.price}`);6}7 8showProduct();

Line 2 asks the server for product.json, and line 3 reads the reply as JSON. Line 5 misspells name as nmae, and TypeScript says nothing. The code prints undefined costs $3. The answer after the ^? on line 4 shows why: product is any, the type that turns checking off (the any, unknown & never lesson covers it).

Now change one thing: say on line 3 that the reply is unknown, the type for "a value you haven't checked yet".

1async function showProduct() {2  const response = await fetch("product.json");3  const product: unknown = await response.json();4  console.log(`${product.nmae} costs $${product.price}`);5}6 7showProduct();

Line 4 gets two errors, on purpose: 'product' is of type 'unknown'. That means "you haven't shown me what this is yet, so you can't read anything from it". Both reads are marked, the typo and the correct price. TypeScript isn't being difficult: it really can't know what the server sent. Your code has to look first. The rest of this lesson is about how.

response.json() gives you any

TypeScript's browser types describe fetch fully: it gives back a Promise of a Response. But a response's body is only known when it arrives, so they say json() gives back a promise of any. (JSON.parse gives any too, for the same reason.) And any spreads: everything you read from it is any as well. This time the server sends the cake's price as text, { "name": "Cake", "price": "4" }:

1async function showPrice() {2  const response = await fetch("cake.json");3  //    ^?4  const product = await response.json();5  const price = product.price;6  //    ^?7  console.log(price.toFixed(2));8}9 10showPrice().catch((error) => console.log(`Crashed: ${error.message}`));

The answer on line 3 shows TypeScript knows response is a Response. Line 4 reads the JSON, and line 5 reads its price. The answer on line 6 shows price is any too. So line 7 can call price.toFixed(2), which formats a number with two decimals, and TypeScript has no complaint. But the price is the text "4", and text has no toFixed. When it runs, the code crashes, and line 10's catch prints Crashed: price.toFixed is not a function.

The obvious fix is to write the type you expect. It looks safer:

1type Product = { name: string; price: number };2 3async function showPrice() {4  const response = await fetch("cake.json");5  const product: Product = await response.json();6  //    ^?7  console.log(product.price.toFixed(2));8}9 10showPrice().catch((error) => console.log(`Crashed: ${error.message}`));

Line 1 describes a Product, and line 5 says the reply is one. The answer on line 6 shows const product: Product, and line 7 has no errors. But nothing changed while the page runs: the price is still text, and the code still prints Crashed: product.price.toFixed is not a function. An any can go into any type without a check, so the annotation is a promise you make, like as (the Type assertions lesson explains why). A helper like fetchJson<Product>() from Generics in practice makes the same promise in one place.

The table below lists the ways to receive JSON. Read each row as: what you write, what TypeScript believes, and what is really checked.

Treat the reply as unknown

unknown is the honest type for a reply: "this could be anything". TypeScript lets you put anything in it, but lets you use it only after a check proves what it is. Each check is a normal JavaScript test, like typeof, and TypeScript narrows the type to match (the Narrowing lesson covers typeof checks). Step through the checks it takes to read a name from a reply:

1const data: unknown = JSON.parse('{ "name": "Tea", "price": 3 }');2 3if (true) {4  console.log(data.name.toUpperCase());5}

Step 1 checks nothing, and line 4 can't read anything. Step 2 proves data is an object, but an object with no known properties: Property 'name' does not exist on type 'object'. Step 3 adds "name" in data (the in & instanceof narrowing lesson covers in), so reading data.name is allowed, but the name itself is unknown. Step 4 checks the name is text, and the errors are gone. The code prints TEA at every step: the checks change what TypeScript knows, and the data is the same.

Why does step 2 need data !== null? Because typeof null is "object" in JavaScript, and null is valid JSON. Here is what TypeScript knows after step 3:

1const data: unknown = JSON.parse('{ "name": "Tea", "price": 3 }');2 3if (typeof data === "object" && data !== null && "name" in data) {4  console.log(data.name);5  //          ^?6}

The answer on line 5 shows object & Record<"name", unknown>. In plain words: an object, and also (that's the &) something with a name property whose value is unknown. Line 4 prints Tea.

Check the data before you trust it

Writing those checks at every place that reads a product would be tiring. Put them in one function instead. It takes the reply as unknown and either gives back a real Product or throws an error that says what was wrong:

1type Product = { name: string; price: number };2 3function parseProduct(data: unknown): Product {4  if (typeof data !== "object" || data === null) throw new Error("Expected an object");5  if (!("name" in data) || typeof data.name !== "string") throw new Error("Expected name to be text");6  if (!("price" in data) || typeof data.price !== "number") throw new Error("Expected price to be a number");7  return { name: data.name, price: data.price };8}9 10const tea = parseProduct(JSON.parse('{ "name": "Tea", "price": 3 }'));11//    ^?12console.log(`${tea.name} costs $${tea.price}`);

Line 3 says parseProduct takes unknown and gives back a Product. Lines 4 to 6 each throw unless one fact is true: the data is an object, its name is text, and its price is a number. After each throw, TypeScript knows that fact, so line 7 can read both and build a new Product. Line 10 checks a reply, and the answer on line 11 shows tea is a Product. Line 12 prints Tea costs $3.

Only the checks make Product true here. If you forget one, TypeScript notices: line 7 would read a property it can't prove exists. Now send different replies through it:

1type Product = { name: string; price: number };2 3function parseProduct(data: unknown): Product {4  if (typeof data !== "object" || data === null) throw new Error("Expected an object");5  if (!("name" in data) || typeof data.name !== "string") throw new Error("Expected name to be text");6  if (!("price" in data) || typeof data.price !== "number") throw new Error("Expected price to be a number");7  return { name: data.name, price: data.price };8}9 10const reply = '{ "name": "Tea", "price": 3 }';11try {12  const product = parseProduct(JSON.parse(reply));13  console.log(`${product.name} costs $${product.price}`);14} catch (error) {15  console.log(error instanceof Error ? error.message : "Something went wrong");16}

A good reply prints Tea costs $3. A price sent as text, a missing name, and null each stop at the check that fails, and the catch on line 14 prints its message instead of a wrong total. An extra field passes, but line 7 copies only name and price. TypeScript has no errors for any reply, because it never sees the reply. That's the point: the checks run while the page runs, where the data is.

(A function that only answers yes or no, value is Product, works too; the Type predicates & assertion functions lesson shows that kind. A function that throws with a message makes a bad reply easier to understand.)

Schema libraries like Zod

A hand-written check has a weak spot: you write the shape twice, once as a type and once as checks, and they can drift apart. Here a new field was added to the type, but not to the check:

1type Product = { name: string; price: number; inStock: boolean };2 3function isProduct(value: unknown): value is Product {4  return (5    typeof value === "object" && value !== null &&6    "name" in value && typeof value.name === "string" &&7    "price" in value && typeof value.price === "number"8  );9}10 11const data: unknown = JSON.parse('{ "name": "Tea", "price": 3 }');12if (isProduct(data)) {13  console.log(data.inStock ? "In stock" : "Sold out");14}

Line 1 now says every product has inStock. Lines 3 to 9 are a yes-or-no check, value is Product, that still checks only the name and price. The reply on line 11 has no inStock, but the check says yes, so line 13 reads data.inStock, which is undefined, and prints Sold out. TypeScript has no errors: it believes the check.

A schema library fixes this. You describe the shape once, as a schema: an object made by the library that can check data. The library makes the type from the schema, so the two can't drift. A popular one is Zod. A real project installs it with npm install zod and writes import * as z from "zod". This page can't install packages, so the examples import ./mini-zod, a small stand-in written for this lesson with the same few calls. Press Edit & run to see it as a second file.

1import * as z from "./mini-zod";2 3const Product = z.object({ name: z.string(), price: z.number() });4type Product = z.infer<typeof Product>;5//   ^?6 7const tea = Product.parse(JSON.parse('{ "name": "Tea", "price": 3 }'));8console.log(`${tea.name} costs $${tea.price}`);9 10const cake = Product.parse(JSON.parse('{ "name": "Cake", "price": "4" }'));

Line 3 makes the schema: an object whose name is a string and whose price is a number. Line 4 makes the type from it with z.infer, and the answer on line 5 shows the result: { name: string; price: number; }. (Giving the type the same name as the schema is allowed: one is a value, the other a type.) Line 7 checks a good reply with .parse, and line 8 prints Tea costs $3. Line 10 checks the cake, whose price is text, and .parse throws, on purpose here.

When you'd rather not use try and catch, .safeParse gives back a result instead of throwing:

1import * as z from "./mini-zod";2 3const Product = z.object({ name: z.string(), price: z.number() });4 5const result = Product.safeParse(JSON.parse('{ "name": "Cake", "price": "4" }'));6if (result.success) {7  console.log(result.data.price + 1);8} else {9  console.log(result.error.message);10}

Line 5 checks the cake. The result has success: true with the checked data, or false with an error. Line 6 tests it, so line 7 may read result.data and line 9 may read result.error. The price is text, so line 9 prints the stand-in's message, value.price should be a number. The real Zod words its messages differently, and lists every field that failed. Reading data without testing success first is an error:

1import * as z from "./mini-zod";2 3const Product = z.object({ name: z.string(), price: z.number() });4 5const result = Product.safeParse(JSON.parse('{ "name": "Tea", "price": 3 }'));6console.log(result.data.price + 1);

Line 6 reads result.data straight away. TypeScript marks it, on purpose: Property 'data' does not exist on a result that might be the failed kind, which has only error. This kind of type, where one property says which shape you have, is a discriminated union.

The table below compares a hand-written check with a schema library. Read each row as a question, then each answer.

A menu loaded from the server

A real page loads a whole menu, checks the reply's status, checks every item, and shows a message when anything is wrong. Here it is with hand-written checks; with Zod, parseMenu would be z.array(Product).parse:

1type Product = { name: string; price: number };2 3function parseProduct(data: unknown): Product {4  if (typeof data !== "object" || data === null) throw new Error("Expected an object");5  if (!("name" in data) || typeof data.name !== "string") throw new Error("Expected name to be text");6  if (!("price" in data) || typeof data.price !== "number") throw new Error("Expected price to be a number");7  return { name: data.name, price: data.price };8}9 10function parseMenu(data: unknown): Product[] {11  if (!Array.isArray(data)) throw new Error("Expected a list");12  return data.map(parseProduct);13}14 15async function loadMenu(): Promise<Product[]> {16  const response = await fetch("menu.json");17  if (!response.ok) throw new Error(`The server answered ${response.status}`);18  return parseMenu(await response.json());19}20 21loadMenu()22  .then((menu) => console.log(menu.map((item) => `${item.name} $${item.price}`).join(", ")))23  .catch((error) => console.log(`Menu unavailable: ${error.message}`));

Lines 3 to 8 are parseProduct from before. Lines 10 to 13 check a whole list: line 11 throws unless the data is a list, and line 12 runs parseProduct on every item with map. Line 15 says loadMenu gives back a promise of a product list (the Promises & async functions lesson covers typing promises). Line 17 stops when the server answers with an error status, like 404, because fetch doesn't throw for those. Line 18 checks the JSON before anything else sees it. The code prints Tea $3, Cake $4. If any item failed, line 23 would print Menu unavailable and the reason.

Every line after line 18 works with a checked Product[], with no any left. Now sort some one-line snippets by what TypeScript says about them:

Common mix-ups

A successful status doesn't mean the body has the shape you expect. Here the server answers 200, but one menu item uses title instead of name:

1type Product = { name: string; price: number };2 3async function showPrice() {4  const response = await fetch("old-menu.json");5  if (response.ok) {6    const menu: Product[] = await response.json();7    console.log(menu[1].name.toUpperCase());8  }9}10 11showPrice().catch((error) => console.log(`Crashed: ${error.message}`));

Line 5 checks response.ok, which only says the server answered with a success status. Line 6 says the body is a Product[], with no check. Line 7 reads the second item's name, which doesn't exist, and the code prints Crashed: Cannot read properties of undefined (reading 'toUpperCase'). TypeScript had no errors.

• "Writing : Product on the reply checks it." No. any goes into any type without a check. The annotation is a promise, like as.
• "fetchJson<Product>() is safer than : Product." No. A type argument that appears only in the result is the same promise, written in one place.
• "unknown makes the data safe." No. unknown makes you check. The checks are what make it safe.
• "response.ok means the body is what I expect." No. It only means a success status, like 200. The body can still have any shape.
• "Checking the object and its name is enough to call it a Product." No. Check every field the type lists, or a missing price gets through as undefined.
• "Zod checks the data when TypeScript checks my code." No. TypeScript only gets the type from the schema. The schema checks the data while the page runs, when the data exists.

Practice exercises

Each exercise is TypeScript. Press Edit & run on the starter code to try a fix: the errors update as you type, and the console shows what it prints. Try a guess first, then use the hints.

1async function loadOrder() {2  const response = await fetch("product.json");3  const order = await response.json();4}

1async function loadOrder() {2  const response = await fetch("product.json");3  const order = await response.json();4  //    ^?5}

const reply = '{ "name": "Tea", "price": 3 }';
const product: unknown = JSON.parse(reply);

if (typeof product === "object" && product !== null && "price" in product) {
  console.log(product.price * 2);
}

1const reply = '{ "name": "Tea", "price": 3 }';2const product: unknown = JSON.parse(reply);3 4if (typeof product === "object" && product !== null && "price" in product && typeof product.price === "number") {5  console.log(product.price * 2);6}

1const data: unknown = JSON.parse('{ "price": 4 }');2 3console.log(data.price * 2);

1const data: unknown = JSON.parse('{ "price": 4 }');2 3if (typeof data === "object" && data !== null && "price" in data && typeof data.price === "number") {4  console.log(data.price * 2);5} else {6  console.log("No price");7}

1type Product = { name: string; price: number };2 3function parseProduct(data: unknown): Product {4  if (typeof data !== "object" || data === null) throw new Error("Expected an object");5  if (!("name" in data) || typeof data.name !== "string") throw new Error("Expected name to be text");6  if (!("price" in data) || typeof data.price !== "number") throw new Error("Expected price to be a number");7  return { name: data.name, price: data.price };8}9 10try {11  const product = parseProduct(JSON.parse('{ "name": 7, "price": 3 }'));12  console.log(product.name);13} catch (error) {14  console.log(error instanceof Error ? error.message : "Something went wrong");15}

1type Product = { name: string; price: number };2 3function parseProduct(data: unknown): Product {4  if (typeof data !== "object" || data === null) throw new Error("Expected an object");5  if (!("name" in data) || typeof data.name !== "string") throw new Error("Expected name to be text");6  if (!("price" in data) || typeof data.price !== "number") throw new Error("Expected price to be a number");7  return { name: data.name, price: data.price };8}9 10try {11  const product = parseProduct(JSON.parse('{ "name": 7, "price": 3 }'));12  console.log(product.name);13} catch (error) {14  // Line 5 throws: the name is the number 7, not text.15  console.log(error instanceof Error ? error.message : "Something went wrong");16}

1type User = { name: string; age: number };2 3function parseUser(data: unknown): User {4  return data;5}6 7const user = parseUser(JSON.parse('{ "name": "Asha", "age": 30 }'));8console.log(`${user.name} is ${user.age}`);

1type User = { name: string; age: number };2 3function parseUser(data: unknown): User {4  if (typeof data !== "object" || data === null) throw new Error("Expected an object");5  if (!("name" in data) || typeof data.name !== "string") throw new Error("Expected name to be text");6  if (!("age" in data) || typeof data.age !== "number") throw new Error("Expected age to be a number");7  return { name: data.name, age: data.age };8}9 10const user = parseUser(JSON.parse('{ "name": "Asha", "age": 30 }'));11console.log(`${user.name} is ${user.age}`);

1import * as z from "./mini-zod";2 3const Product = z.object({ name: z.string(), price: z.number() });4 5const tea = Product.parse(JSON.parse('{ "name": "Tea", "price": 3, "inStock": true }'));6console.log(tea.inStock ? "In stock" : "Sold out");

1import * as z from "./mini-zod";2 3const Product = z.object({ name: z.string(), price: z.number(), inStock: z.boolean() });4 5const tea = Product.parse(JSON.parse('{ "name": "Tea", "price": 3, "inStock": true }'));6console.log(tea.inStock ? "In stock" : "Sold out");

Check your understanding

For each question, keep two moments apart: what TypeScript knows before the code runs, and what the data really is when it arrives. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• response.json() and JSON.parse give any, because nobody knows what arrives until it arrives.
• Writing : Product, as Product, or fetchJson<Product>() on the reply checks nothing. It's a promise you make.
• Give the reply the type unknown. TypeScript then makes you check it before you read anything.
• Put the checks in one function that takes unknown and gives back a real type, or throws a clear error.
• A schema library like Zod describes the shape once: .parse checks the data, and z.infer makes the type.

Coming next: Promises & async functions. It types the promises you have been awaiting here: Promise<T>, async return types, and Promise.all.