Discriminated Unions

## The problem the fallback branch is trying to solve A discriminated union is a set of object types distinguished by a literal-typed tag field, and code that consumes one usually branches on that tag. The failure mode is not the branching — it is *growth*. Someone adds a new member to the union six months later, and every dispatch site in the codebase silently keeps compiling while quietly doing the wrong thing for the new case. The naive defence is a fallback branch that throws: ```ts default: throw new Error('unhandled kind'); ``` This is a runtime tripwire. It tells you about the missed case *after* you deployed, on the first request that hits it. ## What the typed helper changes ```ts function assertNever(value: never): never { throw new Error(`Unexpected value: ${JSON.stringify(value)}`); } ``` The body is the same throw. The parameter annotation is the whole trick. `never` is the type with no values: nothing is assignable to it except an expression the checker has itself concluded is impossible. So `assertNever(x)` is a question posed to the compiler — *have you proven x cannot exist here?* If yes, it compiles. If not, it is a type error, reported at build time, at the exact dispatch site that fell behind the union. Call it in the branch that should be unreachable: ```ts switch (shape.kind) { case 'circle': return Math.PI * shape.radius ** 2; case 'square': return shape.side ** 2; default: return assertNever(shape); } ``` Add `{ kind: 'triangle'; base: number; height: number }` to the union and this file stops compiling until someone writes the triangle case. That is the entire value proposition: a missing case becomes a red build, not a red pager. ## Why the throw stays A common junior instinct is that the helper's body no longer matters, since the compiler proved it unreachable. It matters, because TypeScript types do not exist at runtime. The compiler erases them and emits plain JavaScript; there is no check that a value tagged `kind: 'hexagon'` cannot flow in from a JSON response, a database row written by an older service version, or an `as` assertion somewhere upstream. The type system's proof is a proof about *code you compiled*, not about *data you received*. The throw is what happens when reality disagrees with the annotation, and it should be loud, include the offending value, and never be downgraded to a silent `return undefined`. So the helper does two jobs at two different times: the `never` parameter is a compile-time exhaustiveness check, and the `throw` is a runtime fail-loud for data that violates the declared union. ## Naming and shape The function is conventionally called `assertNever` or `assertUnreachable`; neither is built into TypeScript — you write these few lines yourself, usually once in a shared utility module. It is not the `asserts value is T` assertion-function form, which is a different signature with different semantics; `assertNever` simply takes `never` and returns `never`. The return type matters too. Because `never` is assignable to every type, `return assertNever(shape)` satisfies a function declared to return `number` without any cast, which is why the call is usually written with `return` in front of it. ## What a weak answer looks like The two answers that get marked down are "it throws a better error message" (it does not — the message is whatever you write; the compile-time check is the point) and "it validates the value at runtime" (it validates nothing; a value that reaches it has already defeated the type system). The correct framing is: the plain throw guards runtime only, and the typed helper adds a compile-time guard on top of the same runtime throw. ## When you would not reach for it If the function returns a value and you annotate its return type explicitly, TypeScript can already flag a missing case without any helper, because the function's end point becomes reachable. `assertNever` earns its keep in dispatches that return nothing, in `if/else if` chains, and wherever you want the error to point precisely at the unreachable branch rather than at the function signature.