🚀 Release 0.8.2

🔀 Merge chore/readme-comparison into main
📝 Add an alternatives section
2026-09-25 23:20:02 +00:00 · 2026-09-25 23:17:33 +00:00 · 2026-09-25 23:16:14 +00:00 · 2026-09-24 21:56:33 +00:00 · 2026-09-24 21:55:51 +00:00 · 2026-09-24 20:51:42 +00:00
31 changed files with 2775 additions and 559 deletions
@@ -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
@@ -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
@@ -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.
@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ## [Unreleased]

+## [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
+
 ## [0.7.0] - 2026-09-23

 - reject broad universes (`string`, `number`, template literals) and
@@ -82,7 +108,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.0...main
+[Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.8.2...main
+[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
 [0.5.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.4.0...0.5.0
@@ -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
-  rather than the source. `create:branch` opens a unit of work, `create:finish`
+- `create:*` — front doors of the repo's own workflow; these produce or mutate
+  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
@@ -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
@@ -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
-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
-not a macro: there is no transpiler and no DSL to learn, and the type-level
-contract is the feature — see [development/library.md](./development/library.md)
-for the design decisions and [Caveats](#caveats) for the limits.
+`tiny-pattern-ts` is a pattern-matching library for TypeScript.
+
+The main goal of `tiny-pattern-ts` is to make pattern matching type-safe with a
+lean syntax. This is accomplished by being exhaustive and passing typed
+parameters per branch to the handlers — supported by an outstanding
+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

@@ -6,89 +6,33 @@ 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
+✔ API surface is stable and fully typed @done
+    ✔ Finalize public exports in `src/index.ts` @done
+    ✔ Document all exported types and functions @done
+    ✔ Add JSDoc for public APIs @done
+✔ Test coverage meets threshold @done
+    ✔ Achieve 100% branch coverage on `src/primitive-union.ts` @done
+    ✔ Achieve 100% branch coverage on `src/index.ts` @done

 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
+✔ when using a union type as a property, the current behavior of tagged union matcher is @done
    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
+    ✔ 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 @done

 Documentation:
-☐ Bring README.md back to its previous form — synopsis and examples restored, in the correct place
+✔ Bring README.md back to its previous form — synopsis and examples restored, in the correct place @done
    → 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
+✔ Add comparison section vs. other TS pattern-matching libs in Readme.md @done
+    ✔ Why do we do this? => exhaustiveness encoded type safe @done
+    ✔ Why this form? little syntax, data last, very small, autocomplete, strict typing in the handler; for more features use ts-pattern @done
+✔ Write migration guide for users coming from discriminated unions @done (9/24/2026, 10:21:17 PM)
+✔ Create backlog tasks for implementation @done (9/24/2026, 10:21:16 PM)
+✔ Validate code fences in Markdown (start with README.md) — compile the TypeScript examples against `src/` so the docs cannot drift from the API @done

 Maintenance:
 ☐ Serve CI coverage over a tiny self-hosted webserver (replace the zip artifact) @low
@@ -102,3 +46,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
@@ -45,7 +45,8 @@
        "todotasks",
        "connor",
        "injective",
-        "injectivity"
+        "injectivity",
+        "userland"
    ],
    "ignorePaths": ["dist", "node_modules", "coverage", "*.svg", ".gitignore"]
 }
@@ -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                                              |

@@ -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)
@@ -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.
@@ -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
-library is placeholder code.
+`getTaggedUnionMatcherW`), re-exported from `src/index.ts`; the rest of `src/`
+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`
-  maps the handled tags to their members and `Exclude<T, …>` is the fallback's
-  parameter; the redundant-fallback guard is the same F-bounded constraint. Only
-  the "universe" changes — `T`'s members instead of primitive values.
+- **Same fallback/remainder machinery as the primitive-union matcher.** `HandledTags`
+  recovers the tag values the map handled (`Member<Tags, keyof Handled>`) and
+  `Narrowed<T, K, Exclude<Tags, …>>` is the fallback's parameter; the
+  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
-  union of members instead of dropping one.
+- **`Narrowed` distributes over `T`, narrowing `K` to the tag.** A member whose
+  `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
-  collapse to a union under one handler. A tag colliding with its
-  stringification (`true | "true"`) is rejected by the universe gate — see
-  § Supported universes.
+- A tag need not be unique across the union. Two members sharing one is not a
+  soundness hole: they select a single runtime key, so one handler receiving
+  their union is the only correct behavior — the key is simply not a
+  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

@@ -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

@@ -196,6 +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
+
+#### Decision (2026-09)
+
+`knip.json` declares `"entry": ["src/index.ts", "scripts/*.ts"]`.
+
+#### Why
+
+- Supplying `entry` **replaces** knip's default entry detection, which otherwise
+  derives the public entry from `package.json` `exports`. Adding `scripts/*.ts`
+  there therefore dropped the library entry, so knip resolved the package through
+  its `dist/index.js` output and reported the unreferenced source entry file
+  `src/index.ts` as an unused file.
+- Naming the source entry restores the link between the public API and the
+  source graph without pointing knip at build output.
+
+#### Rejected
+
+- `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
+  build layout changes.
+
 ### `maintain:outdated` ignores `@types/node`

 #### Decision (2026-09)
@@ -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.
@@ -1,5 +1,5 @@
 {
    "$schema": "./node_modules/knip/schema.json",
-    "entry": ["scripts/*.ts"],
+    "entry": ["src/index.ts", "scripts/*.ts"],
    "ignoreDependencies": ["@runwisp/pubv"]
 }
@@ -1,7 +1,7 @@
 {
    "name": "tiny-pattern-ts",
-    "version": "0.7.0",
-    "description": "Pattern matching for TypeScript/ESM environments (F#-style, not regex)",
+    "version": "0.8.2",
+    "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.68.0",
+        "mdast-util-from-markdown": "^2.0.3",
+        "oxfmt": "^0.70.0",
        "oxlint": "^1.83.0",
        "oxlint-tsgolint": "^7.0.2001",
        "publint": "^0.3.24",
@@ -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;
+    }
+}
@@ -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.
@@ -0,0 +1,10 @@
+{
+    "extends": "../../tsconfig.json",
+    "compilerOptions": {
+        "noEmit": true,
+        "noUnusedLocals": false,
+        "noUnusedParameters": false
+    },
+    "include": ["__generated__/**/*.test.ts"],
+    "exclude": []
+}
@@ -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");
+});
@@ -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,
@@ -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
-        ? "broad types like string, number and template literals are not supported"
-        : [Collisions<T>] extends [never]
+    IsLiteral<PatternKey<T>> extends true
+        ? [Collisions<T>] extends [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
@@ -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
@@ -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;
@@ -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 };`;
@@ -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
-// member.
+// type; `Member` inverts the projection against the tag set to recover the tag.
+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
-// index within `MapTaggedUnion`'s keys, and the conditional drops a stray key
-// outside `T` so it cannot widen the remainder. The remainder is
-// `Exclude<T, …>`, mirroring the primitive-union matcher's
-// `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 tag values whose `PatternKey` is handled.
+type HandledTags<T extends object, K extends keyof T, Handled> = Member<
+    Tags<T, K>,
+    keyof Handled
+>;

 // 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;
@@ -8,5 +8,6 @@
        "allowImportingTsExtensions": true,
        "verbatimModuleSyntax": true
    },
-    "include": ["src", "scripts"]
+    "include": ["src", "scripts"],
+    "exclude": ["src/doc-test"]
 }
Author	SHA1	Message	Date
tmu	ac1fd60043	🚀 Release 0.8.2 CI / release-gate (push) Successful in 2s Details CI / build (push) Successful in 37s Details CI / maintain (push) Failing after 15s Details CI / publish (push) Failing after 15s Details	2026-09-25 23:20:02 +00:00
tmu	f5871c37c8	🔀 Merge chore/readme-comparison into main	2026-09-25 23:17:33 +00:00
tmu	7a1eaa0d7f	📝 Add an alternatives section Add a short README section under Alternatives, one heading per alternative (ts-pattern, Effect.Match, match-iz and plain switch), each saying what it is and what tiny-pattern-ts is or does differently. State the data-last, pipe-friendly shape in Description. - measure the footprint: ~0.2 kB minified + gzipped, not the unminified ~1.8 kB; ts-pattern is ~2 kB - correct match-iz: it ships types, it just cannot prove exhaustiveness - drop switchcase / ts-match (unmaintained) - check off the backlog task Resolves: backlog "Add comparison section vs. other TS pattern-matching libs"	2026-09-25 23:16:14 +00:00
tmu	09011d838f	🔀 Merge chore/cleanup-readme into main CI / release-gate (push) Successful in 3s Details CI / build (push) Successful in 27s Details CI / publish (push) Skipped Details CI / maintain (push) Failing after 15s Details	2026-09-24 21:56:33 +00:00
tmu	8261759190	📝 Restore and rewrite the README entry point The README collapsed to API-only prose once the old match/P surface was dropped. Rebuild its entry-point shape: a quick-start Synopsis walked through a Contact union, a dedicated Installation section, and a real-world Examples section (primitive-union dispatch, a fallback, a property union narrowed by the tagged-union matcher, and the widening variant). Set the tagline and Description to the library's identity — exhaustive, type-safe pattern matching for TypeScript — and state the goal Moose-style: type-safe pattern matching with a lean syntax, accomplished by exhaustive branches and typed per-branch handler parameters, backed by autocomplete and a tiny footprint. Drop the F#-style framing and the stale "matches method is a type guard" and "(not regex)" copy from the README, AGENTS.md and the package.json description. Every fence is a doc-test, so the examples cannot drift from the API.	2026-09-24 21:55:51 +00:00
tmu	28d87b3387	📝 Close out migration guide and backlog tasks	2026-09-24 20:51:42 +00:00
tmu	ccbd0a297c	🔀 Merge feature/doc-tests into main CI / release-gate (push) Successful in 3s Details CI / build (push) Successful in 29s Details CI / publish (push) Skipped Details CI / maintain (push) Successful in 15s Details	2026-09-24 13:51:41 +00:00
tmu	400fe902e0	♻️ Run doc-test generation as an explicit CI step Drop the `pretest:ci` lifecycle hook and call `create:doc-tests` from the `build` job before `test:ci`. The hook hid the step from the job log and made `test:ci` behave differently under npm than when run directly.	2026-09-24 13:08:45 +00:00
tmu	4dc58395c0	♻️ Run doc tests outside the coverage gate An example that exercises a line no hand-written test reaches would let the `--100` gate pass on documentation alone. Node has no file-level exclusion, and c8's `--exclude` only filters the report, so run the two in separate processes: `test:coverage` runs c8 over the tracked tests only (`git ls-files`, which skips the untracked generated files), and `test:doc` runs the generated examples without c8. `test:ci` chains them.	2026-09-24 12:52:42 +00:00
tmu	a9b588e1c3	♻️ Drop assert imports from doc fences `assert` is the sole injected exception: the generated test always binds it, so a fence must not import it. Revert the README imports and the generator's node:assert merging; the fences keep the assigned variables and `assert.equal` calls, and the generator again rejects a fence that imports node:assert.	2026-09-24 12:17:24 +00:00
tmu	d0dd8641f2	✅ Assert README example results Assign every documented matcher result to a variable and assert it with `assert.equal`, so the compiled README doc-tests verify behavior instead of merely running the code. The examples import `node:assert` themselves to stay copy-pasteable; the generator now merges that import into its prelude assert rather than rejecting it (only `node:test` remains reserved).	2026-09-24 12:13:36 +00:00
tmu	30d97a9209	✨ Compile doc code fences into tests Every `ts`-tagged fence in README.md / CONTRIBUTING.md now becomes an executed `node:test` case in a gitignored generated file, so a documented example cannot drift from the API. The generator hoists and merges the leading imports, rewrites the library specifier to the `#test-tiny-pattern-ts` alias, and rejects a fence with no describing paragraph or one that re-imports a prelude module. CI regenerates via `pretest:ci`; `create:doc-tests` runs the generator, formats, then typechecks the output against a scoped tsconfig that relaxes `noUnusedLocals`. c8's default excludes already omit the generated `*.test.ts`, so `test:ci` is unchanged.	2026-09-24 11:53:29 +00:00
tmu	d1963b0329	🔀 Merge feature/api-surface into main CI / release-gate (push) Successful in 3s Details CI / build (push) Successful in 26s Details CI / publish (push) Skipped Details CI / maintain (push) Successful in 15s Details	2026-09-23 22:51:21 +00:00
tmu	0bde38d6e4	📝 Summarize the API docs work in the changelog	2026-09-23 22:51:11 +00:00
tmu	38484aa16d	📝 Refresh license year, backlog notes and JSDoc Bump the copyright to 2026 in LICENSE and README, add the comparison-section notes to the backlog, and trim the primitive-union factory JSDoc now that the universe rules live in README § Caveats.	2026-09-23 22:50:05 +00:00
tmu	c878e60ff2	📝 Bind the handler-map function in every example Each README and JSDoc example now assigns the function that takes the handler object (the factory result, or the tagged key step) to a match… variable and reuses it, so the builder is created once instead of per call.	2026-09-23 22:33:43 +00:00
tmu	c8bee95088	📝 Document when to use each matcher Add the universe/return axes and a "Use when" column to the README API table, and the same one-liner to each of the four factory JSDoc blocks.	2026-09-23 22:25:39 +00:00
tmu	5ddbbdc183	♻️ Keep the public API to the four factories The builder types are already the inferred return types and travel into the emitted .d.ts, so exporting them only made them nameable while pinning the internal Strict/Widening split as API. Revert the type exports and the public renames, drop the type-surface test, and document only the factories in README and development/library.md.	2026-09-23 22:19:02 +00:00
tmu	9c9468fa3c	📝 Explain the W widening suffix in the API section State that the `W` suffix means widening and what that widens: the matcher's return value goes from one common `R` to the union of every handler's return type.	2026-09-23 22:11:22 +00:00
tmu	f485b1bae2	✨ Finalize and document the public API surface Export the matcher builder types from the barrel and rename them off the internal Strict/Widening suffixes, so the type a factory returns is nameable: PrimitiveUnionMatcher/W, TaggedUnionMatcher/W, and the tagged-union factory types. Add TSDoc to every public symbol — the declarations carry it into the published package — and pin the exported names in src/index.test.ts. Document the API in README and record the surface decision (and the rejected matcher-shared export) in development/library.md.	2026-09-23 21:39:15 +00:00
tmu	acf9d06ddd	🚀 Release 0.8.1 CI / release-gate (push) Successful in 2s Details CI / build (push) Successful in 35s Details CI / maintain (push) Successful in 14s Details CI / publish (push) Failing after 16s Details	2026-09-23 21:24:42 +00:00
tmu	eba60f6569	🔀 Merge chore/coverage-threshold into main	2026-09-23 21:23:37 +00:00
tmu	52ce655d8e	👷 Gate CI at 100% coverage test:ci now runs c8 with --all --include "src/*/.ts" --100, so the build job fails when any runtime file under src/ is untested. --all is what makes the gate non-vacuous: without it c8 counts only the files the suite happened to load, and a new untested module stays invisible. Add src/index.test.ts to load the public barrel, which was previously never imported at runtime and so read as 0% under --all. matcher-shared.ts is types-only (an empty runtime image) and carries a file-level c8 ignore with the reason. Why 100% and the rejected alternatives: development/ci.md § Coverage threshold.	2026-09-23 21:12:24 +00:00
tmu	76327a8c47	🔀 Merge chore/duplicate-tag-union-test into main	2026-09-23 20:55:56 +00:00
tmu	d7004c0f71	📝 Clarify the duplicate-tag known issue	2026-09-23 20:52:45 +00:00
tmu	69231eb9ac	📝 Note the duplicate-tag tests in the changelog	2026-09-23 20:30:44 +00:00
tmu	7ff371c569	✅ Pin the duplicate-tag union collapse	2026-09-23 20:30:35 +00:00
tmu	0339a493a2	📝 Track the TypeScript 5.0 CI baseline	2026-09-23 20:28:53 +00:00
tmu	2c856f28e3	🔀 Merge chore/open-universe-guidance into main	2026-09-23 20:01:52 +00:00
tmu	4260a4732c	📝 Document why open universes are rejected Add a README Caveats subsection with user-facing guidance for the two open-universe shapes: parse external input at the boundary down to a finite union, or use a runtime Map registry for extensible domains. Point the finite-universe bullet at it, and point the rejected fix/open-universe-* entry in development/library.md back at the new guidance, so rule and decision cross-reference without duplicating each other.	2026-09-23 19:51:19 +00:00
tmu	11d364e187	🚀 Release 0.8.0 CI / release-gate (push) Successful in 3s Details CI / build (push) Successful in 34s Details CI / maintain (push) Successful in 15s Details CI / publish (push) Failing after 19s Details	2026-09-23 17:42:32 +00:00
tmu	8dc0b95320	🔀 Merge fix/union-valued-discriminant into main	2026-09-23 17:37:37 +00:00
tmu	7b90f898d3	✅ Cover property-union autocomplete and rejection Add property-union tests for the completion popup, a broad value in the union, and value/stringification collisions. Rename the existing property-union tests to a `property union:` prefix so they can be selected with `--test-name-pattern`, and extend the autocomplete helper with a `key` option so a probe can complete on a property other than `kind`.	2026-09-23 16:32:16 +00:00
tmu	1bdf7f0315	🐛 Reject mixed literal and broad universes `UnsupportedReason` tested `IsLiteral<PatternKey<T>> extends false`. `IsLiteral` is `boolean` for a union that mixes a literal with a broad type (`"a" \| \`x-${number}\``), so `boolean extends false` is false and the mix was accepted. Test `extends true` instead, which rejects it. Found while adding property-union broad-universe coverage; the gate is shared with the primitive-union matcher.	2026-09-23 16:32:09 +00:00
tmu	55bf6c24a7	🐛 Narrow union-valued and optional discriminants The tagged-union matcher selected handler parameters with `Extract<T, Record<K, V>>`, which only keeps a member whose discriminant is a singleton literal. A property that is itself a union (`{ color: "red" \| "green" \| "blue" }`) or optional (`{ type?: "x" }`) matched no member, so every handler received `never`, and the fallback saw the whole shape instead of the unhandled tags. Replace the selector with `Narrowed`, which distributes over `T`, drops a member whose `K` cannot take the tag, and narrows `K`. The `T[K] extends V` fast path keeps an exact member (a discriminated union's declared interface) untouched. The fallback reuses `Narrowed` over `Exclude<Tags, HandledTags>`, so a union-valued property narrows to the unhandled tags rather than the whole shape. Matching a defined tag on an optional property makes the key required (`{ type: "x" }`); the `undefined` tag yields `{ type?: never }` under `exactOptionalPropertyTypes` (absence) or `{ type?: undefined }` when the property admits an explicit `undefined`.	2026-09-23 16:04:00 +00:00
tmu	e7b5c0284d	🔀 Merge chore/prune-backlog into main	2026-09-23 15:27:05 +00:00
tmu	013bfa883b	📝 Prune the backlog; document the LSP shutdown fix Remove every done/cancelled backlog item; the reasons they recorded are already in development/ (library.md, testing.md, tooling.md, workflow.md) and git history is the archive. The one exception was the TS 7 LSP shutdown workaround, which lived only in a code comment. Record it under development/testing.md § Autocomplete (Known issue) before dropping the bug item.	2026-09-23 15:12:54 +00:00
tmu	d99d84d387	🚀 Release 0.7.1 CI / release-gate (push) Successful in 2s Details CI / build (push) Successful in 34s Details CI / maintain (push) Successful in 15s Details CI / publish (push) Failing after 17s Details	2026-09-23 14:56:59 +00:00
tmu	02f64f804e	🔀 Merge fix/knip-library-entry into main	2026-09-23 14:56:15 +00:00
tmu	cbaed8fabc	🐛 Stop knip reporting the source entry Listing scripts/*.ts in knip's `entry` replaced its default entry detection, which derives the public entry from package.json `exports`. Adding the CLI scripts therefore dropped the library entry, so knip resolved the package through dist/index.js and flagged the unreferenced src/index.ts as unused. Name the source entry alongside the scripts. Record the rationale in development/tooling.md.	2026-09-23 14:55:27 +00:00
tmu	410903198e	🔀 Merge chore/upgrade-deps into main	2026-09-23 14:51:49 +00:00
tmu	2e4262383c	⬆️ Upgrade dependencies Bump every direct dependency to the latest registry version: cspell 10.3.3, knip 6.38.0, oxfmt 0.70.0, oxlint 1.85.0, oxlint-tsgolint 7.0.2002 and type-fest 5.10.0, plus their transitive updates. oxfmt is the only range widened (^0.68.0 -> ^0.70.0); the rest moved within their existing semver ranges. `npm run maintain:outdated` is now clean and `npm run verify` is green with no rule or format fallout. `maintain:knip` still reports the pre-existing `src/index.ts` false positive (dist-only `exports`), which predates this bump.	2026-09-23 14:50:29 +00:00