🚀 Release 0.8.3

The agent-side LSP extension is declared in `.pi/settings.json`, not in
`package.json`, so neither `npm update` nor `maintain:outdated` sees it.
Bump it with `pi install npm:@spences10/pi-lsp@0.0.47 -l`, which
rewrites the pin and refreshes the gitignored `.pi/npm/` install cache,
then reformat the file: pi writes it back in its own two-space style,
which `check:oxfmt` rejects.

0.0.47 bounds the project-binary trust prompt — it follows tool
cancellation and times out after 30 s, returning a tool error instead of
leaving the session stuck in `Working`, and an allow-once decision now
survives an idle language-server restart. The read-only usage and the
`tsc --lsp` wiring are unchanged, so `development/tooling.md` only moves
the recorded version. No changelog note: the pin is agent tooling, not
shipped code, as when it was adopted (863198d).

The running pi session still has 0.0.46 loaded; restart pi to pick up
the new version.

.gitea/workflows/ci.yml

@@ -77,6 +77,13 @@ jobs:
             - run: npm ci
             - run: npm run build
             - run: npm run check
+            # Compile the prose examples into gitignored tests. Kept as an
+            # explicit step (not a `pretest:ci` hook) so it is visible in the
+            # job log and `test:ci` stays a plain command.
+            - run: npm run create:doc-tests
+            # Fails the build below 100% coverage on `src/` (`c8 --all --100`);
+            # the same run produces the report published below. See
+            # development/ci.md § Coverage threshold.
             - run: npm run test:ci
             # Publish this tag's coverage to the self-hosted pages server,
             # served read-only at

.gitignore

@@ -1,6 +1,10 @@
 node_modules
 dist
 coverage
+
+# Generated doc-tests (scripts/create-doc-tests.ts); the folder is kept via .gitkeep
+src/doc-test/__generated__/*.test.ts
+!src/doc-test/__generated__/.gitkeep
 *.log
 *.tsbuildinfo
 *.local

.pi/settings.json

@@ -1,3 +1,3 @@
 {
-    "packages": ["npm:@spences10/pi-lsp@0.0.46"]
+    "packages": ["npm:@spences10/pi-lsp@0.0.47"]
 }

AGENTS.md

@@ -7,10 +7,11 @@ first-action facts. Do not restate evolving prose here — it will drift.
 
 ## First action
 
-- Project: F#-style pattern matching for TypeScript/ESM. Node `>=26` (pinned via `.node-version`), ESM-only (no CommonJS shim).
+- Project: pattern matching for TypeScript/ESM. Node `>=26` (pinned via `.node-version`), ESM-only (no CommonJS shim).
 - **While iterating:** `npm run test` (`check:tsc` + the unit suite) for fast feedback on the files you changed.
 - **Optional code intelligence:** this repo installs `@spences10/pi-lsp` (pinned in `.pi/settings.json`) as a project-local pi extension. It talks to the repo's own TypeScript 7 via `tsc --lsp --stdio` and exposes **read-only** tools — `lsp_hover`, `lsp_definition`, `lsp_references`, `lsp_find_symbol`, `lsp_document_symbols`, `lsp_diagnostics(_many)`. **When you are looking for a symbol, reach for the LSP before `rg`/`grep`** — `lsp_references` / `lsp_find_symbol` / `lsp_definition` / `lsp_document_symbols` are semantic and cross-file, so they see shadowing, imports and overloads that a text search cannot; use `lsp_hover` to read inferred types on generic-heavy code. Use `rg` for what the LSP cannot see — doc prose, string literals, config, task lists, file discovery — and reconcile the two sets before editing (symbols from the LSP, strings and prose from `rg`). It has no rename / code-action / apply-edit surface — the write side is pi's `edit` tool + `check:tsc`. Treat empty LSP output as _inconclusive_, not success: **`npm run test` / `npm run verify` remain the sole authoritative gate** (see the next bullet). The server keeps running across that gate with a ~5 min idle timeout and registers no file watchers, so if you change `tsconfig.json` / `package.json` mid-session its diagnostics can be stale — when LSP output disagrees with `check:tsc`, trust `check:tsc` and restart pi (or wait out the idle timeout) before concluding the LSP is wrong.
 - **Definition of done — run this before you call the work finished:** `npm run verify`. If all green, commit. If red, look at the output, fix the root cause, and re-run.
+- **Touched a `ts`-tagged fence in `README.md` / `CONTRIBUTING.md`?** Run `npm run create:doc-tests` first: it regenerates the gitignored tests under `src/doc-test/__generated__/`, formats and type-checks them, so `verify` executes the documented example. CI runs it in an explicit step before `test:ci`; the fast local tiers do not. See [development/docs.md](./development/docs.md).
 - **On commit:** write a good message (see [CONTRIBUTING.md § Commit messages](./CONTRIBUTING.md#commit-messages)). Lefthook's pre-commit hook already runs the fast, offline, staged-file checks — don't run them by hand. If the hook fails on style, `npm run fix`, restage, recommit.
 - **Document decisions where the next maintainer will look:** rationale, rejected alternatives and known issues go in `development/<category>.md` (see [development/README.md](./development/README.md)); the actionable rule stays in [CONTRIBUTING.md](./CONTRIBUTING.md) and links to it. Write each fact once — never copy the rule into `development/` or the reason into `CONTRIBUTING.md` — and change both in the same commit when a rule changes.
 - **`npm run maintain` is NOT part of the feature loop.** Its scans are advisory, never a gate; run them only on an explicit maintenance / update-deps branch.

CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.3] - 2026-09-28
+
+- upgrade dependencies: oxfmt 0.71 (the only range widened), oxlint 1.86,
+  oxlint-tsgolint 7.0.2003, cspell 10.3.5 and the rest within their existing
+  ranges; no rule or format fallout
+- prune the completed items from the backlog; their rationale already lives in
+  the README, `development/` and the released changelog entries
+
+## [0.8.2] - 2026-09-25
+
+- write the README's Synopsis and Examples sections
+- document the public API in the README
+- add TSDoc to the four public matcher factories
+- document alternatives
+
+## [0.8.1] - 2026-09-23
+
+- gate CI at 100% coverage: `test:ci` runs c8 with `--all --100` over `src/`,
+  and a test loads the `index.ts` barrel so it is measured
+- pin the duplicate-tag union collapse (members sharing a tag dispatch through
+  one handler) with tests
+
+## [0.8.0] - 2026-09-23
+
+- reject a universe that mixes a literal with a broad type (e.g.
+  `"a" | \`x-${number}\``), which the finite-literal gate let through
+- narrow the tagged-union matcher's handler parameters for a union-valued or
+  optional discriminant, and its fallback to the unhandled tags, instead of
+  passing `never`
+
 ## [0.7.1] - 2026-09-23
 
 - upgrade dependencies
@@ -86,7 +116,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - basic setup
 
-[Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.7.1...main
+[Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.8.3...main
+[0.8.3]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.8.2...0.8.3
+[0.8.2]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.8.1...0.8.2
+[0.8.1]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.8.0...0.8.1
+[0.8.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.7.1...0.8.0
 [0.7.1]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.7.0...0.7.1
 [0.7.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.6.0...0.7.0
 [0.6.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.5.0...0.6.0

CONTRIBUTING.md

@@ -22,6 +22,8 @@ the rules so agents and humans don't diverge.
 - **Test:** `npm run test`, `npm run test:ci`
 - **Watch:** `npm run watch` - re-runs tests on file save, humans only
 - **Checks:** `npm run check`, `npm run fix`
+- **Doc tests:** `npm run create:doc-tests` — compile the `ts`-tagged fences
+  in the prose docs into executed, gitignored tests
 - **Verify:** `npm run verify` — the definition of done
 - **Maintenance:** `npm run maintain` — advisory only
 - **Individual fixes:** `npm run fix:oxfmt`, `npm run fix:oxlint`
@@ -41,7 +43,7 @@ faster tiers catch less, slower tiers are more thorough":
 | `npm run verify`                 | manual                  | Definition of done: `npm run check` + unit tests, one shot                                                                                              | ~6s   |
 | `npm run fix`                    | manual                  | Auto-resolve fixable issues (lint, format)                                                                                                              | ~3s   |
 | `npm run maintain`               | manual / CI (advisory)  | `maintain:knip` + `maintain:outdated` (whole-project + network scans)                                                                                   | ~10s  |
-| CI build (auto)                  | on push to `main` / tag | `build` job (build + correctness + packaging) — see [.gitea/workflows/ci.yml](./.gitea/workflows/ci.yml)                                                | ~30s+ |
+| CI build (auto)                  | on push to `main` / tag | `build` job (build + correctness + coverage + packaging) — see [.gitea/workflows/ci.yml](./.gitea/workflows/ci.yml)                                     | ~30s+ |
 | CI maintain (auto, non-blocking) | on push to `main`       | `npm run maintain` — reports, never fails the build                                                                                                     | ~10s  |
 | CI publish (auto)                | on tag                  | packaging checks + `publish:publint` / `publish:attw`, then the Gitea release page and `npm publish` (skipped, and the job failed, without `NPM_TOKEN`) | ~15s  |
 
@@ -87,6 +89,17 @@ Per [AGENTS.md § Never do](./AGENTS.md#never-do), reach green honestly — fix
 types, never suppress the checks you can't make pass. Full rationale:
 [development/testing.md](./development/testing.md).
 
+## Documentation examples
+
+Every `ts`-tagged fence in `README.md` / `CONTRIBUTING.md` is compiled into an
+executed test, so a documented example cannot drift from the API. Describe each
+fence with the paragraph directly above it (that text becomes the test title),
+and keep its library import self-contained;
+`npm run create:doc-tests` regenerates, formats and type-checks the tests under
+`src/doc-test/__generated__/`. CI runs it in an explicit step before `test:ci`,
+so run it yourself before `npm run verify` when you touched a fence. Why:
+[development/docs.md](./development/docs.md).
+
 ## Code style and formatting
 
 `oxfmt` is the formatter and `oxlint` is the linter (with type-aware rules).
@@ -115,17 +128,21 @@ intended to run. A `<prefix>:<name>` script is implicitly aggregated by a
 `<prefix>` script (if one exists) and run by the corresponding lefthook hook or
 CI step. Pick the prefix that matches the script's lifecycle:
 
-- `create:*` — front doors of the repo's own workflow; these mutate git state
+- `create:*` — front doors of the repo's own workflow; these produce or mutate
-  rather than the source. `create:branch` opens a unit of work, `create:finish`
+  workflow artifacts (git state, generated doc-tests) rather than the
+  hand-written source. `create:branch` opens a unit of work, `create:finish`
   closes the branch half, `create:release` closes the release half
-  (maintainer-only). No bare `create` aggregator on purpose.
+  (maintainer-only), and `create:doc-tests` regenerates the compiled prose
+  examples. No bare `create` aggregator on purpose.
 - `check:*` — read-only verification; never modifies files. Aggregated by
   `npm run check`.
 - `fix:*` — mutating counterpart of a `check:*` script. Aggregated by
   `npm run fix`; the diff is the review surface.
 - `test:*` — test scripts. `test` is the canonical entry point (`check:tsc` +
   unit tests); `test:unit` skips the typecheck for fast local iteration;
-  `test:ci` adds c8 coverage.
+  `test:coverage` runs c8 over the hand-written tests only; `test:doc` runs the
+  generated doc examples without coverage; `test:ci` chains the two and fails
+  below 100% coverage on `src/` (CI-only; `verify` stays coverage-free).
 - `watch:*` — long-running watchers for the manual inner dev loop. Aggregated by
   `watch`.
 - `maintain:*` — advisory repo-maintenance scans: read-only, but whole-project

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 tmu
+Copyright (c) 2026 tmu
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,15 +1,55 @@
 # tiny-pattern-ts
 
-Pattern matching for TypeScript/ESM environments (F#-style, not regex).
+Exhaustive, type-safe pattern matching for TypeScript.
+
+## Synopsis
+
+```ts
+import { getTaggedUnionMatcher } from "tiny-pattern-ts";
+
+// 1. We have a union type
+type Contact =
+    | { kind: "email"; address: string }
+    | { kind: "phone"; number: string }
+    | { kind: "messenger"; username: string };
+
+// 2. Create a matcher providing the discriminant property
+const matchContact = getTaggedUnionMatcher<Contact>()("kind");
+
+// 3. Define handlers for each branch of the union
+const formatContact = matchContact({
+    email: (e) => `MAIL: ${e.address}`,
+    phone: (p) => `PHONE: ${p.number}`,
+    messenger: (m) => `MESSENGER: @${m.username}`,
+});
+
+// 4. Call the matcher with a value
+const mailOutput = formatContact({ kind: "email", address: "ada@example.com" });
+assert.equal(mailOutput, "MAIL: ada@example.com");
+
+const phoneOutput = formatContact({ kind: "phone", number: "+1 555 0100" });
+assert.equal(phoneOutput, "PHONE: +1 555 0100");
+```
 
 ## Description
 
-`tiny-pattern-ts` brings F#-style pattern matching to TypeScript. Patterns are
+`tiny-pattern-ts` is a pattern-matching library for TypeScript.
-ordinary objects whose `matches` method is a TypeScript type guard, so narrowing
+
-composes the way any other guard does. It is deliberately not a regex engine and
+The main goal of `tiny-pattern-ts` is to make pattern matching type-safe with a
-not a macro: there is no transpiler and no DSL to learn, and the type-level
+lean syntax. This is accomplished by being exhaustive and passing typed
-contract is the feature — see [development/library.md](./development/library.md)
+parameters per branch to the handlers — supported by an outstanding
-for the design decisions and [Caveats](#caveats) for the limits.
+autocomplete and a tiny footprint. The matchers are data last and pipe-friendly:
+build the handler map once, then apply the resulting matcher to values
+(`match(value)`, or `pipe(value, match)`).
+
+See [development/library.md](./development/library.md) for the design decisions
+and [Caveats](#caveats) for the limits.
+
+## Installation
+
+```sh
+npm install tiny-pattern-ts
+```
 
 ## Requirements
 
@@ -19,9 +59,202 @@ for the design decisions and [Caveats](#caveats) for the limits.
   both resolve on TS >= 5.0 in `node10` / `node16` / `nodenext` / `bundler`.
 - The package is **ESM-only** (no CommonJS shim).
 
+## Examples
+
+A few real-world recipes. Each binds the handler-map function once and reuses
+it, so the matcher is allocated a single time.
+
+### Dispatch on a primitive union
+
+A result code is itself a finite union, so `getPrimitiveUnionMatcher` keys a
+handler on each member:
+
+```ts
+import { getPrimitiveUnionMatcher } from "tiny-pattern-ts";
+
+type ResultCode = "ok" | "created" | "no-content";
+
+const toStatus = getPrimitiveUnionMatcher<ResultCode>()({
+    ok: () => 200,
+    created: () => 201,
+    "no-content": () => 204,
+});
+
+assert.equal(toStatus("ok"), 200);
+assert.equal(toStatus("created"), 201);
+assert.equal(toStatus("no-content"), 204);
+```
+
+### Leave cases to a fallback
+
+Pass a fallback as the second argument to handle only part of the universe; it
+receives the members the map leaves uncovered — here the parameter is
+`"deprecated" | "gateway-timeout"`:
+
+```ts
+import { getPrimitiveUnionMatcher } from "tiny-pattern-ts";
+
+type Status = "active" | "beta" | "deprecated" | "gateway-timeout";
+
+const rollout = getPrimitiveUnionMatcher<Status>()(
+    { active: () => "enabled", beta: () => "enabled" },
+    (status) => `blocked (${status})`,
+);
+
+assert.equal(rollout("active"), "enabled");
+assert.equal(rollout("deprecated"), "blocked (deprecated)");
+```
+
+### Dispatch on a property union
+
+The value does not have to be the union itself. When a single property carries a
+finite union, the tagged-union matcher keys on it and narrows the whole record to
+the selected value:
+
+```ts
+import { getTaggedUnionMatcher } from "tiny-pattern-ts";
+
+interface Invoice {
+    readonly currency: "eur" | "usd" | "jpy";
+    readonly amount: number;
+}
+
+const matchCurrency = getTaggedUnionMatcher<Invoice>()("currency");
+
+const symbolOf = matchCurrency({
+    eur: (i) => `€${i.amount.toFixed(2)}`,
+    usd: (i) => `$${i.amount.toFixed(2)}`,
+    jpy: (i) => `¥${i.amount.toFixed(0)}`,
+});
+
+assert.equal(symbolOf({ currency: "usd", amount: 12.5 }), "$12.50");
+assert.equal(symbolOf({ currency: "jpy", amount: 900 }), "¥900");
+```
+
+### Widen the return type
+
+When the handlers return different types, reach for the widening `W` variant: the
+matcher's return is their union rather than one common type — here
+`string | string[] | undefined`:
+
+```ts
+import { getPrimitiveUnionMatcherW } from "tiny-pattern-ts";
+
+type Field = "name" | "tags" | "note";
+
+const parse = getPrimitiveUnionMatcherW<Field>()({
+    name: () => "Ada",
+    tags: () => ["admin", "beta"],
+    note: () => undefined,
+});
+
+assert.equal(parse("name"), "Ada");
+assert.deepEqual(parse("tags"), ["admin", "beta"]);
+assert.equal(parse("note"), undefined);
+```
+
 ## API
 
-Yet to be implemented
+The package exports four factories. Two axes pick one:
+
+- **Universe** — a _primitive-union_ matcher matches a value that is itself a
+  finite union (`"yes" | "no"`); a _tagged-union_ matcher matches an object
+  discriminated by a property (`{ kind: … }`).
+- **Return** — the _strict_ variant gives every handler one common return type
+  `R`; the _widening_ variant (`W`) widens the return value to the union of the
+  handler returns.
+
+| Factory                          | Use when                                                                  | Return                |
+| -------------------------------- | ------------------------------------------------------------------------- | --------------------- |
+| `getPrimitiveUnionMatcher<T>()`  | the value is the union and all handlers return the same type              | one common `R`        |
+| `getPrimitiveUnionMatcherW<T>()` | the value is the union and handlers return different types                | union of the handlers |
+| `getTaggedUnionMatcher<T>()`     | the value is a discriminated object and all handlers return the same type | one common `R`        |
+| `getTaggedUnionMatcherW<T>()`    | the value is a discriminated object and handlers return different types   | union of the handlers |
+
+Bind the function that takes the handler map to a `match…` variable once and
+reuse it; the [Examples](#examples) do this, so the builder is allocated once.
+
+### Primitive-union matchers
+
+`getPrimitiveUnionMatcher<T>()` takes the finite universe `T` and returns a
+builder. Calling the builder with a handler map keyed by `T`'s members returns a
+matcher: a function from `T` to the common return type.
+
+```ts
+import { getPrimitiveUnionMatcher } from "tiny-pattern-ts";
+
+const matchAnswer = getPrimitiveUnionMatcher<"yes" | "no">();
+
+const reply = matchAnswer({
+    yes: () => "agreed",
+    no: () => "declined",
+});
+
+const answer = reply("yes");
+assert.equal(answer, "agreed");
+```
+
+Add a fallback as the second argument to leave members unhandled; the fallback
+receives the remainder:
+
+```ts
+import { getPrimitiveUnionMatcher } from "tiny-pattern-ts";
+
+const matchLabel = getPrimitiveUnionMatcher<"yes" | "no" | "maybe">();
+
+const label = matchLabel(
+    { yes: () => "agreed", no: () => "declined" },
+    (other) => `not sure: ${other}`, // other: "maybe"
+);
+
+const answer = label("yes");
+assert.equal(answer, "agreed");
+
+const fallback = label("maybe");
+assert.equal(fallback, "not sure: maybe");
+```
+
+`getPrimitiveUnionMatcherW` is the same builder, but the matcher's return type
+is the union of the handler return types rather than one common `R`.
+
+### Tagged-union matchers
+
+`getTaggedUnionMatcher<T>()` takes a discriminated union `T`. The returned
+function takes the discriminant property's name and returns the handler-map
+builder, keyed by that property's tags.
+
+```ts
+import { getTaggedUnionMatcher } from "tiny-pattern-ts";
+
+type Shape =
+    { kind: "circle"; radius: number } | { kind: "square"; side: number };
+
+const matchShape = getTaggedUnionMatcher<Shape>()("kind");
+
+const area = matchShape({
+    circle: (s) => Math.PI * s.radius ** 2,
+    square: (s) => s.side ** 2,
+});
+
+const circleArea = area({ kind: "circle", radius: 2 });
+assert.equal(circleArea, Math.PI * 4);
+
+const squareArea = area({ kind: "square", side: 3 });
+assert.equal(squareArea, 9);
+```
+
+`getTaggedUnionMatcherW` is the widening counterpart, exactly as in the
+primitive-union pair. The discriminant key is restricted to properties whose
+values are tags; see [Caveats](#caveats) for the supported tags and the
+`boolean` / `null` / `undefined` key projection.
+
+### The universe
+
+The primitive universe `T` must be a finite union of literals with no
+value/stringification collision. A broad member (`string`, `number`, a template
+literal) or a colliding pair (`true | "true"`, `1 | "1"`) is rejected at the
+factory. The reasons and the rejected alternatives are in
+[development/library.md](./development/library.md).
 
 ## Caveats
 
@@ -40,9 +273,59 @@ Yet to be implemented
 - **`NaN` and `-0` cannot be matched specifically.** They have no literal type,
   so both stay part of `number`.
 
+### Why open universes are rejected
+
+An open universe — one carrying a broad member, as in
+`type Units = "s" | "ms" | "min" | (string & {})` — is not a dispatch concern.
+If the values arrive from outside the program, parse them at the boundary down
+to a finite union and match the narrowed result; the openness never reaches the
+matcher. If the domain is genuinely extensible, the right shape is a runtime
+`Map` of handlers, where "no handler" is a lookup, not a pattern. Either way an
+open matcher would abandon the one guarantee this library exists to give —
+provable exhaustiveness — to automate what a `switch` and a default arm already
+cover. The type-level cost of supporting open universes is recorded in
+[development/library.md](./development/library.md#supported-universes).
+
+## Alternatives
+
+### [`ts-pattern`](https://github.com/gvergnaud/ts-pattern)
+
+- is the full structural matcher — nested and partial patterns, guards, unions,
+  captures — exhausting at `.exhaustive()`
+- has a fluent `.with(…)` chain that is heavy on syntax; tiny-pattern-ts is one
+  handler map
+- is about 2 kB minified and gzipped; tiny-pattern-ts is 0.2 kB
+- reach for it when you need a feature tiny-pattern-ts does not cover
+
+### [Effect's `Match`](https://effect.website/docs/code-style/pattern-matching/)
+
+- is the same piped matcher (`Match.type` / `Match.when` / `Match.exhaustive`),
+  but only as part of the `effect` ecosystem
+- tiny-pattern-ts is standalone: no runtime dependency to buy into
+
+### [`match-iz`](https://github.com/shuckster/match-iz)
+
+- expresses patterns in the TC39 proposal's style, deciding each case at runtime
+- is written in JavaScript with hand-maintained declarations, so its types do
+  not prove the cases exhaustive
+- tiny-pattern-ts does: exhaustiveness is a compile-time guarantee, not an
+  `otherwise` fallback
+
+### plain `switch` (baseline)
+
+- is the zero-dependency baseline — pair it with
+  [`eslint-plugin-strict-pattern-matching`](https://www.npmjs.com/package/eslint-plugin-strict-pattern-matching)
+  for exhaustiveness
+- is a statement, not an expression, so it cannot produce a value directly
+- leaves the `never` guard to you; tiny-pattern-ts is an expression and does not
+  need one
+
+The [TC39 pattern-matching proposal](https://github.com/tc39/proposal-pattern-matching)
+is still stage 1, so userland libraries remain the only option today.
+
 ## License
 
-MIT © 2025 tmu. See [LICENSE](./LICENSE).
+MIT © 2026 tmu. See [LICENSE](./LICENSE).
 
 ## Contributing
 

backlog.tasks

@@ -6,89 +6,9 @@ Backlog and tracking for tiny-pattern-ts. Managed in vscode-todotasks format.
 
 Setup:
 ☐ Split off template into separate package => pi --session 01a07dde-7050-7054-bb36-1606d7eb2bc3 @low
-✔ straighten oxc rules @done
-    ✔ oxc forbids ternary => remove oxc rule @done
-    ✔ oxc wants comments to start comments with a capital letter => remove oxc rule @done
-    ✔ there already exists a /* */ block comment in primitive.ts, => change to multi-line comment @done
-
-✔ Remove example code files and its documentation and its exports from index.ts @high @done
-    ✔ remove src/match.ts and its documentation @high @done
-    ✔ remove src/pattern.ts and its documentation @high @done
-    ✔ remove src/index.test.ts and its documentation @high @done
-    ✔ exports from `src/index.ts` should only be the public API surface @done
-
-
-v1.0:
-☐ API surface is stable and fully typed
-    ☐ Finalize public exports in `src/index.ts`
-    ☐ Document all exported types and functions
-    ☐ Add JSDoc for public APIs
-☐ Test coverage meets threshold
-    ☐ Achieve 100% branch coverage on `src/primitive-union.ts`
-    ☐ Achieve 100% branch coverage on `src/index.ts`
-
-Testing:
-✔ Cover autocomplete with real completion test cases in the suite @medium @done
-    → `src/util/__tests__/lsp-completion.ts` (`#test-utils/…`) is the helper; the suite asserts its labels (see development/testing.md § Autocomplete)
-    → wire it into `node --test` so a test asserts the offered labels
-    → note: `Parameters<typeof factory>[0]` resolves only the *last* overload; use `@ts-expect-error` call sites for factory negatives, not `not.toExtend<Parameters<…>>`
-✔ Drive the LSP completion helper through the LSP protocol library instead of a hand-rolled JSON-RPC client @medium @done
-    ✔ Add `vscode-languageserver-protocol` and record the tooling decision @done
-    ✔ Rewrite `src/util/__tests__/lsp-completion.ts` onto `createMessageConnection` and typed requests @done
-    ✔ Update `development/testing.md § Autocomplete` for the new client @done
-    ✔ Run `npm run verify` and check the task off @done
-✘ Test a literal union widened with `(string & {})` — `"red" | "green" | "yellow" | (string & {})` @medium @cancelled
-    → broad universes are rejected; the rejection is covered by the broad-universe gate tests
-✔ Type hole when using broad types like string as a universe @high @done
-    → decided: broad universes are rejected at the factory, so the exhaustive overload can always be proven
-    → value/stringification collisions (`true | "true"`, `1 | "1"`) are rejected too; handler params are typed by `Member<T, K>`
-    → see development/library.md § Supported universes
-
-Matcher:
-✔ Clean up: adopt the 3-overload matcher (`src/prototype-ac2.ts`) and delete the prototypes @high @done
-    → `getMatcher` / `getMatcherW`, each with overloads `ExhaustiveLoose` → `Fallback` → `Handlers` (order is load-bearing)
-    → fold into `src/primitive.ts` / the public API; drop `src/prototype*.ts`
-✔ `_` should receive only the unhandled `T` keys, not all of `T` @medium @done
-    → the fallback is now a second argument: `(handlers, (s) => …)`, `s: Exclude<T, keyof handlers>`
-✔ A fallback for an already-exhaustive handler map must be a compile error @medium @done
-    → rejected by an F-bounded constraint on `Handled` (checked *after* inference); a conditional in the fallback parameter is evaluated too early and breaks contextual typing
-✔ Implement matcher with similar API like matcher from primitive.ts @high @done
-    → `getTaggedUnionMatcher` / `getTaggedUnionMatcherW`, curried on the discriminant key
-    → fallback is the second argument; `_` removed
-✔ Rename `primitive` to `primitive-union` and `getMatcher` to `getPrimitiveMatcher` @medium @done
-    → `src/primitive.ts` / `src/primitive.test.ts` → `primitive-union.*`
-    → `getMatcherW` → `getPrimitiveMatcherW` for symmetry with the tagged-union pair
-    → update `src/index.ts`, `development/library.md` and any README references
-    → shipped as `getPrimitiveUnionMatcher` / `getPrimitiveUnionMatcherW`; kept `Union` for symmetry with the tagged-union pair
-☐ when using a union type as a property, the current behavior of tagged union matcher is
-    to pass never to handler parameters
-    → new matcher function needed or can be fixed in tagged union matcher
-    ☐ optional discriminant (`{ type?: "x" }`) is the same hole: the boolean/nullish change now admits the `undefined` tag, so the factory accepts the key, but `Extract<T, Record<K, V>>` still passes `never` to both the `x` and `undefined` handlers
-
-Bugs:
-✔ TS 7 LSP server logs `context canceled` on stderr at shutdown @done
-    → `handleExit` returns `io.EOF`, cancelling the background context while `Session.updateWatches` is still in flight; the bare error is flushed to stderr and the server exits 1
-    → close stdin after `shutdown` instead of sending `exit`; the server exits cleanly (code 0, no output), kill kept as a fallback
-Enhancements:
-✔ Allow boolean literals in primitive union patterns (e.g. `true: () => "yes"`) @medium @done
-    ✔ Are there other primitive types that should be supported in union patterns? (e.g. `bigint`, `symbol`) @medium @done
-        → added boolean, null and undefined; rejected `symbol` (compile-time brand, nothing at runtime) and `bigint` (not a property key)
-✔ Allow boolean, null and undefined discriminant values in tagged-union patterns @medium @done
-    → moved the `PatternKey` / `PatternParam` projection to `matcher-shared.ts` and keyed the tagged-union handler map through it; see development/library.md § Tagged-union matcher
 
 Documentation:
-☐ Bring README.md back to its previous form — synopsis and examples restored, in the correct place
-    → previous section order: title, tagline, Synopsis, Description, Requirements, Examples, API, License, Contributing
-    → previous Examples order: literal/exhaustive, typeof, structural/discriminated unions, when, any
 ☐ Create `examples/` directory with runnable snippets
-☐ Add comparison section vs. other TS pattern-matching libs in Readme.md
-☐ Write migration guide for users coming from discriminated unions
-☐ Create backlog tasks for implementation
-✔ Document the matcher design paths in `development/` — union vs overload merge, inferred universe (`NoInfer`), conditional `RequireKeys`, cases-first — and why each was abandoned @done
-☐ Validate code fences in Markdown (start with README.md) — compile the TypeScript examples against `src/` so the docs cannot drift from the API
-
-Workflow:
-✔ Resolve the finish/push tension: `create:finish` leaves `main` ahead of its upstream while `create:branch` refuses until `main` matches upstream — decide whether `finish` should push or `branch` should compare only `BEHIND` (see development/workflow.md) @done
 
 Maintenance:
 ☐ Serve CI coverage over a tiny self-hosted webserver (replace the zip artifact) @low
@@ -102,3 +22,4 @@ Maintenance:
     ☐ Add a minimal dir-listing webserver to the gitea docker setup for serving landing page (reuse existing reverse proxy)
     ☐ CI writes landing page to a shared volume keyed by project + tag (e.g. `/landing/tiny-pattern-ts/<tag>/`)
     ☐ Browse to `…/tiny-pattern-ts/index.html` in the browser
+☐ Add testing with TypeScript 5.0 baseline in CI

cspell.json

@@ -45,7 +45,8 @@
         "todotasks",
         "connor",
         "injective",
-        "injectivity"
+        "injectivity",
+        "userland"
     ],
     "ignorePaths": ["dist", "node_modules", "coverage", "*.svg", ".gitignore"]
 }

development/README.md

@@ -24,6 +24,7 @@ One file per category:
 | [workflow.md](./workflow.md)     | Branching and merging, script prefixes, feedback tiers, commit messages |
 | [tooling.md](./tooling.md)       | Toolchain choices and configuration, editor setup                       |
 | [testing.md](./testing.md)       | Test strategy and type-driven development                               |
+| [docs.md](./docs.md)             | Validating the Markdown code fences in the prose docs                   |
 | [ci.md](./ci.md)                 | CI pipeline, runner image, coverage serving                             |
 | [publishing.md](./publishing.md) | Release and npm publishing                                              |
 

development/ci.md

@@ -97,6 +97,39 @@ Leave `act_runner`'s `force_pull` disabled.
   (`docker rmi gitea.e1nsnull.de/tmu/act-ci:<version>`); do not reach for
   force-pull.
 
+## Coverage threshold
+
+#### Decision (2026-09)
+
+`npm run test:ci` fails below 100% statements / branches / functions / lines
+across `src/**/*.ts` (`c8 --all --include "src/**/*.ts" --100`). The gate rides
+the `build` job; `npm run verify` stays coverage-free.
+
+#### Why
+
+- The types are the feature, so an untested branch is a hole in the contract,
+  not a metric to trade off; 100% is the only threshold that means "no hole".
+- `--all` counts a `src/` file no test imports. Without it c8 reports only the
+  files the suite happened to load, so a new untested module is invisible and
+  the threshold passes vacuously.
+- The gate rides `test:ci`, which `build` already runs — no new job or step.
+- `verify` stays fast and local; the slower coverage run is a CI-only tier (see
+  [workflow.md § Feedback tiers](./workflow.md#feedback-tiers)).
+
+#### Rejected
+
+- Per-file thresholds: a global 100% already forces every counted file to 100%.
+- A `check:coverage` script: it would re-run the suite or read c8's temp dir,
+  and no `check:*` script runs tests.
+- `--all` without `--include`: it would also sweep `scripts/`, which is not the
+  shipped surface.
+
+#### Known issue
+
+- `src/matcher-shared.ts` is types only, so its runtime image is empty; c8 still
+  lists it under `--all`. It carries a file-level `/* c8 ignore start */` with
+  the reason. Adding runtime code there means removing that directive.
+
 ## Coverage serving
 
 #### Decision (2026-09)

development/docs.md

@@ -0,0 +1,61 @@
+# Docs
+
+Why the prose documentation is maintained the way it is. The actionable rules
+are in [CONTRIBUTING.md](../CONTRIBUTING.md); this file records the rationale.
+
+## Validating Markdown code fences
+
+#### Decision (2026-11)
+
+Compile every `ts / `typescript fence in the prose docs into a real
+`node:test` case under `src/doc-test/__generated__/`, typechecked by a scoped
+`tsc` project and executed by `node --test`.
+
+#### Why
+
+- A documented example is a promise about the API. Left unchecked it drifts the
+  moment a signature changes, and a reader copies broken code.
+- The repo runs TypeScript 7, the native/Go compiler. It exposes **no legacy JS
+  compiler API** (`ts.createProgram`, `ts.transpileModule`, `ts.createSourceFile`
+  are all `undefined`; `Object.keys(require("typescript"))` is
+  `["version", "versionMajorMinor"]`). So `@typescript/vfs`, the type-aware
+  `eslint-plugin-markdown` and `docs-ts` / `@effect/docgen` cannot run here.
+- `node --check` parses as JS and rejects valid TS type annotations, so it is not
+  a gate. The only faithful validator is the `tsc` **CLI**, which means emitting
+  real `.ts` files and letting the existing `check:tsc` / `node --test` pipeline
+  judge them.
+
+#### Rejected
+
+- **A packaged doc-test tool** (see above) — no usable compiler API on TS 7.
+- **Embedding a typecheck in the generator** — duplicates the gate, and would
+  not exercise the repo's own resolution.
+- **`node --check`** — wrong language level.
+
+#### Known issue
+
+- Scanned sources are hard-coded to `README.md` and `CONTRIBUTING.md`. A
+  `docs/` + `examples/` list is the natural extension; `development/` must never
+  be scanned (its fences are illustrative, not compilable).
+- The generator hoists and merges leading imports, rewrites `tiny-pattern-ts` to
+  the `#test-tiny-pattern-ts` source alias, and rejects an example that imports
+  `node:assert` / `node:test` (the prelude already binds both). Titles are the
+  immediately preceding paragraph; a fence with no such paragraph is a fatal
+  error, which keeps every example described.
+- `oxlint src/doc-test` reports "No files found" because the generated
+  `*.test.ts` are gitignored. That is cosmetic: the files are still typechecked
+  and run.
+- The generated tests are `*.test.ts`, which c8's default excludes already keep
+  out of the `--100` gate. Do not add an `--exclude` for them: passing any
+  `--exclude` replaces the defaults, so every hand-written test file and
+  `__tests__/` helper re-enters coverage and the gate fails.
+- Generated examples must not run under `c8`: an example could cover a line no
+  hand-written test reaches, so the coverage gate would pass on documentation
+  alone. `test:coverage` therefore runs c8 over the tracked tests only
+  (`git ls-files 'src/*.test.ts'` — the generated files are untracked), and
+  `test:doc` runs the examples in a separate process without c8. `test:ci`
+  chains the two, so correctness and coverage stay independent.
+- The CI `build` job runs `npm run create:doc-tests` as an explicit step before
+  `npm run test:ci`, not a `pretest:ci` lifecycle hook: the hook hides the step
+  from the job log and makes `test:ci` behave differently under npm than when
+  run directly.

development/library.md

@@ -5,8 +5,39 @@ user-facing reference is [README § API](../README.md#api).
 
 The matchers are implemented in `src/primitive-union.ts` (`getPrimitiveUnionMatcher` /
 `getPrimitiveUnionMatcherW`) and `src/tagged-union.ts` (`getTaggedUnionMatcher` /
-`getTaggedUnionMatcherW`), re-exported from `src/index.ts`; the rest of the
+`getTaggedUnionMatcherW`), re-exported from `src/index.ts`; the rest of `src/`
-library is placeholder code.
+is implementation detail.
+
+## Public surface
+
+#### Decision (2026-09)
+
+`src/index.ts` exports the four factories and nothing else. Every exported
+function carries TSDoc; the builder types and the `matcher-shared.ts`
+vocabulary stay internal.
+
+#### Why
+
+- The factories are the whole contract: a consumer calls one and never needs to
+  name the builder type it returns.
+- The builder interfaces are already the inferred return types, so they travel
+  into the emitted `.d.ts` regardless. Exporting them would only make them
+  nameable while freezing the internal `Strict` / `Widening` overload split as
+  API.
+- TSDoc travels into the emitted declarations, so editor hovers and the
+  published package document the API without a hand-written `.d.ts`.
+
+#### Rejected
+
+- **Exporting the builder types** (`PrimitiveUnionMatcher`, …). Nameable, but it
+  grows the surface for no call-site benefit and pins the `Strict` / `Widening`
+  split.
+- **Exporting the `matcher-shared.ts` vocabulary** (`Matchable`, `UnaryFn`,
+  `PatternKey`, `Member`, `PatternReturns`, …). They appear in the public
+  signatures, but a consumer never needs to name them; exporting them would
+  freeze plumbing as API.
+- **A hand-written `.d.ts` or a separate API document.** It would drift from the
+  implementation; TSDoc is generated from the source.
 
 ## Matcher shape
 
@@ -145,6 +176,10 @@ inversion: the handler parameter is the member(s) of `T` whose `PatternKey` is
   object satisfy the exhaustive overload and reaches the `dispatch` throw.
   Rejecting at the boundary avoids threading an open/closed branch through
   `Handlers`, `Fallback` and `MustBePartial`.
+- **The finite-literal predicate is `IsLiteral<PatternKey<T>> extends true`.**
+  `IsLiteral` is `boolean` for a union that mixes a literal with a broad type
+  (`"a" | \`x-${number}\``), so `extends false`would treat the mix as
+supported;`extends true` is the check that rejects it.
 - **Collisions are rejected, not merged.** `Member<T, K>` would be sound (the
   handler gets the union), but the API is one handler per member; rejecting
   keeps `Member` a singleton and the remainder exact.
@@ -163,7 +198,9 @@ Extract<T, Stringified<T>>` catches numeric collisions too.
   non-self-referential parameter type (`{ [K in keyof H]: … R … }` gives
   `unknown`); an F-bounded guard referencing `keyof Handled` in `Handled`'s own
   constraint sees the constraint, not the map; all handlers share one `R` (only
-  the fallback widens it); `IsLiteral` is the finite-literal predicate.
+  the fallback widens it); `IsLiteral` is the finite-literal predicate. The
+  user-facing consequence — open universes are a parsing or registry concern,
+  not a dispatch one — is guidance in README § Why open universes are rejected.
 - **`Member<T, K>` without the gate:** sound, but a colliding handler gets a
   union and `1 | "1"` stays one runtime key.
 - **A round-trip injectivity gate** (`IsEqual<T, PatternParam<PatternKey<T>>>`):
@@ -208,16 +245,27 @@ The key is a separate call because `K` is inferred from its literal argument and
 
 #### Why
 
-- **Same fallback/remainder machinery as the primitive-union matcher.** `HandledMembers`
+- **Same fallback/remainder machinery as the primitive-union matcher.** `HandledTags`
-  maps the handled tags to their members and `Exclude<T, …>` is the fallback's
+  recovers the tag values the map handled (`Member<Tags, keyof Handled>`) and
-  parameter; the redundant-fallback guard is the same F-bounded constraint. Only
+  `Narrowed<T, K, Exclude<Tags, …>>` is the fallback's parameter; the
-  the "universe" changes — `T`'s members instead of primitive values.
+  redundant-fallback guard is the same F-bounded constraint. Only the "universe"
+  changes — `T`'s members instead of primitive values.
 - **`T extends object`, not `Record<PropertyKey, unknown>`.** An `interface` has
   no implicit index signature, so the `Record` constraint would reject
   interface-based unions. The runtime reads the tag off `object` with one
   assertion, the tagged twin of the primitive-union dispatch's `shape as string | number`.
-- **`MapTaggedUnion` distributes with `Extract`.** A duplicated tag yields a
+- **`Narrowed` distributes over `T`, narrowing `K` to the tag.** A member whose
-  union of members instead of dropping one.
+  `K` cannot take the tag drops out; a duplicated tag yields a union of members
+  instead of dropping one. `T[K] extends V` returns the exact member (a
+  discriminated union's declared interface) untouched, so the mapped form only
+  handles a property that is itself a union.
+- **A union-valued or optional discriminant is supported.** A single shape whose
+  property is a union (`{ color: "red" | "green" | "blue" }`) is narrowed per
+  handler instead of being passed `never`. Matching a defined tag on an optional
+  property (`{ type?: "x" }`) proves the key is present, so it becomes required
+  (`{ type: "x" }`); the `undefined` tag narrows it to `{ type?: never }` under
+  `exactOptionalPropertyTypes` (absence) or `{ type?: undefined }` when the
+  property explicitly admits `undefined`.
 - **A `boolean` / `null` / `undefined` tag goes through the shared
   `PatternKey` / `Member` projection.** `Discriminated` admits those tags
   (they are in `Tag`), but they cannot key a mapped type, so the handler map is
@@ -228,10 +276,13 @@ The key is a separate call because `K` is inferred from its literal argument and
 
 #### Known issue
 
-- A member's tag must be unique across the union; two members with the same tag
+- A tag need not be unique across the union. Two members sharing one is not a
-  collapse to a union under one handler. A tag colliding with its
+  soundness hole: they select a single runtime key, so one handler receiving
-  stringification (`true | "true"`) is rejected by the universe gate — see
+  their union is the only correct behavior — the key is simply not a
-  § Supported universes.
+  discriminant. The gate rejects only the distinct-value collision
+  (`true | "true"`), where two values share a key and `Member` can no longer
+  invert it; see § Supported universes. Pinned by the duplicate-tag tests in
+  `src/tagged-union.test.ts`.
 
 ## Primitive universe
 

development/testing.md

@@ -35,7 +35,8 @@ in
 [CONTRIBUTING.md § Development commands](../CONTRIBUTING.md#development-commands).
 `c8` uses V8 coverage, so the `--strip-types` source is instrumented without a
 build step, and the runner relies on the `.ts` import-extension convention (see
-[tooling.md](./tooling.md#source-imports-use-ts-extensions)).
+[tooling.md](./tooling.md#source-imports-use-ts-extensions)). CI gates that
+coverage at 100% (see [ci.md § Coverage threshold](./ci.md#coverage-threshold)).
 
 ## Handler arguments
 
@@ -198,6 +199,11 @@ the CLI is for manual inspection.
   delay is needed.
 - The server answers some requests with a string id (`client/registerCapability`);
   the client must tolerate `string | number` ids or the server stalls.
+- `LspSession.close()` sends `shutdown` and then closes stdin instead of
+  sending `exit`. The TS 7 Go server's `handleExit` returns `io.EOF`, cancelling
+  the background context while a watch update is still in flight, and logs a
+  bare `context canceled` before exiting 1; EOF on stdin exits 0 with no output.
+  The kill stays as a fallback for a server that does not exit.
 
 ## Known issues
 

development/tooling.md

@@ -196,27 +196,28 @@ joining the oxfmt-superseded rules already off.
   are part of the public API.
 - The narrower scope keeps the signal high without config-file boilerplate.
 
-### `knip` lists `src/index.ts` as an entry
+### `knip` does not list the library entry
 
 #### Decision (2026-09)
 
-`knip.json` declares `"entry": ["src/index.ts", "scripts/*.ts"]`.
+`knip.json` declares `"entry": ["scripts/*.ts"]`; the library entry
+`src/index.ts` is not listed.
 
 #### Why
 
-- Supplying `entry` **replaces** knip's default entry detection, which otherwise
+- knip derives the public entry from `package.json` `exports` and resolves it to
-  derives the public entry from `package.json` `exports`. Adding `scripts/*.ts`
+  `src/index.ts` itself, so naming the file is a redundant pattern and
-  there therefore dropped the library entry, so knip resolved the package through
+  `maintain:knip` reports it as a configuration hint.
-  its `dist/index.js` output and reported the unreferenced source entry file
+- Listing `scripts/*.ts` does not switch that derivation off: the scope stays
-  `src/index.ts` as an unused file.
+  clean with or without `dist/`, and with the barrel's own test removed.
-- Naming the source entry restores the link between the public API and the
-  source graph without pointing knip at build output.
 
 #### Rejected
 
+- `"src/index.ts"` in `entry`: it silenced an `unused files` report for the
+  barrel, which the derivation above no longer produces; keeping it only adds a
+  hint.
 - `paths` mapping `dist/index.*` back to `src/index.ts`: more config to model a
-  relation the explicit entry states directly, and it would break whenever the
+  relation knip already resolves.
-  build layout changes.
 
 ### `maintain:outdated` ignores `@types/node`
 
@@ -327,7 +328,7 @@ of a hand-rolled JSON-RPC client.
 
 #### Decision (2026-09)
 
-`@spences10/pi-lsp` is pinned to `0.0.46` and used read-only.
+`@spences10/pi-lsp` is pinned to `0.0.47` and used read-only.
 
 #### Why
 

development/workflow.md

@@ -96,7 +96,8 @@ aggregator.
 
 #### Why
 
-- Both members create something real: a branch, a release.
+- Every member creates something real: a branch, a release, the compiled
+  doc-tests.
 - It joined both lists in [CONTRIBUTING.md](../CONTRIBUTING.md) alongside its
   first members, so it could not go invisible the way the retired `use:` prefix
   did.

knip.json

@@ -1,5 +1,5 @@
 {
     "$schema": "./node_modules/knip/schema.json",
-    "entry": ["src/index.ts", "scripts/*.ts"],
+    "entry": ["scripts/*.ts"],
     "ignoreDependencies": ["@runwisp/pubv"]
 }

package.json

@@ -1,7 +1,7 @@
 {
     "name": "tiny-pattern-ts",
-    "version": "0.7.1",
+    "version": "0.8.3",
-    "description": "Pattern matching for TypeScript/ESM environments (F#-style, not regex)",
+    "description": "Exhaustive, type-safe pattern matching for TypeScript",
     "keywords": [
         "adt",
         "algebraic-data-types",
@@ -28,7 +28,8 @@
     "type": "module",
     "sideEffects": false,
     "imports": {
-        "#test-utils/*": "./src/util/__tests__/*"
+        "#test-utils/*": "./src/util/__tests__/*",
+        "#test-tiny-pattern-ts": "./src/index.ts"
     },
     "exports": {
         ".": {
@@ -47,7 +48,8 @@
         "check:oxfmt": "oxfmt --check ${LEFTHOOK_FILES:-.}",
         "check:oxlint": "oxlint ${LEFTHOOK_FILES:-src scripts}",
         "check:tsc": "tsc",
-        "clean": "rm -rf dist coverage",
+        "clean": "rm -rf dist coverage src/doc-test/__generated__/*.test.ts",
+        "create:doc-tests": "node --strip-types scripts/create-doc-tests.ts && sh -c 'oxfmt src/doc-test/__generated__/*.test.ts' && tsc -p src/doc-test/tsconfig.json",
         "fix": "npm run fix:oxlint && npm run fix:oxfmt",
         "fix:oxfmt": "oxfmt ${LEFTHOOK_FILES:-.}",
         "fix:oxlint": "oxlint --fix src scripts",
@@ -58,7 +60,9 @@
         "maintain:knip": "knip --include dependencies,exports,files",
         "maintain:outdated": "check-outdated --ignore-pre-releases --ignore-packages @types/node",
         "test": "npm run check:tsc && node --test --strip-types \"src/**/*.test.ts\"",
-        "test:ci": "c8 --reporter=text --reporter=lcov --reporter=html node --test --strip-types \"src/**/*.test.ts\"",
+        "test:ci": "npm run test:coverage && npm run test:doc",
+        "test:coverage": "c8 --all --include \"src/**/*.ts\" --reporter=text --reporter=lcov --reporter=html --100 node --test --strip-types $(git ls-files 'src/*.test.ts')",
+        "test:doc": "node --test --strip-types \"src/doc-test/__generated__/*.test.ts\"",
         "test:unit": "node --test --strip-types \"src/**/*.test.ts\"",
         "verify": "npm run check && npm run test:unit",
         "watch": "npm run watch:test",
@@ -83,7 +87,8 @@
         "expect-type": "1.4.0",
         "knip": "^6.34.0",
         "lefthook": "^2.1.12",
-        "oxfmt": "^0.70.0",
+        "mdast-util-from-markdown": "^2.0.3",
+        "oxfmt": "^0.71.0",
         "oxlint": "^1.83.0",
         "oxlint-tsgolint": "^7.0.2001",
         "publint": "^0.3.24",

scripts/create-doc-tests.ts

@@ -0,0 +1,445 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import type { Code, Heading, Paragraph, PhrasingContent, Root } from "mdast";
+import { fromMarkdown } from "mdast-util-from-markdown";
+
+/**
+ * Compile the TypeScript examples embedded in the prose docs into runnable
+ * tests, so a doc fence that drifts from the API fails CI. Every ```ts fence in
+ * the scanned Markdown becomes a `test(...)` in a generated
+ * `src/doc-test/__generated__/<Name>.test.ts`; the file is typechecked by
+ * `tsc` and executed by `node --test` exactly like a hand-written test.
+ *
+ * Usage: node --strip-types scripts/create-doc-tests.ts
+ *
+ * Why regenerate-then-typecheck instead of a lint plugin: development/docs.md §
+ * Validating Markdown code fences. The repo is TypeScript 7 (the native
+ * compiler), which does not expose the legacy JS compiler API, so the only
+ * faithful check is to emit real `.ts` files and let the existing `check:tsc` /
+ * `node --test` pipeline judge them.
+ */
+
+/** The package's public entry, as spelled inside the examples. */
+const LIBRARY_SOURCE = "tiny-pattern-ts";
+
+/** Matches the library specifier (single- or double-quoted) inside an import. */
+const LIBRARY_SPECIFIER = new RegExp(
+    `(?<quote>["'])${LIBRARY_SOURCE}\\k<quote>`,
+    "g",
+);
+
+/**
+ * A source specifier resolved to `src/index.ts` by `package.json#imports`.
+ * Examples import `from "tiny-pattern-ts"`, which neither `node` nor `tsc`
+ * resolves to source before `dist/` exists, so the generator rewrites it.
+ */
+const PRELUDE_IMPORT_SOURCE = "#test-tiny-pattern-ts";
+
+/** Markdown files to scan, relative to the repo root. */
+const SOURCES = ["README.md", "CONTRIBUTING.md"];
+
+/** Directory the generated tests are written to (gitignored contents). */
+const OUTPUT_DIR = "src/doc-test/__generated__";
+
+/** Fences whose info-string matches one of these are compiled; others skipped. */
+const TYPESCRIPT_LANGS: ReadonlySet<string> = new Set(["ts", "typescript"]);
+
+/**
+ * Modules the generated file already imports. An example that imports one of
+ * these would collide with the prelude binding (duplicate `test` / `assert`), so
+ * it is surfaced as a fatal error and the example is rewritten.
+ */
+const PRELUDE_MODULES: ReadonlySet<string> = new Set([
+    "node:assert",
+    "node:test",
+]);
+
+/** One line of the prelude every generated file starts with. */
+const PRELUDE_TEST = 'import { test } from "node:test";';
+const PRELUDE_ASSERT = 'import { strict as assert } from "node:assert";';
+
+/** Indentation applied to every fence body line inside the `test` callback. */
+const INDENT = "    ";
+
+const EMPTY = "";
+const INITIAL_COUNT = 0;
+const WRITE_INCREMENT = 1;
+const FIRST_ITEM = 0;
+const FAILURE_EXIT_CODE = 1;
+
+/** Strip all leading blank lines so the import scan starts at real content. */
+const LEADING_BLANK_LINES = /^(?:[ \t]*\r?\n)+/;
+/** Collapse the plain text of a title paragraph to one line. */
+const WHITESPACE = /\s+/g;
+/** Split an info-string like `ts title="x"` into its bare language. */
+const LANG_SEPARATOR = /\s+/;
+
+/** One leading `import` statement, including a multi-line named import. */
+const IMPORT_STATEMENT =
+    /^import\s+(?:(?:type\s+)?[\w$*{}\s,]+?\s+from\s+)?["'][^"'\n]+["']\s*;?[ \t]*(?:\r?\n|$)/;
+
+/** `import { a, b } from "src";`, with an optional `type` keyword. */
+const NAMED_IMPORT =
+    /^import\s+(?<isType>type\s+)?\{(?<specifiers>[^}]*)\}\s+from\s+["'](?<source>[^"']+)["']\s*;?$/;
+
+/** The module in a `… from "src"` statement. */
+const FROM_SOURCE = /from\s+["'](?<source>[^"']+)["']/;
+
+/** The module in a side-effect `import "src"` statement. */
+const SIDE_EFFECT_SOURCE = /^import\s+["'](?<source>[^"']+)["']/;
+
+type Block = Root["children"][number];
+
+class DocTestError extends Error {
+    public constructor(message: string) {
+        super(message);
+        this.name = "DocTestError";
+    }
+}
+
+/** Merge named specifiers that target the same module into one import. */
+interface NamedImportGroup {
+    readonly source: string;
+    readonly isType: boolean;
+    readonly names: string[];
+}
+
+/** One compiled fence, ready to be wrapped in a `test(...)`. */
+interface DocCase {
+    readonly title: string;
+    readonly body: string;
+}
+
+/** Accumulator threaded through the Markdown walk. */
+interface BuilderState {
+    readonly named: Map<string, NamedImportGroup>;
+    readonly passthrough: Set<string>;
+    readonly cases: DocCase[];
+    title: string | undefined;
+}
+
+/** Read one capture group, tolerating the type-level `groups` optionality. */
+const groupOf = (match: RegExpExecArray, name: string): string | undefined => {
+    const { groups } = match;
+    return groups === undefined ? undefined : groups[name];
+};
+
+/** Recursively concatenate the literal text of a single inline node. */
+const inlineText = (node: PhrasingContent): string => {
+    if ("value" in node) {
+        return node.value;
+    }
+    if ("children" in node) {
+        return node.children.map(inlineText).join(EMPTY);
+    }
+    return EMPTY;
+};
+
+/** Render a paragraph/heading node to its plain text for use as a test title. */
+const textOf = (node: Paragraph | Heading): string =>
+    node.children.map(inlineText).join(EMPTY).replace(WHITESPACE, " ").trim();
+
+/**
+ * Split a fence into its leading `import` statements and the executable body.
+ * Only a contiguous run of imports at the very top is hoisted; anything after
+ * the first non-import line stays in the body verbatim.
+ */
+const splitImports = (code: string): { imports: string[]; body: string } => {
+    const imports: string[] = [];
+    let rest = code.replace(LEADING_BLANK_LINES, EMPTY);
+    let match = IMPORT_STATEMENT.exec(rest);
+    while (rest.startsWith("import") && match !== null) {
+        const statement = match[FIRST_ITEM] ?? EMPTY;
+        imports.push(statement.trim());
+        rest = rest.slice(statement.length).replace(LEADING_BLANK_LINES, EMPTY);
+        match = IMPORT_STATEMENT.exec(rest);
+    }
+    return { imports, body: rest.trim() };
+};
+
+/** The module an import statement points at, or `undefined` if unreadable. */
+const importSource = (statement: string): string | undefined => {
+    const fromMatch = FROM_SOURCE.exec(statement);
+    if (fromMatch !== null) {
+        return groupOf(fromMatch, "source");
+    }
+    const sideEffectMatch = SIDE_EFFECT_SOURCE.exec(statement);
+    return sideEffectMatch === null
+        ? undefined
+        : groupOf(sideEffectMatch, "source");
+};
+
+/**
+ * Reject an example that imports a harness-provided module, then rewrite the
+ * library specifier to the source alias so the emitted file resolves.
+ */
+const normalizeImport = (statement: string): string => {
+    const source = importSource(statement);
+    if (source !== undefined && PRELUDE_MODULES.has(source)) {
+        throw new DocTestError(
+            `example imports "${source}", which the harness injects; remove the line:\n  ${statement.trim()}`,
+        );
+    }
+    return statement.replace(
+        LIBRARY_SPECIFIER,
+        `$<quote>${PRELUDE_IMPORT_SOURCE}$<quote>`,
+    );
+};
+
+/** Split the `{ a, b }` contents of a named import into trimmed specifiers. */
+const specifiersOf = (raw: string): string[] =>
+    raw
+        .split(",")
+        .map((name) => name.trim())
+        .filter((name) => name.length > INITIAL_COUNT);
+
+/** Add named specifiers to the group for `(isType, source)`, merging. */
+const addNamedImport = (
+    named: Map<string, NamedImportGroup>,
+    ref: Pick<NamedImportGroup, "source" | "isType">,
+    names: readonly string[],
+): void => {
+    const key = `${ref.isType ? "type:" : "value:"}${ref.source}`;
+    const existing = named.get(key);
+    if (existing === undefined) {
+        named.set(key, {
+            source: ref.source,
+            isType: ref.isType,
+            names: [...names],
+        });
+        return;
+    }
+    for (const name of names) {
+        if (!existing.names.includes(name)) {
+            existing.names.push(name);
+        }
+    }
+};
+
+/** Sort each hoisted import into a merged named group or a passthrough set. */
+const collectImports = (
+    statements: readonly string[],
+    named: Map<string, NamedImportGroup>,
+    passthrough: Set<string>,
+): void => {
+    for (const raw of statements) {
+        const statement = normalizeImport(raw);
+        const match = NAMED_IMPORT.exec(statement);
+        if (match === null) {
+            passthrough.add(statement);
+        } else {
+            addNamedImport(
+                named,
+                {
+                    source: groupOf(match, "source") ?? EMPTY,
+                    isType: groupOf(match, "isType") !== undefined,
+                },
+                specifiersOf(groupOf(match, "specifiers") ?? EMPTY),
+            );
+        }
+    }
+};
+
+/** Render the hoisted imports: merged named groups first, then the rest. */
+const renderImports = (
+    named: ReadonlyMap<string, NamedImportGroup>,
+    passthrough: ReadonlySet<string>,
+): string[] => {
+    const lines: string[] = [];
+    for (const group of named.values()) {
+        const keyword = group.isType ? "import type" : "import";
+        lines.push(
+            `${keyword} { ${group.names.join(", ")} } from "${group.source}";`,
+        );
+    }
+    for (const statement of passthrough) {
+        lines.push(statement);
+    }
+    return lines;
+};
+
+/** The bare language of a fence's info-string, e.g. `ts` in `ts title="x"`. */
+const typescriptLang = (code: Code): string =>
+    (code.lang ?? EMPTY).trim().split(LANG_SEPARATOR)[FIRST_ITEM] ?? EMPTY;
+
+/** Set the title a following fence will inherit. */
+const handleTitleNode = (
+    state: BuilderState,
+    node: Paragraph | Heading,
+): void => {
+    state.title = textOf(node);
+};
+
+/** Report and reset a non-TS fence that was skipped. */
+const skipFence = (state: BuilderState, name: string, code: Code): void => {
+    process.stderr.write(
+        `${name}: skipped non-TypeScript fence (lang="${code.lang ?? EMPTY}")\n`,
+    );
+    state.title = undefined;
+};
+
+/** Compile a described TS fence into a case, or reject it. */
+const compileFence = (
+    state: BuilderState,
+    name: string,
+    code: Code,
+): DocCase => {
+    const { title } = state;
+    if (title === undefined) {
+        const lang = typescriptLang(code);
+        throw new DocTestError(
+            `${name}: a \`\`\`${lang} fence has no preceding paragraph or ` +
+                `heading to use as its test title — describe the example.`,
+        );
+    }
+    const { imports, body } = splitImports(code.value);
+    collectImports(imports, state.named, state.passthrough);
+    return { title, body };
+};
+
+/** Compile one TS fence into a case, or reject/skip it. */
+const handleCodeNode = (
+    state: BuilderState,
+    name: string,
+    code: Code,
+): void => {
+    const lang = typescriptLang(code);
+    if (!TYPESCRIPT_LANGS.has(lang)) {
+        skipFence(state, name, code);
+        return;
+    }
+    state.cases.push(compileFence(state, name, code));
+};
+
+/** Route one Markdown block, preserving the "described fence" invariant. */
+const handleNode = (state: BuilderState, name: string, node: Block): void => {
+    if (node.type === "paragraph" || node.type === "heading") {
+        handleTitleNode(state, node);
+    } else if (node.type === "code") {
+        handleCodeNode(state, name, node);
+    } else {
+        // Only a paragraph/heading introduces a fence; any other block breaks
+        // the "immediately preceded" chain.
+        state.title = undefined;
+    }
+};
+
+/** Walk one Markdown file and collect its cases and hoisted imports. */
+const parseDoc = (
+    name: string,
+    markdown: string,
+): Omit<BuilderState, "title"> => {
+    const state: BuilderState = {
+        named: new Map(),
+        passthrough: new Set(),
+        cases: [],
+        title: undefined,
+    };
+    for (const node of fromMarkdown(markdown).children) {
+        handleNode(state, name, node);
+    }
+    return {
+        named: state.named,
+        passthrough: state.passthrough,
+        cases: state.cases,
+    };
+};
+
+/** Indent a fence body one level for the body of the `test` callback. */
+const indentBody = (body: string): string =>
+    body
+        .split("\n")
+        .map((line) =>
+            line.length > INITIAL_COUNT ? `${INDENT}${line}` : line,
+        )
+        .join("\n");
+
+/** Wrap one compiled fence in an executed `test(...)`. */
+const renderCase = (docCase: DocCase): string => {
+    const indented = indentBody(docCase.body);
+    return `test(${JSON.stringify(docCase.title)}, () => {\n${indented}\n});`;
+};
+
+/** Build the prelude + hoisted imports that top every generated file. */
+const buildHeader = (name: string, imports: readonly string[]): string[] => {
+    const header = [
+        "// Generated by scripts/create-doc-tests.ts — do not edit by hand.",
+        `// Source: ${name}`,
+        EMPTY,
+        PRELUDE_TEST,
+        PRELUDE_ASSERT,
+    ];
+    if (imports.length > INITIAL_COUNT) {
+        header.push(EMPTY, ...imports);
+    }
+    header.push(EMPTY);
+    return header;
+};
+
+/** Turn one Markdown file into the source of its generated test file. */
+const buildTestFile = (name: string, markdown: string): string => {
+    const parsed = parseDoc(name, markdown);
+    if (parsed.cases.length === INITIAL_COUNT) {
+        return EMPTY;
+    }
+    const imports = renderImports(parsed.named, parsed.passthrough);
+    const header = buildHeader(name, imports);
+    const blocks = parsed.cases.map(renderCase);
+    return `${header.join("\n")}\n${blocks.join("\n\n")}\n`;
+};
+
+/** Map a source Markdown path to its generated test path under OUTPUT_DIR. */
+const outputFor = (source: string): string =>
+    path.join(
+        OUTPUT_DIR,
+        `${path.basename(source, path.extname(source))}.test.ts`,
+    );
+
+/** Write a generated file when there is content, else clear a stale one. */
+const writeIfAny = (dest: string, name: string, out: string): boolean => {
+    if (out === EMPTY) {
+        process.stderr.write(`${name}: no TypeScript fences\n`);
+        fs.rmSync(dest, { force: true });
+        return false;
+    }
+    fs.writeFileSync(dest, out);
+    return true;
+};
+
+/** Generate the doc-test for one source; return whether a file was written. */
+const generateFor = (root: string, source: string): boolean => {
+    const abs = path.join(root, source);
+    if (!fs.existsSync(abs)) {
+        process.stderr.write(`skipped missing ${source}\n`);
+        return false;
+    }
+    const name = path.basename(source);
+    const out = buildTestFile(name, fs.readFileSync(abs, "utf8"));
+    return writeIfAny(path.join(root, outputFor(source)), name, out);
+};
+
+const main = (): void => {
+    const root = process.cwd();
+    fs.mkdirSync(path.join(root, OUTPUT_DIR), { recursive: true });
+    let written = INITIAL_COUNT;
+    for (const source of SOURCES) {
+        if (generateFor(root, source)) {
+            written += WRITE_INCREMENT;
+        }
+    }
+    process.stdout.write(
+        `created doc-tests for ${written} file(s) under ${OUTPUT_DIR}/\n`,
+    );
+};
+
+try {
+    main();
+} catch (error) {
+    if (error instanceof DocTestError) {
+        process.stderr.write(`${error.message}\n`);
+        process.exitCode = FAILURE_EXIT_CODE;
+    } else {
+        throw error;
+    }
+}

src/doc-test/README.md

@@ -0,0 +1,12 @@
+# Generated doc-tests
+
+`__generated__/` is the output of [`scripts/create-doc-tests.ts`](../../scripts/create-doc-tests.ts):
+each `*.test.ts` is compiled from the ```ts fences in a prose doc and is
+**gitignored**, not edited by hand. `npm run create:doc-tests` regenerates them,
+formats them with `oxfmt`, then type-checks them with
+[`tsconfig.json`](./tsconfig.json) — the scoped config that relaxes
+`noUnusedLocals` so example-only locals (and the injected `assert`) compile.
+
+CI regenerates them in an explicit step before `test:ci`; the fast local `test` /
+`verify` tiers do not. See [development/docs.md](../../development/docs.md) for why the
+generator is shaped this way.

src/doc-test/tsconfig.json

@@ -0,0 +1,10 @@
+{
+    "extends": "../../tsconfig.json",
+    "compilerOptions": {
+        "noEmit": true,
+        "noUnusedLocals": false,
+        "noUnusedParameters": false
+    },
+    "include": ["__generated__/**/*.test.ts"],
+    "exclude": []
+}

src/index.test.ts

@@ -0,0 +1,27 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+
+import { expectTypeOf } from "expect-type";
+
+import {
+    getPrimitiveUnionMatcher,
+    getPrimitiveUnionMatcherW,
+    getTaggedUnionMatcher,
+    getTaggedUnionMatcherW,
+} from "./index.ts";
+
+// The published entry point is the barrel (`package.json` exports
+// `./dist/index.js`), so every factory must be reachable from here. Importing it
+// also loads the module, which is what lets c8's `--all` measure it — see
+// development/ci.md § Coverage threshold.
+test("index: the public entry point re-exports every matcher factory", () => {
+    // Assert
+    expectTypeOf(getPrimitiveUnionMatcher).toBeFunction();
+    assert.equal(typeof getPrimitiveUnionMatcher, "function");
+    expectTypeOf(getPrimitiveUnionMatcherW).toBeFunction();
+    assert.equal(typeof getPrimitiveUnionMatcherW, "function");
+    expectTypeOf(getTaggedUnionMatcher).toBeFunction();
+    assert.equal(typeof getTaggedUnionMatcher, "function");
+    expectTypeOf(getTaggedUnionMatcherW).toBeFunction();
+    assert.equal(typeof getTaggedUnionMatcherW, "function");
+});

src/index.ts

@@ -1,3 +1,11 @@
+/**
+ * The public entry point of `tiny-pattern-ts`.
+ *
+ * Exports the four matcher factories and nothing else; the builder types they
+ * return and the rest of `src/` are implementation detail.
+ *
+ * @module
+ */
 export {
     getPrimitiveUnionMatcher,
     getPrimitiveUnionMatcherW,

src/matcher-shared.ts

@@ -1,3 +1,4 @@
+/* c8 ignore start -- types only: the module has no runtime image to cover */
 import type { IsLiteral, IsNever, ValueOf } from "type-fest";
 
 // The primitive-union and tagged-union matchers differ in their universe, but the
@@ -62,11 +63,11 @@ export type Collisions<T> = Extract<T, Stringified<T>>;
 // universe is a finite union of literals with no value/stringification
 // collision: only then can `PatternKey` be inverted unambiguously.
 export type UnsupportedReason<T extends Matchable> =
-    IsLiteral<PatternKey<T>> extends false
+    IsLiteral<PatternKey<T>> extends true
-        ? "broad types like string, number and template literals are not supported"
+        ? [Collisions<T>] extends [never]
-        : [Collisions<T>] extends [never]
+            ? never
-          ? never
+            : `a value and its stringification collide. Value is "${Collisions<T> & string}"`
-          : `a value and its stringification collide. Value is "${Collisions<T> & string}"`;
+        : "broad types like string, number and template literals are not supported";
 
 // The diagnostic for an unsupported universe. Extends `HandlerMap` so the
 // implementation's `handlers: HandlerMap` stays assignable when the gate is

src/primitive-union.test.ts

@@ -528,6 +528,8 @@ test("getPrimitiveUnionMatcher: a broad universe is rejected", () => {
     getPrimitiveUnionMatcher<number>()({ 1: () => 1 });
     // @ts-expect-error a template literal is open
     getPrimitiveUnionMatcher<`a${string}`>()({ a: () => 1 });
+    // @ts-expect-error a literal mixed with a template literal is open
+    getPrimitiveUnionMatcher<"a" | `x-${number}`>()({ a: () => 1 });
     // @ts-expect-error `string | boolean` is open because of `string`
     getPrimitiveUnionMatcher<string | boolean>()({ true: () => 1 });
     // @ts-expect-error the widening factory rejects broad universes too

src/primitive-union.ts

@@ -96,9 +96,50 @@ const dispatch =
             shape as never,
         );
 
+/**
+ * Create a matcher for a finite primitive universe, with one common return
+ * type.
+ *
+ * Use it when the value itself is the union (`"yes" | "no"`) and every handler
+ * returns the same type.
+ *
+ * The returned builder takes a handler map keyed by the members; supplying a
+ * second fallback argument allows a partial map and receives the unhandled
+ * remainder.
+ *
+ * @typeParam T - The finite universe of primitive members to match.
+ * @returns A builder for the handler map, or the handler map plus a fallback.
+ * @example
+ *     const matchAnswer = getPrimitiveUnionMatcher<"yes" | "no">();
+ *     const describe = matchAnswer({
+ *         yes: () => "agreed",
+ *         no: () => "declined",
+ *     });
+ *     describe("yes"); // "agreed"
+ */
 export const getPrimitiveUnionMatcher = <
     T extends Matchable,
 >(): PrimitiveUnionMatcherStrict<T> => dispatch;
+
+/**
+ * Create a matcher for a finite primitive universe whose return type is the
+ * union of every handler's return type.
+ *
+ * Use it when the value itself is the union (`"yes" | "no"`) and the handlers
+ * return different types. The `W` (widening) counterpart of
+ * {@link getPrimitiveUnionMatcher}; the universe constraint and the optional
+ * fallback are identical.
+ *
+ * @typeParam T - The finite universe of primitive members to match.
+ * @returns A builder for the handler map, or the handler map plus a fallback.
+ * @example
+ *     const matchReply = getPrimitiveUnionMatcherW<"yes" | "no">();
+ *     const reply = matchReply({
+ *         yes: () => 1,
+ *         no: () => "declined",
+ *     });
+ *     // reply: (shape: "yes" | "no") => number | string
+ */
 export const getPrimitiveUnionMatcherW = <
     T extends Matchable,
 >(): PrimitiveUnionMatcherWidening<T> => dispatch;

src/tagged-union.test.ts

@@ -892,6 +892,434 @@ test("getTaggedUnionMatcher: the maximum illegal tag universe is rejected", () =
     });
 });
 
+// ============================================================================
+// Property unions
+// ============================================================================
+
+test("property union: narrows each handler", () => {
+    // Arrange — one shape, not a union of variants; `color` is a union.
+    interface Paint {
+        readonly color: "red" | "green" | "blue";
+        readonly value: number;
+    }
+    const factory = getTaggedUnionMatcher<Paint>()("color");
+
+    // Act
+    const describe = factory({
+        red: (s) => {
+            expectTypeOf(s).toEqualTypeOf<{
+                readonly color: "red";
+                readonly value: number;
+            }>();
+            assert.equal(s.color, "red");
+            return s.value;
+        },
+        green: (s) => {
+            expectTypeOf(s).toEqualTypeOf<{
+                readonly color: "green";
+                readonly value: number;
+            }>();
+            assert.equal(s.color, "green");
+            return s.value;
+        },
+        blue: (s) => {
+            expectTypeOf(s).toEqualTypeOf<{
+                readonly color: "blue";
+                readonly value: number;
+            }>();
+            assert.equal(s.color, "blue");
+            return s.value;
+        },
+    });
+
+    // Assert
+    expectTypeOf(describe).toEqualTypeOf<(shape: Paint) => number>();
+    assert.equal(describe({ color: "red", value: 1 }), 1);
+    assert.equal(describe({ color: "green", value: 2 }), 2);
+    assert.equal(describe({ color: "blue", value: 3 }), 3);
+});
+
+test("property union: a fallback receives the unhandled values", () => {
+    // Arrange
+    interface Paint {
+        color: "red" | "green" | "blue";
+        value: number;
+    }
+    const factory = getTaggedUnionMatcher<Paint>()("color");
+
+    // Act
+    const describe = factory(
+        {
+            red: (s) => {
+                expectTypeOf(s).toEqualTypeOf<{
+                    color: "red";
+                    value: number;
+                }>();
+                assert.equal(s.color, "red");
+                return 1 as const;
+            },
+        },
+        (s) => {
+            expectTypeOf(s).toEqualTypeOf<{
+                color: "green" | "blue";
+                value: number;
+            }>();
+            assert.ok(s.color === "green" || s.color === "blue");
+            return 2 as const;
+        },
+    );
+
+    // Assert
+    expectTypeOf(describe).toEqualTypeOf<(shape: Paint) => 1 | 2>();
+    assert.equal(describe({ color: "red", value: 1 }), 1);
+    assert.equal(describe({ color: "green", value: 2 }), 2);
+    assert.equal(describe({ color: "blue", value: 3 }), 2);
+});
+
+test("property union: a numeric property narrows each handler", () => {
+    // Arrange
+    interface Version {
+        code: 1 | 2 | 3;
+        value: number;
+    }
+    const factory = getTaggedUnionMatcher<Version>()("code");
+
+    // Act
+    const describe = factory({
+        1: (s) => {
+            expectTypeOf(s).toEqualTypeOf<{ code: 1; value: number }>();
+            assert.equal(s.code, 1);
+            return 1;
+        },
+        2: (s) => {
+            expectTypeOf(s).toEqualTypeOf<{ code: 2; value: number }>();
+            assert.equal(s.code, 2);
+            return 2;
+        },
+        3: (s) => {
+            expectTypeOf(s).toEqualTypeOf<{ code: 3; value: number }>();
+            assert.equal(s.code, 3);
+            return 3;
+        },
+    });
+
+    // Assert
+    expectTypeOf(describe).toEqualTypeOf<(shape: Version) => number>();
+    assert.equal(describe({ code: 1, value: 10 }), 1);
+    assert.equal(describe({ code: 2, value: 20 }), 2);
+    assert.equal(describe({ code: 3, value: 30 }), 3);
+});
+
+test("property union: an optional property is required for a defined tag", () => {
+    // Arrange — `type?` is `"x" | undefined`; both handlers must be typed,
+    // and matching `"x"` proves the key is present, so `type` becomes required.
+    interface Maybe {
+        type?: "x";
+        value: number;
+    }
+    const factory = getTaggedUnionMatcher<Maybe>()("type");
+
+    // Act
+    const describe = factory({
+        x: (s) => {
+            expectTypeOf(s).toEqualTypeOf<{ type: "x"; value: number }>();
+            assert.equal(s.type, "x");
+            return 1;
+        },
+        undefined: (s) => {
+            // The input only allows absence (exactOptionalPropertyTypes), so
+            // the `undefined` tag narrows the key to never-present.
+            expectTypeOf(s).toEqualTypeOf<{ type?: never; value: number }>();
+            assert.equal(s.type, undefined);
+            return 2;
+        },
+    });
+
+    // Assert
+    expectTypeOf(describe).toEqualTypeOf<(shape: Maybe) => number>();
+    assert.equal(describe({ type: "x", value: 1 }), 1);
+    assert.equal(describe({ value: 2 }), 2);
+});
+
+test("property union: an optional fallback receives the undefined tag", () => {
+    // Arrange
+    interface Maybe {
+        type?: "x";
+        value: number;
+    }
+    const factory = getTaggedUnionMatcher<Maybe>()("type");
+
+    // Act
+    const describe = factory(
+        {
+            x: (s) => {
+                expectTypeOf(s).toEqualTypeOf<{ type: "x"; value: number }>();
+                assert.equal(s.type, "x");
+                return 1 as const;
+            },
+        },
+        (s) => {
+            expectTypeOf(s).toEqualTypeOf<{
+                type?: never;
+                value: number;
+            }>();
+            assert.equal(s.type, undefined);
+            return 2 as const;
+        },
+    );
+
+    // Assert
+    expectTypeOf(describe).toEqualTypeOf<(shape: Maybe) => 1 | 2>();
+    assert.equal(describe({ type: "x", value: 1 }), 1);
+    assert.equal(describe({ value: 2 }), 2);
+});
+
+test("property union: explicit `undefined` stays distinct from absence", () => {
+    // Arrange — `type?: "x" | undefined` admits an explicit `undefined`, unlike
+    // the bare optional above; the two representations must not be conflated.
+    interface Explicit {
+        type?: "x" | undefined;
+        value: number;
+    }
+    const factory = getTaggedUnionMatcher<Explicit>()("type");
+
+    // Act
+    const describe = factory({
+        x: (s) => {
+            expectTypeOf(s).toEqualTypeOf<{ type: "x"; value: number }>();
+            assert.equal(s.type, "x");
+            return 1;
+        },
+        undefined: (s) => {
+            expectTypeOf(s).toEqualTypeOf<{
+                type?: undefined;
+                value: number;
+            }>();
+            assert.equal(s.type, undefined);
+            return 2;
+        },
+    });
+
+    // Assert
+    expectTypeOf(describe).toEqualTypeOf<(shape: Explicit) => number>();
+    assert.equal(describe({ type: "x", value: 1 }), 1);
+    assert.equal(describe({ type: undefined, value: 2 }), 2);
+    assert.equal(describe({ value: 3 }), 2);
+});
+
+test("property union: a union-valued member is split, not dropped", () => {
+    // A member whose tag is itself a union sits beside a singleton-tag member.
+    // Selecting members with `Extract<T, Record<K, V>>` keeps only the
+    // singleton; the distributive narrowing must keep both sides of the
+    // union-valued member.
+    // Arrange
+    type Mixed = { kind: "a"; a: number } | { kind: "a" | "b"; b: number };
+    const factory = getTaggedUnionMatcher<Mixed>()("kind");
+
+    // Act
+    const describe = factory({
+        a: (s) => {
+            expectTypeOf(s).toEqualTypeOf<
+                { kind: "a"; a: number } | { kind: "a"; b: number }
+            >();
+            assert.equal(s.kind, "a");
+            return 1;
+        },
+        b: (s) => {
+            expectTypeOf(s).toEqualTypeOf<{ kind: "b"; b: number }>();
+            assert.equal(s.kind, "b");
+            return 2;
+        },
+    });
+
+    // Assert
+    expectTypeOf(describe).toEqualTypeOf<(shape: Mixed) => number>();
+    assert.equal(describe({ kind: "a", a: 1 }), 1);
+    assert.equal(describe({ kind: "a", b: 2 }), 1);
+    assert.equal(describe({ kind: "b", b: 3 }), 2);
+});
+
+test("property union: getTaggedUnionMatcherW widens the returns", () => {
+    // Arrange
+    interface Paint {
+        color: "red" | "green" | "blue";
+        value: number;
+    }
+    const factory = getTaggedUnionMatcherW<Paint>()("color");
+
+    // Act
+    const describe = factory({
+        red: (s) => {
+            expectTypeOf(s).toEqualTypeOf<{ color: "red"; value: number }>();
+            assert.equal(s.color, "red");
+            return "r" as const;
+        },
+        green: (s) => {
+            expectTypeOf(s).toEqualTypeOf<{ color: "green"; value: number }>();
+            assert.equal(s.color, "green");
+            return 1 as const;
+        },
+        blue: (s) => {
+            expectTypeOf(s).toEqualTypeOf<{ color: "blue"; value: number }>();
+            assert.equal(s.color, "blue");
+            return true as const;
+        },
+    });
+
+    // Assert
+    expectTypeOf(describe).toEqualTypeOf<(shape: Paint) => "r" | 1 | true>();
+    assert.equal(describe({ color: "red", value: 1 }), "r");
+    assert.equal(describe({ color: "green", value: 2 }), 1);
+    assert.equal(describe({ color: "blue", value: 3 }), true);
+});
+
+test("property union: enforces its contract", () => {
+    // Arrange
+    interface Paint {
+        color: "red" | "green" | "blue";
+        value: number;
+    }
+    const factory = getTaggedUnionMatcher<Paint>()("color");
+
+    // Act / Assert — the calls below must not compile
+    factory({
+        red: () => 1,
+        green: () => 2,
+        blue: () => 3,
+        // @ts-expect-error `yellow` is not a value of `color`
+        yellow: () => 4,
+    });
+    // @ts-expect-error a gap without a fallback is not exhaustive
+    factory({ red: () => 1 });
+    // @ts-expect-error a fallback is redundant once every value is handled
+    factory({ red: () => 1, green: () => 2, blue: () => 3 }, () => 0);
+});
+
+test("property union: a broad value in the union is rejected", () => {
+    // Arrange — the property is a union, but not a finite union of literals: a
+    // template literal cannot be proven exhaustive.
+    interface Template {
+        kind: "a" | `x-${number}`;
+        a: number;
+    }
+
+    // Act / Assert — the calls below must not compile
+    // @ts-expect-error a template literal is not a finite literal
+    getTaggedUnionMatcher<Template>()("kind")({ a: () => 1 });
+    // @ts-expect-error the widening factory rejects broad values too
+    getTaggedUnionMatcherW<Template>()("kind")({ a: () => 1 });
+});
+
+test("property union: a value/stringification collision is rejected", () => {
+    // Arrange — one property holding both a value and its stringification; both
+    // would key the same handler.
+    interface BooleanColliding {
+        kind: "true" | true;
+        a: number;
+    }
+    interface NumericColliding {
+        kind: "1" | 1;
+        a: number;
+    }
+
+    // Act / Assert — the calls below must not compile
+    // @ts-expect-error `true` collides with the string tag `"true"`
+    getTaggedUnionMatcher<BooleanColliding>()("kind")({ true: () => 1 });
+    // @ts-expect-error the number tag `1` collides with the string tag `"1"`
+    getTaggedUnionMatcher<NumericColliding>()("kind")({ "1": () => 1 });
+    // @ts-expect-error the widening factory rejects the collision too
+    getTaggedUnionMatcherW<BooleanColliding>()("kind")({ true: () => 1 });
+});
+
+test("property union: a collision is rejected beside legal members", () => {
+    // Arrange — the map is otherwise complete, so only the collision can make
+    // it invalid.
+    interface Colliding {
+        kind: "true" | true | "a";
+        a: number;
+    }
+
+    // Act / Assert — the call below must not compile
+    // @ts-expect-error `true` collides with the string tag `"true"`
+    getTaggedUnionMatcher<Colliding>()("kind")({ true: () => 1, a: () => 2 });
+});
+
+// ============================================================================
+// Duplicate tags
+// ============================================================================
+
+// A tag is a discriminant only while it is unique across the union. Two members
+// may still share one: the tag set `Tags<T, K>` dedupes, so a single handler is
+// exhaustive for both and receives their union. This is the documented known
+// issue (development/library.md § Tagged-union matcher); the tests below pin the
+// behavior so it cannot change silently.
+
+test("duplicate tag: members sharing a tag collapse to one handler", () => {
+    // Arrange — `kind` is not a true discriminant: both members carry `"a"`.
+    interface First {
+        readonly kind: "a";
+        readonly first: number;
+    }
+    interface Second {
+        readonly kind: "a";
+        readonly second: string;
+    }
+    type Clashing = First | Second;
+    const factory = getTaggedUnionMatcher<Clashing>()("kind");
+
+    // Act
+    const pick = factory({
+        a: (s) => {
+            // The shared tag cannot be split, so the handler sees both members.
+            expectTypeOf(s).toEqualTypeOf<First | Second>();
+            assert.equal(s.kind, "a");
+            return "first" in s ? s.first : s.second.length;
+        },
+    });
+
+    // Assert — the one `a` key is exhaustive and both members reach it.
+    expectTypeOf(pick).toEqualTypeOf<(shape: Clashing) => number>();
+    assert.equal(pick({ kind: "a", first: 1 }), 1);
+    assert.equal(pick({ kind: "a", second: "abc" }), 3);
+});
+
+test("duplicate tag: handling one tag consumes every member that shares it", () => {
+    // Arrange — `"a"` selects two members; `"c"` selects one.
+    type Mixed =
+        | { readonly kind: "a"; readonly a: number }
+        | { readonly kind: "a"; readonly b: string }
+        | { readonly kind: "c"; readonly c: boolean };
+    const factory = getTaggedUnionMatcher<Mixed>()("kind");
+
+    // Act
+    const describe = factory(
+        {
+            a: (s) => {
+                expectTypeOf(s).toEqualTypeOf<
+                    | { readonly kind: "a"; readonly a: number }
+                    | { readonly kind: "a"; readonly b: string }
+                >();
+                return 1 as const;
+            },
+        },
+        (s) => {
+            // Handling `"a"` removes both of its members, not just one.
+            expectTypeOf(s).toEqualTypeOf<{
+                readonly kind: "c";
+                readonly c: boolean;
+            }>();
+            assert.equal(s.kind, "c");
+            return 2 as const;
+        },
+    );
+
+    // Assert
+    expectTypeOf(describe).toEqualTypeOf<(shape: Mixed) => 1 | 2>();
+    assert.equal(describe({ kind: "a", a: 1 }), 1);
+    assert.equal(describe({ kind: "a", b: "x" }), 1);
+    assert.equal(describe({ kind: "c", c: true }), 2);
+});
+
 // ============================================================================
 // Dispatch — runtime behavior
 // ============================================================================
@@ -935,6 +1363,7 @@ interface LabelsProbe {
     readonly tail?: string;
     readonly typeName?: string;
     readonly typeSource?: string;
+    readonly key?: string;
 }
 
 const labelsFor = ({
@@ -944,6 +1373,7 @@ const labelsFor = ({
     tail = "",
     typeName = "Shape",
     typeSource = SHAPE_SOURCE,
+    key = "kind",
 }: LabelsProbe): Promise<readonly string[]> => {
     const session = new LspSession(REPO_ROOT);
     const target: CompletionTarget = {
@@ -951,7 +1381,7 @@ const labelsFor = ({
         source: [
             `import { ${factory} } from "./index.ts";`,
             typeSource,
-            `const m = ${factory}<${typeName}>()("kind")({`,
+            `const m = ${factory}<${typeName}>()("${key}")({`,
             body,
             `}${tail});`,
             "",
@@ -1038,6 +1468,91 @@ test("autocomplete: boolean and nullish tags are offered by name", () => {
     });
 });
 
+// A single shape whose property is a union: the popup is still keyed by the
+// property's values, not by the members of a union type.
+const PALETTE_SOURCE = `interface Palette { color: "red" | "green" | "blue"; value: number }`;
+const FLAG_SOURCE = `interface Flag { kind: true | false | null | undefined; a: number }`;
+
+test("property union: autocomplete offers the property's values", () => {
+    // Arrange
+    const name = "property_union_fresh";
+
+    // Act
+    const labels = labelsFor({
+        name,
+        factory: "getTaggedUnionMatcher",
+        typeName: "Palette",
+        typeSource: PALETTE_SOURCE,
+        key: "color",
+        body: "    /*COMPLETE*/",
+    });
+
+    // Assert
+    return labels.then((result) => {
+        assert.deepEqual([...result], ["blue", "green", "red"]);
+    });
+});
+
+test("property union: autocomplete drops a handled value", () => {
+    // Arrange
+    const name = "property_union_after_key";
+
+    // Act
+    const labels = labelsFor({
+        name,
+        factory: "getTaggedUnionMatcher",
+        typeName: "Palette",
+        typeSource: PALETTE_SOURCE,
+        key: "color",
+        body: "    red: () => 1,\n    /*COMPLETE*/",
+    });
+
+    // Assert
+    return labels.then((result) => {
+        assert.deepEqual([...result], ["blue", "green"]);
+    });
+});
+
+test("property union: autocomplete makes the remaining values optional with a fallback", () => {
+    // Arrange
+    const name = "property_union_with_fallback";
+
+    // Act
+    const labels = labelsFor({
+        name,
+        factory: "getTaggedUnionMatcher",
+        typeName: "Palette",
+        typeSource: PALETTE_SOURCE,
+        key: "color",
+        body: "    /*COMPLETE*/",
+        tail: ", () => 0",
+    });
+
+    // Assert
+    return labels.then((result) => {
+        assert.deepEqual([...result], ["blue?", "green?", "red?"]);
+    });
+});
+
+test("property union: autocomplete offers boolean and nullish values by name", () => {
+    // Arrange
+    const name = "property_union_boolean_nullish";
+
+    // Act
+    const labels = labelsFor({
+        name,
+        factory: "getTaggedUnionMatcher",
+        typeName: "Flag",
+        typeSource: FLAG_SOURCE,
+        body: "    /*COMPLETE*/",
+    });
+
+    // Assert
+    return labels.then((result) => {
+        assert.deepEqual([...result], ["false", "null", "true", "undefined"]);
+    });
+});
+
 // `Mixed` has two common keys, but `id`'s value is not a tag, so only `kind`
 // may serve as the discriminant.
 const MIXED_SOURCE = `type Mixed = { id: Date; kind: "a"; a: number } | { id: Date; kind: "b"; b: number };`;

src/tagged-union.ts

@@ -1,4 +1,4 @@
-import type { Exact, UnknownRecord } from "type-fest";
+import type { Exact, SetRequired, UnknownRecord } from "type-fest";
 
 import type {
     HandlerMap,
@@ -28,34 +28,49 @@ type Discriminated<T extends object> = {
     [K in keyof T]: T[K] extends Matchable ? K : never;
 }[keyof T];
 
-// The member(s) of `T` tagged `V`. `Extract` distributes over the union, so a
+// The member(s) of `T` narrowed to the tag(s) `V`. Distributes over `T`, so a
 // duplicated tag maps to a union of members rather than silently dropping one.
+// A member whose `K` cannot take `V` drops out; the rest have `K` narrowed to
+// `Extract<T[K], V>`. `T[K] extends V` keeps an exact member (a discriminated
+// union's declared interface) untouched, so only a property that is itself a
+// union — or optional — goes through the mapped form. `SetRequired` makes `K`
+// required unless `V` admits `undefined`: a defined tag yields `{ type: "x" }`,
+// while the `undefined` tag keeps `{ type?: never }` (absence) or
+// `{ type?: undefined }` when the property admits an explicit `undefined`.
 // Keyed by `PatternKey`, so `boolean`/`null`/`undefined` tags can key a mapped
-// type; `Member` inverts the projection against the tag set to recover the
+// type; `Member` inverts the projection against the tag set to recover the tag.
-// member.
+type Narrowed<T extends object, K extends keyof T, V> = T extends object
+    ? [Extract<T[K], V>] extends [never]
+        ? never
+        : T[K] extends V
+          ? T
+          : undefined extends V
+            ? { [P in keyof T]: P extends K ? Extract<T[P], V> : T[P] }
+            : SetRequired<
+                  { [P in keyof T]: P extends K ? Extract<T[P], V> : T[P] },
+                  K
+              >
+    : never;
+
 type MapTaggedUnion<T extends object, K extends keyof T> = {
-    [P in PatternKey<Tags<T, K>>]: Extract<T, Record<K, Member<Tags<T, K>, P>>>;
+    [P in PatternKey<Tags<T, K>>]: Narrowed<T, K, Member<Tags<T, K>, P>>;
 };
 
 type Handlers<T extends object, K extends keyof T, R> = {
     [P in PatternKey<Tags<T, K>>]: UnaryFn<MapTaggedUnion<T, K>[P], R>;
 };
 
-// The members `Handled` covers. Mapping over the projected keys keeps every
+// The tag values whose `PatternKey` is handled.
-// index within `MapTaggedUnion`'s keys, and the conditional drops a stray key
+type HandledTags<T extends object, K extends keyof T, Handled> = Member<
-// outside `T` so it cannot widen the remainder. The remainder is
+    Tags<T, K>,
-// `Exclude<T, …>`, mirroring the primitive-union matcher's
+    keyof Handled
-// `Exclude<T, Member<T, keyof Handled>>`.
+>;
-type HandledMembers<T extends object, K extends keyof T, Handled> = {
-    [P in PatternKey<Tags<T, K>>]: P extends keyof Handled
-        ? MapTaggedUnion<T, K>[P]
-        : never;
-}[PatternKey<Tags<T, K>>];
 
 // The fallback is a *second argument*, not a property of the handler map, so
-// its parameter can be the remainder the map left uncovered. See development/library.md.
+// its parameter can be the remainder the map left uncovered: the members
+// narrowed to the tags the map did not handle. See development/library.md.
 type Fallback<T extends object, K extends keyof T, Handled, R> = UnaryFn<
-    Exclude<T, HandledMembers<T, K, Handled>>,
+    Narrowed<T, K, Exclude<Tags<T, K>, HandledTags<T, K, Handled>>>,
     R
 >;
 
@@ -137,10 +152,56 @@ const dispatch =
         );
     };
 
+/**
+ * Create a matcher for a discriminated union, with one common return type.
+ *
+ * Use it when the value is an object discriminated by a property
+ * (`{ kind: "circle" } | { kind: "square" }`) and every handler returns the
+ * same type.
+ *
+ * The first call fixes the union `T`; the returned function takes the
+ * discriminant property's name (`K`, restricted to properties whose values are
+ * tags), and that returns the handler-map builder. Supplying a second fallback
+ * argument to the builder allows a partial map and receives the members whose
+ * tag was not handled. A `boolean`, `null` or `undefined` tag is keyed by its
+ * stringified form (`true` -> `"true"`); see README § Caveats.
+ *
+ * @typeParam T - The discriminated-union type to match.
+ * @returns A function that takes the discriminant property's name.
+ * @example
+ *     type Shape =
+ *         | { kind: "circle"; radius: number }
+ *         | { kind: "square"; side: number };
+ *
+ *     const matchShape = getTaggedUnionMatcher<Shape>()("kind");
+ *     const area = matchShape({
+ *         circle: (s) => Math.PI * s.radius ** 2,
+ *         square: (s) => s.side ** 2,
+ *     });
+ */
 export const getTaggedUnionMatcher = <
     T extends object,
 >(): TaggedUnionMatcherFactory<T> => dispatch;
 
+/**
+ * Create a matcher for a discriminated union whose return type is the union of
+ * every handler's return type.
+ *
+ * Use it when the value is a discriminated object and the handlers return
+ * different types. The `W` (widening) counterpart of
+ * {@link getTaggedUnionMatcher}; the curried key step and the optional fallback
+ * are identical.
+ *
+ * @typeParam T - The discriminated-union type to match.
+ * @returns A function that takes the discriminant property's name.
+ * @example
+ *     const matchShape = getTaggedUnionMatcherW<Shape>()("kind");
+ *     const describe = matchShape({
+ *         circle: () => "round",
+ *         square: () => 4,
+ *     });
+ *     // describe: (shape: Shape) => string | number
+ */
 export const getTaggedUnionMatcherW = <
     T extends object,
 >(): TaggedUnionMatcherWideningFactory<T> => dispatch;

tsconfig.json

@@ -8,5 +8,6 @@
         "allowImportingTsExtensions": true,
         "verbatimModuleSyntax": true
     },
-    "include": ["src", "scripts"]
+    "include": ["src", "scripts"],
+    "exclude": ["src/doc-test"]
 }