typescript-advanced-type-guards
/typescript-advanced-type-guards
Runtime type guards, narrowing, and exhaustiveness checking for TypeScript — typeof/instanceof/in guards, custom and generic type predicates (value is T), discriminated union narrowing, assertion functions (asserts value is T), branded/nominal types validated at runtime, and exhaustive switch statements with a never guard. Use when replacing an unsafe `as` assertion with a real runtime check, fixing "Object is possibly undefined", modeling impossible states out of existence, writing an `is*` predicate, or making a switch over a union fail to compile when a case is missing.
- Author
- pantheon-org ↗
- Repository
- tekhne ↗
- Licence
- MIT
- Last repository change
- 21.10.2026
Assessment and security
- Files in this package
- 21
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Runtime type guards, narrowing, and exhaustiveness checking for TypeScript — typeof/instanceof/in guards, custom and generic type predicates (value is T), discriminated union narrowing, assertion functions (asserts value is T), branded/nominal types validated at runtime, and exhaustive switch statements with a never guard. Use when replacing an unsafe `as` assertion with a real runtime check, fixing "Object is possibly undefined", modeling impossible states out of existence, writing an `is*` predicate, or making a switch over a union fail to compile when a case is missing.
Triggers from the description
Original author description
Runtime type guards, narrowing, and exhaustiveness checking for TypeScript — typeof/instanceof/in guards, custom and generic type predicates (value is T), discriminated union narrowing, assertion functions (asserts value is T), branded/nominal types validated at runtime, and exhaustive switch statements with a never guard. Use when replacing an unsafe `as` assertion with a real runtime check, fixing "Object is possibly undefined", modeling impossible states out of existence, writing an `is*` predicate, or making a switch over a union fail to compile when a case is missing.
How it works
- Mindset
- When to Apply
- Use When
- Scope
- When NOT to Use
- Quick Commands
- Quick Fixes
- Anti-Patterns
- References
SKILL.md preview
---
name: typescript-advanced-type-guards
description: Runtime type guards, narrowing, and exhaustiveness checking for TypeScript — typeof/instanceof/in guards, custom and generic type predicates (value is T), discriminated union narrowing, assertion functions (asserts value is T), branded/nominal types validated at runtime, and exhaustive switch statements with a never guard. Use when replacing an unsafe `as` assertion with a real runtime check, fixing "Object is possibly undefined", modeling impossible states out of existence, writing an `is*` predicate, or making a switch over a union fail to compile when a case is missing.
allowed-tools: Read, Write, Edit, Bash
---
# 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?"
## Scope
### In Scope
- `typeof`, `instanceof`, `in`, truthiness, and equality narrowing.
- Custom and generic type predicate functions (`value is T`).
- Discriminated union narrowing and exhaustiveness checking with `never`.
- Assertion functions (`asserts condition`, `asserts value is T`).
- Branded/nominal types validated by a runtime type guard.
### Out of Scope
- The type-system mechanics behind a union or conditional type itself — see the sibling `typescript-type-system` skill.
- Zod-based schema validation as a library choice — see `runtime-validation.md` in the sibling `typescript-practices` skill; this skill covers hand-written predicates and assertion functions.
- General design patterns (builder, state machine, event emitter) that *use* guards — see the sibling `typescript-design-patterns` skill.
## When NOT to Use
Do not use this skill for compiler configuration (tsconfig, strict-mode flags — see `typescript-compiler-config`) or for utility-type mechanics like `Pick`/`Omit`/`ReturnType` (see `typescript-utility-types`). Do not use it as a substitute for actually running `tsc --noEmit` — the reference files teach the pattern, but the compiler is the source of truth on whether a guard actually narrows.
## Quick Commands
### Type Check
```bash
npx tsc --noEmit
```
### Find Unsafe Patterns
```bash
rg -n "\\bany\\b|@ts-ignore| as " src
```
## Quick Fixes
### "Object is possibly 'undefined'"
```typescript
// BAD — non-null assertion hides the real problem
function getHost(config: Config): string {
return config.host!.toUpperCase();
}
// GOOD — guard before access
function getHost(config: Config): string {
if (config.host === undefined) throw new Error("host is required");
return config.host.toUpperCase();
}
```
### "Type X is not assignable to type Y"
```typescript
// BAD — forces an incompatible assignment
const id = getValue() as string;
// GOOD — narrow first, then assign
const raw = getValue();
if (typeof raw !== "string") throw new TypeError("Expected string");
const id = raw; // TypeScript now knows id: string
```
## Anti-Patterns
### NEVER use `any` as a default escape hatch
**WHY:** `any` disables type checking and hides the design bug the error was pointing at.
**BAD**:
```typescript
function process(data: any) {
return data.value;
}
```
**GOOD**:
```typescript
function process<T extends { value: unknown }>(data: T) {
return data.value;
}
```
### NEVER silence type errors with unchecked assertions
**WHY:** an `as` assertion bypasses compiler safety without a matching runtime guarantee.
**BAD**:
```typescript
const id = input as string;
```
**GOOD**:
```typescript
if (typeof input !== "string") throw new TypeError("Expected string");
const id = input;
```
### NEVER use numeric `enum` for a discriminated union tag
**WHY:** numeric enums generate a reverse mapping at runtime (`Direction[0] === "Up"`), inflate bundle size, and let any number be assigned where the enum type is expected — none of which a string-literal union has.
**BAD**:
```typescript
enum Status { Pending, Active, Closed }
function handle(status: Status) { /* Status.Pending accepts any number */ }
```
**GOOD**:
```typescript
type Status = "pending" | "active" | "closed";
function handle(status: Status) { /* only the three literal strings are valid */ }
```
### NEVER let a discriminant literal widen
**WHY:** `let` and object-literal inference widen `"success"` to `string`, which breaks exhaustive narrowing on the union's discriminant even though the runtime value never changes.
**BAD**:
```typescript
let kind = "success"; // inferred as string, not "success"
const result = { kind, data: 42 }; // result.kind: string — narrowing fails
```
**GOOD**:
```typescript
const kind = "success" as const;
const result = { kind, data: 42 } as const; // result.kind: "success"
```
### NEVER leave a switch over a union without an exhaustiveness check
**WHY:** without a `never`-typed default branch, adding a new union variant compiles silently and the new case is unhandled at runtime.
**BAD**:
```typescript
function area(shape: Shape): number {
switch (shape.kind) {
case "circle": return Math.PI * shape.radius ** 2;
case "square": return shape.size ** 2;
// no default — adding "triangle" to Shape compiles without warning
}
}
```
**GOOD**:
```typescript
function area(shape: Shape): number {
switch (shape.kind) {
case "circle": return Math.PI * shape.radius ** 2;
case "square": return shape.size ** 2;
default:
const _exhaustive: never = shape;
throw new Error(`Unhandled shape: ${_exhaustive}`);
}
}
```
## References
| File | Covers |
| --- | --- |
| `references/basic-guards.md` | `typeof`, `instanceof`, `in`, truthiness, and equality narrowing |
| `references/generic-guards.md` | Reusable generic type predicates (`isArrayOf`, `hasProperty`, `isInstance`) |
| `references/discriminated-unions.md` | Tagged unions, multiple discriminants, state-machine narrowing |
| `references/exhaustiveness-checking.md` | The `never` exhaustiveness pattern across switch, if/else, and pattern matching |
| `references/assertion-functions.md` | `asserts condition` and `asserts value is T` functions |
| `references/branded-types-guards.md` | Nominal types validated by a runtime predicate, multi-level brands, unwrap utilities |
- [TypeScript Handbook: Narrowing](https://www.typescriptlang.org/docs/handbook/2/narrowing.html)
- [TypeScript Handbook: Assertion Functions](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions)
Files in this package (21)
- SKILL.md 8 KB
- .audits/2026-09-23/Analysis.md 1 KB
- .audits/2026-09-23/Remediation.md 1 KB
- .audits/2026-09-23/audit.json 1 KB
- evals/instructions.json 2 KB
- evals/summary.json 1 KB
- evals/scenario-0/capability.txt 1 KB
- evals/scenario-0/criteria.json 1 KB
- evals/scenario-0/task.md 1 KB
- evals/scenario-1/capability.txt 1 KB
- evals/scenario-1/criteria.json 1 KB
- evals/scenario-1/task.md 1 KB
- evals/scenario-2/capability.txt 1 KB
- evals/scenario-2/criteria.json 1 KB
- evals/scenario-2/task.md 1 KB
- references/assertion-functions.md 3 KB
- references/basic-guards.md 2 KB
- references/branded-types-guards.md 6 KB
- references/discriminated-unions.md 5 KB
- references/exhaustiveness-checking.md 6 KB
- references/generic-guards.md 3 KB
Versions
The database has no other skills named typescript-advanced-type-guards.
Database snapshot: 13.11.2026 · package version eaf1e4aea886 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90typescript-narrowing
Narrow union types safely with guards, discriminated unions, and exhaustiveness checks. Use when working with values that could be several types, or when the compiler will not let you access a property you know is there. - 100typescript-strict
Use this skill when writing, reviewing, or fixing TypeScript where type safety matters — type errors, narrowing, unsafe casts, or tightening compiler strictness. Triggers: user mentions "TypeScript", "type error", "tsc", "strict", "type safety", "narrowing", "any", "unknown",… - 90typescript-type-system
Use when working with TypeScript's type system including strict mode, advanced types, generics, type guards, and compiler configuration. - 100typescript-narrowing-expert
Use when designing discriminated unions, debugging control-flow analysis, choosing satisfies vs as, building branded types, writing user-defined type guards, or composing conditional types and template literal types. Triggers: "Type X is not assignable to type Y" after a type… - 91typescript-best-practices
TypeScript idioms and type-safety patterns: discriminated unions, branded types, narrowing, boundary validation. Use when reading, writing, or reviewing any .ts or .tsx file. - 95typescript-advanced-type-system
Advanced TypeScript type-system mechanics — union and intersection types, conditional types with `infer`, mapped types, template literal types, generics and their constraints, index signatures, type assertions, and extracting types from other types (return types, array elements,…