Why narrowing matters
Most values in a real program arrive with a type that is wider than what you need. A form field is string | undefined, an API response is a union of success and error shapes, and an event handler receives whatever the browser decided to send. Narrowing is how TypeScript follows your checks through the code and shrinks those wide types down to the one you are actually holding.
The good news is that you rarely have to ask for it. The compiler performs control-flow analysis on every function: each if, return, throw and assignment teaches it something about the variables in scope. The trick is learning which checks it understands, so you can write code that reads naturally and still type-checks without casts.
Every
asin a codebase is a place where a human promised the compiler something it couldn't verify. Narrowing lets you keep fewer promises.
typeof and truthiness
The simplest guards are the ones JavaScript already has. typeof checks narrow primitives, and a truthiness check removes null and undefined (along with 0 and the empty string, which is the classic trap).
function formatPrice(value: number | string | undefined) { if (value === undefined) return "—"; if (typeof value === "string") { // value: string return value.trim(); } // value: number return value.toFixed(2);}Notice that the early return does as much work as the if itself. After the first line, undefined is gone from the type for the rest of the function. Early returns keep the happy path flat and give the compiler clear boundaries to reason about.
Discriminated unions
When you control the shape of your data, the most robust pattern is a discriminated union: every member carries a literal field, usually called type, kind or status, that tells them apart. A switch on that field narrows each branch to exactly one member.
type Result<T> = | { status: "ok"; data: T } | { status: "error"; error: string; retryable: boolean };function render(result: Result<User[]>) { switch (result.status) { case "ok": return result.data.map((user) => user.name).join(", "); case "error": return result.retryable ? "Try again" : result.error; }}This scales well because adding a new member is a compile-time event. Every switch that handles the union now has a branch it does not cover, and with an exhaustiveness check the compiler will point at each one.
Exhaustiveness checks
Assigning the narrowed value to never in the default branch turns a forgotten case into a type error rather than a runtime surprise:
function assertNever(value: never): never { throw new Error(`Unhandled case: ${JSON.stringify(value)}`);}switch (result.status) { case "ok": /* … */ break; case "error": /* … */ break; default: assertNever(result);}Custom type guards
Sometimes the check you need is too involved for the compiler to infer, such as validating data from JSON.parse. A function with a value is T return type tells TypeScript what a true result means.
type User = { id: string; name: string };function isUser(value: unknown): value is User { return ( typeof value === "object" && value !== null && "id" in value && typeof value.id === "string" && "name" in value && typeof value.name === "string" );}const users = JSON.parse(body).filter(isUser); // User[]Since TypeScript 5.5, simple arrow functions passed to filter infer their own predicate, so values.filter((v) => v !== null) already returns a non-null array. Reach for an explicit guard when the logic is reused or more than a line long.
Takeaways
- Return early: each exit removes a case from the rest of the function.
- Model states as discriminated unions instead of optional fields.
- Add an exhaustiveness check where new cases are likely.
- Write type guards for data you don't control, and keep them next to the type.
None of this requires exotic type-level programming. It's ordinary JavaScript, written so that both your colleagues and the compiler can follow it.


