What exactly is a discriminated union and why is it useful?

It is a union of object types that all share one literal property — the discriminant — set to a distinct value per variant. TypeScript reads that tag in a switch or if and narrows the value to the matching variant, so each branch only sees the fields that branch actually has. That removes a whole class of "property does not exist" bugs and makes state machines and tagged results safe to refactor.

How does the generated switch guarantee exhaustiveness?

The default case assigns the value to a variable typed never (const _exhaustive: never = value). After handling every known tag, the remaining type is never, which assigns fine. If you later add a variant but forget a case, the remaining type is no longer never and TypeScript fails to compile — turning a missed case into a build error instead of a runtime surprise.

What is the difference between named variant interfaces and inline members?

With "Named variant interfaces" on, each variant becomes its own exported interface (e.g. interface Circle) and the union references them by name (Circle | Square | Triangle); guards and factories then return those named types. With it off, the union is built from anonymous inline object literals and guards narrow with Extract . Named interfaces are easier to reference elsewhere; inline members keep everything in one declaration.

What does the match() helper generate?

It emits a Handlers type — a map from each tag to a function that receives the narrowed variant and returns R — plus a match function that looks up handlers[value.discriminant] and calls it. Because the handler map must cover every tag, you get exhaustiveness on the call site too, and each handler is typed to its specific variant rather than the whole union.

Can the tag value be a number or boolean instead of a string?

Yes. The emitter detects a numeric tag (like 1 or 200) or true / false and writes it as a bare literal instead of a quoted string, while ordinary string tags are single-quoted. Field property names that are not valid identifiers are quoted automatically too, so the output stays valid TypeScript.

Does this parse existing TypeScript, or only build from the model?

It is a builder, not a parser — you compose the union from the discriminant key and variant list rather than pasting source to be read. That keeps the output predictable and lets the tool generate the matching guards, switch, factories and match() helper from the same model. The full model is encoded in the shareable URL so you can hand a draft to a teammate.

Discriminated Union Generator

Compose a tagged union from a model — a discriminant key plus a list of variants, each with its own typed fields — and get a complete, type-safe bundle: the union type, a type guard per variant, an exhaustive switch with a never default for compile-time exhaustiveness, factory constructors, and a match() pattern-matcher. The preview updates live as you edit and the whole model is captured in a shareable URL.

About this ToolHow it works, benefits & use cases

A discriminated (tagged) union is the TypeScript pattern that makes state machines, reducer actions and tagged results fully type-safe: every variant shares one literal property — the discriminant, like type, kind or status — and the compiler uses that tag to narrow the type inside a switch or if. This generator is a model-driven builder, not a parser: you declare a discriminant key and a list of variants, give each variant its own typed fields (with optional flags), and it assembles a complete bundle you can switch between. That bundle includes the union type itself (optionally as named interfaces such as Circle), a type guard per variant (isCircle(s): s is Circle), an exhaustive switch handler whose never default fails the build if you ever add a variant and forget to handle it, factory constructor functions per variant, and a match() helper that pattern-matches on the tag with a strongly typed handler map. Presets cover the common shapes — geometric shapes, async state, Redux-style actions, an API result and a form-field union — and the live preview re-renders instantly as you edit. The whole model is captured in a shareable URL and everything is generated in your browser.

How to Use

1Set a Union name (e.g. Shape) and a Discriminant key (e.g. kind, type, or status).
2Add variants with the Add variant button; give each a tag literal such as circle or LOADING.
3On each variant, add field rows — a property name plus its TypeScript type — and tick "opt" for optional fields.
4Toggle options: export declarations, named variant interfaces, and a readonly discriminant tag.
5Use the output selector to switch the live preview between Union, Guards, Switch, Factories, match() or All.
6Or start from a preset (Shapes, Async state, Redux action, API result, Form field), then copy, download, or share.

Key Benefits

Model-driven builder: compose variants and fields visually instead of hand-typing every branch
Emits a full bundle — union, per-variant type guards, exhaustive switch, factories and a match() helper
The generated switch uses a never default for compile-time exhaustiveness checking
Optional named variant interfaces (e.g. Circle) or anonymous inline object members
Strongly typed match() handler map so each branch receives the narrowed variant type
Five presets covering shapes, async state, Redux actions, API results and form fields
Live preview, shareable URL, and fully in-browser generation with no upload

Common Use Cases

Modeling async data as idle / loading / success / error with type-safe payloads
Defining Redux or reducer action types that share a type discriminant
Typing API results with ok and err branches that carry different fields
Building shape or geometry unions where each kind has its own dimensions
Generating guards and an exhaustive switch so a forgotten case becomes a compile error
Producing factory constructors and a match() helper alongside the type in one paste

Shape.ts

The tagged union type (+ named variant interfaces)

export interface Circle {
  kind: 'circle';
  radius: number;
}

export interface Square {
  kind: 'square';
  size: number;
}

export interface Triangle {
  kind: 'triangle';
  base: number;
  height: number;
}

export type Shape =
  | Circle
  | Square
  | Triangle;

Compile-time exhaustiveness guaranteed

The generated switch assigns the value to a never in its default case. Add a variant later and forget to handle it, and TypeScript fails the build.

3variants4fields0optional

Presets

Union shape

Union name

Discriminant key

export declarations

Named variant interfaces

e.g. interface Circle

readonly tag

freeze the discriminant

Variants

Tag 1

opt

Tag 2

opt

Tag 3

opt

What a discriminated union buys you

A discriminated (tagged) union shares one literal property — the discriminant — across every variant. TypeScript uses that tag to narrow the type inside a switch or if, so each branch only sees the fields that branch actually has.

A complete bundle, not just a type

Beyond the union itself, the generator emits a type guard per variant, an exhaustive switch whose never default catches unhandled cases at compile time, factory constructors, and a match() helper that pattern-matches on the tag with a handler map.

Was this tool helpful?

Share Your Experience

Help others discover this tool!

Share on

Discriminated Union Generator

How to Use

Key Benefits

Common Use Cases

Presets

Union shape

Variants

What a discriminated union buys you

A complete bundle, not just a type

Was this tool helpful?

Share Your Experience

Related tools

Frequently Asked Questions - Discriminated Union Generator