Designing the Discriminant

## The idea A **discriminated union** (also called a tagged union) is a union of object types that all share one property — the *discriminant* or *tag* — whose type is a different literal in each member. Because the tag values are disjoint, a single equality comparison tells the compiler which member it is holding, and control-flow analysis narrows the value for the rest of that branch. ```ts type Shape = | { kind: 'circle'; radius: number } | { kind: 'square'; side: number }; function area(s: Shape): number { if (s.kind === 'circle') { return Math.PI * s.radius ** 2; // s is the circle member here } return s.side ** 2; // s is the square member here } ``` ## Requirement 1 — the tag is on every member Reading a property off a union value is only allowed when *all* constituents declare it. If one member omits `kind`, `s.kind` is a compile error before narrowing ever gets a chance. This is why "one shared tag, present everywhere" is the design rule rather than a stylistic preference. There is a useful escape hatch when one member genuinely has no tag: give it the tag explicitly typed as `undefined`. ```ts type Result = | { error: string; data?: undefined } | { error?: undefined; data: number }; ``` `undefined` is itself a unit type, so `if (r.error !== undefined)` discriminates cleanly, and the member that lacks a field says so in the type rather than leaving a hole. ## Requirement 2 — the tag's type is a literal, not a wide primitive TypeScript calls `'circle'`, `42`, `true`, `null`, `undefined` and enum members **unit types**: types with exactly one value. A discriminant must be one of these (or a union of them) in each member. If any member declares `kind: string`, that member can hold *any* string, so `s.kind === 'circle'` proves nothing about it and the compiler keeps it in the narrowed set. The narrowing silently degrades — no error, just a union where you expected one member. Booleans work well because `boolean` is really the union `true | false`: ```ts type Response = | { ok: true; data: string } | { ok: false; error: Error }; function read(r: Response) { return r.ok ? r.data : r.error.message; } ``` A member may also carry a union of literals — `{ kind: 'circle' | 'ellipse'; ... }` — and comparing against either literal still selects it. ## Requirement 3 — the values distinguish the members If two members share the same tag value, checking it cannot separate them; the narrowed type stays a union of both. Tag values must be unique *within one union*. Reusing the same tag value across two different unions is fine — they are separate types — but reusing it inside one is a modelling bug that shows up as "why is this still a union?". ## One tag per union Discriminate on a single property. A design that expects the compiler to combine two independent fields ("when `mode` is `'edit'` and `source` is `'remote'`…") is fighting the model: each check narrows independently, and the cross-product of two axes rarely collapses to the member you want. If two axes are genuinely orthogonal, keep them as two fields (or two nested unions); if they are not orthogonal, flatten them into one tag with the combinations that actually exist. ## Why this works at all — the erasure angle Everything else in TypeScript's type layer disappears at compile time. The discriminant is the exception you rely on: the tag is an ordinary property with an ordinary runtime value, and `s.kind === 'circle'` is a plain JavaScript comparison that survives into the emitted code. Narrowing is not the compiler inserting a runtime check — it is the compiler *reading* a check you already wrote and drawing the type-level conclusion. That is precisely why discriminated unions are the recommended way to model variants: the type-level story and the runtime story are the same expression. ## What breaks in practice - The tag widens to `string` when an object literal is stored in a variable without an annotation — narrowing then fails at the assignment, not at the comparison. - The tag is optional (`kind?: 'circle'`), so `undefined` leaks into every branch. - The tag is a `number` field that also carries data (an id, a count) — data fields make poor tags because their values are not a closed, meaningful set. - Members are declared with a shared base type that types the tag as the wide union for all of them, so no member has a single literal. Pick a conventional tag name (`kind`, `type`, `status`), make it required, give it a string literal per member, and the compiler does the rest.