Code Review Red Flags with Assertions
You'll learn: How to spot patterns in code reviews where type assertions signal deeper problems that should be fixed at the source instead.
The Core Idea
Type assertions are like declaring "trust me, I know better than TypeScript." While sometimes necessary, they often paper over design flaws, missing information, or incorrect assumptions. During code review, certain assertion patterns should raise immediate questions: Why does the developer need to override the type system here? Could we restructure the code so the types flow naturally instead?
Think of assertions like duct tape. Sometimes it's the right tool for a quick fix, but if you see duct tape holding together critical infrastructure, you know there's a deeper problem that needs proper repair.
Common Red Flags
Multiple Assertions in Sequence
When you see assertions chained together or appearing multiple times in a short code section, it suggests the types are fundamentally misaligned with the actual data flow.
Assertions at Module Boundaries
If every function that receives data from another module immediately asserts its type, the module contract is poorly defined. The types should communicate these guarantees directly.
Double Assertions as a Pattern
The value as unknown as TargetType pattern appearing repeatedly means types are consistently incompatible—a sign that either your type definitions or your runtime data structures need rethinking.
Assertions Without Justification Comments
An assertion without an explanation is a red flag. If it's truly necessary, the reviewer (and future maintainers) deserve to know why the type system couldn't express this relationship.
Asserting Away Discriminated Union Information
When code asserts a union type to one variant without checking the discriminant property, it's bypassing the type safety the discriminated union was designed to provide.
Non-Null Assertions on Optional Properties
Using property! without prior validation means assuming data will always be present—an assumption that may break at runtime.
Assertions in Error Handling Code
If error handling blocks contain assertions, it suggests the error types aren't properly typed, or worse, that the developer is making assumptions about error shapes that might not hold.
Assertions to Satisfy Tests
When test code is full of assertions just to make TypeScript happy, it often means the test setup isn't properly typed or the code under test has type issues being hidden.
Better Questions to Ask
When you spot assertions in code review:
- "Can we add runtime validation here instead?"
- "Should this function's return type be narrower?"
- "Could we use a type predicate or guard function?"
- "Is this third-party library missing type definitions we could add?"
- "Would restructuring the data flow eliminate this assertion?"
Key Takeaway: Assertions in code review should trigger investigation, not approval. Each one represents either a legitimate type system limitation (rare and worth documenting) or a design issue that assertions are hiding (common and worth fixing).