TypeScript narrowing: unions, unknown and any

What it is

A union type such as string | number says a value is one of several types. Narrowing is the compiler's control-flow analysis: after a check, the type inside that branch is reduced. The handbook lists the checks it understands: typeof x === "string", truthiness, equality against a literal, "kind" in x, x instanceof Date, assignments, and user-defined type predicates (function isFish(p: Pet): p is Fish). A discriminated union gives each member a literal property (kind: "circle" | "square"); a switch on it narrows to one member, and once every case is handled the remaining type is never, which is how exhaustiveness checks work. any turns checking off for that value and everything derived from it. unknown also accepts every value, but it is "not legal to do anything with an unknown value" until it has been narrowed.

Why it matters

any spreads silently: one any return type makes every downstream expression unchecked with no warning. unknown at the edges (parsed JSON, message payloads, caught errors) forces the check to happen where the data enters. Discriminated unions turn "forgot to handle the new variant" into a compile error instead of a runtime surprise.

How to apply

• Enable strict, which includes noImplicitAny; treat each remaining explicit any as a documented exception with a comment saying why.
• Type boundary data as unknown and narrow with a validator or explicit checks; wrap JSON.parse, which returns any, in a function that returns unknown.
• Model states as a discriminated union ({ status: "loading" } | { status: "ok"; data: T } | { status: "error"; error: Error }) rather than optional fields that can contradict each other.
• End every switch over a union with a default branch that assigns the value to a never-typed variable; adding a variant then fails to compile at every unhandled switch.
• Write a type predicate only when the runtime check guarantees the type; a wrong predicate is an any in disguise.
• In catch (e), treat e as unknown and check e instanceof Error before reading .message.

Pitfalls

Narrowing does not survive into callbacks or across function calls: if (x.a) list.forEach(() => x.a.b) does not compile because the callback may run later, after x.a changed. Narrowing of a property is reset by an assignment to it, but not by a function call that might mutate the object: the compiler assumes the object unchanged, a deliberate trade-off in its control-flow analysis. A type assertion (as Foo) is not narrowing; it overrides the checker and should be as rare as any.