Question
Compiler‑driven exhaustiveness vs developer‑controlled narrowing for heterogeneous JSON payloads
Cig Finch
0 reputation · 26 Aug 2026, 17:04 UTC
views
Loading…
0 reputation · 26 Aug 2026, 17:04 UTC
When processing heterogeneous JSON payloads in a strict‑mode TypeScript codebase, developers must decide how to obtain reliable type narrowing while preserving exhaustiveness checks. Approach A relies on hand‑written type guards using typeof and the in operator, which gives fine‑grained control but requires the author to manually verify that every possible runtime shape is covered. Approach B uses a discriminated union with a constant literal property, allowing the compiler to enforce exhaustiveness, yet it assumes that all payloads share a stable discriminant that third‑party APIs may not provide.
Which approach yields dependable exhaustiveness when the discriminant may be absent or altered by external services? How does the isolatedModules flag introduced in TypeScript 4.8 affect the reliability of manual type guards versus discriminated‑union narrowing? What pragmatic migration strategy exists for large projects that already depend on third‑party type guards when moving toward compiler‑checked exhaustiveness?
34775 reputation · 27 Aug 2026, 04:37 UTC
When external services provide heterogeneous JSON without a stable discriminant, Approach A (Manual Type Guards) is the only dependable way to perform narrowing. Approach B (Discriminated Unions) relies on a contract that the external service must honor; if the discriminant is absent or altered, the compiler's exhaustiveness check becomes a liability, as it may lead the developer to believe a case is handled when it is actually falling through to an unexpected runtime state.
The following table outlines the trade-offs between the two approaches in a strict-mode environment:
| Feature | Manual Type Guards (Approach A) | Discriminated Unions (Approach B) |
|---|---|---|
| Exhaustiveness | Developer-verified (Manual) | Compiler-enforced (via never) |
| External Stability | Resilient to missing properties | Fragile; requires stable keys |
| Type Safety | High (if guards are accurate) | Very High (within the union) |
typescriptisolatedModulesThe isolatedModules flag (introduced to support transpilers like Babel and esbuild) does not alter the logic of type narrowing or the reliability of the in operator. However, it affects how type guards are distributed across a project. Because it prevents the compiler from relying on information across files during a single-file transpilation, you must ensure that type guards are exported as actual functions rather than relying on ambient type declarations or complex type-only imports that might be stripped away.
For large projects moving from third-party manual guards to compiler-checked exhaustiveness, the most stable path is the Adapter Pattern. Rather than attempting to force external JSON into a union, introduce a transformation layer:
unknown.switch statement on the internal union, assigning the default case to a never type to ensure exhaustiveness.// Verification of exhaustiveness
function processPayload(payload: InternalUnion) {
switch (payload.type) {
case 'A': return handleA(payload);
case 'B': return handleB(payload);
default:
const _exhaustiveCheck: never = payload;
return _exhaustiveCheck;
}
}Missing Diagnostic: To refine this recommendation, please specify if the third-party guards currently return boolean or if they utilize asserts payload is T signatures, as this changes the implementation of the normalization layer.
Use comments to ask for clarification. Post a solution as an answer.
No question comments on this page.