Duolith docs

0098. A <match> element for unions, and a resource's states as a union

  • Status: Accepted (Mik, 16 Nov 2026)
  • Date: 2026-11-14
  • Decided by: integrator (internal only), approved by Mik on 16 Nov 2026 as a language change
  • Planning item: none

Context

Mik asked that a case nobody handled fail when the app is built. In the script block that already works: with the options of decision 0097, a switch over a union that misses a member, in a function that returns a value, is E0346. Markup has no such construct. <show when> with <otherwise> handles two cases, and a union of three ("info" | "success" | "danger", or a resource that is loading, loaded or failed) becomes a chain of <show> elements in which a missing case is silently not shown.

A resource has the same gap. feed.data is T | undefined and feed.error is a separate field, so TypeScript forces a page to handle "no data yet" (E0343) but not "failed": a page can show its list and a spinner and never show the error.

Proposal

  1. **<match value={expression}> with <case is="word"> children**, and an optional <case else>. It is written in the script view as a switch over the value, with each case's children narrowed, ending in default: { const unhandled: never = value; } when there is no <case else>. A missing case is then a TypeScript error at the <match> (E0340, "Type 'danger' is not assignable to type 'never'"). Matching on a field of a tagged union is <match value={result.status}>, and the case's children see result narrowed, as <show> narrows today. ``duolith <match value={tone}> <case is="info"><icon name="info" /></case> <case is="success"><icon name="check" /></case> <case is="danger"><icon name="alert" /></case> </match>
  1. A resource's state as a tagged union, beside its current fields: feed.state is { status: "loading" } | { status: "ready"; data: T } | { status: "failed"; error: DataError }. With <match value={feed.state.status}> a page that forgets the failed state does not build.

Alternatives considered

OptionWhy not
<switch> / {#match} syntax of our ownA template language with rules TypeScript does not see; the Angular problem decision 0095 avoids
An analyzer check that every <show> chain covers a unionNeeds types the analyzer does not have; would be a second type checker
Only the script-block switchWorks today, but moves markup into functions that return strings, away from the markup it decides

Consequences if accepted

spec/language/elements.yaml gains match and case, with conformance fixtures; the script view gains one more mapping (decision 0095's table gains a row); the web emitter renders the matching case as <show> does. The resource's union is additive: data, error and loading keep their meaning.

As built (wave 5)

  • <match value={...}> with <case is="word"> and <case else> (spec/language/elements.yaml). The analyzer lowers it to a chain of shows, so web and native render it as they render <show>; it checks the structure itself: only cases inside (E0502), a case only inside a match (E0503), each case has is or else (E0504), no word twice (E0505), else last (E0506).
  • The script view writes a switch, ending in default: ((unhandled: never) => unhandled)(value) on the match's name. A missing case is E0500 ("this <match> has no case for "failed""), and a case the union does not have is E0501, instead of the general E0340.
  • resource().state is { status: "loading" } | { status: "ready"; data; refreshing } | { status: "failed"; error; message }. A value shown stays ready while it refreshes, and while a refresh fails.