Document Limitations with Comments
You'll learn when and how to clearly document type system boundaries with explanatory comments rather than forcing unsafe workarounds.
The Core Idea
TypeScript is powerful, but it has limits. Sometimes the type system simply cannot express what your runtime code does—recursive types hit depth limits, complex inference fails, or the relationship between values is too dynamic. When you hit these walls, the healthiest approach isn't to twist your types into unreadable pretzels or scatter any everywhere. Instead, add a clear comment explaining the constraint and why your current approach is the best available option.
Think of it like a construction sign: "Bridge weight limit: 10 tons." You're not hiding a structural problem—you're clearly marking a known boundary so everyone understands the situation.
When Comments Beat Over-Engineering
You've hit a legitimate type limit when:
- Deeply nested recursive types cause "Type instantiation is excessively deep"
- Type inference gives up and you need a strategic assertion
- Runtime behavior depends on external data that types can't capture
- The "perfect" type would require HKT simulation or unreadable complexity
In these cases, a well-placed comment is far more valuable than:
- 50 lines of incomprehensible type-level code
- Sprinkling
anywithout explanation - Nested type assertions that lie to the compiler
- Trying to bend TypeScript into something it isn't
The Right Way to Document Type Boundaries
interface DeepNestedConfig {
// TypeScript's recursive type depth limit prevents fully typing
// this at compile time. Runtime validation in parseConfig() ensures safety.
sections: unknown;
}
function processApiResponse(data: unknown) {
// API contract documented in api-spec.md
// Shape validated by Zod schema before this point
const typed = data as { id: string; items: unknown[] };
return typed;
}
These comments do three things:
- Acknowledge the limitation (recursive depth, unknown shape)
- Explain where safety comes from (runtime validation, external docs)
- Point to the alternative guarantee (Zod schema, spec document)
Key Takeaway: When TypeScript's type system reaches its limits, a clear comment explaining the constraint and your safety strategy is better than forcing unreadable type gymnastics or hiding gaps with suppressions.