Understand TypeScript's type narrowing system — typeof, instanceof, in operator, discriminated unions, custom type predicates, and the never type for exhaustive checks. Learn to write safe code that TypeScript can reason about statically.
TypeScript's type narrowing is like a detective refining a list of suspects. You start with a wide type (string | number | null) — any of those could be true. Each check you write (if typeof x === 'string') eliminates some suspects, and inside that branch TypeScript narrows its understanding of the type to only what's still possible. By the time you reach a specific branch, TypeScript knows exactly what type is present and unlocks the appropriate properties and methods. The narrowing is purely static — it's TypeScript reading your conditions and updating its type model, with zero runtime cost.
TypeScript understands several JavaScript constructs and uses them to narrow types automatically:
function formatValue(value: string | number | null | undefined): string {
// typeof narrowing
if (typeof value === "string") {
return value.toUpperCase(); // value: string here
}
// Nullish check narrowing
if (value == null) {
return "N/A"; // value: null | undefined here
}
// At this point, TypeScript knows value must be number
return value.toFixed(2); // value: number here
}
// instanceof narrowing
function handleError(err: unknown): string {
if (err instanceof Error) {
return err.message; // err: Error
}
if (err instanceof TypeError) {
return err.stack ?? "No stack"; // err: TypeError (subtype of Error)
}
return String(err);
}The in operator narrows by checking for the presence of a property — particularly useful for discriminating between object shapes:
interface Circle { kind: "circle"; radius: number; }
interface Square { kind: "square"; side: number; }
interface Triangle { kind: "triangle"; base: number; height: number; }
type Shape = Circle | Square | Triangle;
// Using 'in' to check for unique properties
function describeShape(shape: Shape): string {
if ("radius" in shape) {
return `Circle with radius ${shape.radius}`; // shape: Circle
}
if ("side" in shape) {
return `Square with side ${shape.side}`; // shape: Square
}
return `Triangle ${shape.base} × ${shape.height}`; // shape: Triangle
}A discriminated union gives every member a shared literal property (the discriminant). TypeScript then narrows based on that property's value — the most ergonomic and exhaustive narrowing pattern:
type ApiResult<T> =
| { status: "loading" }
| { status: "success"; data: T }
| { status: "error"; message: string; code: number };
function renderUser(result: ApiResult<User>) {
switch (result.status) {
case "loading":
return <Spinner />;
case "success":
return <UserCard user={result.data} />; // result.data: User
case "error":
return <Error msg={result.message} />; // result.message: string
}
}When built-in constructs are not enough, you can teach TypeScript about narrowing by writing a function that returns a type predicate — a return type of the form arg is Type:
// Without a type predicate — TypeScript cannot use the result to narrow
function isString(value: unknown): boolean {
return typeof value === "string";
}
// After calling isString(x), TypeScript still thinks x is unknown
// With a type predicate — the caller's type is narrowed on true
function isString(value: unknown): value is string {
return typeof value === "string";
}
const x: unknown = "hello";
if (isString(x)) {
console.log(x.toUpperCase()); // x is narrowed to string — OK
}
// Real-world example — filtering an array to remove null/undefined
function isDefined<T>(value: T | null | undefined): value is T {
return value !== null && value !== undefined;
}
const maybeUsers: (User | null)[] = getUsers();
const users: User[] = maybeUsers.filter(isDefined); // Clean array of UserAfter narrowing all known members of a union, the remaining type should be never. You can exploit this to write exhaustive checks that fail at compile time when a new union member is added without updating the handler:
type Direction = "north" | "south" | "east" | "west";
function move(dir: Direction): string {
switch (dir) {
case "north": return "Moving north";
case "south": return "Moving south";
case "east": return "Moving east";
case "west": return "Moving west";
default:
// If we reach here, dir is 'never' — all cases handled
const exhaustiveCheck: never = dir;
throw new Error(`Unhandled direction: ${exhaustiveCheck}`);
}
}
// Now if you add "up" to Direction without updating the switch:
// TypeScript errors: Type '"up"' is not assignable to type 'never'
// This is a compile-time safety net — no tests requiredAssertion functions (TypeScript 3.7+) throw on falsy values and narrow the type afterward — useful for writing asserts that double as type narrowing:
function assertIsString(val: unknown): asserts val is string {
if (typeof val !== "string") {
throw new TypeError(`Expected string, got ${typeof val}`);
}
}
const raw: unknown = getConfigValue();
assertIsString(raw);
// After this line, TypeScript treats raw as string
console.log(raw.toUpperCase()); // OKMany developers think type guards add runtime overhead — they are ordinary JavaScript (typeof, instanceof, property checks). TypeScript only reads them during compilation to update its type model. The runtime cost is identical to any conditional check you'd write in plain JavaScript.
Many developers think you need type predicates for every custom check — built-in constructs (typeof, instanceof, in, truthiness, equality) narrow automatically. Type predicates are only needed when TypeScript cannot infer the narrowing from your function's return value.
Many developers use as Type casts instead of narrowing — a cast silences the error but doesn't actually verify the type at runtime. A type guard actually checks the type and narrows it. In production code, prefer narrowing over casting.
Many developers think discriminated unions require complex setup — any shared literal property works as the discriminant. The pattern is as simple as adding a kind or type or status string literal to each member.
Many developers think the never exhaustive check is just defensive coding — it's a compile-time guarantee. Add a new union member without updating the switch and TypeScript immediately errors at the default branch. No test is needed to catch the regression.
Many developers think filtering with Array.filter removes null types automatically — filter's return type is still (T | null)[] in TypeScript. You need a type predicate isDefined<T>(x: T | null | undefined): x is T to get TypeScript to infer the filtered array as T[].
API error handling: switch on result.status with a discriminated union (loading | success | error) is the standard pattern in React data fetching — each case narrows to the exact shape with exactly the right properties available.
Filtering arrays of nullable values: isDefined type predicate used with .filter() is ubiquitous in codebases that fetch data from APIs that can return null for missing items — it removes nulls while keeping TypeScript happy.
Redux reducers: every switch case on action.type is a discriminated union — TypeScript narrows action to the specific action type in each case, giving you typed payload without any casting.
Plugin systems: checking for the presence of specific methods using the in operator allows a plugin host to safely call optional plugin capabilities without runtime errors.
Form validation: assertion functions (asserts value is string) are used in validation utilities that throw on invalid input — callers don't need additional if-checks after calling the validator.
Event handling: instanceof narrowing on Event objects (e instanceof MouseEvent, e instanceof KeyboardEvent) unlocks the specific properties (e.clientX, e.key) that TypeScript knows are only available on the narrowed type.
What are type guards and how do you create custom ones?
Reading answers is not the same as knowing them. Practice saying them out loud with AI feedback — that's what builds real interview confidence.