Narrowing in Depth

A function checks that a value is a valid photo, returns true, and the caller still gets an error for using it as a photo. The check ran. It proved the thing. TypeScript has no idea, because a function returning boolean tells the checker nothing about what that boolean means.

The foundations course covered narrowing with built-in checks. This lesson is about extending it: teaching the checker what your own functions prove, keeping a switch exhaustive as the code changes, and recognising the places narrowing silently stops applying.

What the checker already follows

A quick recap, because everything here builds on it:

typeof value === "string"          // primitives
value === null   value == null     // absence
Array.isArray(value)
value instanceof Error             // classes
"size" in photo                    // property presence
photo.kind === "raw"               // a literal discriminant

Control flow narrows too, which is worth stating explicitly:

function process(photo: Photo | null): string {
  if (photo === null) {
    throw new Error("no photo");
  }

  return photo.name;        // Photo - the throw removed the other case
}

A throw or a return in one branch eliminates that possibility from everything after it. That is why early returns read so well here: each one permanently removes a case.

Assignment narrows as well:

let value: string | number = getValue();
value = "text";
value.toUpperCase();        // string, from the assignment

Teaching the checker what you proved

Bad — a check returning boolean.

function isPhoto(value: unknown): boolean {
  return typeof value === "object" && value !== null && "name" in value;
}

if (isPhoto(input)) {
  input.name;
  //    ~~~~ 'input' is of type 'unknown'
}

Good — a check that says what it proves.

function isPhoto(value: unknown): value is Photo {
  return typeof value === "object" && value !== null && "name" in value;
}

if (isPhoto(input)) {
  input.name;               // Photo
}

value is Photo is a type predicate. The function still returns a boolean at runtime; the annotation tells the checker what true means.

The first version forces the caller to assert afterwards — (input as Photo).name — which discards the check they just performed and would compile identically if the check were removed. So the assertion, not the check, is what the type system is relying on.

The important caveat: a predicate is a promise the checker does not verify. Write one whose body does not actually establish the type and you have a hole with a confident-looking signature. Keep the body a direct check of exactly what the predicate claims.

Narrowing both branches

value is T narrows the true branch only. In the false branch the type is unchanged, which is wrong when the union has two members:

function isString(value: string | number): value is string { ... }

if (isString(value)) {
  value;      // string
} else {
  value;      // still string | number
}

asserts and the newer is behaviour fix this. The current tool is TypeIs-style narrowing, available by writing the predicate so both sides follow — in practice, for a union you own, prefer a discriminant check inline, and reserve predicates for validating unknown.

The other form is an assertion function:

asserts value is Photo means "if this returns, the value is a Photo". No if needed at the call site, and the narrowing applies to everything after.

One constraint catches people: an assertion function must be called on a value with an explicit type annotation, and it cannot be an arrow function assigned to an inferred const. Declare it with function.

Exhaustiveness that survives change

The foundations course showed a switch over a discriminated union. The version that keeps working as the union grows:

When every case is handled, upload in the default branch is never and the call compiles. Add a fourth state and the remaining member is not assignable to never, so you get an error naming exactly what you forgot.

assertNever written once and imported everywhere is the practical form. It costs one file and turns "find every switch on this union" into a compile error listing them.

The same technique works for if/else if chains and for mapped lookups:

Record<Union, T> requires every member as a key. That is often tidier than a switch when each case maps to a value rather than to logic.

Where narrowing stops

Four places it silently does not apply.

The first one, concretely:

Capturing it in a const fixes it, because a const cannot change:

And the third one, which is the easiest to miss because it looks like ordinary sequential code:

Destructuring first removes the doubt:

The general fix is the same each time: capture what you narrowed into a const.

Narrowing unknown safely

The pattern for data you did not create:

Three steps: rule out non-objects and null, treat it as a record of unknowns, then check each field. The single as is contained and does not claim anything about the fields — every one is checked individually.

This is honest and it is tedious, and for anything with more than a few fields a validation library does it from a declaration. That is the next lesson but one; the manual version is worth knowing because it shows what the library is doing.

A cheat sheet to keep

Where to go next

You can now teach the checker what your own checks prove, keep a union exhaustive as it changes, and recognise the four places narrowing stops applying. The assertNever helper is the single highest-value thing here — it converts a class of "we forgot to update that switch" bug into a build failure.

Next is unknown, any, and never, the three types people misuse most. Two of them have appeared repeatedly in this course already; the lesson explains what each actually means and why one of them switches off checking far beyond the line it appears on.

Before you move on, write a type predicate for a shape you receive from outside, and use it. Then delete the is from the signature and watch every call site break. That difference is the value of the annotation, made visible.