typescript-advanced-type-guards

TypeScript Type Guards

Runtime type guards and narrowing: the compile-time type system backed by an actual runtime check, so a type guarantee is real rather than asserted.

Mindset

A type guard is a promise the compiler will hold you to only if the runtime check underneath it is honest. Never reach for any or an unchecked as assertion as a shortcut past a type error — both disable the exact safety net a guard exists to provide, and the error they suppress almost always points at a real design gap. Prefer narrowing a value before use over asserting its type after the fact: if (typeof x !== "string") throw ... gives the compiler a real fact to reason from; x as string gives it nothing but your word. Verify a narrowing actually narrows by re-running tsc --noEmit after the change — a guard that looks correct can still fail to narrow if its predicate doesn't match the shape TypeScript expects. Every union that models a real set of states deserves an exhaustive switch with a never-typed default branch, so adding a new state without updating every handler is a compile error, not a silent gap.

When to Apply

Use this skill when:

• Replacing an unsafe as assertion with a runtime check that narrows for real
• Writing a custom type predicate (function is*(x): x is T)
• Modeling impossible field combinations out of existence with a discriminated union
• Adding an assertion function (asserts value is T) to validate and narrow in one call
• Creating branded/nominal types with a validating factory function
• Adding exhaustiveness checking to a switch over a union so new variants can't be silently unhandled
• Fixing "Object is possibly 'undefined'" without reaching for a non-null assertion (!)

Use When

• "How do I fix this TypeScript compile error without an as assertion?"
• "How do I check the shape of an unknown value at runtime?"
• "How do I make my switch statement error if I add a new case and forget to handle it?"
• "How do I stop two IDs of the same primitive type from being mixed up?"