Measuring Assertion Debt in Your Codebase
You'll learn how to quantify and track type assertions in your codebase so you can prioritize refactoring efforts and reduce technical debt.
Understanding Assertion Debt
Just like technical debt, assertion debt is the accumulated cost of type assertions (as, !, double assertions) that weaken type safety. Each assertion is a small lie to the compiler—a spot where you've overridden TypeScript's checks. Over time, these add up, creating blind spots in your type coverage.
Think of assertions like duct tape repairs in a house. One or two are manageable, but if you have dozens, you need an inventory to know which to fix first.
Tracking Assertions with grep
The simplest measurement tool is command-line search:
# Count 'as' assertions
grep -r " as " src/ --include="*.ts" --include="*.tsx" | wc -l
# Count non-null assertions
grep -r "!" src/ --include="*.ts" --include="*.tsx" | grep -v "!=" | wc -l
# Find double assertions
grep -r " as unknown as " src/ --include="*.ts"
This gives you a baseline number. Track it over time to see if assertion debt is growing or shrinking.
Measuring with ESLint Rules
ESLint provides more sophisticated tracking through the @typescript-eslint plugin:
@typescript-eslint/consistent-type-assertions- flags or restricts assertion syntax@typescript-eslint/no-non-null-assertion- reports all!operators- Custom rules to count
as unknown aspatterns
Run ESLint with formatting that counts issues, then track the number in your CI pipeline.
Manual Inspection for Prioritization
Numbers alone don't tell you which assertions are dangerous. Manual review helps you categorize:
- Safe: After exhaustive validation (acceptable)
- Low-risk: DOM queries where element existence is guaranteed
- Medium-risk: Third-party library types that could change
- High-risk: Business logic assertions hiding real type errors
Focus refactoring efforts on high-risk assertions first.
Key Takeaway: Track assertion usage through grep counts, ESLint metrics, and manual audits to identify technical debt hotspots and measure progress as you refactor toward stronger type safety.