Typing Browser Storage and APIs

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

localStorage

A small key-value store in the browser that keeps text until it is cleared.

sessionStorage

Like localStorage but for one tab, gone when the tab closes.

JSON.stringify / JSON.parse

Turn a value into text, and text back into a value.

Typed wrapper

A small object that hides raw storage behind typed get and set functions.

URLSearchParams

A helper for reading and building the ?name=value&... part of a URL.

structuredClone

Makes a deep, independent copy of a value.

DataCloneError

The error structuredClone throws for things it can't copy, like functions.

Store

An object that holds state and tells listeners when it changes.

Unsubscribe

The function a subscribe call returns, which stops the listener.

1. 1

   Break the link between key and value

   In the first example add storage.set("visits", "three");. Predict the error: the value must be number because the key is "visits". Then try storage.set("colour", "red");.

2. 2

   Add a key

   Add fontSize: number to StorageShape. TypeScript immediately complains that guards is missing fontSize: the mapped type forces a guard for every key. Add it.

3. 3

   Count clicks only

   In the store example add a third button reset that sets { count: 0, clicks: 0 }. Then remove clicks from the type: every place that used it becomes an error.

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

1. 1

   The problem this solves: the browser keeps only text, and what you read back may be missing, old or edited by someone else, so trusting it blindly causes crashes. Typed wrappers and checks make sure only data of the right shape gets into your code. localStorage (kept until cleared) and sessionStorage (kept until the tab closes) store strings only, under string keys. The type is Storage: getItem(key): string | null, setItem(key, value: string): void, removeItem, clear, and a length. Reading a key that doesn't exist gives null, not undefined. Storing a number turns it into text ("3"); storing an object gives the useless "[object Object]". So you convert yourself with JSON.stringify on the way in and JSON.parse on the way out.

2. 2

   JSON.parse(text) returns **any** (Topic 13.4), and stored data is exactly the kind of untrusted input from that topic: an older version of your app wrote a different shape, another tab changed it, or a user edited it in the developer tools. So assign the result to unknown, check it, and fall back to a default when it is wrong. JSON.parse also throws on text that isn't JSON, so wrap it in try/catch.

3. 3

   A typed wrapper makes this safe in one place. Describe your storage as one object type, { theme: "light" | "dark"; visits: number }, and write get<K extends keyof Shape>(key: K): Shape[K] | undefined and set<K extends keyof Shape>(key: K, value: Shape[K]). The generic K links the key to its value type: set("visits", "three") is now a compile error, and get("theme") is known to return the theme union or undefined (Topic 8.3 explains the indexed access Shape[K]). The wrapper checks on read with one guard per key, so the types stay honest.

4. 4

   **URLSearchParams** reads and builds the query part of a URL (?q=ts&page=2). get(name) returns string | null (not a number, not undefined), getAll(name) returns string[], has, set, append, delete, and toString(). Everything is text, so page needs Number(...) and a check for NaN. new URL("https://example.com/search?q=ts") gives a URL object whose searchParams is one of these.

5. 5

   **structuredClone(value)** makes a deep copy that is independent of the original: copied objects, arrays, Map, Set and Date all stay what they are (unlike the old JSON.parse(JSON.stringify(x)) trick, which turns a Date into a string and drops undefined). Its type is structuredClone<T>(value: T): T, so the copy has the same type. The catch: it throws a DataCloneError for things that can't be cloned, such as functions and DOM elements, and TypeScript does not warn you, because a type with a method is still a valid T. It also drops class prototypes: a cloned class instance becomes a plain object.

6. 6

   A typed store is a tiny object holding state with three methods: read it, change it, and tell listeners it changed. It is the heart of Zustand, Redux and similar libraries, and a generic createStore<S>(initial: S) types all of it from one S. subscribe(listener) returns a function that removes the listener (a cleanup function, the same idea as using in Topic 13.5). State updates take a function (prev: S) => S so you never mutate the old state. Pairing it with typed storage gives a store that survives a page reload.

7. 7

   A note about this course's playground: localStorage in the live examples is an in-memory stand-in that resets every time you press Run, because the preview is sandboxed. In a real page the data persists. Test persistence in your own browser's developer tools (Application tab).

• ↔

  A typed wrapper with guards costs code per key, and gives data you can trust. A schema library (Topic 13.4) shortens it. For throwaway data, a plain JSON.parse with a fallback may be enough.

• ↔

  A hand-written store is thirty lines and fully typed. A library adds devtools, middleware and React bindings; choose it when you need those.

• I can say what localStorage stores and what getItem returns.

• I can read stored JSON as unknown, validate it and fall back safely.

• I can write a generic typed get/set keyed by an object type.

• I can read and build query strings with URLSearchParams.

• I can explain what structuredClone copies and what makes it throw.

• I can write a small typed store with get, set and subscribe.