TypeScript type-guard narrowing diagnostic guide

You write a TypeScript function that accepts string | NumberInput and add a type guard expecting the narrowed type to carry through the rest of the block. Instead, the compiler treats the variable as the original union, or emits an error when you access a narrowed property. This guide explains why the narrowing stalls, how to verify it with the TypeScript compiler, and which fixes apply to each cause.

Recognizable condition

A type guard—whether a user-defined predicate, the in operator, or instanceof—narrows a union type within its controlling block. When the narrowed type disappears after the block ends, or the compiler reports an unexpected type error inside the block, the condition is recognizable. The narrowing scope is limited to the immediate control-flow block; exiting and re-entering the same scope requires re-applying the guard or an explicit type assertion.

Cause and diagnostic table

Ordered checks

1. Run tsc --strict --noEmit from the project root. Confirm zero type errors in guarded blocks; the compiler log should reflect successful narrowing. This command requires a tsconfig.json and can be executed in any terminal with Node.js and TypeScript installed.
2. Inspect the narrowed variable’s type in the compiler output (search for the narrowed type in the emitted diagnostics).
3. If the guard uses a user-defined type predicate, verify the predicate syntax is x is T and that T is a valid type reference.
4. For in or instanceof guards, confirm the right-hand side is a valid property name or constructor, respectively.
5. Execute the compiled JavaScript and log the narrowed variable’s type at runtime to validate that compile-time narrowing aligns with runtime behavior.

Concrete supported example

interface Square { kind: 'square'; side: number }
interface Circle { kind: 'circle'; radius: number }
type Shape = Square | Circle

function area(s: Shape): number {
  if ('side' in s) {               // built-in in operator type guard
    return s.side ** 2
  }
  return Math.PI * s.radius ** 2   // narrowed to Circle
}

The illustration above follows TypeScript 4.4 type-guard semantics. The compiler’s --noEmit output should show the narrowed type within the if block; verify this with tsc --strict --noEmit in your project.

Fixes tied to findings

Scope-limited narrowing: If the narrowed type vanishes after the block, restructure the logic so the guard remains in scope, or apply an explicit type assertion (as T) after the guard when the type is needed beyond the block.

Overlapping union members: Refine the union to remove redundancy, or add a discriminant property that uniquely identifies each member. Running tsc --strict --noEmit after the change will confirm the narrowing is now unambiguous.

Pre-4.4 flow analysis limitations: Upgrade to TypeScript 4.4 or later. The refined flow analysis supports nested block narrowing, async type guards, and more complex predicates while preserving soundness across declare module and ambient contexts.

Predicate syntax errors: Ensure the type predicate follows the x is T pattern exactly. A missing space or incorrect type reference will cause the guard to be ignored.

Escalation criteria

If compiler output shows Type 'property' does not exist on type ... after a guard, and refining the union or upgrading TypeScript does not resolve it, open a reproducible minimal example on the TypeScript GitHub repository. Include the tsc --strict --noEmit log, the TypeScript version, and the exact guard syntax.